Skip to main content
POST
Promotions is enabled per organizationUntil Yuno enables Promotions for your organization, this endpoint answers 204 (nothing applies). Ask your Technical Account Manager or Key Account Manager. See Promotions.
Using a payment link or the Web SDK? You don’t call this endpointThe checkout page of a payment link asks for the quote by itself as soon as it has identified the card from the first digits the customer types, and updates the price and the discount in its order summary. The Web SDK asks by itself too, with your public key, and hands the quote to your page. Call this endpoint from a direct API integration: from your server with your secret key, or from the browser with your public key. See Promotions.

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.
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.
Secret key (server)
Public key (browser)

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. A request that carries a code gets a preview instead, with no quote_id and no expires_at: see Price a promotion code.
  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.
A promotion applies only when the payment carries that 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. A code competes 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 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 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 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.

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 in code with the rest of the context:
Code (server)
This endpoint sends no idempotency key, so the answer is a preview: the same amounts as a quote, with no quote_id and no expires_at.
Preview (200)
  • A preview shows the price and nothing more. Show charge_amount to your customer. Yuno signs, stores and counts nothing. A preview can’t be paid: there is no quote_id to 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 answers 404 PROMOTION_NOT_FOUND.
  • payment_method.type is 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 404 or 422, not 204. The answer is 404 PROMOTION_NOT_FOUND when no promotion of the account holds the code or the promotion holding it has not started, and 422 PROMOTION_NOT_APPLICABLE with a reason when it holds the code and doesn’t apply: EXPIRED, DISABLED, USAGE_LIMIT_REACHED, CONDITIONS_NOT_MET, CURRENCY_MISMATCH, ZERO_DISCOUNT or ZERO_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 is 422 PROMOTION_NOT_APPLICABLE with the reason ZERO_CHARGE, as on a payment. The reason comes before USAGE_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].id is its id. An automatic promotion that would leave a charge of zero answers 204.
  • A request without a code is unchanged. It gets a signed quote, with quote_id and expires_at. A payment that carries a code is quoted with its X-Idempotency-Key, and that quote is signed and counts a use. See Promotion codes.
Code that leaves a charge of zero (422)

Answers

Authorizations

public-api-key
string
header
default:<Your public-api-key>
required
private-secret-key
string
header
default:<Your private-secret-key>
required

Body

application/json
account_id
string
required

The account that will create the payment (UUID). Required with the secret key. With the public key and checkout_session, it's optional: Yuno takes the account from the checkout session, and a value you send must match it.

amount
object
required

The original amount of the payment, before any promotion. It must be the same amount you later send on the payment. Secret key only: send this, not checkout_session.

country
string
required

The country of the payment (MAX 2; MIN 2; ISO 3166-1).

payment_method
object
required

The payment method of the payment you are about to create. For a card, identify it in ONE of three ways: send bin, or token, or vaulted_token. Any two of them together are rejected with 400 INVALID_PARAMETERS.

checkout_session
string

Checkout session id (UUID v4). Use it with the public key instead of amount; the amount comes from the session. The session must not have been used to pay yet, be at most 2 hours old, and belong to your organization. Never send it with the secret key.

code
string

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

promotions
object[]
required

The promotions that apply. One entry in this release; a later release may return more than one. The outer discount_amount is the sum of each entry's discount_amount.

Minimum array length: 1
original_amount
object
required

The amount you sent, before the discount.

discount_amount
object
required

Total discount (sum of promotions[].discount_amount). Always positive.

charge_amount
object
required

What the customer pays: original minus discount.

quote_id
string

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.

expires_at
string<date-time>

The quote is valid until this instant: 30 minutes after it was issued. Absent from a preview (a request that carries a code).