Saltar al contenido principal
POST

Autorizaciones

Authorization
string
header
requerido

JWT de sesión (de register/login) o llave de API (pk_...). X-API-Key: <token> se acepta como header alternativo.

Encabezados

Idempotency-Key
string

Alternativa al campo JSON idempotency_key. Es obligatorio para method: "card" cuando el body no trae la clave, y opcional para cobros QR. No envíes valores distintos en el body y el header.

Maximum string length: 256
Pattern: ^[^\r\n]{1,256}$

Cuerpo

application/json
country
string
requerido

País del corredor. Obligatorio para todos los métodos salvo checkout, donde es opcional y solo preselecciona el país del pagador en la página.

Ejemplo:

"BO"

currency
string
requerido

Moneda del corredor. Obligatoria para todos los métodos salvo checkout, que la rechaza con 400 — el cobro se denomina en settlement_asset. Los cobros con tarjeta en Chile están documentados para CLP (montos enteros) y UF (máximo dos decimales, se cobra nativo en el riel de tarjetas y se convierte internamente), pero los corredores CL/UF/card y CL/UF/cash están temporalmente deshabilitados en producción mientras se aprueban; las solicitudes actuales responden 409 corridor_disabled o 422 core_rejected.

Ejemplo:

"BOB"

amount
string
requerido

String decimal positivo. Monto en moneda local para métodos de corredor; para checkout se denomina en el settlement_asset ("50" USDT, "0.001" BTC, "2" gramos de oro). Los decimales se limitan por moneda (CLP no admite decimales, UF máximo dos); violarlo responde 422 core_rejected con el mensaje "amount has too many decimals for this currency". Los corredores UF están temporalmente deshabilitados en producción mientras se aprueban.

description
string
channel
string

Indicación opcional de canal que se pasa al core.

expires_in
integer

Expiración del cobro en segundos. Para method: "qr", envía segundos enteros; el servidor selecciona el riel QR configurado. El contrato QR legacy tiene un máximo efectivo de 86399 segundos, mientras el riel QR de 7 días tiene un máximo efectivo de 604800 segundos. Los valores sobre el máximo del riel se recortan, no se rechazan. Para checkout, acepta de 600 a 604800 (10 minutos a 7 días; default 24 horas).

method
enum<string>
predeterminado:qr

Modo de cobro. qr crea un cobro QR activo a través del procesador; bank_transfer anuncia un depósito entrante y devuelve la referencia a incluir en la descripción de la transferencia; fintoc (solo Chile) devuelve una payment_url hosted donde el pagador transfiere desde cualquier banco o billetera chilena y el depósito se detecta automáticamente; pix (solo Brasil) devuelve una payment_url hosted de un checkout redirect PIX (payer_name y payer_document obligatorios, mínimo 1 BRL); card devuelve una payment_url hosted de un checkout de tarjeta con 3-D Secure (Bolivia en BOB, tarjetas internacionales en USD cuando country es US, o tarjetas en Chile en CLP o UF); en la página de tarjeta de Chile el pagador puede dividir el cobro en 2-48 cuotas del emisor (el recibo muestra months; los pagos one-click con tarjeta guardada siempre son en una cuota); checkout devuelve una checkout_url pública donde el pagador elige el método de pago (QR, tarjeta, transferencia bancaria o crypto). Usa /v1/payins/collect para cobros pull.

Opciones disponibles:
qr,
bank_transfer,
fintoc,
card,
checkout,
wallet,
cash,
pix
idempotency_key
string

Para method: "card", esta clave es obligatoria: envíala en el body o como header Idempotency-Key. Es opcional para qr, bank_transfer, fintoc, pix y checkout. Un retry con la misma clave devuelve el payin original con HTTP 200 e idempotency_hit: true — la misma payment_url/checkout_url en los métodos hosted, o la MISMA reference en una transferencia anunciada — en vez de abrir un segundo cobro. En las transferencias anunciadas esto define si la plata se puede acreditar: dos anuncios vivos con el mismo monto y sin identidad del pagador son indistinguibles, así que el depósito que llegue quedaría unassigned. Si omites la clave igual colapsamos un retry idéntico (misma cuenta, moneda, monto y documento del pagador) en el anuncio original; manda una clave distinta cuando de verdad necesites dos cobros separados del mismo monto y pagador.

