Promotions

​

How it works

1. Create the promotion. Use the Yuno Dashboard. You set the discount, the dates, and the conditions a payment must meet (card BIN or BIN range, card type, payment method, country, currency, minimum or maximum amount).
2. Get a quote. Before the payment, Yuno prices it: which promotion applies, the original amount, the discount, and the charge. The answer carries quote_id, promotions (one entry today, with id, name, description, discount and discount_amount), original_amount, discount_amount, charge_amount and expires_at. In the checkout page of a payment link this happens by itself. With the Web SDK, the SDK asks and hands the quote to your page. With a direct API integration, you call Create Promotion Quote.
3. Create the payment with the quote. Send the original amount and additional_data.order.discounts: [{ "type": "YUNO_PROMOTION", "quote_id": "qte_…" }] on Create Payment. Yuno charges the quoted total and returns the breakdown. The checkout page of a payment link adds the line by itself; with the Web SDK or the API, your server adds it.

​

Enable promotions for your organization

1. Ask your Technical Account Manager or Key Account Manager to enable Promotions for your organization. Start with sandbox.
2. Once it’s on, give the team members who work with promotions the Manage promotions permission (to create and disable them) and the View promotions permission (to see them), then create your promotions from the Dashboard. Each promotion belongs to one account_id, the account you have selected when you create it. If you run the same campaign on several accounts, create it once per account.
3. Test a payment in sandbox with a card that meets the conditions, then ask for production.

​

Create a promotion

• Promotions can’t be edited. The only change is to disable one, and that’s final. To change a discount, disable the promotion and create a new one. This keeps every past payment explainable.
• There’s no delete. A disabled or expired promotion stays in your list.
• The status follows the dates. SCHEDULED before starts_at, ACTIVE inside the window, EXPIRED after ends_at, and DISABLED once you disable it. Dates are UTC.
• All conditions must hold. AND across condition keys, OR inside each key’s values list. Omit a key for no condition on that dimension.
• Fixed discounts have a currency. A FIXED discount lists one amount per currency (each above zero). When you also set an amount condition, the two must list the same currencies, or Yuno rejects the promotion.

​

Promotion codes

​

When more than one promotion matches

​

What the customer sees at checkout

1. Shows the promotion’s name above the price rows.
2. Updates the order summary: the original price, the discount, and the new total. The pay button keeps saying “Pay”: the new total is in the summary.

​

Web SDK integration

1. Show the price. Pass onPromotionQuoteUpdated to startCheckout. It receives the promotion that applies to the payment method the customer has selected, and null when there is none: no promotion applies, the customer changed the card or the payment method, or the quote expired. The SDK then asks again and a new promotion follows if one applies, so null can arrive right before it. Show its computed.total (what the customer pays), computed.discount and name, and go back to the regular price on null. The Web SDK reference lists every field.
2. Send the quote on the payment. When the customer pays, your yunoCreatePayment callback receives tokenWithInformation. When a quote is live for that card, tokenWithInformation.quote holds the discount line, { "type": "YUNO_PROMOTION", "quote_id": "…" }. From your server, create the payment with the original amount and additional_data.order.discounts: [tokenWithInformation.quote], as shown below. Without the line the payment is charged in full.

​

Direct API integration

1. Get the quote. Send the payment context: account, country, and payment_method. For a card, send inside payment_method either its bin (the first 6 to 8 digits of the card) with card_type, or a token (token or vaulted_token) from which Yuno resolves the card. Never both: a bin together with a token, a bin together with a vaulted token, or a token together with a vaulted_token is rejected with 400 INVALID_PARAMETERS, and so is a bin with fewer than 6 digits, more than 8 (never send the full card number), or anything but digits. 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. A 6-digit BIN only matches conditions that cover its whole 6-digit block, so send 8 digits when a promotion lists 8-digit prefixes or narrow ranges. Wallets (Apple Pay, Google Pay) aren’t a supported target for this release (see below): don’t build on a wallet quote yet.
2. Show the price. On 200, show charge_amount to your customer. On 204, create the payment as usual, with no quote_id on a discount line. A 204 also means Yuno couldn’t price the payment in time, Promotions is temporarily disabled by Yuno, or the promotion would make the charge zero. If the request itself fails (408, 5xx or no answer), create the payment at the full price too: a payment never depends on a quote.
3. Create the payment with the quote. Send the original amount and additional_data.order.discounts: [{ "type": "YUNO_PROMOTION", "quote_id": "<quote_id>" }], as shown below.

​

Create the payment with the quote

