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.
Create a bank beneficiary
/api/v1/beneficiaries
Register a US account. Scope payouts:write.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
methodstringRequiredach or wire.
ach · wire
holderTypestringOptionalHolder type.
namestringRequiredAccount holder name.
emailstringRequiredHolder email.
accountNumberstringRequired4–17 digits. Stored encrypted; the response only shows the last 4.
accountTypestringOptionalRequired for ach.
countryCodestringRequiredHolder country code.
addressstringRequiredAddress.
citystringRequiredCity.
statestringOptionalRequired if countryCode is US.
postalCodestringRequiredPostal code.
bankNamestringRequiredBank name.
bankCodestringRequiredABA routing number (9 digits).
bankCountrystringRequiredAlways US for ach/wire.
bankAddressstringRequiredBank address.
bankCitystringRequiredBank city.
bankStatestringRequiredBank state (2-letter US code, e.g. WA).
bankPostalCodestringRequiredBank postal code.
Responses
- HTTP 201Beneficiary created. Response fields in camelCase.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 422
invalid_beneficiaryA field required for the method is missing, or the routing number is invalid.
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"
}List bank beneficiaries
/api/v1/beneficiaries
List of your merchant’s US accounts. Scope payouts:read.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
Responses
- HTTP 200List.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After.
curl -X GET "$CLOBEPAY_API_BASE/beneficiaries" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200{
"items": []
}Retrieve a beneficiary
/api/v1/beneficiaries/{beneficiaryId}
Detail by UUID. Scope payouts:read.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
beneficiaryIduuidRequiredBeneficiary UUID.
Responses
- HTTP 200Detail.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 404
not_foundIt does not exist or is not yours. Also if beneficiaryId is not a UUID.
curl -X GET "$CLOBEPAY_API_BASE/beneficiaries/a41c82e7-3b6d-4c90-9e2a-5f17d0b8c4e3" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200Detail.