Deposit accounts
A bank account per merchant to receive transfers.
Every merchant can have a deposit account to receive bank transfers without creating a link for each one. In Mexico the account is a CLABE. POST /deposit-accounts creates the account (or returns the existing one) and requires Idempotency-Key. Each credit is recorded as a payin with source = deposit_account and follows pending → settled.
Create a deposit account
/api/v1/deposit-accounts
Creates or returns the merchant account in that currency. Scope deposit_accounts:write.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
Idempotency-KeystringRequired1–255 characters. Required on this POST. The same key and body replay the original response (Idempotent-Replayed: true). A different body returns 422 idempotency_key_reuse.
currencystringRequiredAccount currency. In Mexico: MXN.
Responses
- HTTP 201Account created.
- HTTP 200An account in that currency already existed.
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 400
Bad Requestcurrency is not MXN (standard validation 400, message: ["currency must be MXN"]). - HTTP 400
idempotency_key_requiredThe Idempotency-Key header is missing. - HTTP 409
verification_not_approvedThe merchant does not have an approved verification. - HTTP 409
payment_method_not_enabledThe merchant does not have the deposit account payment method enabled. Contact Clobepay. - HTTP 503
deposit_account_pendingThe account is being created. Retry in a few minutes with the same Idempotency-Key. - HTTP 503
deposit_account_unavailableThe account could not be created or assigned right now. Retry later; if it persists, contact Clobepay.
curl -X POST "$CLOBEPAY_API_BASE/deposit-accounts" \ -H "Idempotency-Key: deposit-mxn-1" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"currency":"MXN"}'Response
{
"id": "c5d18a90-4e27-4b6f-91c2-7a8e3d5f0146",
"object": "deposit_account",
"currency": "MXN",
"country": "MX",
"accountNumber": "646180110400000000",
"bankName": "Example Bank",
"status": "active",
"createdAt": "2026-11-19T18:00:00.000Z"
}List deposit accounts
/api/v1/deposit-accounts
Merchant accounts. Scope deposit_accounts: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/deposit-accounts" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200{
"object": "list",
"data": [
{
"id": "c5d18a90-4e27-4b6f-91c2-7a8e3d5f0146",
"object": "deposit_account",
"currency": "MXN",
"country": "MX",
"accountNumber": "646180110400000000",
"bankName": "Example Bank",
"status": "active",
"createdAt": "2026-11-19T18:00:00.000Z"
}
],
"hasMore": false
}Retrieve a deposit account
/api/v1/deposit-accounts/{depositAccountId}
Detail by UUID. Scope deposit_accounts:read.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
depositAccountIduuidRequiredAccount 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 depositAccountId is not a UUID.
curl -X GET "$CLOBEPAY_API_BASE/deposit-accounts/c5d18a90-4e27-4b6f-91c2-7a8e3d5f0146" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200{
"id": "c5d18a90-4e27-4b6f-91c2-7a8e3d5f0146",
"object": "deposit_account",
"currency": "MXN",
"country": "MX",
"accountNumber": "646180110400000000",
"bankName": "Example Bank",
"status": "active",
"createdAt": "2026-11-19T18:00:00.000Z"
}