Volver a la referencia

Cuentas de depósito

Una cuenta bancaria por comercio para recibir transferencias.

Cada comercio puede tener una cuenta de depósito para recibir transferencias bancarias sin crear un link por cada una. En México la cuenta es una CLABE. POST /deposit-accounts crea la cuenta (o devuelve la ya existente) y exige Idempotency-Key. Cada abono se registra como un payin con source = deposit_account y sigue pending → settled.

POST

Crear una cuenta de depósito

/api/v1/deposit-accounts

Crea o devuelve la cuenta del comercio en esa moneda. Scope deposit_accounts:write.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

Idempotency-Key
header
stringObligatorio

1–255 caracteres. Obligatoria en este POST. Si repites la misma llave y el mismo cuerpo, se devuelve la respuesta original (Idempotent-Replayed: true). Si el cuerpo cambia, 422 idempotency_key_reuse.

currency
body
stringObligatorio

Moneda de la cuenta. En México: MXN.

Respuestas

  • HTTP 201Cuenta creada.
  • HTTP 200Ya existía una cuenta en esa moneda.

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 400Bad Requestcurrency no es MXN (400 estándar de validación, message: ["currency must be MXN"]).
  • HTTP 400idempotency_key_requiredFalta el header Idempotency-Key.
  • HTTP 409verification_not_approvedEl comercio no tiene la verificación aprobada.
  • HTTP 409payment_method_not_enabledEl comercio no tiene habilitado el método de pago de las cuentas de depósito. Contacta a Clobepay.
  • HTTP 503deposit_account_pendingLa cuenta se está creando. Reintenta en unos minutos con la misma Idempotency-Key.
  • HTTP 503deposit_account_unavailableNo se pudo crear o asignar la cuenta en este momento. Reintenta más tarde; si persiste, contacta a 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"}'

Respuesta

{
  "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

Listar cuentas de depósito

/api/v1/deposit-accounts

Cuentas del comercio. Scope deposit_accounts:read.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

Respuestas

  • HTTP 200Listado.

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
GET/deposit-accounts
curl -X GET "$CLOBEPAY_API_BASE/deposit-accounts" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

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

Consultar una cuenta de depósito

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

Detalle por UUID. Scope deposit_accounts:read.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

depositAccountId
path
uuidObligatorio

UUID de la cuenta.

Respuestas

  • HTTP 200Detalle.

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 404not_foundNo existe o no es tuya. También si depositAccountId no es un UUID.
GET/deposit-accounts/{depositAccountId}
curl -X GET "$CLOBEPAY_API_BASE/deposit-accounts/c5d18a90-4e27-4b6f-91c2-7a8e3d5f0146" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

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"
}