Saltar al contenido principal
POST
Esta solicitud crea un pago. Se necesita una sesión de checkout cuando el workflow es SDK_CHECKOUT (el predeterminado), así que créala primero. No se necesita para los workflows DIRECT o REDIRECT.
ImportanteAunque algunos objetos no son obligatorios al crear un pago, la experiencia de pago del usuario puede mejorar si envías esta información.
Pagos con 3DSConsulta la página 3D Secure para saber cómo crear pagos con 3DS en Yuno.
PromocionesPara cobrar el precio de una promoción, envía el amount original y una línea de descuento en additional_data.order.discounts con type: YUNO_PROMOTION y el quote_id de una cotización de promoción. Yuno cobra el precio con descuento, mantiene el amount tal como lo enviaste y devuelve discount_amount. Consulta Promociones. El ejemplo de cotización de promoción necesita que Promotions esté habilitado para tu organización: hasta que Yuno lo habilite, Create Promotion Quote responde 204 y no existe ningún quote_id.
Para autorizar un pago sin capturarlo de inmediato (no se le cobra al cliente), envía capture: false dentro del detalle del método de pago, en el objeto que corresponde al tipo de método de pago: payment_method.detail.card.capture para tarjetas y payment_method.detail.wallet.capture para billeteras que admiten autorización (por ejemplo, PayPal con un billing agreement guardado en vault). Yuno solo lee el indicador en el objeto que corresponde al tipo de método de pago, así que capture: false dentro de card se ignora en un pago con billetera y el pago se captura de inmediato. Si quieres procesar pagos en un solo paso (autorización y captura al mismo tiempo), envía capture como true en ese mismo objeto. Para probar en Sandbox todos los resultados posibles de una transacción en Yuno, consulta la documentación de datos de prueba.
Metadata y lógica de enrutamientoLas reglas de enrutamiento leen la metadata del pago, combinada con la metadata de su cliente. Si usas metadata para definir la lógica de enrutamiento, defínela en el pago o en el cliente. La metadata que se define solo en la sesión de checkout no llega al enrutamiento del pago. La metadata de la sesión de checkout solo decide qué métodos de pago y qué cuotas muestra la sesión cuando una regla de enrutamiento tiene una condición de metadata, así que define la misma metadata en ambos si necesitas las dos cosas.
vaulted_token reemplaza el fingerprint del dispositivoSi envías payment_method.vaulted_token junto con payment_method.token, el vaulted_token reemplaza todos los datos de pago, incluido el fingerprint del dispositivo (third_party_session_id). Si necesitas un análisis antifraude con el fingerprint del dispositivo, no envíes los dos campos juntos.
Para pagos en dos pasos (autorización y luego captura), envía capture como false como se describe arriba, y luego usa el endpoint Capture Authorization. Esta solicitud requiere un X-Idempotency-Key. Consulta Autenticación para más detalles.

Autorizaciones

public-api-key
string
header
predeterminado:<Your public-api-key>
requerido
private-secret-key
string
header
predeterminado:<Your private-secret-key>
requerido

Encabezados

X-Idempotency-Key
string
requerido

Identificador único que se usa en los encabezados HTTP para garantizar que una solicitud se procese una sola vez, aunque se reintente por problemas de red o timeouts.

Cuerpo

application/json
account_id
string
predeterminado:{{account_id}}
requerido

El identificador único de la cuenta. Encuentras este dato en el dashboard de Yuno (UUID, 36 caracteres).

merchant_order_id
string
predeterminado:""
requerido

El identificador único del pedido del cliente (MAX 255; MIN 3).

description
string
requerido

La descripción del pago (MAX 255; MIN 3).

amount
object
requerido

Indica el objeto del monto del pago, con el valor y la moneda.

country
enum<string>
requerido

País donde se debe procesar la transacción (MAX 2; MIN 2; ISO 3166-1).

Opciones disponibles:
AR,
BO,
BR,
CL,
CO,
CR,
EC,
SV,
GT,
HN,
MX,
NI,
PA,
PY,
PE,
US,
UY
payment_method
object
requerido

El objeto del método de pago.

taxes
object

Indica el objeto de impuestos del pedido.

checkout
object

Indica el objeto checkout. Este objeto no es obligatorio en pagos directos. Es obligatorio cuando workflow se define como SDK_CHECKOUT o no se envía. No es obligatorio en pagos DIRECT o REDIRECT.

additional_data
object

Indica el objeto additional_data. Este objeto no es obligatorio. Sin embargo, si envías esta información, la experiencia de pago de tu usuario mejora.

merchant_reference
string

Identificación de la transacción de pago definida por el comercio (MAX 255; MIN 3). Opcional, complementa el merchant_order_id.

response_additional_data
object

Controla los datos adicionales que se devuelven en la respuesta del pago y en los webhooks del pago.

customer_payer
object

Indica el objeto customer de los pagos.

workflow
enum<string>
predeterminado:SDK_CHECKOUT

