Crear cotización de promoción
Calcula el precio de un pago antes de crearlo. Devuelve una cotización firmada cuando se aplica una promoción, o una vista previa del precio de un código promocional.
Dos formas de llamarlo
- Clave secreta, desde tu servidor. Envía
amountyaccount_id, y nocheckout_session. Este es el flujo que se describe a continuación. - Clave pública, desde el navegador. Envía
checkout_sessionen lugar deamount; el monto proviene de la sesión. Yuno toma la cuenta de la sesión de checkout, por lo queaccount_ides opcional aquí, y un valor que envíes debe coincidir con la cuenta de la sesión.countryse sigue validando contra esa sesión. La sesión no debe haberse usado aún para pagar, debe tener como máximo 2 horas de antigüedad y debe pertenecer a tu organización.
payment_method es obligatorio en ambas. Una cotización es válida durante 30 minutos desde que se emite, en ambas. code es opcional en ambas: envíalo para calcular el precio de un código promocional. Consulta Calcular el precio de un código promocional.
Cómo usar la cotización
- Envía el contexto del pago que estás a punto de crear.
amountes el monto original, antes de cualquier promoción. Para una tarjeta, envía dentro depayment_methodsubin(los primeros 6 a 8 dígitos) o un token (tokenovaulted_token), nunca ambos. - Con
200, muestracharge_amounta tu cliente. Eso es lo que pagará. La respuesta incluyequote_id,promotions(una entrada por ahora:id,name,description,discount,discount_amount), los tres totales fuera de la lista (original_amount,discount_amount,charge_amount) yexpires_at. Elquote_ides largo, de unos 300 a 730 caracteres: guárdalo completo (hasta 1000 caracteres) y envíalo sin cambios. Una solicitud que lleva uncoderecibe en su lugar una vista previa, sinquote_idniexpires_at: consulta Calcular el precio de un código promocional. - Crea el pago con el mismo
amountoriginal yadditional_data.order.discounts: [{ "type": "YUNO_PROMOTION", "quote_id": "<quote_id>" }]. Consulta Crear pago y Promociones.
quote_id en una línea de descuento. Un pago sin él se cobra completo.
Reglas
- Gana el mayor ahorro. Cuando coinciden dos o más promociones, la cotización es para la que más ahorra al cliente, luego la más antigua, luego el
idmás pequeño. Una promoción por pago; no se acumulan. Uncodecompite en la misma selección. - 30 minutos. Una cotización es válida hasta
expires_at, 30 minutos después de emitirse. Dentro de ese tiempo el pago cobra el precio cotizado, aunque la fecha de fin de la promoción haya pasado después de emitirse la cotización, o hayas deshabilitado la promoción después de emitirse la cotización. - Todas las condiciones deben cumplirse ya. Una cotización existe solo cuando todas las condiciones de la promoción se cumplen para el contexto que envías.
- Precio cotizado o ningún pago. Si la cotización venció, o el monto, la moneda o la cuenta del pago difieren de lo que cotizaste, o el pago difiere en un detalle al que la cotización está ligada (el país, el método de pago, el tipo de tarjeta y el BIN de la tarjeta cuando las condiciones de la promoción los usan, y la sesión de checkout cuando la cotización se hizo con una), Yuno rechaza el pago con
422y uno de los códigosPROMOTION_*enumerados en Promociones. Nunca vuelve a calcular el precio. Obtén una cotización nueva y envía el reintento con unX-Idempotency-Keynuevo. - No se consume nada. Una cotización es una lectura. Preguntar de nuevo da el mismo precio;
expires_at, y por tanto elquote_id, cambian con el momento en que preguntas, así que no uses el id como clave. Una cotización que nunca usas no requiere limpieza, y una cotización puede respaldar varios pagos. - Que no haya coincidencia no es un error. La respuesta es
204cuando no se aplica nada. Crea el pago como de costumbre, sinquote_iden una línea de descuento. Un204también significa que las promociones no están habilitadas para tu organización o Yuno las deshabilitó temporalmente, que Yuno no pudo calcular el precio del pago a tiempo, o que una promoción automática dejaría el cobro en cero (una promoción nunca deja un cobro en cero; para un código, consulta Calcular el precio de un código promocional). Si la solicitud misma falla (408,5xx, sin respuesta), crea el pago como de costumbre también: una cotización nunca bloquea un pago. - BIN o token, nunca ambos, dentro de
payment_method. Un servidor que tiene el número de tarjeta envíapayment_method.bin, los primeros 6 a 8 dígitos. Un servidor que tiene un token envíapayment_method.tokenopayment_method.vaulted_token, y Yuno resuelve el BIN y el tipo de tarjeta a partir de la tarjeta, exactamente como lo hace en el pago. Cualquier combinación de dos entrebin,tokenyvaulted_tokense rechaza con400 INVALID_PARAMETERS, así que no copies elpayment_methodde una solicitud de Crear pago que lleva ambos tokens. Una promoción con una condiciónbinsnecesita el BIN, y una con una condicióncard_typesnecesita elcard_type(no el BIN); sin ellos no se aplica. Las billeteras (Apple Pay, Google Pay) no son un destino compatible en esta versión: no construyas aún sobre una cotización de billetera. - Envía el BIN, nunca el número de tarjeta.
payment_method.binson los primeros 6 a 8 dígitos de la tarjeta, solo dígitos. Menos de 6 dígitos, más de 8 (un prefijo de tarjeta más largo o el número completo de la tarjeta incluido), o cualquier cosa que no sean dígitos se rechaza con400 INVALID_PARAMETERS.
Calcular el precio de un código promocional
Una promoción que requiere un código se aplica solo cuando el pago lleva ese código. Para mostrar el descuento antes de que el cliente pague, envía el código encode junto con el resto del contexto:
quote_id ni expires_at.
- Una vista previa muestra el precio y nada más. Muestra
charge_amounta tu cliente. Yuno no firma, almacena ni cuenta nada. Una vista previa no se puede pagar: no hayquote_idque poner en una línea de descuento. El pago lleva el código mismo,additional_data.order.discounts: [{ "code": "SUMMER10" }]. Consulta Códigos promocionales. - El código tiene de 3 a 32 caracteres: letras, dígitos,
_y-. Yuno lo compara sin distinguir mayúsculas de minúsculas. Un código con otro carácter u otra longitud no encuentra ninguna promoción y responde404 PROMOTION_NOT_FOUND. payment_method.typesigue siendo obligatorio en este endpoint, igual que sin un código.- La vista previa no cuenta ningún uso del código. Yuno cuenta un uso cuando un pago lleva el código. Consulta Códigos promocionales.
- Un código que no se aplica se rechaza, no se muestra en vista previa. Responde
404o422, no204. La respuesta es404 PROMOTION_NOT_FOUNDcuando ninguna promoción de la cuenta tiene el código o la promoción que lo tiene no ha comenzado, y422 PROMOTION_NOT_APPLICABLEcon unreasoncuando la tiene y no se aplica:EXPIRED,DISABLED,USAGE_LIMIT_REACHED,CONDITIONS_NOT_MET,CURRENCY_MISMATCH,ZERO_DISCOUNToZERO_CHARGE. Códigos de error de promociones tiene el mensaje de cada uno. - Un código que deja un cobro en cero responde
ZERO_CHARGE. Cuando el código gana y el cobro sería cero o menos (un descuento del 100 %, o un descuento fijo igual o superior al monto), la respuesta es422 PROMOTION_NOT_APPLICABLEcon el motivoZERO_CHARGE, como en un pago. El motivo va antes queUSAGE_LIMIT_REACHED. - La vista previa puede ser de otra promoción. Cuando una promoción automática ahorra más al cliente que el código, la vista previa es de esa promoción, y
promotions[0].ides su id. Una promoción automática que dejaría un cobro en cero responde204. - Una solicitud sin
codeno cambia. Recibe una cotización firmada, conquote_idyexpires_at. Un pago que lleva un código se cotiza con suX-Idempotency-Key, y esa cotización se firma y cuenta un uso. Consulta Códigos promocionales.
Respuestas
Authorizations
Body
- Option 1
- Option 2
The country of the payment (MAX 2; MIN 2; ISO 3166-1).
Optional. A promotion code to price: 3 to 32 characters, A-Z, 0-9, _ and -, in any case. A code with another character or another length finds no promotion. This endpoint sends no idempotency key, so a request with a code gets a preview: the same amounts as a quote, with no quote_id and no expires_at. Yuno signs, stores and counts nothing: the code is applied when the payment carries it, and a preview can't be sent on a payment. When an automatic promotion saves the customer more than the code, the preview is for that promotion. A code that doesn't apply answers 404 or 422, not 204, and a code that leaves a charge of zero answers 422 with the reason ZERO_CHARGE. See Promotion codes.
Response
200
Opaque and long: about 300 to 730 characters. Store it whole, up to 1000 characters, and send it unchanged on the payment as quote_id on an additional_data.order.discounts line with type: YUNO_PROMOTION. Never parse or shorten it. Absent when the request carries a code: that answer is a preview, and a preview can't be paid.