Back to the reference

Bank beneficiaries

US ACH or wire accounts.

Bank beneficiaries are US accounts for ACH or wire payouts. The POST /beneficiaries body and response use camelCase (accountNumber, holderType, countryCode, postalCode, bankName, bankCode), like the rest of the public API.

POST

Create a bank beneficiary

/api/v1/beneficiaries

Register a US account. Scope payouts:write.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

method
body
stringRequired

ach or wire.

ach · wire

holderType
body
stringOptional

Holder type.

name
body
stringRequired

Account holder name.

email
body
stringRequired

Holder email.

accountNumber
body
stringRequired

4–17 digits. Stored encrypted; the response only shows the last 4.

accountType
body
stringOptional

Required for ach.

countryCode
body
stringRequired

Holder country code.

address
body
stringRequired

Address.

city
body
stringRequired

City.

state
body
stringOptional

Required if countryCode is US.

postalCode
body
stringRequired

Postal code.

bankName
body
stringRequired

Bank name.

bankCode
body
stringRequired

ABA routing number (9 digits).

bankCountry
body
stringRequired

Always US for ach/wire.

bankAddress
body
stringRequired

Bank address.

bankCity
body
stringRequired

Bank city.

bankState
body
stringRequired

Bank state (2-letter US code, e.g. WA).

bankPostalCode
body
stringRequired

Bank postal code.

Responses

  • HTTP 201Beneficiary created. Response fields in camelCase.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 422invalid_beneficiaryA field required for the method is missing, or the routing number is invalid.
POST/beneficiaries
curl -X POST "$CLOBEPAY_API_BASE/beneficiaries" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY" \  -H "Content-Type: application/json" \  -d '{"method":"ach","holderType":"business","name":"Atlas Creativo LLC","email":"finanzas@comercioatlas.mx","accountNumber":"123456789","accountType":"checking","countryCode":"US","address":"1201 3rd Ave","city":"Seattle","state":"WA","postalCode":"98101","bankName":"Example Bank","bankCode":"125000024","bankCountry":"US","bankAddress":"1201 3rd Ave","bankCity":"Seattle","bankState":"WA","bankPostalCode":"98101"}'

Response

HTTP 201
{
  "id": "a41c82e7-3b6d-4c90-9e2a-5f17d0b8c4e3",
  "name": "Atlas Creativo LLC",
  "method": "ach",
  "accountNumberLast4": "6789",
  "countryCode": "US"
}

GET

List bank beneficiaries

/api/v1/beneficiaries

List of your merchant’s US accounts. Scope payouts:read.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

Responses

  • HTTP 200List.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
GET/beneficiaries
curl -X GET "$CLOBEPAY_API_BASE/beneficiaries" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
{
  "items": []
}

GET

Retrieve a beneficiary

/api/v1/beneficiaries/{beneficiaryId}

Detail by UUID. Scope payouts:read.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

beneficiaryId
path
uuidRequired

Beneficiary UUID.

Responses

  • HTTP 200Detail.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 404not_foundIt does not exist or is not yours. Also if beneficiaryId is not a UUID.
GET/beneficiaries/{beneficiaryId}
curl -X GET "$CLOBEPAY_API_BASE/beneficiaries/a41c82e7-3b6d-4c90-9e2a-5f17d0b8c4e3" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
Detail.