Volver a la referencia

Transferencias

Retiros a cuentas bancarias o billeteras USDT.

Con las transferencias retiras tu saldo (en USDT) a un beneficiario bancario o a una billetera. Toda transferencia creada por API entra en pending_approval. Las de más de 1,000 USD requieren doble firma del comercio. Scope payouts:write para crear (límite 10 por minuto). El cuerpo JSON usa camelCase (destinationType, beneficiaryId, cryptoBeneficiaryId, purposeDetail). Las transferencias bancarias exigen el comprobante como archivo multipart en el campo file.

Estados de una transferencia
  • pending_approval → dispatching: Aprobada
  • pending_approval → rejected: Rechazada
  • dispatching → processing: Aceptada por el proveedor
  • dispatching → pending: En revisión del proveedor
  • dispatching → dispatch_unknown: Resultado no confirmado
  • dispatching → failed: Fallida
  • dispatch_unknown → dispatching: Verificar
  • dispatch_unknown → processing: Aceptada por el proveedor
  • dispatch_unknown → pending: En revisión del proveedor
  • dispatch_unknown → failed: Fallida
  • pending → processing: Aceptada por el proveedor
  • pending → failed: Fallida
  • processing → completed: Completada
  • processing → failed: Fallida
GET

Configuración de transferencias

/api/v1/payouts/config

Métodos, umbral de doble firma y propósitos.

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 200Configuración.

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/payouts/config
curl -X GET "$CLOBEPAY_API_BASE/payouts/config" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

HTTP 200
{
  "dualApprovalThresholdUsd": "1000.00",
  "methods": [
    "ach",
    "wire",
    "crypto"
  ]
}

GET

Cotizar una transferencia

/api/v1/payouts/quote

Costo, tipo de cambio referencial y si alcanza el saldo.

Parámetros

Authorization
header
stringObligatorio

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

amount
query
stringObligatorio

Importe que recibe el beneficiario.

method
query
stringOpcional

ach, wire o crypto.

ach · wire · crypto

destination
query
stringOpcional

bank o crypto.

bank · crypto

chain
query
stringOpcional

Red si el destino es crypto.

tron · eth · polygon

Respuestas

  • HTTP 200Cotización. Campos en camelCase (receiveAmount, totalDebit, requiredApprovals).

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 400invalid_amountImporte o método inválido.
GET/payouts/quote
curl -X GET "$CLOBEPAY_API_BASE/payouts/quote?amount=100.00&method=ach&destination=bank" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

HTTP 200
{
  "destinationType": "bank",
  "method": "ach",
  "receiveAmount": "100.00",
  "receiveCurrency": "USD",
  "convertAmount": "100.00",
  "fee": {
    "amount": "1.50",
    "currency": "USDT"
  },
  "totalDebit": "101.50",
  "debitAsset": "USDT",
  "sufficientBalance": true,
  "requiredApprovals": 1,
  "dualApprovalThresholdUsd": "1000.00"
}

POST

Crear una transferencia

/api/v1/payouts

Queda en pending_approval. Scope payouts:write. Bank exige file.

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.

destinationType
form
stringOpcional

bank (por defecto) o crypto.

bank · crypto

beneficiaryId
form
uuidOpcional

Beneficiario bancario US. Obligatorio si destinationType es bank.

cryptoBeneficiaryId
form
uuidOpcional

Billetera USDT. Obligatorio si destinationType es crypto.

amount
form
stringObligatorio

Importe que recibe el beneficiario (USD en bank, USDT en crypto).

purpose
form
stringOpcional

Obligatorio en bank (p. ej. Invoice_Payment). Opcional en crypto.

purposeDetail
form
stringOpcional

Solo con purpose = Other (máx. 140).

description
form
stringOpcional

Concepto (máx. 140).

file
form
fileOpcional

Comprobante obligatorio en transferencias bancarias (multipart). No aplica en crypto.

Respuestas

  • HTTP 201Solicitud creada en pending_approval.

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 400idempotency_key_requiredFalta el header Idempotency-Key.
  • HTTP 422insufficient_balanceEl saldo no alcanza para el importe y el costo.
  • HTTP 422invalid_purposeFalta purpose en un retiro bancario, no es un valor permitido o purposeDetail supera 140 caracteres.
  • HTTP 422supporting_document_requiredFalta el archivo file en un retiro bancario.
POST/payouts
curl -X POST "$CLOBEPAY_API_BASE/payouts" \  -H "Idempotency-Key: payout-10042" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY" \  -F "destinationType=bank" \  -F "beneficiaryId=a41c82e7-3b6d-4c90-9e2a-5f17d0b8c4e3" \  -F "amount=100.00" \  -F "purpose=Invoice_Payment" \  -F "file=@invoice.pdf"

Respuesta

HTTP 201
{
  "id": "e2a9c4d1-6f38-4b7e-a015-c8d94e2b70aa",
  "destinationType": "bank",
  "amount": "100.00",
  "currency": "USD",
  "method": "ach",
  "status": "pending_approval",
  "totalDebit": "101.50",
  "debitAsset": "USDT",
  "requiredApprovals": 1
}

GET

Listar transferencias

/api/v1/payouts

Historial de retiros. 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.

status
query
stringOpcional

Filtra por estado.

page
query
numberOpcional

Página (desde 1).

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/payouts
curl -X GET "$CLOBEPAY_API_BASE/payouts?status=pending_approval" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

HTTP 200
{
  "items": [],
  "page": 1
}

GET

Consultar una transferencia

/api/v1/payouts/{payoutId}

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.

payoutId
path
uuidObligatorio

UUID de la transferencia.

Respuestas

  • HTTP 200Detalle en camelCase (destinationType, totalDebit, requiredApprovals).

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 payoutId no es un UUID.
GET/payouts/{payoutId}
curl -X GET "$CLOBEPAY_API_BASE/payouts/e2a9c4d1-6f38-4b7e-a015-c8d94e2b70aa" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

HTTP 200
Detalle en camelCase (destinationType, totalDebit, requiredApprovals).