Create Promotion Quote

​

Two ways to call it

• Secret key, from your server. Send amount and account_id, and no checkout_session. This is the flow described below.
• Public key, from the browser. Send checkout_session instead of amount; the amount comes from the session. Yuno takes the account from the checkout session, so account_id is optional here, and a value you send must match the session’s account. country is 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.

{
    "account_id": "493e9374-510a-4201-9e09-de669d75f256",
    "amount": { "currency": "USD", "value": 250.00 },
    "country": "AR",
    "payment_method": { "type": "CARD", "bin": "457896", "card_type": "CREDIT" }
}

{
    "checkout_session": "3f0c2b1e-7d5a-4b1c-9e2f-8a6d4c1b0e77",
    "country": "AR",
    "payment_method": { "type": "CARD", "bin": "457896", "card_type": "CREDIT" }
}

​

How to use the quote

1. Send the context of the payment you’re about to create. amount is the original amount, before any promotion. For a card, send inside payment_method either its bin (the first 6 to 8 digits) or a token (token or vaulted_token), never both.
2. On 200, show charge_amount to your customer. That’s what they’ll pay. The answer includes quote_id, promotions (one entry today: id, name, description, discount, discount_amount), the three totals outside the list (original_amount, discount_amount, charge_amount) and expires_at. The quote_id is long, about 300 to 730 characters: store it whole (up to 1000 characters) and send it unchanged.
3. Create the payment with the same original amount and additional_data.order.discounts: [{ "type": "YUNO_PROMOTION", "quote_id": "<quote_id>" }]. See Create Payment and Promotions.

​

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.
• 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 422 and one of the PROMOTION_* codes listed in Promotions. It never re-prices. Get a new quote, and send the retry with a new X-Idempotency-Key.
• Nothing is consumed. A quote is a read. Asking again gives the same price; the expires_at, and so the quote_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 204 when nothing applies. Create the payment as usual, with no quote_id on a discount line. A 204 also means Promotions is not enabled for your organization or is temporarily disabled by Yuno, Yuno could not price the payment in time, or the promotion would make the charge zero (a promotion never makes a charge of zero). 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 sends payment_method.bin, the first 6 to 8 digits. A server that holds a token sends payment_method.token or payment_method.vaulted_token, and Yuno resolves the BIN and the card type from the card, exactly as it does on the payment. Any two of bin, token and vaulted_token together are rejected with 400 INVALID_PARAMETERS, so don’t copy the payment_method of a Create Payment request that carries both tokens. A promotion with a bins condition needs the BIN, and one with a card_types condition needs the card_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.bin is 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 with 400 INVALID_PARAMETERS.
• Promotion codes aren’t available yet. The Dashboard creates promotions that apply automatically, and no promotion can require a code today. code is reserved for them: leave it out. A quote that carries a code finds no promotion.

​

Answers