{
    "account_id": "493e9374-510a-4201-9e09-de669d75f256",
    "country": "AR",
    "amount": { "currency": "USD", "value": 250.00 },
    "additional_data": {
        "order": {
            "discounts": [{ "type": "YUNO_PROMOTION", "quote_id": "qte_eyJ2IjoxLCJrIjoi…" }]
        }
    }
}

​

What the payment carries

{
    "id": "b2c9d0e1-6f0e-4c2a-9c55-7d8a0b311f2e",
    "status": "SUCCEEDED",
    "amount": { "currency": "USD", "value": 250.00 },
    "discount_amount": { "currency": "USD", "value": 25.00 },
    "additional_data": {
        "order": {
            "discounts": [
                {
                    "type": "YUNO_PROMOTION",
                    "quote_id": "qte_eyJ2IjoxLCJrIjoi…",
                    "id": "b7c1a4f2-6e0d-4a3b-9c55-1f2e7d8a0b31",
                    "name": "10% off with credit cards - Mother's Day",
                    "unit_amount": 25.00,
                    "discount_indicator": null,
                    "discount_rate": null
                },
                {
                    "type": "MERCHANT",
                    "id": "LOYALTY-5",
                    "name": "Loyalty 5%",
                    "unit_amount": 12.50,
                    "discount_indicator": null,
                    "discount_rate": null
                }
            ]
        }
    },
    "transactions": {
        "type": "PURCHASE",
        "amount": 225.00
    }
}

• amount − discount_amount = the transaction amount.
• discount_amount and the Yuno discount line describe the promotion attached when the payment was created, whatever the outcome: Retrieve Payment and the webhooks of a declined, canceled or refunded payment still show them (the cancel and refund answers carry only discount_amount), and refunds never shrink them. Use status, sub_status and the transaction to know whether the net was charged.
• A payment without a promotion is byte-for-byte today’s response.
• Every payment.* webhook carries the same discount_amount and the same filled discount line.

​

Refunds, captures and cancellations

• Refund. Leave amount empty to refund what the customer paid and hasn’t been refunded yet (225.00). A refund above that is rejected with 400 INVALID_PARAMETERS. The payment reaches REFUNDED when the net is refunded, so amount.refunded then equals 225.00, not amount.value; before that its sub_status is PARTIALLY_REFUNDED.
• Capture. Leave amount empty to capture what was authorized (the net). amount.captured becomes 225.00 and the sub_status CAPTURED; a smaller amount leaves it PARTIALLY_CAPTURED.
• Cancel. Voids the authorization for the net; the payment keeps its discount_amount.
• Everything that reads the amount uses the net: routing rules, fraud, 3D Secure and receipts. A split payment can’t allocate more than the net (400). Installments aren’t a supported combination for this release (see below).

​

The customer pays the quoted price, or the payment is rejected

​

What’s not included yet

• Subscriptions and recurring payments. Promotions apply to one-time payments; a payment that carries a subscription or an external_subscription is rejected with PROMOTION_SUBSCRIPTION_UNSUPPORTED, and the checkout page of a subscription payment link shows no promotion and charges the regular price.
• Other payment routes. The quote line is accepted on Create Payment only, not on multi-method payments, payment links or checkout sessions created through the API, or capture. A payment link opened in its checkout page is discounted when the customer pays.
• Currency conversion. A promotion is priced in the payment’s own currency and Yuno doesn’t convert a promoted payment. A payment with a Yuno promotion and a currency conversion is rejected with 422 PROMOTION_CONTEXT_MISMATCH: set your price in each currency and send the payment without the conversion.
• Seamless. The SDK creates the payment itself, so no promotion is asked or applied.
• Payment methods. This release is for cards only. PSE, bank transfers, cash and voucher methods, and other alternative payment methods aren’t a supported target: don’t configure a promotion’s conditions for one, and don’t ask for a quote on a payment that uses one.
• Wallets. Apple Pay and Google Pay aren’t a supported target for this release. Don’t configure a promotion for a wallet payment method, and don’t build on the Web SDK’s external buttons asking for a quote. Yuno doesn’t block this today: a card promotion still applies to a wallet payment that reaches Yuno typed as a card, so it’s quoted and discounted like any other card payment.
• Installments. Paying a promoted amount in installments isn’t supported for this release, and Yuno doesn’t block it today either: a promoted payment sent with installments gets the discount, but the installment plan shown to the customer is computed on the original, non-discounted amount.
• Combining promotions. One promotion per payment.
• Usage limits and caps. A promotion has no redemption limit, and a quote isn’t consumed either.
• Editing a promotion. Disable and create a new one.
• Promotion codes. Every promotion applies automatically; the quote’s code field is reserved for codes.
• Coupons.