Create Payment

Creates a payment from an existing checkout session and a payment method. Set a stable merchant_order_id on the upstream checkout session so a retry of the same logical operation can be looked up via Get Payment by Merchant Order instead of producing a duplicate payment.

POST /v1/payments

cURL

cURL

curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'public-api-key: YOUR_PUBLIC_API_KEY' \
  --header 'private-secret-key: YOUR_PRIVATE_SECRET_KEY' \
  --data '{
  "account_id": "YOUR_ACCOUNT_CODE",
  "merchant_order_id": "order-20260301-001",
  "description": "Premium subscription - March 2026",
  "country": "BR",
  "amount": { "currency": "BRL", "value": 150.00 },
  "workflow": "DIRECT",
  "payment_method": {
    "type": "CARD",
    "vaulted_token": "4a8b9c2d-1e3f-5678-90ab-cdef12345678",
    "detail": { "card": { "capture": true, "installments": 1 } }
  }
}'

201

Payment

{ "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": "[e-mail]", "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": "PSP123456789ABCDEF", "pspReference": "PSP123456789ABCDEF", "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": "PSP123456789ABCDEF", "pspReference": "PSP123456789ABCDEF", "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, "subscription_code": null, "routing_rules": { "smart_routing": false, "monitors": false, "condition": { "id": 146526, "name": null, "description": null } }, "simplified_mode": false }

Create a new payment. Works across every workflow (SDK checkout, hosted checkout, direct back to back, redirect) and every supported payment method.

Set payment_method.detail.card.capture to true to authorize and capture in one call, or false to authorize only and capture or cancel later. For direct 3DS integrations, populate payment_method.detail.card.three_d_secure with your authentication result. The Yuno SDK and hosted checkout handle 3DS automatically. Test in sandbox with the Yuno Testing Gateway.

Set a stable merchant_order_id on the upstream checkout session to make retries safe. This endpoint does not honor X-Idempotency-Key. The dedupe pattern is to look up an existing payment with Get Payment by Merchant Order before retrying. See Avoiding duplicates.

Metadata and routing logic. If you use metadata to drive routing rules, it must also be set on the Checkout Session. Setting it only here will not trigger route logic.

Authorizations

public-api-key · string · header · required

Your public API key from the Yuno Dashboard

private-secret-key · string · header · required

Your private secret key (server-side only)

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.

Show child attributes

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.

Show child attributes

checkout · object

Links this payment to a previously-created Checkout Session. Required when workflow is SDK_CHECKOUT (or when workflow is omitted, since SDK_CHECKOUT is the default). Not required for DIRECT or REDIRECT back-to-back payments.

Show child attributes

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.

Show child attributes

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.

Show child attributes

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.

Show child attributes

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.

Show child attributes

split_marketplace · object[]

Split marketplace array of objects

Show child attributes

metadata · object[]

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

Show child attributes

Response

201

application/json

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

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

Show child attributes

checkout · object

Show child attributes

payment_method · object

Show child attributes

customer_payer · object

Show child attributes

additional_data · object

Show child attributes

transactions · object

Show child attributes

transactions_history · object[]

Show child attributes

callback_url · string

Example:

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

workflow · string

Example:

"SDK_CHECKOUT"

metadata · object[]

Show child attributes

fraud_screening · any

subscription_code · any

routing_rules · object

Show child attributes

simplified_mode · boolean · default: true

Example:

false