Maximum string length: 256
Pattern: ^[^\r\n]{1,256}$
customer
object

Prefill opcional de facturación para el checkout de tarjeta (método card). El pagador puede completarlo o corregirlo en la página.

success_url
string

URL https pública opcional (métodos card y checkout) a la que se redirige al pagador tras un pago aprobado.

failure_url
string

URL https pública opcional (métodos card y checkout) a la que se redirige al pagador cuando el pago falla o expira.

expires_at
string<date-time>

Expiración RFC3339 opcional de la sesión de pago con tarjeta (método card); mínimo 5 minutos hacia adelante, máximo 48 horas desde la creación; default 60 minutos.

settlement_asset
enum<string>

Solo checkout — el saldo virtual en que se denomina y liquida el cobro. Todo pago se convierte automático a este asset al acreditar (pagos en el mismo asset no convierten). Debe estar habilitado para tu organización (422 settlement_asset_disabled si no). Si se omite, se usa el asset de liquidación de payins de la cuenta (payin_settlement_asset, fallback USD). BOB, MXN, ARS, CLP y UF se rechazan (422 invalid_pair): el checkout no liquida en fiat.

Opciones disponibles:
USD,
USDT,
USDC,
BTC,
GOLD,
SILVER,
PLATINUM
save_card
boolean
predeterminado:false

Solo método card — ofrece al pagador el checkbox "guardar esta tarjeta" en la página hosted. La credencial se guarda SOLO si el pagador lo marca (consentimiento explícito) y el pago 3-D Secure se aprueba; el flujo payin_received/payin_credited lleva entonces un bloque stored_credential y la tarjeta aparece en GET /v1/stored-cards.

payer_reference
string

Solo método card — identificador propio en texto plano del pagador (máx 120 caracteres). Es la identidad preferida para reutilizar sesiones abiertas pending/challenge; si falta, se usa customer.email. También acota el discovery y los cobros de tarjetas guardadas dentro de la cuenta que llama; el mismo correo o referencia en otra cuenta no puede descubrir ni usar la credencial.

Maximum string length: 120
service_type
string

Override opcional de texto plano para el tipo de servicio del payin con tarjeta (MDD 90).

Maximum string length: 120
stored_card_id
string<uuid>

Solo método card — paga con una tarjeta guardada previamente (ver GET /v1/stored-cards). La página hosted salta la captura de tarjeta y muestra la guardada; el 3-D Secure corre igual. Mutuamente excluyente con save_card. Tarjeta desconocida, revocada o de otra cuenta responde 404. Los datos de facturación guardados con la credencial se aplican automáticamente en la página hosted (resumen enmascarado con enlace para editar — el pagador no re-tipea nada).

payer_name
string

Identidad del pagador. Obligatorio para pix (redirect hosted Brasil); en transferencia anunciada es el nombre opcional de la persona o empresa que hará la transferencia, cuando NO es el titular de la cuenta.

Maximum string length: 140
payer_document
string

Identidad del pagador. Obligatorio para qr en BR/BOB y para pix (redirect hosted Brasil); en transferencia anunciada es el documento tributario o de identidad opcional del pagador (al menos 5 caracteres, uno de ellos un dígito): si lo omites se usa el documento verificado del titular, así un depósito propio se reconoce aunque el pagador olvide la referencia. Envíalo cuando paga un tercero.

Maximum string length: 40
payer_phone
string

Teléfono del pagador hosted o collect; algunos métodos wallet lo exigen.

Maximum string length: 40
payer_email
string<email>

Email opcional del pagador para payins QR que admiten identidad, incluido BR/BOB.

Maximum string length: 120
payer_account
string

Solo transferencia anunciada — número de cuenta bancaria del pagador (al menos 5 caracteres). Opcional; es una señal extra de conciliación cuando el corredor informa la cuenta de origen.

Maximum string length: 40

Respuesta

Replay idempotente de un QR o anuncio de transferencia (bank_transfer) o reutilización de una sesión abierta de tarjeta (card). Los replays de QR y transferencias devuelven el payin original con idempotency_hit: true; la reutilización devuelve la payment_url existente y session_reused: true. No se crea un segundo charge ni una segunda sesión.

payin_id
string<uuid>
status
string
reference
string
payer_source
string
idempotency_hit
boolean