El workflow del pago. Indica si la integración usa el SDK de Yuno o es una conexión directa. Guías

  • SDK_CHECKOUT: [Recomendado] Usa el SDK de Yuno.
  • DIRECT: integración directa con la información del proveedor, para una experiencia de pago personalizada.
  • REDIRECT: integración directa con redirección al proveedor.

Opciones disponibles:
SDK_CHECKOUT,
CHECKOUT,
REDIRECT,
DIRECT,
SDK_SEAMLESS
external_subscription
object

Vincula este pago a una suscripción gestionada en una plataforma de facturación externa. Si está presente en un pago aprobado con una tarjeta guardada en vault, Yuno se hace cargo de los cobros recurrentes de la suscripción. No se puede enviar junto con el objeto subscription (devuelve INVALID_REQUEST). El objeto se devuelve en la respuesta del pago, en Retrieve Payment y en los webhooks del pago.

external_invoice
object

Vincula este pago a una factura de una plataforma de facturación externa, para que un pago que cobras con Yuno pague esa factura (por ejemplo, una recarga de saldo). Yuno revisa la factura antes de cobrar. Cuando el pago se aprueba, Yuno lo informa en la factura; cuando se rechaza, Yuno registra un intento fallido y la factura sigue abierta. En las facturas puntuales se acepta un monto menor que el saldo pendiente; las facturas de suscripciones que Stripe cobra automáticamente necesitan el monto exacto. No se puede enviar junto con external_subscription ni subscription (devuelve INVALID_REQUEST). El objeto se devuelve en la respuesta del pago, en Retrieve Payment y en los webhooks del pago. Consulta Pay a Stripe invoice (top-ups) para ver las reglas de montos y los códigos de error.

subscription
object

Indica el objeto subscription. Envía exactamente una de tres formas: condiciones en línea (frequency, availability y amount) para crear una suscripción, plan_id para crearla a partir de un plan, o id para cobrar una suscripción existente. Consulta Start a subscription with the first payment.

callback_url
string

La URL a la que se redirige al cliente después del pago. Solo es obligatoria en integraciones DIRECT que tienen una redirección (MAX 526; MIN 3).

fraud_screening
object

Objeto de análisis antifraude.

split_marketplace
object[]

Array de objetos de split marketplace

metadata
object[]

Etiquetas personalizadas de clave y valor para seguir este pago o agregarle contexto (por ejemplo, order_id, invoice, campaign). Hasta 120 elementos.

Respuesta

201

id
string
Ejemplo:

"6c44ed29-cc51-4479-a5eb-108afdaadd50"

account_id
string
Ejemplo:

"493e9374-510a-4201-9e09-de669d75f256"

description
string
Ejemplo:

"Test Payment"

country
string
Ejemplo:

"US"

status
string
Ejemplo:

"SUCCEEDED"

sub_status
string
Ejemplo:

"APPROVED"

merchant_order_id
string
Ejemplo:

"1744403449"

created_at
string
Ejemplo:

"2025-04-11T20:30:49.825637Z"

updated_at
string
Ejemplo:

"2025-04-11T20:30:51.953868Z"

amount
object
discount_amount
object

El descuento total de la promoción de Yuno aplicada al pago: la suma de las líneas YUNO_PROMOTION de additional_data.order.discounts. No aparece cuando no se aplicó ninguna promoción. El monto cobrado es amount.value menos este valor, y está en transactions.amount. Consulta Promociones.

checkout
object
payment_method
object
customer_payer
object
additional_data
object
transactions
object
transactions_history
object[]
callback_url
string
Ejemplo:

"http://www.google.com/?checkoutSession=7fb7093e-dc67-4c7a-80c5-d25cf5e6ff27"

workflow
string
Ejemplo:

"SDK_CHECKOUT"

metadata
object[]
fraud_screening
any
Ejemplo:

""

subscription_code
string<uuid> | null

Identificador de la suscripción que este pago creó o cobró. Es null cuando el pago no incluye una suscripción.

plan_id
string

El plan de la suscripción en el momento en que se creó este pago. Aparece solo en los pagos creados con subscription.plan_id y en sus renovaciones; en los demás casos no aparece.

plan_assigned_at
string<date-time>

Momento en que se asignó el plan a la suscripción (UTC, ISO 8601). Aparece solo en los pagos que incluyen plan_id.

routing_rules
object
simplified_mode
boolean
predeterminado:true
Ejemplo:

false

external_subscription
object

La suscripción de una plataforma de facturación externa a la que pertenece este pago, tal como se envió al crear el pago. La clave aparece en la respuesta solo cuando el pago incluyó external_subscription.

external_invoice
object

La factura de una plataforma de facturación externa que paga este pago (una recarga), tal como se envió al crear el pago. La clave aparece en la respuesta solo cuando el pago incluyó external_invoice. Consulta Pay a Stripe invoice (top-ups).

shipping
any | null

Envío.