Create Promotion Quote
Prices a payment before you create it. Returns a signed quote when a promotion applies, or a preview of the price of a promotion code.
Two ways to call it
- Secret key, from your server. Send
amountandaccount_id, and nocheckout_session. This is the flow described below. - Public key, from the browser. Send
checkout_sessioninstead ofamount; the amount comes from the session. Yuno takes the account from the checkout session, soaccount_idis optional here, and a value you send must match the session’s account.countryis still validated against that session. The session must not have been used to pay yet, be at most 2 hours old, and belong to your organization.
payment_method is required on both. A quote is valid for 30 minutes after it is issued, on both. code is optional on both: send it to price a promotion code. See Price a promotion code.
How to use the quote
- Send the context of the payment you’re about to create.
amountis the original amount, before any promotion. For a card, send insidepayment_methodeither itsbin(the first 6 to 8 digits) or a token (tokenorvaulted_token), never both. - On
200, showcharge_amountto your customer. That’s what they’ll pay. The answer includesquote_id,promotions(one entry today:id,name,description,discount,discount_amount), the three totals outside the list (original_amount,discount_amount,charge_amount) andexpires_at. Thequote_idis long, about 300 to 730 characters: store it whole (up to 1000 characters) and send it unchanged. A request that carries acodegets a preview instead, with noquote_idand noexpires_at: see Price a promotion code. - Create the payment with the same original
amountandadditional_data.order.discounts: [{ "type": "YUNO_PROMOTION", "quote_id": "<quote_id>" }]. See Create Payment and Promotions.
quote_id on a discount line. A payment without one is charged in full.
Rules
- Biggest saving wins. When two or more promotions match, the quote is for the one that saves the customer the most, then the oldest, then the smallest
id. One promotion per payment; no stacking. Acodecompetes in the same selection. - 30 minutes. A quote is valid until
expires_at, 30 minutes after it is issued. Inside that time the payment charges the quoted price, even if the promotion’s end date passed after the quote was issued, or you disabled the promotion after the quote was issued. - Every condition must already be true. A quote exists only when the promotion’s conditions all hold for the context you send.
- Quoted price or no payment. If the quote expired, or the payment’s amount, currency or account differs from what you quoted, or the payment differs in a detail the quote is bound to (the country, payment method, card type and card BIN when the promotion’s conditions use them, and the checkout session when the quote was made with one), Yuno rejects the payment with
422and one of thePROMOTION_*codes listed in Promotions. It never re-prices. Get a new quote, and send the retry with a newX-Idempotency-Key. - Nothing is consumed. A quote is a read. Asking again gives the same price; the
expires_at, and so thequote_id, move with the time you ask, so don’t use the id as a key. A quote you never use needs no cleanup, and one quote can back several payments. - No match isn’t an error. The answer is
204when nothing applies. Create the payment as usual, with noquote_idon a discount line. A204also means Promotions is not enabled for your organization or is temporarily disabled by Yuno, Yuno could not price the payment in time, or an automatic promotion would make the charge zero (a promotion never makes a charge of zero; for a code, see Price a promotion code). If the request itself fails (408,5xx, no answer), create the payment as usual too: a quote never blocks a payment. - BIN or token, never both, inside
payment_method. A server that holds the card number sendspayment_method.bin, the first 6 to 8 digits. A server that holds a token sendspayment_method.tokenorpayment_method.vaulted_token, and Yuno resolves the BIN and the card type from the card, exactly as it does on the payment. Any two ofbin,tokenandvaulted_tokentogether are rejected with400 INVALID_PARAMETERS, so don’t copy thepayment_methodof a Create Payment request that carries both tokens. A promotion with abinscondition needs the BIN, and one with acard_typescondition needs thecard_type(not the BIN); without them it doesn’t apply. Wallets (Apple Pay, Google Pay) aren’t a supported target for this release: don’t build on a wallet quote yet. - Send the BIN, never the card number.
payment_method.binis the first 6 to 8 digits of the card, digits only. Fewer than 6 digits, more than 8 (a longer card prefix or the full card number included), or anything but digits is rejected with400 INVALID_PARAMETERS.
Price a promotion code
A promotion that requires a code applies only when the payment carries that code. To show the discount before the customer pays, send the code incode with the rest of the context:
quote_id and no expires_at.
- A preview shows the price and nothing more. Show
charge_amountto your customer. Yuno signs, stores and counts nothing. A preview can’t be paid: there is noquote_idto put on a discount line. The payment carries the code itself,additional_data.order.discounts: [{ "code": "SUMMER10" }]. See Promotion codes. - The code has 3 to 32 characters: letters, digits,
_and-. Yuno matches it without regard to case. A code with another character or another length finds no promotion and answers404 PROMOTION_NOT_FOUND. payment_method.typeis still required on this endpoint, as without a code.- The preview counts no use of the code. Yuno counts a use when a payment carries the code. See Promotion codes.
- A code that doesn’t apply is refused, not previewed. It answers
404or422, not204. The answer is404 PROMOTION_NOT_FOUNDwhen no promotion of the account holds the code or the promotion holding it has not started, and422 PROMOTION_NOT_APPLICABLEwith areasonwhen it holds the code and doesn’t apply:EXPIRED,DISABLED,USAGE_LIMIT_REACHED,CONDITIONS_NOT_MET,CURRENCY_MISMATCH,ZERO_DISCOUNTorZERO_CHARGE. Promotion Error Codes has the message of each. - A code that leaves a charge of zero answers
ZERO_CHARGE. When the code wins and the charge would be zero or less (a 100% discount, or a fixed discount at or above the amount), the answer is422 PROMOTION_NOT_APPLICABLEwith the reasonZERO_CHARGE, as on a payment. The reason comes beforeUSAGE_LIMIT_REACHED. - The preview can be for another promotion. When an automatic promotion saves the customer more than the code, the preview is for that promotion, and
promotions[0].idis its id. An automatic promotion that would leave a charge of zero answers204. - A request without a
codeis unchanged. It gets a signed quote, withquote_idandexpires_at. A payment that carries a code is quoted with itsX-Idempotency-Key, and that quote is signed and counts a use. See Promotion codes.
Answers
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.