Volver a la referencia

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.

POST

Crear un beneficiario bancario

/api/v1/beneficiaries

Alta de una cuenta US. Scope payouts: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.

method
body
stringObligatorio

ach o wire.

ach · wire

holderType
body
stringOpcional

Tipo de titular.

name
body
stringObligatorio

Nombre del titular.

email
body
stringObligatorio

Correo del titular.

accountNumber
body
stringObligatorio

4–17 dígitos. Se guarda cifrado; en la respuesta solo ves los últimos 4.

accountType
body
stringOpcional

Requerido en ach.

countryCode
body
stringObligatorio

Código de país del titular.

address
body
stringObligatorio

Dirección.

city
body
stringObligatorio

Ciudad.

state
body
stringOpcional

Requerido si countryCode es US.

postalCode
body
stringObligatorio

Código postal.

bankName
body
stringObligatorio

Nombre del banco.

bankCode
body
stringObligatorio

ABA routing number (9 dígitos).

bankCountry
body
stringObligatorio

Siempre US para ach/wire.

bankAddress
body
stringObligatorio

Dirección del banco.

bankCity
body
stringObligatorio

Ciudad del banco.

bankState
body
stringObligatorio

Estado del banco (código de 2 letras de EE. UU., p. ej. WA).

bankPostalCode
body
stringObligatorio

Código postal del banco.

Respuestas

  • HTTP 201Beneficiario creado. Campos de respuesta en camelCase.

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 422invalid_beneficiaryFalta un campo requerido para el método o el routing number es inválido.
POST/beneficiaries
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"
}

GET

Listar beneficiarios bancarios

/api/v1/beneficiaries

Listado de cuentas US de tu comercio. Scope payouts: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/beneficiaries
curl -X GET "$CLOBEPAY_API_BASE/beneficiaries" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

HTTP 200
{
  "items": []
}

GET

Consultar un beneficiario

/api/v1/beneficiaries/{beneficiaryId}

Detalle por UUID. Scope payouts: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.

beneficiaryId
path
uuidObligatorio

UUID del beneficiario.

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 tuyo. También si beneficiaryId no es un UUID.
GET/beneficiaries/{beneficiaryId}
curl -X GET "$CLOBEPAY_API_BASE/beneficiaries/a41c82e7-3b6d-4c90-9e2a-5f17d0b8c4e3" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

HTTP 200
Detalle.