Skip to main content
POST
/
v1
/
payments
Create payment
curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments \
  --header 'Content-Type: application/json' \
  --header 'account-code: <api-key>' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "checkout_session": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "payment_method": {
    "type": "CARD",
    "token": "tok_4a8b9c2d-1e3f-5678-90ab-cdef12345678"
  },
  "amount": {
    "currency": "BRL",
    "value": 150
  },
  "country": "BR",
  "customer": {
    "document": {
      "document_type": "CPF",
      "document_number": "12345678901"
    },
    "email": "maria.silva@example.com",
    "first_name": "Maria",
    "last_name": "Silva",
    "phone": "+5511999990000"
  },
  "description": "Premium subscription - March 2026",
  "installments": 1,
  "metadata": {
    "order_source": "web",
    "campaign": "spring-2026"
  }
}
'
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "checkout_session": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "SUCCEEDED",
  "amount": {
    "currency": "BRL",
    "value": 150
  },
  "country": "BR",
  "payment_method": {
    "type": "CARD"
  },
  "provider": {
    "name": "stripe_connect",
    "transaction_id": "pi_3abc123def456"
  },
  "merchant_order_id": "order-20260301-001",
  "created_at": "2026-03-01T14:31:00.000Z",
  "updated_at": "2026-03-01T14:31:02.000Z"
}
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
required

Your public API key from the Yuno Dashboard

​
private-secret-key
string
header
required

Your private secret key (server-side only)

​
account-code
string
header
required

Your account identifier. The alias X-Account-Code is also accepted.

Body

application/json
​
checkout_session
string<uuid>
required

The checkout session ID from the create session response

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
payment_method
object
required
​
amount
object
required
Example:
{ "currency": "BRL", "value": 100 }
​
country
string
required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Z]{2}$
Example:

"BR"

​
customer
object
​
description
string

Payment description

Example:

"Premium subscription - March 2026"

​
installments
integer

Number of installments (for card payments)

Required range: x >= 1
Example:

1

​
three_ds
object

3DS authentication preferences

​
merchant_order_id
string

Your unique order reference. If not provided, inherits from the checkout session.

Example:

"order-12345"

​
metadata
object

Custom key-value pairs for storing additional information. Keys and values must be strings. Maximum 50 keys, each key max 40 characters, each value max 500 characters.

Example:
{
  "order_source": "web",
  "campaign": "spring-2026"
}

Response

Payment created successfully

​
id
string<uuid>

Unique payment identifier

Example:

"f47ac10b-58cc-4372-a567-0e02b2c3d479"

​
checkout_session
string<uuid>
Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
status
enum<string>

Current payment status

Available options:
SUCCEEDED,
PENDING,
DECLINED,
REJECTED,
CANCELLED,
REFUNDED,
PARTIALLY_REFUNDED,
AUTHORIZED
Example:

"SUCCEEDED"

​
amount
object
Example:
{ "currency": "BRL", "value": 100 }
​
country
string
Example:

"BR"

​
payment_method
object
​
provider
object
​
merchant_order_id
string
Example:

"order-20260301-001"

​
created_at
string<date-time>
Example:

"2026-03-01T14:31:00.000Z"

​
updated_at
string<date-time>
Example:

"2026-03-01T14:31:02.000Z"

​
transactions
object[]

Individual processing attempts for this payment

​
refunds
object[]

Refund records associated with this payment

​
three_ds
object

3DS authentication details, present for card payments

​
metadata
object

Custom key-value pairs set by the merchant

​
failure_reason
object

Decline details when status is DECLINED or REJECTED

​
customer_id
string<uuid>

ID of the associated customer record

​
installments
object

Installment details if payment was split into installments