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.
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
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
Idempotency-KeystringObligatorio1–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.
currencystringObligatorioMoneda de la cuenta. En México: MXN.
Respuestas
- HTTP 201Cuenta creada.
- HTTP 200Ya existía una cuenta en esa moneda.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 400
Bad Requestcurrency no es MXN (400 estándar de validación, message: ["currency must be MXN"]). - HTTP 400
idempotency_key_requiredFalta el header Idempotency-Key. - HTTP 409
verification_not_approvedEl comercio no tiene la verificación aprobada. - HTTP 409
payment_method_not_enabledEl comercio no tiene habilitado el método de pago de las cuentas de depósito. Contacta a Clobepay. - HTTP 503
deposit_account_pendingLa cuenta se está creando. Reintenta en unos minutos con la misma Idempotency-Key. - HTTP 503
deposit_account_unavailableNo se pudo crear o asignar la cuenta en este momento. Reintenta más tarde; si persiste, contacta a 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"}'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"
}Listar cuentas de depósito
/api/v1/deposit-accounts
Cuentas del comercio. Scope deposit_accounts:read.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
Respuestas
- HTTP 200Listado.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After.
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
}Consultar una cuenta de depósito
/api/v1/deposit-accounts/{depositAccountId}
Detalle por UUID. Scope deposit_accounts:read.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
depositAccountIduuidObligatorioUUID de la cuenta.
Respuestas
- HTTP 200Detalle.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 404
not_foundNo existe o no es tuya. También si depositAccountId no es un UUID.
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"
}