Skip to main content
POST
/
payments
curl --request POST \ --url https://api-sandbox.y.uno/v1/payments \ --header 'Content-Type: application/json' \ --header 'X-Idempotency-Key: <x-idempotency-key>' \ --header 'private-secret-key: <api-key>' \ --header 'public-api-key: <api-key>' \ --data ' { "description": "Test Payment", "account_id": "{{account-code}}", "merchant_order_id": "AA01", "merchant_reference": "Test_AAB", "country": "US", "additional_data": { "airline": { "legs": [ { "arrival_airport": "AMS", "base_fare": 200, "base_fare_currency": "USD", "carrier_code": "KL", "departure_airport": "EZE", "departure_airport_timezone": "-03:00", "departure_datetime": "2024-07-03T05:00:00", "arrival_datetime": "2024-08-03T05:00:00", "fare_basis_code": "HL7LNR", "fare_class_code": "FR", "flight_number": "842", "stopover_code": "s" } ], "passengers": [ { "country": "US", "date_of_birth": "1984-05-01", "document": { "document_number": "123456789", "document_type": "SSN", "country": "US" }, "phone": { "country_code": "1", "number": "5551234567" }, "first_name": "John", "last_name": "Doe", "loyalty_number": "123456", "loyalty_tier": "GOLD", "middle_name": "Theodore", "nationality": "US", "type": "s" } ], "pnr": "1P-2UUGJW", "tickets": [ { "ticket_number": "123456", "restricted": false, "total_fare_amount": 80, "total_tax_amount": 22, "total_fee_amount": 14, "issue": null, "e_ticket": false } ] }, "order": { "fee_amount": 100, "tip_amount": 50, "items": [ { "brand": "XYZ", "category": "Clothes", "id": "123AD", "manufacture_part_number": "XYZ123456", "name": "Skirt", "quantity": 1, "sku_code": "8765432109", "unit_amount": 4800 } ], "shipping_amount": 50 }, "seller_details": { "name": "Test_company", "email": "testcompany@example.com", "reference": "AAOO", "website": "www.testcompany.com", "industry": "ELECTRONICS", "merchant_category_code": "TTRR", "country": "US", "document": { "document_number": "123456789", "document_type": "EIN" }, "phone": { "country_code": "1", "number": "5551234567" } } }, "amount": { "currency": "USD", "value": 5000 }, "checkout": { "session": "{{checkout_session}}" }, "customer_payer": { "id": "{{customer_id}}", "billing_address": { "address_line_1": "123 Main St", "address_line_2": "Apt 502", "city": "New York", "country": "US", "state": "NY", "zip_code": "10001", "neighborhood": "Midtown" }, "browser_info": { "accept_header": "true", "color_depth": "24", "javascript_enabled": true, "language": "en-US", "screen_height": "2048", "screen_width": "1152", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9" }, "date_of_birth": "1990-02-28", "device_fingerprints": [ { "provider_id": "CLEARSALE", "id": "hi88287gbd8d7d782ge287gbd8d7d78" } ], "document": { "document_type": "SSN", "document_number": "123456789" }, "email": "johndoe@example.com", "first_name": "John", "gender": "MALE", "ip_address": "192.168.123.167", "last_name": "Doe", "merchant_customer_id": "example00234", "merchant_customer_created_at": "2014-05-12 13:05:00", "nationality": "US", "phone": { "country_code": "1", "number": "5551234567" }, "shipping_address": { "address_line_1": "123 Main St", "address_line_2": "Apt 502", "city": "New York", "country": "US", "state": "NY", "zip_code": "10001", "neighborhood": "Midtown" } }, "payment_method": { "token": "{{onetime_token}}" }, "metadata": [ { "key": "ID", "value": "SD00" } ], "callback_url": "www.example.com" } '
{ "id": "6c44ed29-cc51-4479-a5eb-108afdaadd50", "account_id": "493e9374-510a-4201-9e09-de669d75f256", "description": "Card Payment", "country": "US", "status": "SUCCEEDED", "sub_status": "APPROVED", "merchant_order_id": "1744403449", "created_at": "2025-04-11T20:30:49.825637Z", "updated_at": "2025-04-11T20:30:51.953868Z", "amount": { "captured": 0, "currency": "USD", "currency_conversion": null, "refunded": 0, "value": 15000 }, "checkout": { "session": "7fb7093e-dc67-4c7a-80c5-d25cf5e6ff27", "sdk_action_required": false }, "payment_method": { "vaulted_token": "dcc06b32-43ad-4627-aa75-c631eb50c2ac", "type": "CARD", "vault_on_success": true, "token": "8cabcd5c-1b40-4407-b14a-14ab21741865", "parent_payment_method_type": null, "payment_method_detail": { "card": { "verify": false, "capture": true, "installments": 1, "installments_plan_id": null, "first_installment_deferral": 0, "installments_type": "", "installment_amount": null, "soft_descriptor": "", "authorization_code": "835631", "retrieval_reference_number": "", "voucher": null, "card_data": { "holder_name": "Fannie Weissnat", "iin": "41961111", "lfd": "0010", "number_length": 16, "security_code_length": 1, "brand": "VISA", "issuer_name": "METABANK", "issuer_code": null, "country_code": "US", "category": "PREPAID RELOADABLE", "type": "DEBIT", "three_d_secure": { "version": null, "electronic_commerce_indicator": null, "cryptogram": null, "transaction_id": null, "directory_server_transaction_id": null, "pares_status": null, "acs_id": null }, "fingerprint": "5605f3e4-69e7-4a9f-9646-2ac8c2e33e12", "expiration_month": 3, "expiration_year": 24 }, "stored_credentials": { "reason": null, "usage": null, "subscription_agreement_id": null, "network_transaction_id": null } } } }, "customer_payer": { "id": "94121f98-98f7-4d57-aa5f-228401d35b12", "merchant_customer_id": "1744402154", "first_name": "John", "last_name": "Doe", "gender": "", "date_of_birth": "1990-02-28", "email": "john.doe2@gmail.com", "nationality": "US", "ip_address": "192.168.123.167", "device_fingerprint": "hi88287gbd8d7d782ge....", "device_fingerprints": [], "browser_info": { "user_agent": "string", "accept_header": "string", "accept_content": null, "accept_browser": null, "color_depth": "string", "screen_height": "string", "screen_width": "string", "javascript_enabled": true, "java_enabled": null, "browser_time_difference": null, "language": "string" }, "document": { "document_type": "SSN", "document_number": "38799992" }, "phone": { "number": "5551234567", "country_code": "1" }, "billing_address": { "address_line_1": "123 Main St", "address_line_2": "Apt 502", "country": "US", "state": "California", "city": "Los Angeles", "zip_code": "90001", "neighborhood": "Test" }, "shipping_address": { "address_line_1": "123 Main St", "address_line_2": "Apt 502", "country": "US", "state": "California", "city": "Los Angeles", "zip_code": "90001", "neighborhood": "Test" }, "merchant_customer_created_at": "2023-08-05T14:43:58.980718Z" }, "additional_data": { "airline": { "pnr": "1P-2UUGJW", "legs": [ { "departure_airport": "EZE", "departure_datetime": "2014-05-12 13:05:00", "departure_airport_timezone": "-03:00", "arrival_airport": "AMS", "arrival_airport_timezone": "+00:00", "arrival_datetime": "", "carrier_code": "KL", "flight_number": "842", "fare_basis_code": "HL7LNR", "fare_class_code": "FR", "base_fare": 200, "base_fare_currency": "USD", "stopover_code": "s" } ], "passengers": [ { "first_name": "string", "last_name": "string", "middle_name": "string", "type": "s", "date_of_birth": "stringstri", "nationality": "US", "document": { "document_type": "SSN", "document_number": "351040753" }, "country": "US", "loyalty_number": "string", "loyalty_tier": "strin", "email": null, "phone": null } ], "ticket": { "ticket_number": "123456", "e_ticket": false, "restricted": false, "total_fare_amount": 80, "total_tax_amount": 22, "total_fee_amount": 14, "issue": null }, "tickets": null }, "order": { "fee_amount": 40.5, "shipping_amount": 10.35, "tip_amount": null, "items": [ { "id": "123AD", "name": "Skirt", "quantity": 3, "unit_amount": 20, "category": "Clothes", "brand": "XYZ", "sku_code": "8765432109", "manufacture_part_number": "XYZ123456" } ], "account_funding": null, "tickets": null, "fulfillment": null, "discounts": null }, "seller_details": null }, "transactions": { "id": "9dc9524a-504d-4eaf-84ef-c881b46aab25", "type": "PURCHASE", "status": "SUCCEEDED", "category": "CARD", "amount": 15000, "provider_id": "YUNO_TEST_PAYMENT_GW", "payment_method": { "vaulted_token": "dcc06b32-43ad-4627-aa75-c631eb50c2ac", "type": "CARD", "vault_on_success": true, "token": "8cabcd5c-1b40-4407-b14a-14ab21741865", "parent_payment_method_type": null, "detail": { "card": { "verify": false, "capture": true, "installments": 1, "installments_plan_id": null, "first_installment_deferral": 0, "installments_type": "", "installment_amount": null, "soft_descriptor": "", "authorization_code": "835631", "retrieval_reference_number": "", "voucher": null, "card_data": { "holder_name": "Fannie Weissnat", "iin": "41961111", "lfd": "0010", "number_length": 16, "security_code_length": 1, "brand": "VISA", "issuer_name": "METABANK", "issuer_code": null, "country_code": "US", "category": "PREPAID RELOADABLE", "type": "DEBIT", "three_d_secure": { "version": null, "electronic_commerce_indicator": null, "cryptogram": null, "transaction_id": null, "directory_server_transaction_id": null, "pares_status": null, "acs_id": null }, "fingerprint": "5605f3e4-69e7-4a9f-9646-2ac8c2e33e12", "expiration_month": 3, "expiration_year": 24 }, "stored_credentials": { "reason": null, "usage": null, "subscription_agreement_id": null, "network_transaction_id": null } } } }, "response_code": "SUCCEEDED", "response_message": "Transaction successful", "reason": null, "description": "Test Payment", "merchant_reference": "1744403449", "provider_data": { "id": "YUNO_TEST_PAYMENT_GW", "transaction_id": "04d94195-a6ce-455a-b027-5f237f91a576", "account_id": "", "status": "SUCCEEDED", "sub_status": "", "status_detail": "", "response_message": null, "response_code": null, "raw_response": { "amount": { "currency": "USD", "value": 2100 }, "merchantAccount": "YunoPaymentsECOM", "paymentPspReference": "ZKHXKZGXMLBX8N82", "pspReference": "VKJTCWZ9575ZGN82", "reference": "34343434", "status": "received" }, "third_party_transaction_id": "", "third_party_account_id": null, "iso8583_response_code": null, "iso8583_response_message": null }, "connection_data": { "id": "90defca1-c913-4894-965c-ed536b65951a", "name": null }, "created_at": "2025-04-11T20:30:51.097215Z", "updated_at": "2025-04-11T20:30:51.199007Z" }, "transactions_history": [ { "id": "9dc9524a-504d-4eaf-84ef-c881b46aab25", "type": "PURCHASE", "status": "SUCCEEDED", "category": "CARD", "amount": 15000, "provider_id": "YUNO_TEST_PAYMENT_GW", "payment_method": { "vaulted_token": "dcc06b32-43ad-4627-aa75-c631eb50c2ac", "type": "CARD", "vault_on_success": true, "token": "8cabcd5c-1b40-4407-b14a-14ab21741865", "parent_payment_method_type": null, "detail": { "card": { "verify": false, "capture": true, "installments": 1, "installments_plan_id": null, "first_installment_deferral": 0, "installments_type": "", "installment_amount": null, "soft_descriptor": "", "authorization_code": "835631", "retrieval_reference_number": "", "voucher": null, "card_data": { "holder_name": "Fannie Weissnat", "iin": "41961111", "lfd": "0010", "number_length": 16, "security_code_length": 1, "brand": "VISA", "issuer_name": "METABANK", "issuer_code": null, "country_code": "US", "category": "PREPAID RELOADABLE", "type": "DEBIT", "three_d_secure": { "version": null, "electronic_commerce_indicator": null, "cryptogram": null, "transaction_id": null, "directory_server_transaction_id": null, "pares_status": null, "acs_id": null }, "fingerprint": "5605f3e4-69e7-4a9f-9646-2ac8c2e33e12", "expiration_month": 3, "expiration_year": 24 }, "stored_credentials": { "reason": null, "usage": null, "subscription_agreement_id": null, "network_transaction_id": null } } } }, "response_code": "SUCCEEDED", "response_message": "Transaction successful", "reason": null, "description": "Test Payment", "merchant_reference": "1744403449", "provider_data": { "id": "YUNO_TEST_PAYMENT_GW", "transaction_id": "04d94195-a6ce-455a-b027-5f237f91a576", "account_id": "", "status": "SUCCEEDED", "sub_status": "", "status_detail": "", "response_message": null, "response_code": null, "raw_response": { "amount": { "currency": "USD", "value": 2100 }, "merchantAccount": "YunoPaymentsECOM", "paymentPspReference": "ZKHXKZGXMLBX8N82", "pspReference": "VKJTCWZ9575ZGN82", "reference": "34343434", "status": "received" }, "third_party_transaction_id": "", "third_party_account_id": null, "iso8583_response_code": null, "iso8583_response_message": null }, "connection_data": { "id": "90defca1-c913-4894-965c-ed536b65951a", "name": null }, "created_at": "2025-04-11T20:30:51.097215Z", "updated_at": "2025-04-11T20:30:51.199007Z" } ], "callback_url": "http://www.google.com/?checkoutSession=7fb7093e-dc67-4c7a-80c5-d25cf5e6ff27", "workflow": "SDK_CHECKOUT", "metadata": [ { "key": "ID", "value": "1234" } ], "fraud_screening": null, "payment_link_id": "", "subscription_code": null, "routing_rules": { "smart_routing": false, "monitors": false, "condition": { "id": 146526, "name": null, "description": null } }, "simplified_mode": false }
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.
If you want to process payments in a Single Step (Authorization and Capture simultaneously), you need to send the payment_method.detail.card.capture attribute as true, so the payment is captured automatically. To test all possible transaction outcomes within Yuno in Sandbox, please refer to the following documentation for test data.
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.
On the other hand, if you wish to process the payment in Two Steps (First Authorization and then Capture), you need to send payment_method.detail.card.capture attribute as false. Please follow the steps below to implement a two-step flow:
  1. Create an authorization using the Authorize Payment request.
  2. Capture the created authorization using the Capture Authorization request.
Note that this request requires an X-Idempotency-Key. Check the Authentication page for more information.

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.

​
additional_data
object
required

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.

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

​
merchant_reference
string

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

​
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
​
subscription
object

Specifies the subscription object.

​
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
any
​
routing_rules
object
​
simplified_mode
boolean
default:true
Example:

false