Core Yuno Payments API — customers, checkout sessions, payments, refunds, captures, subscriptions, payouts, disputes, reports, banking connectivity and PCI Proxy. Header API-key auth with X-Idempotency-Key idempotency.
{
"openapi": "3.1.0",
"info": {
"title": "Yuno Payments API",
"description": "Yuno payment orchestration API for processing payments across Latin America",
"version": "1.0.0",
"contact": {
"name": "Yuno Support",
"email": "support@y.uno"
}
},
"servers": [
{
"url": "https://api-sandbox.y.uno",
"description": "Sandbox"
},
{
"url": "https://api.y.uno",
"description": "Production"
}
],
"security": [
{
"publicApiKey": [],
"privateSecretKey": [],
"accountCode": []
}
],
"paths": {},
"components": {
"securitySchemes": {
"publicApiKey": {
"type": "apiKey",
"in": "header",
"name": "public-api-key",
"description": "Your public API key from the Yuno Dashboard"
},
"privateSecretKey": {
"type": "apiKey",
"in": "header",
"name": "private-secret-key",
"description": "Your private secret key (server-side only)"
},
"accountCode": {
"type": "apiKey",
"in": "header",
"name": "account-code",
"description": "Your account identifier. The alias X-Account-Code is also accepted."
}
},
"schemas": {
"Amount": {
"type": "object",
"required": [
"currency",
"value"
],
"properties": {
"currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "BRL"
},
"value": {
"type": "number",
"description": "Payment amount in major currency units (e.g., 150.00 means 150 BRL, not cents). For zero-decimal currencies like CLP and PYG, use whole numbers (e.g., 15000 means 15,000 CLP).",
"example": 100
}
},
"example": {
"currency": "BRL",
"value": 100
}
},
"CustomerDocument": {
"type": "object",
"required": [
"document_type",
"document_number"
],
"properties": {
"document_type": {
"type": "string",
"enum": [
"CPF",
"CNPJ",
"CC",
"CE",
"NIT",
"PP",
"CURP",
"RFC"
],
"description": "Type of identification document"
},
"document_number": {
"type": "string",
"description": "Document number (digits only). CPF: 11 digits, CNPJ: 14 digits.",
"example": "12345678901"
}
},
"example": {
"document_type": "CPF",
"document_number": "12345678901"
}
},
"CheckoutSessionRequest": {
"type": "object",
"required": [
"amount",
"country",
"merchant_order_id",
"account_id",
"payment_description"
],
"properties": {
"amount": {
"$ref": "#/components/schemas/Amount"
},
"country": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code",
"pattern": "^[A-Z]{2}$",
"example": "BR"
},
"merchant_order_id": {
"type": "string",
"description": "Your unique order identifier",
"example": "order-001"
},
"account_id": {
"type": "string",
"description": "Your Yuno account identifier. Same value as the account-code header.",
"example": "your-account-id"
},
"payment_description": {
"type": "string",
"description": "Description of the payment. Required for checkout session creation.",
"example": "Premium subscription - March 2026"
},
"customer_id": {
"type": "string",
"format": "uuid",
"description": "Optional existing customer ID",
"example": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f"
},
"workflow": {
"type": "string",
"enum": [
"SDK_CHECKOUT",
"SDK_LITE",
"SDK_SEAMLESS",
"SDK_HEADLESS",
"DIRECT"
],
"description": "Integration workflow type",
"example": "SDK_CHECKOUT"
},
"callback_url": {
"type": "string",
"format": "uri",
"description": "URL to receive server-side payment notifications",
"example": "https://merchant.com/webhooks/yuno"
},
"return_url": {
"type": "string",
"format": "uri",
"description": "URL to redirect the customer after payment completion (required for 3DS, PIX, and redirect-based methods)",
"example": "https://merchant.com/checkout/complete"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "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"
}
},
"recurring_payment": {
"type": "object",
"description": "Optional configuration for recurring payments and subscriptions",
"properties": {
"description": {
"type": "string",
"description": "Description of the recurring payment"
},
"management_url": {
"type": "string",
"description": "URL for the customer to manage the recurring payment"
},
"billing_agreement": {
"type": "string",
"description": "Billing agreement for the recurring payment"
},
"regular_billing": {
"type": "object",
"required": [
"interval_unit",
"interval_count"
],
"properties": {
"interval_unit": {
"type": "string",
"enum": [
"year",
"month",
"day",
"hour",
"minute"
],
"description": "The frequency unit for recurring charges"
},
"interval_count": {
"type": "integer",
"minimum": 1,
"description": "The number of interval units between charges"
}
}
},
"trial_billing": {
"type": "object",
"properties": {
"interval_unit": {
"type": "string",
"enum": [
"year",
"month",
"day",
"hour",
"minute"
]
},
"interval_count": {
"type": "integer",
"minimum": 1
}
}
}
}
}
},
"example": {
"amount": {
"currency": "BRL",
"value": 150
},
"country": "BR",
"merchant_order_id": "order-20260301-001",
"account_id": "your-account-id",
"payment_description": "Premium subscription - March 2026",
"workflow": "SDK_CHECKOUT",
"recurring_payment": {
"regular_billing": {
"interval_unit": "month",
"interval_count": 1
}
}
}
},
"CheckoutSession": {
"type": "object",
"properties": {
"checkout_session": {
"type": "string",
"format": "uuid",
"description": "The checkout session identifier",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"amount": {
"$ref": "#/components/schemas/Amount"
},
"country": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code",
"example": "BR"
},
"merchant_order_id": {
"type": "string",
"description": "Your unique order identifier",
"example": "order-20260301-001"
},
"status": {
"type": "string",
"description": "Session status",
"example": "ACTIVE"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Session creation timestamp",
"example": "2026-03-01T14:30:00.000Z"
},
"payment_methods": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Payment method type"
}
}
},
"description": "Available payment methods for this session"
},
"callback_url": {
"type": "string",
"format": "uri",
"description": "URL to receive server-side payment notifications",
"example": "https://merchant.com/webhooks/yuno"
},
"return_url": {
"type": "string",
"format": "uri",
"description": "URL to redirect the customer after payment completion (required for 3DS, PIX, and redirect-based methods)",
"example": "https://merchant.com/checkout/complete"
}
},
"example": {
"checkout_session": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": {
"currency": "BRL",
"value": 150
},
"country": "BR",
"merchant_order_id": "order-20260301-001",
"status": "ACTIVE",
"created_at": "2026-03-01T14:30:00.000Z",
"payment_methods": [
{
"type": "CARD"
},
{
"type": "PIX"
},
{
"type": "BOLETO"
}
]
}
},
"PaymentRequest": {
"type": "object",
"required": [
"checkout_session",
"payment_method",
"amount",
"country"
],
"properties": {
"checkout_session": {
"type": "string",
"format": "uuid",
"description": "The checkout session ID from the create session response",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"payment_method": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"CARD",
"PIX",
"BOLETO",
"PSE",
"SPEI",
"OXXO",
"BNPL",
"GOOGLE_PAY",
"APPLE_PAY"
],
"description": "Payment method type",
"example": "CARD"
},
"token": {
"type": "string",
"description": "Payment method token (for tokenized card payments)",
"example": "tok_4a8b9c2d-1e3f-5678-90ab-cdef12345678"
},
"vaulted_token": {
"type": "string",
"description": "Vaulted payment method token (for returning customers)"
}
}
},
"amount": {
"$ref": "#/components/schemas/Amount"
},
"country": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code",
"pattern": "^[A-Z]{2}$",
"example": "BR"
},
"customer": {
"type": "object",
"properties": {
"document": {
"$ref": "#/components/schemas/CustomerDocument"
},
"email": {
"type": "string",
"format": "email",
"description": "Customer email address",
"example": "maria.silva@example.com"
},
"first_name": {
"type": "string",
"example": "Maria"
},
"last_name": {
"type": "string",
"example": "Silva"
},
"phone": {
"type": "string",
"example": "+5511999990000"
}
}
},
"description": {
"type": "string",
"description": "Payment description",
"example": "Premium subscription - March 2026"
},
"installments": {
"type": "integer",
"description": "Number of installments (for card payments)",
"minimum": 1,
"example": 1
},
"three_ds": {
"type": "object",
"description": "3DS authentication preferences",
"properties": {
"required": {
"type": "boolean",
"description": "Force 3DS authentication",
"default": false
},
"exemption": {
"type": "string",
"enum": [
"LOW_VALUE",
"TRA",
"TRUSTED_BENEFICIARY",
"RECURRING",
"NONE"
],
"description": "SCA exemption to request"
}
}
},
"merchant_order_id": {
"type": "string",
"description": "Your unique order reference. If not provided, inherits from the checkout session.",
"example": "order-12345"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "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"
}
}
},
"example": {
"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"
},
"description": "Premium subscription - March 2026",
"installments": 1
}
},
"Payment": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique payment identifier",
"example": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"checkout_session": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"status": {
"type": "string",
"enum": [
"SUCCEEDED",
"PENDING",
"DECLINED",
"REJECTED",
"CANCELLED",
"REFUNDED",
"PARTIALLY_REFUNDED",
"AUTHORIZED"
],
"description": "Current payment status",
"example": "SUCCEEDED"
},
"amount": {
"$ref": "#/components/schemas/Amount"
},
"country": {
"type": "string",
"example": "BR"
},
"payment_method": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "CARD"
}
}
},
"provider": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Payment provider name",
"example": "stripe_connect"
},
"transaction_id": {
"type": "string",
"description": "Provider transaction reference",
"example": "pi_3abc123def456"
}
}
},
"merchant_order_id": {
"type": "string",
"example": "order-20260301-001"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2026-03-01T14:31:00.000Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2026-03-01T14:31:02.000Z"
},
"transactions": {
"type": "array",
"description": "Individual processing attempts for this payment",
"items": {
"$ref": "#/components/schemas/Transaction"
}
},
"refunds": {
"type": "array",
"description": "Refund records associated with this payment",
"items": {
"$ref": "#/components/schemas/RefundRecord"
}
},
"three_ds": {
"type": "object",
"description": "3DS authentication details, present for card payments",
"properties": {
"required": {
"type": "boolean",
"description": "Whether 3DS authentication is required"
},
"version": {
"type": "string",
"description": "3DS protocol version",
"example": "2.2.0"
},
"status": {
"type": "string",
"enum": [
"AUTHENTICATED",
"CHALLENGED",
"ATTEMPTED",
"FAILED",
"UNAVAILABLE"
]
},
"eci": {
"type": "string",
"description": "Electronic Commerce Indicator",
"example": "05"
},
"redirect_url": {
"type": "string",
"format": "uri",
"description": "URL to redirect the customer for 3DS challenge"
}
}
},
"metadata": {
"type": "object",
"description": "Custom key-value pairs set by the merchant",
"additionalProperties": {
"type": "string"
}
},
"failure_reason": {
"type": "object",
"description": "Decline details when status is DECLINED or REJECTED",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable decline code",
"example": "insufficient_funds"
},
"message": {
"type": "string",
"description": "Human-readable decline reason"
},
"provider_code": {
"type": "string",
"description": "Raw decline code from the payment provider"
}
}
},
"customer_id": {
"type": "string",
"format": "uuid",
"description": "ID of the associated customer record"
},
"installments": {
"type": "object",
"description": "Installment details if payment was split into installments",
"properties": {
"count": {
"type": "integer",
"description": "Number of installments",
"example": 3
},
"plan_id": {
"type": "string",
"description": "Installment plan ID if using merchant installments"
}
}
}
},
"example": {
"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",
"customer_id": "cust_9a8b7c6d-5e4f-3210-abcd-ef0987654321",
"transactions": [
{
"id": "txn_1a2b3c4d-5e6f-7890-abcd-ef1234567890",
"status": "APPROVED",
"provider": "stripe_connect",
"provider_transaction_id": "pi_3abc123def456",
"response_code": "00",
"response_message": "Approved",
"created_at": "2026-03-01T14:31:01.000Z"
}
],
"refunds": [],
"three_ds": {
"version": "2.2",
"eci": "05",
"status": "AUTHENTICATED"
},
"metadata": {
"order_source": "web",
"campaign": "spring-2026"
},
"installments": null,
"failure_reason": null,
"created_at": "2026-03-01T14:31:00.000Z",
"updated_at": "2026-03-01T14:31:02.000Z"
}
},
"InstallmentsPlanRequest": {
"type": "object",
"required": [
"account_id",
"name",
"merchant_reference",
"installments_plan",
"country_code",
"amount"
],
"properties": {
"account_id": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Account IDs this plan applies to",
"example": [
"1a3a576a-01d0-40ff-a68e-494f82145773"
]
},
"name": {
"type": "string",
"description": "Name of the installment plan",
"example": "Standard Plan"
},
"merchant_reference": {
"type": "string",
"description": "Merchant reference for the plan",
"example": "001 08 Agosto 2023"
},
"installments_plan": {
"type": "array",
"items": {
"type": "object",
"required": [
"installment",
"rate"
],
"properties": {
"installment": {
"type": "integer",
"description": "Number of installments",
"example": 2
},
"rate": {
"type": "number",
"description": "Interest rate multiplier",
"example": 1.294
}
}
},
"description": "Array of installment options with rates"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code",
"pattern": "^[A-Z]{2}$",
"example": "BR"
},
"amount": {
"type": "object",
"required": [
"Currency",
"min_value",
"max_value"
],
"properties": {
"Currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "BRL"
},
"min_value": {
"type": "number",
"description": "Minimum amount for this plan",
"example": 0
},
"max_value": {
"type": "number",
"description": "Maximum amount for this plan",
"example": 10000000000
}
}
},
"brand": {
"type": "string",
"nullable": true,
"description": "Card brand filter (optional)"
},
"iin": {
"type": "string",
"nullable": true,
"description": "IIN/BIN filter (optional)"
}
},
"example": {
"account_id": [
"1a3a576a-01d0-40ff-a68e-494f82145773"
],
"name": "Standard Plan",
"merchant_reference": "001 08 Agosto 2023",
"installments_plan": [
{
"installment": 1,
"rate": 1
},
{
"installment": 2,
"rate": 1.294
},
{
"installment": 6,
"rate": 1.42
},
{
"installment": 12,
"rate": 1.525
}
],
"country_code": "BR",
"amount": {
"Currency": "BRL",
"min_value": 0,
"max_value": 10000000000
},
"brand": null,
"iin": null
}
},
"InstallmentsPlan": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique installment plan identifier",
"example": "3e599453-e147-4d1c-8643-73e4d980c2ae"
},
"name": {
"type": "string",
"example": "Standard Plan"
},
"account_id": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"example": [
"1a3a576a-01d0-40ff-a68e-494f82145773"
]
},
"merchant_reference": {
"type": "string",
"example": "001 08 Agosto 2023"
},
"installments_plan": {
"type": "array",
"items": {
"type": "object",
"properties": {
"installment": {
"type": "integer"
},
"rate": {
"type": "number"
}
}
}
},
"brand": {
"type": "string",
"nullable": true
},
"iin": {
"type": "string",
"nullable": true
},
"country_code": {
"type": "string",
"example": "BR"
},
"first_installment_deferral": {
"type": "integer",
"description": "Number of periods before first installment",
"example": 1
},
"amount": {
"type": "object",
"properties": {
"Currency": {
"type": "string"
},
"min_value": {
"type": "number"
},
"max_value": {
"type": "number"
}
}
}
},
"example": {
"id": "3e599453-e147-4d1c-8643-73e4d980c2ae",
"name": "Standard Plan",
"account_id": [
"1a3a576a-01d0-40ff-a68e-494f82145773"
],
"merchant_reference": "001 08 Agosto 2023",
"installments_plan": [
{
"installment": 1,
"rate": 1
},
{
"installment": 2,
"rate": 1.294
},
{
"installment": 12,
"rate": 1.525
}
],
"brand": null,
"iin": null,
"country_code": "BR",
"first_installment_deferral": 1,
"amount": {
"Currency": "BRL",
"min_value": 0,
"max_value": 10000000000
}
}
},
"Issuer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Issuer identifier",
"example": "1"
},
"name": {
"type": "string",
"description": "Issuer name (bank name)",
"example": "Banco de Bogota"
}
},
"example": {
"id": "1",
"name": "Banco de Bogota"
}
},
"CustomerRequest": {
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Customer email address",
"example": "maria.silva@example.com"
},
"first_name": {
"type": "string",
"description": "Customer first name",
"example": "Maria"
},
"last_name": {
"type": "string",
"description": "Customer last name",
"example": "Silva"
},
"phone": {
"type": "string",
"description": "Customer phone number",
"example": "+5511999990000"
},
"document": {
"$ref": "#/components/schemas/CustomerDocument"
},
"merchant_customer_id": {
"type": "string",
"description": "Your internal customer identifier",
"example": "cust-internal-001"
}
},
"example": {
"email": "maria.silva@example.com",
"first_name": "Maria",
"last_name": "Silva",
"phone": "+5511999990000",
"document": {
"document_type": "CPF",
"document_number": "12345678901"
},
"merchant_customer_id": "cust-internal-001"
}
},
"Customer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Yuno customer identifier",
"example": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f"
},
"email": {
"type": "string",
"format": "email",
"example": "maria.silva@example.com"
},
"first_name": {
"type": "string",
"example": "Maria"
},
"last_name": {
"type": "string",
"example": "Silva"
},
"phone": {
"type": "string",
"example": "+5511999990000"
},
"document": {
"$ref": "#/components/schemas/CustomerDocument"
},
"merchant_customer_id": {
"type": "string",
"example": "cust-internal-001"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2026-03-01T10:00:00.000Z"
}
},
"example": {
"id": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f",
"email": "maria.silva@example.com",
"first_name": "Maria",
"last_name": "Silva",
"phone": "+5511999990000",
"document": {
"document_type": "CPF",
"document_number": "12345678901"
},
"merchant_customer_id": "cust-internal-001",
"created_at": "2026-03-01T10:00:00.000Z"
}
},
"PayoutRequest": {
"type": "object",
"required": [
"amount",
"country",
# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/yuno/refs/heads/main/openapi/_original/yuno-openapi-original.json