Back to the reference

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.

POST

Create a deposit account

/api/v1/deposit-accounts

Creates or returns the merchant account in that currency. Scope deposit_accounts:write.

Parameters

Authorization
header
stringRequired

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

Idempotency-Key
header
stringRequired

1–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.

currency
body
stringRequired

Account currency. In Mexico: MXN.

Responses

  • HTTP 201Account created.
  • HTTP 200An account in that currency already existed.

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 400Bad Requestcurrency is not MXN (standard validation 400, message: ["currency must be MXN"]).
  • HTTP 400idempotency_key_requiredThe Idempotency-Key header is missing.
  • HTTP 409verification_not_approvedThe merchant does not have an approved verification.
  • HTTP 409payment_method_not_enabledThe merchant does not have the deposit account payment method enabled. Contact Clobepay.
  • HTTP 503deposit_account_pendingThe account is being created. Retry in a few minutes with the same Idempotency-Key.
  • HTTP 503deposit_account_unavailableThe account could not be created or assigned right now. Retry later; if it persists, contact Clobepay.
POST/deposit-accounts
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"
}

GET

List deposit accounts

/api/v1/deposit-accounts

Merchant accounts. Scope deposit_accounts: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/deposit-accounts
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
}

GET

Retrieve a deposit account

/api/v1/deposit-accounts/{depositAccountId}

Detail by UUID. Scope deposit_accounts:read.

Parameters

Authorization
header
stringRequired

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

depositAccountId
path
uuidRequired

Account 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 depositAccountId is not a UUID.
GET/deposit-accounts/{depositAccountId}
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"
}