{ "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", "recipient_id" ], "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "pattern": "^[A-Z]{2}$", "example": "BR" }, "recipient_id": { "type": "string", "format": "uuid", "description": "The recipient to send funds to", "example": "d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a" }, "description": { "type": "string", "description": "Payout description", "example": "Seller payout - Order #1234" }, "merchant_reference": { "type": "string", "description": "Your internal payout reference", "example": "payout-ref-001" }, "purpose": { "type": "string", "description": "Purpose of the payout (see Purposes reference list)", "example": "SELLER_PAYMENT" } }, "example": { "amount": { "currency": "BRL", "value": 500 }, "country": "BR", "recipient_id": "d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a", "description": "Seller payout - Order #1234", "merchant_reference": "payout-ref-001", "purpose": "SELLER_PAYMENT" } }, "Payout": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "e2f3a4b5-c6d7-8e9f-0a1b-2c3d4e5f6a7b" }, "status": { "type": "string", "enum": [ "SUCCEEDED", "PENDING", "FAILED", "CANCELLED" ], "description": "Current payout status", "example": "PENDING" }, "amount": { "$ref": "#/components/schemas/Amount" }, "country": { "type": "string", "example": "BR" }, "recipient_id": { "type": "string", "format": "uuid", "example": "d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a" }, "merchant_reference": { "type": "string", "example": "payout-ref-001" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-01T16:00:00.000Z" } }, "example": { "id": "e2f3a4b5-c6d7-8e9f-0a1b-2c3d4e5f6a7b", "status": "PENDING", "amount": { "currency": "BRL", "value": 500 }, "country": "BR", "recipient_id": "d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a", "merchant_reference": "payout-ref-001", "created_at": "2026-03-01T16:00:00.000Z" } }, "ReportRequest": { "type": "object", "required": [ "date_range" ], "properties": { "date_range": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time", "description": "Start date in ISO 8601 datetime format", "example": "2026-01-01T00:00:00.000Z" }, "to": { "type": "string", "format": "date-time", "description": "End date in ISO 8601 datetime format", "example": "2026-01-31T23:59:59.999Z" } }, "description": "Date range for the report. Must use datetime format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z'), not date-only format." }, "type": { "type": "string", "description": "Type of report to generate", "example": "TRANSACTIONS" } }, "example": { "date_range": { "from": "2026-02-01T00:00:00.000Z", "to": "2026-02-28T23:59:59.999Z" }, "type": "TRANSACTIONS" } }, "Report": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" }, "status": { "type": "string", "enum": [ "PROCESSING", "COMPLETED", "FAILED" ], "description": "Report generation status", "example": "PROCESSING" }, "date_range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "example": "2026-02-01T00:00:00.000Z" }, "to": { "type": "string", "format": "date-time", "example": "2026-02-28T23:59:59.999Z" } } }, "download_url": { "type": "string", "format": "uri", "description": "URL to download the completed report", "example": "https://reports.y.uno/download/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-01T12:00:00.000Z" } }, "example": { "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "status": "COMPLETED", "date_range": { "from": "2026-02-01T00:00:00.000Z", "to": "2026-02-28T23:59:59.999Z" }, "download_url": "https://reports.y.uno/download/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "created_at": "2026-03-01T12:00:00.000Z" } }, "RecipientRequest": { "type": "object", "required": [ "merchant_recipient_id", "country" ], "properties": { "merchant_recipient_id": { "type": "string", "description": "Your internal recipient identifier", "example": "seller-001" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "pattern": "^[A-Z]{2}$", "example": "BR" }, "name": { "type": "string", "description": "Recipient name", "example": "Carlos Oliveira" }, "email": { "type": "string", "format": "email", "example": "carlos@example.com" }, "document": { "$ref": "#/components/schemas/CustomerDocument" }, "bank_account": { "type": "object", "properties": { "bank_code": { "type": "string", "example": "001" }, "account_number": { "type": "string", "example": "12345-6" }, "account_type": { "type": "string", "enum": [ "CHECKING", "SAVINGS" ], "example": "CHECKING" } } }, "split_configuration": { "type": "object", "description": "Rules for automatic split calculation at the recipient level.", "properties": { "calculation_type": { "type": "string", "description": "The method used to calculate the split amount.", "enum": [ "PERCENTAGE", "FIXED", "MIXED" ], "example": "PERCENTAGE" }, "percentage": { "type": "number", "description": "Percentage of the total payment amount to be split (0.01-100.00). Required if calculation_type is PERCENTAGE or MIXED.", "minimum": 0.01, "maximum": 100, "example": 10.5 }, "fixed_amount": { "type": "number", "description": "Fixed amount to be split. Required if calculation_type is FIXED or MIXED.", "minimum": 0.0001, "example": 5 }, "currency": { "type": "string", "description": "ISO 4217 currency code. Required for all calculation types.", "example": "USD" }, "rounding_mode": { "type": "string", "description": "The rounding strategy for calculated amounts. Required for PERCENTAGE and MIXED.", "enum": [ "STANDARD", "ROUND_UP", "ROUND_DOWN" ], "example": "STANDARD" } } } }, "example": { "merchant_recipient_id": "seller-001", "country": "BR", "name": "Carlos Oliveira", "email": "carlos@example.com", "document": { "document_type": "CPF", "document_number": "98765432100" }, "bank_account": { "bank_code": "001", "account_number": "12345-6", "account_type": "CHECKING" }, "split_configuration": { "calculation_type": "PERCENTAGE", "percentage": 10.5, "rounding_mode": "STANDARD", "currency": "BRL" } } }, "Recipient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a" }, "merchant_recipient_id": { "type": "string", "example": "seller-001" }, "country": { "type": "string", "example": "BR" }, "name": { "type": "string", "example": "Carlos Oliveira" }, "email": { "type": "string", "format": "email", "example": "carlos@example.com" }, "document": { "$ref": "#/components/schemas/CustomerDocument" }, "bank_account": { "type": "object", "properties": { "bank_code": { "type": "string", "example": "001" }, "account_number": { "type": "string", "example": "12345-6" }, "account_type": { "type": "string", "example": "CHECKING" } } }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-01T09:00:00.000Z" }, "split_configuration": { "type": "object", "description": "Rules for automatic split calculation at the recipient level.", "properties": { "calculation_type": { "type": "string", "description": "The method used to calculate the split amount.", "enum": [ "PERCENTAGE", "FIXED", "MIXED" ], "example": "PERCENTAGE" }, "percentage": { "type": "number", "description": "Percentage of the total payment amount to be split (0.01-100.00). Required if calculation_type is PERCENTAGE or MIXED.", "minimum": 0.01, "maximum": 100, "example": 10.5 }, "fixed_amount": { "type": "number", "description": "Fixed amount to be split. Required if calculation_type is FIXED or MIXED.", "minimum": 0.0001, "example": 5 }, "currency": { "type": "string", "description": "ISO 4217 currency code. Required for all calculation types.", "example": "USD" }, "rounding_mode": { "type": "string", "description": "The rounding strategy for calculated amounts. Required for PERCENTAGE and MIXED.", "enum": [ "STANDARD", "ROUND_UP", "ROUND_DOWN" ], "example": "STANDARD" } } } }, "example": { "id": "d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a", "merchant_recipient_id": "seller-001", "country": "BR", "name": "Carlos Oliveira", "email": "carlos@example.com", "document": { "document_type": "CPF", "document_number": "98765432100" }, "bank_account": { "bank_code": "001", "account_number": "12345-6", "account_type": "CHECKING" }, "split_configuration": { "calculation_type": "PERCENTAGE", "percentage": 10.5, "rounding_mode": "STANDARD", "currency": "BRL" }, "created_at": "2026-03-01T09:00:00.000Z" } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code", "example": "INVALID_REQUEST" }, "message": { "type": "string", "description": "Human-readable error description", "example": "The request body contains invalid or missing fields" }, "type": { "type": "string", "description": "Error category", "enum": [ "VALIDATION_ERROR", "AUTHENTICATION_ERROR", "AUTHORIZATION_ERROR", "NOT_FOUND", "CONFLICT", "RATE_LIMIT_ERROR", "INTERNAL_ERROR", "GATEWAY_ERROR" ] }, "details": { "type": "array", "description": "Field-level validation errors", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "JSON path of the invalid field", "example": "customer.document.document_number" }, "message": { "type": "string", "description": "Validation error message", "example": "Must be 11 digits for CPF" }, "code": { "type": "string", "description": "Machine-readable field error code", "example": "INVALID_FORMAT" } } } }, "provider_error": { "type": "object", "description": "Raw error from the payment provider, when available", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "error": { "code": "INVALID_REQUEST", "message": "The request body contains invalid or missing fields" } } }, "WebhookEvent": { "type": "object", "required": [ "type", "data", "timestamp", "webhook_id" ], "properties": { "type": { "type": "string", "enum": [ "payment.succeeded", "payment.failed", "payment.pending", "refund.succeeded", "refund.failed" ], "description": "The type of webhook event", "example": "payment.succeeded" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/PaymentWebhookData" } ], "description": "Event-specific data payload" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event occurred", "example": "2026-03-01T14:31:05.000Z" }, "webhook_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this webhook delivery (use for deduplication)", "example": "wh_7a8b9c0d-1e2f-3456-7890-abcdef123456" } }, "example": { "type": "payment.succeeded", "data": { "payment_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", "provider_transaction_id": "pi_3abc123def456", "merchant_order_id": "order-20260301-001" }, "timestamp": "2026-03-01T14:31:05.000Z", "webhook_id": "wh_7a8b9c0d-1e2f-3456-7890-abcdef123456" } }, "PaymentWebhookData": { "type": "object", "properties": { "payment_id": { "type": "string", "format": "uuid", "description": "The payment identifier", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "checkout_session": { "type": "string", "format": "uuid", "description": "The checkout session identifier", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "status": { "type": "string", "enum": [ "SUCCEEDED", "PENDING", "DECLINED", "REJECTED", "CANCELLED", "REFUNDED", "PARTIALLY_REFUNDED" ], "description": "The payment status that triggered this event", "example": "SUCCEEDED" }, "amount": { "$ref": "#/components/schemas/Amount" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "BR" }, "payment_method_type": { "type": "string", "description": "The payment method used", "example": "CARD" }, "provider_name": { "type": "string", "description": "The provider that processed the payment", "example": "stripe_connect" }, "provider_transaction_id": { "type": "string", "description": "The provider's transaction reference", "example": "pi_3abc123def456" }, "merchant_order_id": { "type": "string", "description": "Your unique order identifier", "example": "order-20260301-001" }, "refund_amount": { "$ref": "#/components/schemas/Amount", "description": "Refund amount (only present for refund events)" }, "refund_reason": { "type": "string", "description": "Reason for refund (only present for refund events)", "example": "Customer requested partial refund" }, "decline_reason": { "type": "string", "description": "Reason for decline (only present for payment.failed events)", "example": "insufficient_funds" } }, "example": { "payment_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", "provider_transaction_id": "pi_3abc123def456", "merchant_order_id": "order-20260301-001" } }, "FulfillmentNotification": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "SHIPPED", "DELIVERED", "RETURNED" ], "description": "Fulfillment status" }, "tracking_number": { "type": "string", "description": "Shipment tracking number" }, "carrier": { "type": "string", "description": "Shipping carrier name" }, "shipped_at": { "type": "string", "format": "date-time", "description": "Shipment date" } } }, "DisputeUpdate": { "type": "object", "properties": { "evidence": { "type": "object", "properties": { "description": { "type": "string", "description": "Evidence description" }, "documents": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "URLs of supporting documents" } } }, "status": { "type": "string", "enum": [ "EVIDENCE_SUBMITTED", "ACCEPTED" ], "description": "New dispute status" } } }, "Dispute": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "payment_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "OPEN", "EVIDENCE_SUBMITTED", "WON", "LOST", "ACCEPTED" ] }, "amount": { "$ref": "#/components/schemas/Amount" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Subscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "CANCELLED", "PAST_DUE", "EXPIRED" ] }, "amount": { "$ref": "#/components/schemas/Amount" }, "interval": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "YEARLY" ] }, "next_payment_date": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Onboarding": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "recipient_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "IN_PROGRESS", "BLOCKED", "COMPLETED", "FAILED" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OnboardingTransferRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "description": { "type": "string", "description": "Transfer description" } } }, "OnboardingTransfer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "onboarding_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "REVERSED", "FAILED" ] }, "amount": { "$ref": "#/components/schemas/Amount" }, "description": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RecoverPaymentRequest": { "type": "object", "required": [ "payment_id" ], "properties": { "payment_id": { "type": "string", "format": "uuid", "description": "The declined payment to recover" }, "channel": { "type": "string", "enum": [ "PHONE", "SMS", "EMAIL", "WHATSAPP" ], "description": "Outreach channel" }, "language": { "type": "string", "description": "Language code (e.g., pt-BR, es-MX)", "example": "pt-BR" } } }, "RecoverAbandonedRequest": { "type": "object", "required": [ "checkout_session" ], "properties": { "checkout_session": { "type": "string", "format": "uuid", "description": "The abandoned checkout session" }, "channel": { "type": "string", "enum": [ "PHONE", "SMS", "EMAIL", "WHATSAPP" ], "description": "Outreach channel" }, "language": { "type": "string", "description": "Language code", "example": "pt-BR" } } }, "RecoveryAttempt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "QUEUED", "IN_PROGRESS", "COMPLETED", "FAILED" ] }, "channel": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "CampaignRequest": { "type": "object", "required": [ "name", "start_date", "end_date", "country" ], "properties": { "name": { "type": "string", "description": "Campaign name" }, "description": { "type": "string", "description": "Campaign description" }, "start_date": { "type": "string", "format": "date-time", "description": "Campaign start date" }, "end_date": { "type": "string", "format": "date-time", "description": "Campaign end date" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code" } } }, "Campaign": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "DRAFT", "EXPIRED" ] }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "country": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CampaignRuleRequest": { "type": "object", "required": [ "campaign_id", "name", "conditions", "benefit" ], "properties": { "campaign_id": { "type": "string", "format": "uuid", "description": "Associated campaign ID" }, "name": { "type": "string", "description": "Rule name" }, "conditions": { "type": "object", "properties": { "payment_method": { "type": "string", "description": "Payment method filter" }, "min_amount": { "type": "number", "description": "Minimum transaction amount" }, "max_amount": { "type": "number", "description": "Maximum transaction amount" }, "bin_range": { "type": "string", "description": "Card BIN range filter" } } }, "benefit": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "DISCOUNT", "CASHBACK", "INSTALLMENT_RATE" ], "description": "Benefit type" }, "value": { "type": "number", "description": "Benefit value" }, "unit": { "type": "string", "enum": [ "PERCENTAGE", "FIXED" ], "description": "Benefit unit" } } } } }, "CampaignRule": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ] }, "conditions": { "type": "object" }, "benefit": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CustomerSession": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "cs_a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "customer_id": { "type": "string", "format": "uuid", "example": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f" }, "status": { "type": "string", "enum": [ "ACTIVE", "EXPIRED" ], "example": "ACTIVE" }, "sdk_token": { "type": "string", "description": "Token for SDK initialization", "example": "sdk_tok_abc123def456" }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-03-01T15:30:00.000Z" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-01T14:30:00.000Z" } }, "example": { "id": "cs_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "customer_id": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f", "status": "ACTIVE", "sdk_token": "sdk_tok_abc123def456", "expires_at": "2026-03-01T15:30:00.000Z", "created_at": "2026-03-01T14:30:00.000Z" } }, "CustomerSessionRequest": { "type": "object", "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "The customer to create a session for", "example": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f" }, "merchant_customer_id": { "type": "string", "description": "Alternative: your internal customer identifier", "example": "cust-internal-001" } }, "example": { "customer_id": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f" } }, "PaymentMethod": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "pm_1a2b3c4d-5e6f-7890-abcd-ef1234567890" }, "customer_id": { "type": "string", "format": "uuid", "example": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f" }, "type": { "type": "string", "enum": [ "CARD", "PIX", "BOLETO", "PSE", "SPEI", "OXXO" ], "example": "CARD" }, "status": { "type": "string", "enum": [ "ACTIVE", "EXPIRED", "REVOKED" ], "example": "ACTIVE" }, "card": { "type": "object", "properties": { "last_four": { "type": "string", "example": "4242" }, "brand": { "type": "string", "example": "VISA" }, "expiry_month": { "type": "integer", "example": 12 }, "expiry_year": { "type": "integer", "example": 2028 } } }, "vaulted_token": { "type": "string", "description": "Token for reuse in future payments", "example": "vtok_9f8e7d6c-5b4a-3210-fedc-ba9876543210" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-01T10:00:00.000Z" } }, "example": { "id": "pm_1a2b3c4d-5e6f-7890-abcd-ef1234567890", "customer_id": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f", "type": "CARD", "status": "ACTIVE", "card": { "last_four": "4242", "brand": "VISA", "expiry_month": 12, "expiry_year": 2028 }, "vaulted_token": "vtok_9f8e7d6c-5b4a-3210-fedc-ba9876543210", "created_at": "2026-03-01T10:00:00.000Z" } }, "PaymentMethodEnrollRequest": { "type": "object", "required": [ "type", "token" ], "properties": { "type": { "type": "string", "enum": [ "CARD", "PIX", "BOLETO", "PSE", "SPEI", "OXXO" ], "description": "Payment method type", "example": "CARD" }, "token": { "type": "string", "description": "One-time token from SDK tokenization", "example": "tok_4a8b9c2d-1e3f-5678-90ab-cdef12345678" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "pattern": "^[A-Z]{2}$", "example": "BR" } }, "example": { "type": "CARD", "token": "tok_4a8b9c2d-1e3f-5678-90ab-cdef12345678", "country": "BR" } }, "PaymentLink": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "pl_a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "url": { "type": "string", "format": "uri", "description": "Shareable payment link URL", "example": "https://pay.y.uno/pl_a1b2c3d4" }, "amount": { "$ref": "#/components/schemas/Amount" }, "country": { "type": "string", "example": "BR" }, "status": { "type": "string", "enum": [ "ACTIVE", "COMPLETED", "CANCELLED", "EXPIRED" ], "example": "ACTIVE" }, "description": { "type": "string", "example": "Invoice #INV-2026-001" }, "merchant_order_id": { "type": "string", "example": "order-link-001" }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-03-08T23:59:59.000Z" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-01T14:00:00.000Z" } }, "example": { "id": "pl_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "url": "https://pay.y.uno/pl_a1b2c3d4", "amount": { "currency": "BRL", "value": 250 }, "country": "BR", "status": "ACTIVE", "description": "Invoice #INV-2026-001", "merchant_order_id": "order-link-001", "expires_at": "2026-03-08T23:59:59.000Z", "created_at": "2026-03-01T14:00:00.000Z" } }, "PaymentLinkRequest": { "type": "object", "required": [ "amount", "country" ], "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "pattern": "^[A-Z]{2}$", "example": "BR" }, "description": { "type": "string", "description": "Payment description shown to customer", "example": "Invoice #INV-2026-001" }, "merchant_order_id": { "type": "string", "description": "Your unique order identifier", "example": "order-link-001" }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration date for the link", "example": "2026-03-08T23:59:59.000Z" } }, "example": { "amount": { "currency": "BRL", "value": 250 }, "country": "BR", "description": "Invoice #INV-2026-001", "merchant_order_id": "order-link-001", "expires_at": "2026-03-08T23:59:59.000Z" } }, "CurrencyConversion": { "type": "object", "properties": { "from": { "type": "string", "description": "Source currency code", "example": "USD" }, "to": { "type": "string", "description": "Target currency code", "example": "BRL" }, "rate": { "type": "number", "description": "Exchange rate", "example": 5.12 }, "amount": { "type": "number", "description": "Original amount", "example": 100 }, "converted_amount": { "type": "number", "description": "Converted amount", "example": 512 }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-03-01T14:00:00.000Z" } }, "example": { "from": "USD", "to": "BRL", "rate": 5.12, "amount": 100, "converted_amount": 512, "timestamp": "2026-03-01T14:00:00.000Z" } }, "SubscriptionRequest": { "type": "object", "required": [ "customer_id", "amount", "country", "interval" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "The customer for this subscription", "example": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f" }, "amount": { "$ref": "#/components/schemas/Amount" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "pattern": "^[A-Z]{2}$", "example": "BR" }, "interval": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "YEARLY" ], "description": "Billing interval", "example": "MONTHLY" }, "payment_method_id": { "type": "string", "format": "uuid", "description": "Enrolled payment method to charge", "example": "pm_1a2b3c4d-5e6f-7890-abcd-ef1234567890" }, "description": { "type": "string", "description": "Subscription description", "example": "Premium Plan - Monthly" }, "start_date": { "type": "string", "format": "date-time", "description": "When to start billing", "example": "2026-03-01T00:00:00.000Z" } }, "example": { "customer_id": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f", "amount": { "currency": "BRL", "value": 49.9 }, "country": "BR", "interval": "MONTHLY", "payment_method_id": "pm_1a2b3c4d-5e6f-7890-abcd-ef1234567890", "description": "Premium Plan - Monthly", "start_date": "2026-03-01T00:00:00.000Z" } }, "DisputeRequest": { "type": "object", "required": [ "reason", "amount" ], "properties": { "reason": { "type": "string", "description": "Reason for the dispute", "example": "Customer claims item not received" }, "amount": { "$ref": "#/components/schemas/Amount" }, "evidence": { "type": "object", "properties": { "description": { "type": "string", "description": "Evidence description" }, "documents": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "URLs of supporting documents" } } } }, "example": { "reason": "Customer claims item not received", "amount": { "currency": "BRL", "value": 150 } } }, "WebhookRegistration": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "wh_a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/yuno" }, "events": { "type": "array", "items": { "type": "string" }, "example": [ "payment.succeeded", "payment.failed", "payment.refunded" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "example": "ACTIVE" }, "secret": { "type": "string", "description": "Shared secret for HMAC signature verification", "example": "whsec_abc123def456" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-01T10:00:00.000Z" } }, "example": { "id": "wh_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "url": "https://example.com/webhooks/yuno", "events": [ "payment.succeeded", "payment.failed", "payment.refunded" ], "status": "ACTIVE", "secret": "whsec_abc123def456", "created_at": "2026-03-01T10:00:00.000Z" } }, "WebhookRegistrationRequest": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL", "example": "https://example.com/webhooks/yuno" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types to subscribe to", "example": [ "payment.succeeded", "payment.failed", "payment.refunded" ] }, "secret": { "type": "string", "description": "Shared secret for signature verification", "example": "whsec_abc123def456" } }, "example": { "url": "https://example.com/webhooks/yuno", "events": [ "payment.succeeded", "payment.failed", "payment.refunded" ], "secret": "whsec_abc123def456" } }, "Transaction": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "APPROVED", "DECLINED", "ERROR", "PENDING" ] }, "provider": { "type": "string", "description": "Provider that processed this attempt" }, "provider_transaction_id": { "type": "string" }, "response_code": { "type": "string" }, "response_message": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "RefundRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "amount": { "$ref": "#/components/schemas/Amount" }, "status": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED" ] }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } }