Bank accounts

Delete a destination

Deletes a destination, a bank account or a card, so it can no longer be paid or chosen: it leaves GET /v1/beneficiaries/{id}/bank-accounts and the Beneficiary’s collection link, and a payout that names it is refused. Payouts already created to it keep showing its last four digits, and one that is approved or on compliance hold is still sent to it. If it was the Beneficiary’s declared destination, declared_destination_id is cleared and the Beneficiary is told by email. Refused with DESTINATION_HAS_PENDING_PAYOUT while a payout awaiting approval is headed to it: reject that payout, then delete. Idempotent: deleting a destination that is already deleted succeeds.

DELETE

beneficiaries

{id}

bank-accounts

{accountId}

Delete a Beneficiary’s destination

curl --request DELETE \
  --url https://api.usecleff.com/v1/beneficiaries/{id}/bank-accounts/{accountId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.usecleff.com/v1/beneficiaries/{id}/bank-accounts/{accountId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.delete(url, headers=headers)

print(response.text)

const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.usecleff.com/v1/beneficiaries/{id}/bank-accounts/{accountId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecleff.com/v1/beneficiaries/{id}/bank-accounts/{accountId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecleff.com/v1/beneficiaries/{id}/bank-accounts/{accountId}"

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.usecleff.com/v1/beneficiaries/{id}/bank-accounts/{accountId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "error": {
    "code": "bad_request",
    "message": "Validation failed (uuid is expected)",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": {
      "user_id": "usr_...",
      "membership_id": "mem_...",
      "role": "business_admin",
      "environment": "sandbox"
    },
    "docs_url": "https://docs.usecleff.com/errors#bad_request"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": null,
    "docs_url": "https://docs.usecleff.com/errors#unauthorized"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Forbidden resource",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": {
      "user_id": "usr_...",
      "membership_id": "mem_...",
      "role": "business_read_only",
      "environment": "sandbox"
    },
    "docs_url": "https://docs.usecleff.com/errors#forbidden"
  }
}

{
  "error": {
    "code": "BANK_ACCOUNT_NOT_FOUND",
    "message": "BankAccount 9b2f4c1e-5d7a-4e8b-a3c6-1f0d2e4b6a8c not found",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": {
      "user_id": "usr_...",
      "membership_id": "mem_...",
      "role": "business_admin",
      "environment": "sandbox"
    },
    "docs_url": "https://docs.usecleff.com/errors#bank_account_not_found"
  }
}

{
  "error": {
    "code": "DESTINATION_HAS_PENDING_PAYOUT",
    "message": "A payout is awaiting approval to this destination, including 7d1e5a3c-2b4f-4c6a-8e9d-0f1a2b3c4d5e. Reject it with POST /v1/payouts/{payoutId}/reject, then delete the destination",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": {
      "user_id": "usr_...",
      "membership_id": "mem_...",
      "role": "business_admin",
      "environment": "sandbox"
    },
    "docs_url": "https://docs.usecleff.com/errors#destination_has_pending_payout"
  }
}

{
  "error": {
    "code": "BENEFICIARY_ARCHIVED",
    "message": "Beneficiary is archived and accepts no new Payouts, links or bank details",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": {
      "user_id": "usr_...",
      "membership_id": "mem_...",
      "role": "business_admin",
      "environment": "sandbox"
    },
    "docs_url": "https://docs.usecleff.com/errors#beneficiary_archived"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Slow down and retry after the window.",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": null,
    "docs_url": "https://docs.usecleff.com/errors#rate_limited"
  }
}

Agents: fetch this page as plain markdown at https://docs.usecleff.com/api-reference/beneficiaries-bank-accounts-delete.md.

Authorizations

Authorization

string

header

required

Cleff API key, created in the dashboard under Settings → API keys

Path Parameters

string

required

accountId

string

required

Response

Deleted (or already deleted — idempotent)

⌘I

Delete a Beneficiary’s destination

curl --request DELETE \
  --url https://api.usecleff.com/v1/beneficiaries/{id}/bank-accounts/{accountId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.usecleff.com/v1/beneficiaries/{id}/bank-accounts/{accountId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.delete(url, headers=headers)

print(response.text)

const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.usecleff.com/v1/beneficiaries/{id}/bank-accounts/{accountId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecleff.com/v1/beneficiaries/{id}/bank-accounts/{accountId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecleff.com/v1/beneficiaries/{id}/bank-accounts/{accountId}"

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.usecleff.com/v1/beneficiaries/{id}/bank-accounts/{accountId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "error": {
    "code": "bad_request",
    "message": "Validation failed (uuid is expected)",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": {
      "user_id": "usr_...",
      "membership_id": "mem_...",
      "role": "business_admin",
      "environment": "sandbox"
    },
    "docs_url": "https://docs.usecleff.com/errors#bad_request"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": null,
    "docs_url": "https://docs.usecleff.com/errors#unauthorized"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Forbidden resource",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": {
      "user_id": "usr_...",
      "membership_id": "mem_...",
      "role": "business_read_only",
      "environment": "sandbox"
    },
    "docs_url": "https://docs.usecleff.com/errors#forbidden"
  }
}

{
  "error": {
    "code": "BANK_ACCOUNT_NOT_FOUND",
    "message": "BankAccount 9b2f4c1e-5d7a-4e8b-a3c6-1f0d2e4b6a8c not found",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": {
      "user_id": "usr_...",
      "membership_id": "mem_...",
      "role": "business_admin",
      "environment": "sandbox"
    },
    "docs_url": "https://docs.usecleff.com/errors#bank_account_not_found"
  }
}

{
  "error": {
    "code": "DESTINATION_HAS_PENDING_PAYOUT",
    "message": "A payout is awaiting approval to this destination, including 7d1e5a3c-2b4f-4c6a-8e9d-0f1a2b3c4d5e. Reject it with POST /v1/payouts/{payoutId}/reject, then delete the destination",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": {
      "user_id": "usr_...",
      "membership_id": "mem_...",
      "role": "business_admin",
      "environment": "sandbox"
    },
    "docs_url": "https://docs.usecleff.com/errors#destination_has_pending_payout"
  }
}

{
  "error": {
    "code": "BENEFICIARY_ARCHIVED",
    "message": "Beneficiary is archived and accepts no new Payouts, links or bank details",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": {
      "user_id": "usr_...",
      "membership_id": "mem_...",
      "role": "business_admin",
      "environment": "sandbox"
    },
    "docs_url": "https://docs.usecleff.com/errors#beneficiary_archived"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Slow down and retry after the window.",
    "request_id": "req_abc123",
    "occurred_at": "2026-07-07T12:00:00.000Z",
    "actor": null,
    "docs_url": "https://docs.usecleff.com/errors#rate_limited"
  }
}