Create Payment
Create a payment with Yuno. Supports various payment methods, card vaulting, and 3DS configurations.
SDK_CHECKOUT (the default), so create it first. It is not needed for the DIRECT or REDIRECT workflows.
amount and a discount line in additional_data.order.discounts with type: YUNO_PROMOTION and the quote_id of a promotion quote. Yuno charges the discounted price, keeps amount as you sent it, and returns discount_amount. To redeem a promotion code instead of a quote, send { "code": "<code>" } on the discount line. A dry run takes no code (see Dry run). See Promotion codes and Promotions. The promotion quote example needs Promotions enabled for your organization: until Yuno enables it, Create Promotion Quote answers 204 and no quote_id exists.capture: false inside the payment method detail, under the object that matches the payment method type: payment_method.detail.card.capture for cards and payment_method.detail.wallet.capture for wallets that support authorization (for example PayPal with a vaulted billing agreement). Yuno only reads the flag under the object that matches the payment method type, so capture: false under card is ignored on a wallet payment and the payment is captured right away.
If you want to process payments in a Single Step (Authorization and Capture simultaneously), send capture as true under that same object.
To test all possible transaction outcomes within Yuno in Sandbox, refer to the test data documentation.
For Two-Step payments (Authorization then Capture), send capture as false as described above, then use the Capture Authorization endpoint.
This request requires an X-Idempotency-Key. See Authentication for details.
Promotion codes
422 PROMOTION_NOT_APPLICABLE and the reason PROMOTIONS_NOT_ENABLED, and no payment is created. See Promotions.additional_data.order.discounts instead of a quote_id. Send the original amount, never the discounted one.
400 INVALID_PARAMETERS before anything else happens, and no payment is created.
MERCHANT line is ignored. Yuno reads a line as MERCHANT when its type is MERCHANT, or when it has no type and carries an id or a name. Yuno drops the code of such a line without an error: no promotion is applied, and the payment goes on without that discount. To redeem a code, send it on a line with no id, name or unit_amount, and with type left out or set to YUNO_PROMOTION.
No answer repeats your code. Where the promotions service quotes it back in a message, Yuno replaces it with ***.
payment_method.type is not required for a code. A code applies to the whole payment, whatever the payment method. Yuno sends the type to the promotions service only when your payment has one.
Idempotency key and uses
- The
X-Idempotency-Keyis required. Create Payment requires it on every payment: without the header the answer is400 INVALID_PARAMETERSandThe header 'x-idempotency-key' is required.Yuno also trims the key before it counts a use, and a key that is empty after the trim is refused with400 INVALID_PARAMETERS:The header 'x-idempotency-key' is required to apply a promotion code. - A use is counted when Yuno accepts the code for a payment. The count happens at the payment attempt, before the payment reaches a provider, and it is keyed by the
X-Idempotency-Keyof the payment. - The same key again counts no second use. A retry of a payment with the same key and the same code is priced from the first use.
- A key belongs to one code. The same key with another code is refused with
422 PROMOTION_NOT_APPLICABLEand the reasonIDEMPOTENCY_KEY_REUSED. - A declined payment keeps its use. Yuno gives no use back. A new attempt after a decline needs a new
X-Idempotency-Key, and it counts a new use.
Dry run
A dry run takes no promotion code. A payment with the headerX-Dry-Run: true that carries a code on a YUNO_PROMOTION line is refused with 400 INVALID_PARAMETERS, and no payment is created:
true, in any case, makes a dry run. A dry run without a code, or with a quote_id line, is not affected. To try a promotion code, use the sandbox environment.
Answers to a payment with a code
When a code does not become a quote, no payment is created and the answer says why.ENGINE_UNAVAILABLE covers two causes, and the answer does not say which one it is. Both come back with the same reason and the same message.
- Transient: retry later. The promotions service did not answer in time, answered with an error, or Promotions is temporarily disabled by Yuno. Retry the same payment later.
- Not transient: a retry gets the same answer. An automatic promotion wins the selection for this payment and would leave a charge of zero. Send the payment without the code. A payment with no code is charged in full, and the promotion check does not refuse it.
Try again. for both causes, so it does not tell you which one to retry. If the same payment still gets ENGINE_UNAVAILABLE after you retry later, send it without the code. The customer then pays the full price and loses the discount of that code for that payment.
ZERO_CHARGE belongs to a code that wins. When an automatic promotion wins the selection and its quote would charge zero, the payment is not refused with ZERO_CHARGE: Yuno refuses it with 422 PROMOTION_NOT_APPLICABLE and the reason ENGINE_UNAVAILABLE, and no payment is created. That is the not-transient cause of ENGINE_UNAVAILABLE above: send the payment without the code.
A code is refused for these payments too, and no payment is created:
Authorizations
Headers
Body
The unique identifier of the account. You find this information on the Yuno dashboard (UUID, 36 chars).
Country where the transaction must be processed (MAX 2; MIN 2; ISO 3166-1).
AR, BO, BR, CL, CO, CR, EC, SV, GT, HN, MX, NI, PA, PY, PE, US, UY The payment workflow. Indicates whether the integration will use Yuno´s SDK or will be a back to back connection. Guides
SDK_CHECKOUT: [Recommended] - Use Yuno's SDK.DIRECT: Back to back integration with provider info for custom payment experience.REDIRECT: Back to back integration with provider redirection.
SDK_CHECKOUT, CHECKOUT, REDIRECT, DIRECT, SDK_SEAMLESS Links this payment to a subscription managed in an external billing platform. When present on an approved payment with a vaulted card, Yuno takes over the subscription's recurring charges. Cannot be sent together with the subscription object (returns INVALID_REQUEST). The object is returned in the payment response, in Retrieve Payment and in payment webhooks.
Links this payment to an invoice of an external billing platform, so that a payment you collect with Yuno pays that invoice (for example a balance top-up). Yuno checks the invoice before it charges. When the payment is approved, Yuno reports it to the invoice; when it is declined, Yuno records a failed attempt and the invoice stays open. A smaller amount than the amount remaining is accepted on one-off invoices; invoices of subscriptions that Stripe charges automatically need the exact amount. Cannot be sent together with external_subscription or subscription (returns INVALID_REQUEST). The object is returned in the payment response, in Retrieve Payment and in payment webhooks. See Pay a Stripe invoice (top-ups) for the amount rules and the error codes.
Specifies the subscription object. Send exactly one of three shapes: inline terms (frequency, availability and amount) to create a subscription, plan_id to create one from a plan, or id to charge an existing subscription. See Start a subscription with the first payment.
Response
201
- Payment
- Card - With card details
- Card - With airline data
- Card - With customer, billing, and shipping details
- Card - With customer, billing, shipping and order items
- Card - With installments
- Card - With authorization
- Card - With merchant advice code (MAC)
- Card - With device fingerprint
- Card - With vault on success
- Card - With vaulted token
- Alternative payment method
- Card - With shipping, fee and tip amount
- Card - With NT
- Wallet - Direct
- Split Marketplace
The total discount of the Yuno promotion applied to the payment: the sum of the YUNO_PROMOTION lines of additional_data.order.discounts. Absent when no promotion applied. The amount charged is amount.value minus this value, and it is on transactions.amount. See Promotions.
The invoice in an external billing platform that this payment pays (a top-up), as it was sent when the payment was created. The key is in the response only when the payment carried external_invoice. See Pay a Stripe invoice (top-ups).