Skip to main content
POST
This request creates a payment after you created a checkout session.
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.
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 logicIf you use metadata to drive routing logic, it must also be set in the Checkout Session. Filling it only in the Payment object will not activate route logic.
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.

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.

​
checkout
object
required

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.

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

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

​
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
​
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
​
payment_link_id
string
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