Beneficiarios bancarios
Cuentas ACH o wire en Estados Unidos.
Los beneficiarios bancarios son cuentas en EE. UU. para transferencias ACH o wire. El cuerpo y la respuesta de POST /beneficiaries usan camelCase (accountNumber, holderType, countryCode, postalCode, bankName, bankCode), igual que el resto de la API pública.
Crear un beneficiario bancario
/api/v1/beneficiaries
Alta de una cuenta US. Scope payouts:write.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
methodstringObligatorioach o wire.
ach · wire
holderTypestringOpcionalTipo de titular.
namestringObligatorioNombre del titular.
emailstringObligatorioCorreo del titular.
accountNumberstringObligatorio4–17 dígitos. Se guarda cifrado; en la respuesta solo ves los últimos 4.
accountTypestringOpcionalRequerido en ach.
countryCodestringObligatorioCódigo de país del titular.
addressstringObligatorioDirección.
citystringObligatorioCiudad.
statestringOpcionalRequerido si countryCode es US.
postalCodestringObligatorioCódigo postal.
bankNamestringObligatorioNombre del banco.
bankCodestringObligatorioABA routing number (9 dígitos).
bankCountrystringObligatorioSiempre US para ach/wire.
bankAddressstringObligatorioDirección del banco.
bankCitystringObligatorioCiudad del banco.
bankStatestringObligatorioEstado del banco (código de 2 letras de EE. UU., p. ej. WA).
bankPostalCodestringObligatorioCódigo postal del banco.
Respuestas
- HTTP 201Beneficiario creado. Campos de respuesta en camelCase.
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 422
invalid_beneficiaryFalta un campo requerido para el método o el routing number es inválido.
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"}'Respuesta
HTTP 201{
"id": "a41c82e7-3b6d-4c90-9e2a-5f17d0b8c4e3",
"name": "Atlas Creativo LLC",
"method": "ach",
"accountNumberLast4": "6789",
"countryCode": "US"
}Listar beneficiarios bancarios
/api/v1/beneficiaries
Listado de cuentas US de tu comercio. Scope payouts: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/beneficiaries" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200{
"items": []
}Consultar un beneficiario
/api/v1/beneficiaries/{beneficiaryId}
Detalle por UUID. Scope payouts:read.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
beneficiaryIduuidObligatorioUUID del beneficiario.
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 tuyo. También si beneficiaryId no es un UUID.
curl -X GET "$CLOBEPAY_API_BASE/beneficiaries/a41c82e7-3b6d-4c90-9e2a-5f17d0b8c4e3" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200Detalle.