SUMMER10 para “10% de descuento en verano”. Creas la promoción con la API, tu cliente te da el código y tu servidor envía el código en Create Payment. Yuno calcula el precio del pago con el código y cobra el monto con descuento.
Cómo funciona
- Crea la promoción. Llama a Create Promotion con
redemption.modedefinido comoCODE. Defines el descuento, las fechas, las condiciones y, si quieres un tope, el máximo de usos (limits.total). También envías exactamente una de dos cosas: un código propio (redemption.code) o un prefijo (redemption.prefix). Con un prefijo, Yuno construye el código a partir de él. - Recoge el código. Tu cliente te da el código en tu propio checkout.
- Envía el código en el pago. Agrega
{ "code": "SUMMER10" }aadditional_data.order.discountsen Create Payment, con elamountoriginal. - Yuno cobra el precio con descuento. Yuno cambia el código por una cotización, cuenta un uso del código cuando el código aplica y cobra el monto cotizado. La respuesta es la que se describe en What the payment carries.
Crea una promoción con código
Envía la promoción aPOST /v1/promotions. La promoción pertenece a la cuenta indicada en el encabezado X-Account-Code. Un cuerpo que lleva account_id se rechaza con 400 INVALID_PARAMETERS.
Request
Response (201)
X-Idempotency-Keyes obligatorio. Es cualquier texto de 1 a 64 caracteres. La misma clave en la misma cuenta devuelve la primera promoción con201, y Yuno no compara el cuerpo. Una solicitud sin una clave válida se rechaza con400antes de leer el cuerpo.- El modo es
CODE. Cualquier otroredemption.modese rechaza con400 INVALID_PARAMETERS. - Un código que envías tiene de 3 a 32 caracteres: letras, dígitos,
_y-, en mayúsculas o minúsculas. Yuno elimina los espacios alrededor, lo guarda en mayúsculas y compara el código de un pago sin distinguir mayúsculas de minúsculas. Un código con otra longitud se rechaza con400 INVALID_REQUESTy el mensajeredemption.code: CODE_LENGTH, y un código con otro carácter conredemption.code: CODE_CHARACTERS. - Un código es único por cuenta. Otra promoción de la cuenta que no esté deshabilitada y cuyo calendario se solape con este no puede tener el mismo código, y ningún código de lote de la cuenta puede tenerlo tampoco: la solicitud responde
409 CODE_ALREADY_EXISTS. Un código vuelve a estar libre cuando la promoción anterior se deshabilita, o cuando su calendario termina en el momento en que empieza el de la nueva, o antes. - Las condiciones son solo
countriesyamounts. Un código se aplica a todo el pago, sea cual sea el método de pago. Una condiciónbins,payment_methodsocard_typesse rechaza con400 INVALID_REQUESTy los mensajesconditions.bins: FORBIDDEN,conditions.payment_methods: FORBIDDENoconditions.card_types: FORBIDDEN. limits.totales opcional. Es el máximo de usos que acepta el código, un número entero de 1 a 2147483647. Sin él, el código no tiene tope y la respuesta muestralimits: null. Consulta Usos y límites.- Las promociones no se pueden editar y no hay eliminación. El único cambio es Disable Promotion, y es definitivo. Para cambiar un descuento, deshabilita la promoción y crea una nueva.
AUTOMATIC de la cuenta. The Promotion Object describe cada campo.
Deja que Yuno construya el código a partir de un prefijo
Envía exactamente uno deredemption.code y redemption.prefix. El prefijo tiene de 1 a 8 letras o dígitos (A-Z, a-z, 0-9), en mayúsculas o minúsculas, y Yuno lo convierte a mayúsculas. Yuno construye el código a partir de él: el prefijo, y luego un sufijo aleatorio de 5 caracteres tomados de ABCDEFGHJKMNPQRSTUVWXYZ23456789 (las letras y los dígitos sin 0, O, 1, I y L), sin nada entre ellos. El código no está vinculado al id de la promoción. La respuesta incluye el código en redemption.code, y Retrieve Promotion devuelve el mismo código. Esta solicitud envía un prefijo:
Request body, with a prefix
Response (201), with the code Yuno built
- Envía un código o un prefijo, no ambos y no ninguno. Un cuerpo sin ninguno responde
400 INVALID_REQUESTcon los mensajesredemption: CODE_OR_PREFIX_REQUIREDySend exactly one of redemption.code or redemption.prefix.. Un cuerpo con ambos responderedemption: CODE_AND_PREFIX_EXCLUSIVEcon el mismo segundo mensaje. Unnull, un texto vacío y un texto con solo espacios cuentan como no enviados. Uncodeque no es válido, enviado junto con un prefijo, cuenta como ambos. - Un prefijo incorrecto se rechaza. Un carácter fuera de
A-Z,a-zy0-9responderedemption.prefix: FORMAT. Más de 8 caracteres responderedemption.prefix: LENGTH. - Una creación con prefijo nunca responde
409 CODE_ALREADY_EXISTS. Esa respuesta es para un código que envías tú. Yuno nunca construye un código que otra promoción de tu cuenta tenga, sea cual sea su estado: activa, programada, terminada o deshabilitada, y ningún código de lote de tu cuenta lo tiene. Si el código que Yuno sortea está ocupado, Yuno sortea otro, hasta seis veces. Si ninguno de los seis está libre, la creación falla (consulta más abajo). - Una repetición devuelve el mismo código. La misma
X-Idempotency-Keyen la misma cuenta devuelve la primera promoción con201y el código que Yuno construyó para ella. La repetición conserva ese código y no guarda nada, también cuando su prefijo es distinto. - No puedes cambiar el código. Una promoción no se puede editar, así que su código no puede cambiar, ya sea que Yuno lo haya construido o que lo hayas enviado tú. Para obtener otro código, deshabilita la promoción y crea una nueva.
- Si Yuno no puede construir un código, la creación falla. La respuesta es
500 INTERNAL_ERROR, y Yuno no guarda nada. El fallo es del lado de Yuno: reintenta la solicitud.
Crea un lote de códigos
Un lote da a una promoción con código muchos códigos a la vez, por ejemplo un código para cada cliente de una campaña. Cada código del lote tiene su propio límite de usos, y la promoción conserva su límite total. Create Promotion Codes crea el lote, y List Promotion Codes lee los códigos de vuelta. La solicitud envía los encabezadosX-Account-Code y X-Idempotency-Key, ambos obligatorios, y un cuerpo con quantity y prefix:
Request body
quantityes obligatorio. Es el número de códigos del lote, un número entero de 1 a 1000. Un valor ausente respondequantity: REQUIRED, y un valor fuera de ese rango respondequantity: RANGE. Ambos son400 INVALID_REQUEST.prefixes obligatorio. Tiene de 1 a 8 letras o dígitos (A-Zy0-9), en mayúsculas o minúsculas, y Yuno lo convierte a mayúsculas. Un prefijo ausente o vacío respondeprefix: REQUIRED. Un carácter fuera deA-Zy0-9respondeprefix: FORMAT, y más de 8 caracteres respondenprefix: LENGTH.uses_per_codees opcional. Es cuántos pagos acepta cada código, un número entero de 1 a 1000000. Sin él, cada código acepta un pago. Un valor fuera de ese rango respondeuses_per_code: RANGE.- Un código completo se rechaza. Yuno hace cada código de un lote a partir del prefijo, así que un cuerpo con un
coderesponde400 INVALID_REQUESTconcode: NOT_ALLOWED.
ABCDEFGHJKMNPQRSTUVWXYZ23456789, las letras y los dígitos sin 0, O, 1, I y L. Su longitud depende de la cantidad de la solicitud: Yuno toma el sufijo más corto que tenga al menos un millón de valores posibles para cada código. Eso son 5 caracteres hasta 28 códigos, 6 caracteres de 29 a 887 códigos y 7 caracteres de 888 a 1000 códigos.
Response, 201
- La misma clave devuelve el mismo lote. Una
X-Idempotency-Keyrepetida en la misma promoción devuelve el primer lote con201, con los mismos códigos. Yuno no compara el cuerpo. - Cada código es único en la cuenta. Ningún código del lote es un código que tenga una promoción de tu cuenta, sea cual sea el estado de esa promoción, ni un código de otro lote. Un código que envías, y un código que Yuno construye a partir de un prefijo, tampoco pueden ser un código de lote.
- Una promoción admite hasta 10,000 códigos de lote. Un lote que llevaría a la promoción por encima de 10,000 códigos responde
422 PROMOTION_NOT_APPLICABLEcon el motivoBATCH_LIMIT_REACHED, y no guarda nada. - Solo una promoción con código admite un lote. Una promoción
AUTOMATICno tiene código, y responde422 PROMOTION_NOT_APPLICABLEcon el motivoNOT_CODE_PROMOTION. Una promoción deshabilitada respondeDISABLED, y una terminada respondeEXPIRED. - Mantén los códigos en secreto. Cada código funciona como una credencial. Los códigos vuelven solo en esta respuesta y en List Promotion Codes, y Yuno no los escribe en sus registros.
Lee los códigos
List Promotion Codes devuelve los códigos de una promoción, del más antiguo al más reciente.limit acepta de 1 a 500 y por defecto es 100, y next_cursor es null en la última página. Cada código muestra su uses_per_code y su conteo used. Una promoción deshabilitada también lista sus códigos.
Envía el código en el pago
Pon el código en una línea de descuento de Create Payment (POST /v1/payments). Envía el amount original, nunca el que tiene descuento.
Request
X-Idempotency-Key en la solicitud, como en todos los pagos.
La línea de descuento sigue estas reglas. Una línea que incumple una se rechaza con 400 INVALID_PARAMETERS antes de que ocurra cualquier otra cosa, y no se crea ningún pago.
Un código en una línea
MERCHANT se ignora. Yuno lee una línea como MERCHANT cuando su type es MERCHANT, o cuando no tiene type y lleva un id o un name. Yuno descarta el code de esa línea sin error: no se aplica ninguna promoción, y el pago sigue sin ese descuento. Para canjear un código, envíalo en una línea sin id, name ni unit_amount, y con type omitido o definido como YUNO_PROMOTION.
Ninguna respuesta repite tu código. Donde el servicio de promociones lo cita en un mensaje, Yuno lo reemplaza por ***.
Qué hace Yuno con el código
Yuno procesa la línea antes de crear el pago y antes de tokenizar la tarjeta:- Comprueba las reglas anteriores. Un incumplimiento es un
400. - Comprueba que Promotions esté habilitado para tu organización y que el pago pueda llevar un código. Consulta Pagos que no pueden llevar un código.
- Pide una cotización al servicio de promociones con tu cuenta, el
amountdel pago, elcountryy el código. Envía laX-Idempotency-Keyde tu pago, para que el servicio cuente un uso por pago. - Cuando el servicio da una cotización, Yuno reemplaza el código por la cotización en la línea de descuento, y el pago continúa como un pago con cotización. Yuno no envía el código junto con el pago.
- Cuando el servicio no da cotización, Yuno rechaza el pago, y la respuesta indica el motivo (consulta Respuestas). No se crea ningún pago. Yuno nunca cobra el precio completo por un pago cuya línea
YUNO_PROMOTIONlleva un código. Un código en una líneaMERCHANTse ignora (consulta la nota después de la tabla de reglas).
payment_method.typeno es obligatorio para un código. Un código se aplica a todo el pago, sea cual sea el método de pago. Yuno envía el tipo al servicio de promociones solo cuando tu pago lo tiene.- Un número de tarjeta o un token va a la cotización tal como lo lleva el pago. Yuno envía el BIN (como máximo los primeros 8 dígitos) de un número de tarjeta enviado en claro, nunca el número. Un token o un token del vault va tal cual.
- La
X-Idempotency-Keyes obligatoria. Create Payment la exige en cada pago: sin el encabezado la respuesta es400 INVALID_PARAMETERSyThe header 'x-idempotency-key' is required.Yuno también elimina los espacios de la clave antes de contar un uso, y una clave que queda vacía tras eliminarlos se rechaza con400 INVALID_PARAMETERS:The header 'x-idempotency-key' is required to apply a promotion code.
Dry run
Un dry run no acepta ningún código promocional. Un pago con el encabezadoX-Dry-Run: true que lleva un code en una línea YUNO_PROMOTION se rechaza con 400 INVALID_PARAMETERS, y no se crea ningún pago:
Dry run with a code (400)
true, en mayúsculas o minúsculas, hace un dry run. Un dry run sin código, o con una línea quote_id, no se ve afectado. Para probar un código promocional, usa el entorno sandbox.
Muestra el precio antes del pago
Para mostrar el precio con descuento antes de que tu cliente pague, llama a Create Promotion Quote con elcode. Ese endpoint no envía clave de idempotencia, así que la respuesta es una vista previa: la promoción, original_amount, discount_amount y charge_amount, sin quote_id y sin expires_at. Yuno no firma, guarda ni cuenta nada.
Una vista previa no se puede pagar: no hay un quote_id que poner en una línea de descuento. El pago lleva el propio código, como se describe en Envía el código en el pago.
Usos y límites
- Un uso se cuenta cuando Yuno acepta el código para un pago. El conteo ocurre en el intento de pago, antes de que el pago llegue a un proveedor, y se asocia a la
X-Idempotency-Keydel pago. - La misma clave de nuevo no cuenta un segundo uso. Un reintento de un pago con la misma clave y el mismo código se calcula a partir del primer uso. Esto se cumple incluso si la promoción se deshabilitó, terminó o alcanzó su límite después del primer intento.
- Una clave pertenece a un solo código. La misma clave con otro código se rechaza con
422 PROMOTION_NOT_APPLICABLEy el motivoIDEMPOTENCY_KEY_REUSED. - Un código que deja un cobro de cero no cuenta ningún uso. Cuando el código es la promoción que aplica y el pago se cobraría en cero o menos (un descuento del 100%, o un descuento fijo igual o superior al monto), Yuno rechaza el pago con
422 PROMOTION_NOT_APPLICABLEy el motivoZERO_CHARGEantes de contar un uso. Esto se cumple para un código con límite y para uno sin él. Un código en su límite que además deja un cobro de cero respondeZERO_CHARGE, noUSAGE_LIMIT_REACHED. - Un pago rechazado conserva su uso. Yuno no devuelve ningún uso. El conteo solo crece. Un nuevo intento tras un rechazo necesita una nueva
X-Idempotency-Key, y cuenta un nuevo uso. - El límite detiene el siguiente uso. Cuando
limits.usedes igual alimits.total, un pago con el código se rechaza con422 PROMOTION_NOT_APPLICABLEy el motivoUSAGE_LIMIT_REACHED. No se crea ningún pago. limits.usedcuenta los usos de un código que tiene límite. Un código sin límite muestralimits: null.- Solo la promoción que aplica cuenta un uso. Cuando una promoción automática da al cliente un descuento mayor que el código, esa promoción aplica y el código no cuenta ningún uso. Consulta Cuando un código y una promoción automática aplican a la vez.
- Un código de lote cuenta contra su propio límite y contra el límite total, en un solo paso. Un pago que usa un código de lote suma uno al conteo
useddel código y, cuando la promoción tienelimits.total, uno alimits.used. Ambos conteos ocurren o ninguno. Un código en su límite, o una promoción en su límite total, rechaza el pago con422 PROMOTION_NOT_APPLICABLEy el motivoUSAGE_LIMIT_REACHED. Consulta Crea un lote de códigos. - Una solicitud de cotización no cuenta ningún uso. Create Promotion Quote no envía clave, así que una cotización hecha con un
codees una vista previa: Yuno no firma, guarda ni cuenta nada. Un pago con un código cuenta el uso. - Una solicitud de cotización también responde
ZERO_CHARGE. Una solicitud de cotización para un código que gana y deja un cobro de cero recibe422 PROMOTION_NOT_APPLICABLEy el motivoZERO_CHARGE, igual que un pago. No cuenta nada, y el motivo también va antes deUSAGE_LIMIT_REACHEDallí. ZERO_CHARGEpertenece a un código que gana. Cuando una promoción automática gana la selección y su cotización cobraría cero, el pago no se rechaza conZERO_CHARGE: Yuno lo rechaza con422 PROMOTION_NOT_APPLICABLEy el motivoENGINE_UNAVAILABLE. No se crea ningún pago. Una solicitud de cotización en ese caso recibe204.
Cuando un código y una promoción automática aplican a la vez
Un pago recibe una promoción. Las promociones no se suman. Cuando un pago lleva un código, la promoción del código y las promociones automáticas de la cuenta que coinciden con el pago compiten en una sola selección. Gana la que más ahorra al cliente. Si dos ahorran lo mismo, gana la más antigua (elcreated_at más temprano); si también empatan, gana el id más pequeño. El código no tiene ventaja.
En este ejemplo el pago se cobra en USD 220. El código no cuenta ningún uso, y el pago no se rechaza.
Un código que falla se rechaza con su propio motivo, y ninguna promoción automática ocupa su lugar. Por ejemplo, un código que alcanzó su límite y habría ganado responde
USAGE_LIMIT_REACHED; Yuno no aplica en su lugar la promoción automática.
Una promoción automática que tiene una condición de método de pago compite solo cuando el pago lleva payment_method.type: sin él, el pago no tiene un método con el que cumplir la condición.
Pagos que no pueden llevar un código
Un código se aplica a pagos únicos enPOST /v1/payments. Estos pagos se rechazan, y no se crea ningún pago:
Yuno rechaza los tres antes de pedir la cotización, así que el rechazo no cuenta ningún uso. Estos cuerpos tienen un
code y messages, y no tienen reason.
Toda otra ruta que acepta additional_data.order.discounts rechaza una línea con código exactamente como rechaza una línea de cotización YUNO_PROMOTION: el mismo estado, el mismo code y los mismos mensajes. Esto abarca las sesiones de checkout, los enlaces de pago, las suscripciones, la captura y POST /v2/payments. Consulta What’s not included yet.
Respuestas
Cuando un código no se convierte en una cotización, no se crea ningún pago y la respuesta indica el motivo.ENGINE_UNAVAILABLE abarca dos causas, y la respuesta no dice cuál es. Ambas vuelven con el mismo reason y el mismo mensaje.
- Transitoria: reintenta más tarde. El servicio de promociones no respondió a tiempo, respondió con un error, o Yuno deshabilitó Promotions temporalmente. Reintenta el mismo pago más tarde.
- No transitoria: un reintento recibe la misma respuesta. Una promoción automática gana la selección para este pago y dejaría un cobro de cero. Envía el pago sin el código. Un pago sin código se cobra completo, y la comprobación de promociones no lo rechaza.
Try again. en ambas causas, así que no te indica cuál reintentar. Si el mismo pago sigue recibiendo ENGINE_UNAVAILABLE tras reintentar más tarde, envíalo sin el código. El cliente paga entonces el precio completo y pierde el descuento de ese código para ese pago.
Code that reached its limit (422)
Unknown code (404)
Code that leaves a charge of zero (422)