Matriz de corredores
En payins hosted puedes enviar
payer_name, payer_document y payer_phone
cuando el método los exige. Para payouts, flow_type puede ser B2C, B2B o
P2P, según la configuración server-controlled.
Payins hosted y wallet
PYbank_transfer y wallet, CO bank_transfer, y EC wallet devuelven
payment_url. Crea el cobro con una idempotency_key y espera el webhook
firmado payin_received; luego consulta GET /v1/payins/{payinID}.
wallet es un collect push: no entrega URL. El pagador aprueba en su
app y la confirmación llega por webhook, normalmente alrededor de 15 minutos.
CO/COP/bank_transfer usa checkout hosted PSE. COP siempre debe ser entero.
Brasil
Brasil expone dos métodos de payout y un payin PIX hosted. UsaGET /v1/payouts/methods y GET /v1/payins/methods como fuente de verdad.
Payout PIX y TED
Para PIX, envíamethod: "pix" con una llave PIX: CPF, CNPJ, email,
teléfono brasileño (+55 más 10 dígitos fijo u 11 celular) o llave aleatoria EVP/UUID. CPF y
CNPJ se validan con sus dígitos verificadores; no envíes banco ni cuenta.
Para TED, usa method: "bank_transfer" con banco, agencia, tipo de cuenta,
número de cuenta, nombre y CPF/CNPJ. El banco debe venir de
GET /v1/payouts/banks; agencia y tipo de cuenta son obligatorios. El CPF/CNPJ
se valida antes del despacho. Algunos bancos aceptan solo documentos que no
sean CPF; sigue el catálogo y el error de validación del banco.
Ambos métodos BRL aceptan hasta dos decimales. Ante un timeout ambiguo,
consulta el payout con la misma clave y no crees un reemplazo.
Payin PIX hosted
CreaBR/BRL/pix con mínimo 1 BRL, enviando payer_name y
payer_document. La respuesta trae payment_url y queda pending; redirige
al pagador a esa URL.
"1". Repite con la
misma clave para recuperar el mismo cobro hosted.
Payouts y seguridad operacional
ConsultaGET /v1/payouts/methods y GET /v1/payouts/banks antes de mostrar
un formulario. Ante timeout o 5xx, conserva la misma clave y consulta el
recurso; CBPay no reenvía automáticamente una operación ambigua.
Los callbacks entrantes se autentican y tus webhooks salientes llevan
X-Webhook-Signature. Procesa duplicados de forma idempotente.
Ciclo de vida y webhooks
Los estados finales del payin soncompleted y failed; pending y
processing son transitorios.
Errores frecuentes
FAQ
¿Puedo elegir el proveedor o el fallback de PY?
¿Puedo elegir el proveedor o el fallback de PY?
No. El integrador elige solo el corredor neutro. Las variantes son
server-controlled y firmadas.
¿Qué hago después de un timeout?
¿Qué hago después de un timeout?
Conserva la misma idempotency key y consulta el recurso. No abras una segunda
operación.
¿Cuánto tiempo puedo consultar un payin?
¿Cuánto tiempo puedo consultar un payin?
La consulta upstream está disponible solo dentro de 12 meses; conserva el
charge y los webhooks de CBPay.