Skip to main content
POST
This request creates a payment. A checkout session is required when the workflow is SDK_CHECKOUT (the default), so create it first. It is not needed for the DIRECT or REDIRECT workflows.
ImportantAlthough certain objects are not mandatory when creating a Payment, the user’s payment experience can be enhanced if you provide this information.
3DS PaymentsCheck the 3D Secure page to learn how to create payments using 3DS on Yuno.
PromotionsTo charge a promotion’s price, send the original 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.
To authorize a payment without capturing it immediately (the client is not charged), send 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.
Metadata and routing logicRouting rules read the metadata on the payment, merged with the metadata on its customer. If you use metadata to drive routing logic, set it on the payment or on the customer. Metadata set only on the Checkout Session does not reach payment routing. Checkout session metadata only decides which payment methods and installments the session lists when a routing rule has a metadata condition, so set the same metadata on both if you need both.
vaulted_token overrides device fingerprintIf payment_method.vaulted_token is provided alongside payment_method.token, the vaulted_token replaces all payment data, including the device fingerprint (third_party_session_id). If you need fraud screening with a device fingerprint, do not send both fields together.
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

Promotions is enabled per organizationA payment that carries a code works only after Yuno enables Promotions for your organization. Until then it is refused with 422 PROMOTION_NOT_APPLICABLE and the reason PROMOTIONS_NOT_ENABLED, and no payment is created. See Promotions.
To charge the price of a promotion code, put the code on a discount line of additional_data.order.discounts instead of a quote_id. Send the original amount, never the discounted one.
Request
This is the part of the request that matters here; the rest is the body you already send. Yuno exchanges the code for a quote before it creates the payment, and the payment goes on as a payment with a quote. The answer is the one in What the payment carries. Create the promotion with Create Promotion. Promotion codes describes the whole flow. The discount line follows these rules. A line that breaks one is refused with 400 INVALID_PARAMETERS before anything else happens, and no payment is created. A code on a 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-Key is required. Create Payment requires it on every payment: without the header the answer is 400 INVALID_PARAMETERS and The 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 with 400 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-Key of 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_APPLICABLE and the reason IDEMPOTENCY_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 header X-Dry-Run: true that carries a code on a YUNO_PROMOTION line is refused with 400 INVALID_PARAMETERS, and no payment is created:
Dry run with a code (400)
Yuno refuses the payment before it asks for a quote, tokenizes a card or reaches a provider, so it counts no use. The message never repeats your code. Only the value 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.
The message says 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.
Code that leaves a charge of zero (422)
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: Promotion Error Codes lists every answer, with the text of each message.

Authorizations

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

Headers

X-Idempotency-Key
string
required

Unique identifier used in HTTP headers to ensure that a request is processed only once, even if it is retried due to network issues or timeouts.

Body

application/json
account_id
string
default:{{account_id}}
required

The unique identifier of the account. You find this information on the Yuno dashboard (UUID, 36 chars).

merchant_order_id
string
default:""
required

The unique identifier of the customer's order (MAX 255; MIN 3).

description
string
required

The description of the payment (MAX 255; MIN 3).

amount
object
required

Specifies the payment amount object, with the value and currency.

country
enum<string>
required

Country where the transaction must be processed (MAX 2; MIN 2; ISO 3166-1).

Available options:
AR,
BO,
BR,
CL,
CO,
CR,
EC,
SV,
GT,
HN,
MX,
NI,
PA,
PY,
PE,
US,
UY
payment_method
object
required

The payment method object.

taxes
object

Specifies the order's tax object.

checkout
object

Specifies the checkout object. This object is not mandatory for back to back payments. Required when workflow is defined as SDK_CHECKOUT or is not sent. not required for DIRECT or REDIRECT payments.

additional_data
object

Specifies the additional_data object. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

merchant_reference
string

Identification of the payment transaction defined by the merchant (MAX 255; MIN 3). Optional to complement the merchant_order_id.

response_additional_data
object

Controls additional data returned in the payment response and in the payment webhooks.

customer_payer
object

Specifies customer object for payments.

workflow
enum<string>
default:SDK_CHECKOUT

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.

Available options:
SDK_CHECKOUT,
CHECKOUT,
REDIRECT,
DIRECT,
SDK_SEAMLESS
external_subscription
object

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.

external_invoice
object

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.

subscription
object

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.

callback_url
string

The URL where to redirect the customer after the payment. Only required for DIRECT integrations that have a redirection (MAX 526; MIN 3).

fraud_screening
object

Fraud screening object.

split_marketplace
object[]

Split marketplace array of objects

metadata
object[]

Custom key–value tags to track this payment or add context (e.g., order_id, invoice, campaign). Up to 120 items.

Response

201

id
string
Example:

"6c44ed29-cc51-4479-a5eb-108afdaadd50"

account_id
string
Example:

"493e9374-510a-4201-9e09-de669d75f256"

description
string
Example:

"Test Payment"

country
string
Example:

"US"

status
string
Example:

"SUCCEEDED"

sub_status
string
Example:

"APPROVED"

merchant_order_id
string
Example:

"1744403449"

created_at
string
Example:

"2025-04-11T20:30:49.825637Z"

updated_at
string
Example:

"2025-04-11T20:30:51.953868Z"

amount
object
discount_amount
object

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.

checkout
object
payment_method
object
customer_payer
object
additional_data
object
transactions
object
transactions_history
object[]
callback_url
string
Example:

"http://www.google.com/?checkoutSession=7fb7093e-dc67-4c7a-80c5-d25cf5e6ff27"

workflow
string
Example:

"SDK_CHECKOUT"

metadata
object[]
fraud_screening
any
Example:

""

subscription_code
string<uuid> | null

Identifier of the subscription created or charged by this payment. Null when the payment carries no subscription.

plan_id
string

The subscription's plan when this payment was created. Present only on payments created with subscription.plan_id and on their renewals; absent otherwise.

plan_assigned_at
string<date-time>

When the plan was assigned to the subscription (UTC, ISO 8601). Present only on payments that carry plan_id.

routing_rules
object
simplified_mode
boolean
default:true
Example:

false

external_subscription
object

The subscription in an external billing platform that this payment belongs to, as it was sent when the payment was created. The key is in the response only when the payment carried external_subscription.

external_invoice
object

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).

shipping
any | null

Shipping.