Payment Details

The API lets you break down a payment’s total into individual components, such as base charges, taxes, fees, tips, and discounts.

Fee
Shipping
Tips
Taxes
Discounts
Customer validations

These fields are informational: each component is already included in the payment’s total amount.value and isn’t added on top of it. The one exception is a YUNO_PROMOTION discount: you send the original amount and Yuno charges amount.value minus that discount (see Discounts).

Fee amount

A dedicated field (additional_data.order.fee_amount) allows you to specify the fee amount for your services that is included in the transaction. In the following example you can see a request that clarifies that a 180 JPY fee amount is part of a 5000 JPY final transaction. This field is for informational purposes, the fee_amount is already included in the final transaction amount and is not added separately.

curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments \
     --header 'X-Idempotency-Key: <Your idempotency-key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'private-secret-key: <Your private-secret-key>' \
     --header 'public-api-key: <Your public-api-key>' \
     --data '
{
    "description": "Test",
    "account_id": "{{account-code}}",
    "merchant_order_id": "0000023",
    "country": "JP",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "JPY",
        "value": 5000.00
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "additional_data": {
          "order": {
              "fee_amount": 180.00
          }
      },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED"
              }
           }
        }
    }
}
'

Shipping amount

A dedicated field (additional_data.order.shipping_amount) allows you to specify the shipping amount that is included in the transaction. In the following example you can see a request that clarifies that a 270 JPY shipping amount is part of a 5000 JPY final transaction. This field is for informational purposes, the shipping_amount is already included in the final transaction amount and is not added separately.

curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments \
     --header 'X-Idempotency-Key: <Your idempotency-key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'private-secret-key: <Your private-secret-key>' \
     --header 'public-api-key: <Your public-api-key>' \
     --data '
{
    "description": "Test",
    "account_id": "{{account-code}}",
    "merchant_order_id": "0000023",
    "country": "JP",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "JPY",
        "value": 5000.00
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "additional_data": {
          "order": {
              "shipping_amount": 270.00
          }
      },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED"
              }
           }
        }
    }
}
'

Tips

A dedicated field (additional_data.order.tip_amount) allows you to specify the tips amount that is included in the transaction. In the following example you can see a request that clarifies that a 50 JPY tip amount is part of a 5000 JPY final transaction. This field is for informational purposes, the tip_amount is already included in the final transaction amount and is not added separately.

curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments \
     --header 'X-Idempotency-Key: <Your idempotency-key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'private-secret-key: <Your private-secret-key>' \
     --header 'public-api-key: <Your public-api-key>' \
     --data '
{
    "description": "Test",
    "account_id": "{{account-code}}",
    "merchant_order_id": "0000023",
    "country": "JP",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "JPY",
        "value": 5000.00
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "additional_data": {
          "order": {
              "tip_amount": 50.00
          }
      },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED"
              }
           }
        }
    }
}
'

Taxes

A dedicated array of objects (additional_data.order.taxes) allows you to specify the taxes amounts for your services that are included in the transaction.

Field	Type	Description	Example
type*	enum	Tax Type.	VAT
tax_base	float	Taxed base amount for the payment.	10000.00
value*	float	Tax amount value for the payment.	2100.00
percentage	float	Tax rate	21.00

Tax Type	Availability	Description
VAT	COL, ECU	Value Added Tax. Also known as IVA.
CONSUMPTION_TAX	COL	Also known as “Impuesto al consumo”. In Colombia, the National Consumption Tax is an indirect tax applied to the sale of specific goods and services, such as alcoholic beverages, cigarettes, mobile phone services, among others. The rate varies depending on the good or service.
AIRPORT_TAX	COL, BRL	This tax is a fee charged to passengers for the use of airport facilities. This tax varies depending on the airport and may include national and international rates.
VAT_LAW_17934	UYU	In Uruguay, Law No. 17.934 refers to the regulations that establish specific modifications and provisions related to the Value Added Tax (VAT). This law may include regulations on exemptions, special rates, and administrative procedures.
VAT_LAW_19210	UYU	In Uruguay, Law No. 19.210 establishes additional regulations or modifications to VAT rules. This law may focus on aspects such as the digitization of tax processes, new tax rates, or adjustments in exemptions and tax treatments of certain goods and services.
VAT_EXEMPTION	COL, ECU	Value Added Tax Exemption
ISV	DOM	Sales Tax. Also known as “Impuesto Sobre las Ventas”. In the Dominican Republic, the ISV, commonly known as ITBIS (Impuesto a la Transferencia de Bienes Industrializados y Servicios), is a value-added tax applied to the transfer of goods and services. The ITBIS is similar to the VAT in other countries, where the tax is levied at each stage of the production and distribution process.

In the following example, you can see a request that clarifies what taxes are part of a 1000.00 USD final transaction. This field is for informational purposes; the taxes struct is already included in the final transaction amount and has not been added separately.

curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments \
     --header 'X-Idempotency-Key: <Your idempotency-key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'private-secret-key: <Your private-secret-key>' \
     --header 'public-api-key: <Your public-api-key>' \
     --data '
{
    "description": "Test",
    "account_id": "{{account-code}}",
    "merchant_order_id": "0000023",
    "country": "US",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "USD",
        "value": 1000.00
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "additional_data": {
          "order": {
              "taxes": [
                {
                  "type": "AIRPORT_TAX",
                  "tax_base":400000.00
                },
                {
                  "type": "VAT",
                  "value": 320000.00,
                  "tax_base":2000000.00
                }
              ]
          }
      },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED"
              }
           }
        }
    }
}
'

Discounts

A dedicated array of objects (additional_data.order.discounts) allows you to specify the discounts that are included in the transaction. Each line has a type. MERCHANT (the default) is a discount you computed: id, name and unit_amount are required, and id and name have 3 to 255 characters. YUNO_PROMOTION is a promotion quote Yuno computed, with quote_id only; it rejects id, name and unit_amount, a MERCHANT line rejects quote_id, and any mix returns 400 INVALID_PARAMETERS. A line with quote_id and no type is read as YUNO_PROMOTION. Write the type exactly as shown, in capitals: any other spelling returns 400. One quote per payment, and at most 10 discount lines in all. The YUNO_PROMOTION line is accepted on Create Payment only: multi-method payments, payment links, checkout sessions and capture reject it with 400, and a payment that carries a subscription or an external_subscription rejects it with 422 PROMOTION_SUBSCRIPTION_UNSUPPORTED. On the response and on every payment.* webhook Yuno fills the YUNO_PROMOTION line (quote_id, id = the promotion id, unit_amount in the payment currency and, when Yuno has it, name) and adds a discount_amount, the sum of those lines. Your MERCHANT lines keep their id, name and unit_amount; when the payment carries a Yuno promotion, the Create Payment answer, Retrieve Payment and the webhooks list the Yuno line first and mark yours with type: MERCHANT. amount is never rewritten; the net amount charged is on the transaction (transactions.amount). In the following example you can see a request that clarifies that a 5 USD discount amount is part of a 50 USD final transaction. Merchant-computed discounts are informational: the amount is already included in amount and is not added again.

Example

curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments \
     --header 'X-Idempotency-Key: <Your idempotency-key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'private-secret-key: <Your private-secret-key>' \
     --header 'public-api-key: <Your public-api-key>' \
     --data '
{
    "description": "Test",
    "account_id": "{{account-code}}",
    "merchant_order_id": "0000023",
    "country": "US",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "USD",
        "value": 50.00
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "additional_data": {
          "order": {
              "discounts": [
                {
                  "id": "10OFF",
                  "name":"Offer",
                  "unit_amount":5.00
                }
              ]
          }
      },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED"
              }
           }
        }
    }
}
'

Customer validations

A dedicated object (customer_payer.merchant_customer_validations) allows you to specify certain customer validations rules for fraud prevention inquiries.

field	type	description
account_is_verified	bool	If the customer’s account has been validated before on the merchant’s side. True by default
email_is_verified	bool	If the customer’s email has been validated before on the merchant’s side. True by default
phone_is_verified	bool	If the customer’s phone has been validated before on the merchant’s side. True by default

In the following example you can see a request that clarifies that customer has been previously verified outside Yuno.

[...]
  "description": "Test PIX",
    "account_id":"{{account-code}}",
    "merchant_order_id": "0000022",
    "country": "BR",
    "amount": {
        "currency": "BRL",
        "value": 50
    },
   "customer_payer": {
        "merchant_customer_id": "AA001",
        "first_name": "VALERIO",
        "last_name": "DE AGUIAR ZORZATO",
        "email": "test_user_1431202421@testuser.com",
        "phone": {
                "number": "11992149494",
                "country_code": "55"
        },
        "document": {
                "document_type": "CPF",
                "document_number": "96050176876"
        },
        "merchant_customer_validations":{
          "phone_is_verified":true,
          "account_is_verified":true,
          "email_is_verified":true
        }
    },
[...]

Getting Started

Core Concepts

Using Yuno

Direct Integration Use Cases

Payment Features

Payouts and Disputes

Webhooks

Wallets

AI Capabilities

Security and Compliance

Plugins

Additional Services

Fee amount

Shipping amount

Tips

Taxes

Discounts

Customer validations

​Fee amount

​Shipping amount

​Tips

​Taxes

​Discounts

​Customer validations

Fee amount

Shipping amount

Tips

Taxes

Discounts

Customer validations