{ "openapi": "3.1.0", "info": { "title": "YuvexPay API", "description": "The YuvexPay API allows you to accept payments, process withdrawals, manage products and customers programmatically. All API access is over HTTPS and uses JSON request/response bodies.", "version": "1.0.0", "contact": { "name": "YuvexPay Support", "email": "support@yuvexpay.com", "url": "https://docs.yuvexpay.com" } }, "servers": [ { "url": "https://api.yuvexpay.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Authentication", "description": "OAuth 2.0 client credentials flow" }, { "name": "Payments", "description": "Create and manage payments" }, { "name": "Withdrawals", "description": "Create and manage withdrawals" }, { "name": "Products", "description": "Manage product catalog" }, { "name": "Customers", "description": "Manage customer records" }, { "name": "Documents", "description": "Generate receipts and statements" } ], "paths": { "/oauth/token": { "post": { "operationId": "createToken", "summary": "Generate access token", "description": "Exchange your API credentials for a short-lived access token using the OAuth 2.0 client credentials flow. Tokens expire after 1 hour. A maximum of 2 active tokens per credential is enforced.", "tags": [ "Authentication" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "client_secret", "grant_type" ], "properties": { "client_id": { "type": "string", "description": "Your API client ID, found in the dashboard under API credentials." }, "client_secret": { "type": "string", "description": "Your API client secret." }, "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "Must be `client_credentials`." } } }, "example": { "client_id": "cred_abc123", "client_secret": "secret_xyz789", "grant_type": "client_credentials" } } } }, "responses": { "200": { "description": "Token generated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The Bearer token to use in API requests. Access tokens are prefixed with `ypt_`." }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "Token validity in seconds (3600 = 1 hour)." }, "company_id": { "type": "string", "description": "The company ID associated with this token." }, "company_name": { "type": "string", "description": "The company name." } } }, "example": { "access_token": "ypt_abc123example", "token_type": "Bearer", "expires_in": 3600, "company_id": "comp_abc123", "company_name": "My Store" } } } }, "401": { "description": "Invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } } } } }, "/v1/payments": { "post": { "operationId": "createPayment", "summary": "Create a payment", "description": "Create a new payment. Supports PIX, direct credit card charges for headless single-method CARD flows, hosted card checkout, and boleto. Requires an idempotency key.", "tags": [ "Payments" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" }, "example": { "amount": 49.9, "methods": [ "PIX" ], "currency": "BRL", "mode": "headless", "description": "Order #1234", "externalId": "order-1234", "expiresInMinutes": 30, "customer": { "name": "Maria Silva", "email": "maria@example.com", "phone": "+5511999999999", "document": "12345678900" }, "metadata": { "order_id": "1234", "source": "website" } }, "examples": { "headlessPix": { "summary": "Headless PIX payment", "value": { "amount": 49.9, "methods": [ "PIX" ], "currency": "BRL", "mode": "headless", "description": "Order #1234", "externalId": "order-1234", "expiresInMinutes": 30, "customer": { "name": "Maria Silva", "email": "maria@example.com", "phone": "+5511999999999", "document": "12345678900" }, "metadata": { "order_id": "1234", "source": "website" } } }, "headlessCardDirect": { "summary": "Headless direct credit CARD payment", "value": { "amount": 149.9, "methods": [ "CARD" ], "currency": "BRL", "mode": "headless", "description": "Order #5678", "externalId": "order-5678", "customer": { "name": "Maria Silva", "email": "maria@example.com", "phone": "+5511999999999", "document": "12345678900" }, "card": { "number": "4111111111111111", "expiryMonth": "12", "expiryYear": "2030", "ccv": "123", "installments": 1, "remoteIp": "198.51.100.23", "holderInfo": { "postalCode": "01310930", "addressNumber": "100", "phone": "+5511999999999" } } } } } } } }, "responses": { "201": { "description": "Payment created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentResponse" }, "examples": { "headlessPix": { "summary": "Headless PIX payment", "value": { "payment": { "id": "pay_abc123", "txId": "PAY_ABC123XYZ", "amount": 49.9, "feeAmount": 2.99, "netAmount": 46.91, "status": "NEW", "paymentMethod": "PIX", "currency": "BRL", "description": "Order #1234", "expiresAt": "2026-04-14T13:30:00.000Z", "createdAt": "2026-04-14T13:00:00.000Z", "methodData": { "type": "PIX", "pixCopyPaste": "00020126...", "qrCodeBase64": "data:image/png;base64,...", "qrCodeUrl": null } } } }, "headlessCardDirect": { "summary": "Headless direct credit CARD payment", "value": { "payment": { "id": "pay_card123", "txId": "PAY_CARD123XYZ", "amount": 149.9, "feeAmount": 8.25, "netAmount": 141.65, "status": "PENDING", "paymentMethod": "CARD", "currency": "BRL", "description": "Order #5678", "expiresAt": "2026-04-14T13:30:00.000Z", "createdAt": "2026-04-14T13:00:00.000Z", "methodData": { "type": "CARD", "captureType": "DIRECT", "cardSubtype": "CREDIT", "brand": "VISA", "last4Digits": "1111", "installments": 1 } } } }, "hostedCheckout": { "summary": "Hosted multi-method checkout", "value": { "payment": { "id": "pay_hosted123", "txId": "PAY_HOSTED123XYZ", "amount": 49.9, "feeAmount": 2.99, "netAmount": 46.91, "status": "PENDING_METHOD_SELECTION", "methods": [ "PIX", "CARD" ], "currency": "BRL", "checkoutUrl": "https://checkout.yuvexpay.com/checkout/pay_hosted123", "expiresAt": "2026-04-14T13:30:00.000Z", "isSandbox": true, "createdAt": "2026-04-14T13:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "operationId": "listPayments", "summary": "List payments", "description": "Retrieve a paginated list of payments with optional filters.", "tags": [ "Payments" ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/PaymentStatus" }, "description": "Filter by payment status." }, { "name": "method", "in": "query", "schema": { "$ref": "#/components/schemas/PaymentMethod" }, "description": "Filter by payment method." }, { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Start of date range (ISO 8601)." }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "End of date range (ISO 8601)." }, { "name": "minAmount", "in": "query", "schema": { "type": "number" }, "description": "Minimum payment amount." }, { "name": "maxAmount", "in": "query", "schema": { "type": "number" }, "description": "Maximum payment amount." }, { "name": "externalId", "in": "query", "schema": { "type": "string" }, "description": "Filter by your external ID." }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Payments listed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/payments/{paymentId}": { "get": { "operationId": "getPayment", "summary": "Get a payment", "description": "Retrieve a single payment by its ID.", "tags": [ "Payments" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The payment ID." } ], "responses": { "200": { "description": "Payment found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "$ref": "#/components/schemas/Payment" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/payments/txid/{txId}": { "get": { "operationId": "getPaymentByTxId", "summary": "Get payment by transaction ID", "description": "Retrieve a payment using the YuvexPay transaction ID (`txId`) instead of the UUID.", "tags": [ "Payments" ], "parameters": [ { "name": "txId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The YuvexPay transaction ID." } ], "responses": { "200": { "description": "Payment found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "$ref": "#/components/schemas/Payment" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/payments/{paymentId}/refund": { "post": { "operationId": "refundPayment", "summary": "Refund a payment", "description": "Issue a full or partial refund for a paid payment. Requires an idempotency key.", "tags": [ "Payments" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The payment ID to refund." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundPaymentRequest" }, "example": { "amount": 25, "reason": "Customer requested refund" } } } }, "responses": { "200": { "description": "Refund created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "refund": { "$ref": "#/components/schemas/Refund" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } } } }, "/v1/payments/{paymentId}/refunds": { "get": { "operationId": "listRefunds", "summary": "List refunds", "description": "Retrieve all refunds for a specific payment.", "tags": [ "Payments" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The payment ID." } ], "responses": { "200": { "description": "Refunds listed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/withdrawals": { "post": { "operationId": "createWithdrawal", "summary": "Create a withdrawal", "description": "Create a PIX withdrawal to transfer BRL funds from your YuvexPay balance. Requires an idempotency key. Withdrawals may be blocked outside business hours or if your account has restrictions.", "tags": [ "Withdrawals" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWithdrawalRequest" }, "examples": { "pix": { "summary": "PIX withdrawal", "value": { "amount": 500, "method": "PIX", "currency": "BRL", "destination": { "type": "pix", "pixKey": "12345678900", "recipientDocument": "12345678900" }, "description": "Weekly payout" } } } } } }, "responses": { "201": { "description": "Withdrawal created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawal": { "$ref": "#/components/schemas/Withdrawal" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Withdrawals blocked for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "operationId": "listWithdrawals", "summary": "List withdrawals", "description": "Retrieve a paginated list of withdrawals with optional filters.", "tags": [ "Withdrawals" ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/WithdrawalStatus" }, "description": "Filter by withdrawal status." }, { "name": "method", "in": "query", "schema": { "type": "string", "enum": [ "PIX" ] }, "description": "Filter by withdrawal method. Public withdrawals currently support PIX only." }, { "name": "currency", "in": "query", "schema": { "type": "string", "enum": [ "BRL" ] }, "description": "Filter by currency. Public withdrawals currently support BRL only." }, { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Start of date range (ISO 8601)." }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "End of date range (ISO 8601)." }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Withdrawals listed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawals": { "type": "array", "items": { "$ref": "#/components/schemas/Withdrawal" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/withdrawals/limits": { "get": { "operationId": "getWithdrawalLimits", "summary": "Get withdrawal limits", "description": "Retrieve your current daily withdrawal limits, usage, and fee information. Limits are reduced during nighttime hours (22:00-06:00 BRT).", "tags": [ "Withdrawals" ], "responses": { "200": { "description": "Limits retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalLimits" }, "example": { "currentLimit": 5000, "used": 1200, "remaining": 3800, "isNightTime": false, "fee": 2.49, "dayStartHour": 6, "dayEndHour": 22 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/withdrawals/{withdrawalId}": { "get": { "operationId": "getWithdrawal", "summary": "Get a withdrawal", "description": "Retrieve a single withdrawal by its ID.", "tags": [ "Withdrawals" ], "parameters": [ { "name": "withdrawalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The withdrawal ID." } ], "responses": { "200": { "description": "Withdrawal found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawal": { "$ref": "#/components/schemas/Withdrawal" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/products": { "post": { "operationId": "createProduct", "summary": "Create a product", "description": "Create a new product in your catalog. Products can be referenced when creating payments to pre-fill amount and description.", "tags": [ "Products" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductRequest" }, "example": { "name": "Premium Plan", "description": "Monthly premium subscription", "amount": 99.9, "externalId": "plan-premium", "metadata": { "tier": "premium", "billing": "monthly" } } } } }, "responses": { "201": { "description": "Product created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } } }, "get": { "operationId": "listProducts", "summary": "List products", "description": "Retrieve a paginated list of products with optional search and filters.", "tags": [ "Products" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search products by name." }, { "name": "isActive", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Filter by active status." }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Products listed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/PaginationWithPages" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/products/{productId}": { "get": { "operationId": "getProduct", "summary": "Get a product", "description": "Retrieve a single product by its ID.", "tags": [ "Products" ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The product ID." } ], "responses": { "200": { "description": "Product found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateProduct", "summary": "Update a product", "description": "Update one or more fields of an existing product.", "tags": [ "Products" ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The product ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductRequest" } } } }, "responses": { "200": { "description": "Product updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteProduct", "summary": "Deactivate a product", "description": "Soft-delete a product by setting it as inactive. The product data is preserved but it can no longer be used in new payments.", "tags": [ "Products" ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The product ID." } ], "responses": { "200": { "description": "Product deactivated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/products/external/{externalId}": { "get": { "operationId": "getProductByExternalId", "summary": "Get product by external ID", "description": "Retrieve a product using your own external ID instead of the YuvexPay UUID.", "tags": [ "Products" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 }, "description": "Your external product ID." } ], "responses": { "200": { "description": "Product found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/customers": { "post": { "operationId": "createCustomer", "summary": "Create a customer", "description": "Create a new customer record. Customers can be associated with payments for tracking and recurring billing.", "tags": [ "Customers" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" }, "example": { "name": "Maria Silva", "email": "maria@example.com", "document": "12345678900", "documentType": "CPF", "phone": "+5511999999999", "externalId": "cust-001", "metadata": { "plan": "premium" } } } } }, "responses": { "201": { "description": "Customer created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } } }, "get": { "operationId": "listCustomers", "summary": "List customers", "description": "Retrieve a paginated list of customers with optional search and filters.", "tags": [ "Customers" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search by name, email, or document." }, { "name": "isActive", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Filter by active status." }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Customers listed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "pagination": { "$ref": "#/components/schemas/PaginationWithPages" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/customers/{customerId}": { "get": { "operationId": "getCustomer", "summary": "Get a customer", "description": "Retrieve a single customer by their ID, including metadata.", "tags": [ "Customers" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The customer ID." } ], "responses": { "200": { "description": "Customer found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/CustomerDetail" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateCustomer", "summary": "Update a customer", "description": "Update one or more fields of an existing customer.", "tags": [ "Customers" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The customer ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerRequest" } } } }, "responses": { "200": { "description": "Customer updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteCustomer", "summary": "Deactivate a customer", "description": "Soft-delete a customer by setting them as inactive. Customer data is preserved.", "tags": [ "Customers" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The customer ID." } ], "responses": { "200": { "description": "Customer deactivated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/customers/external/{externalId}": { "get": { "operationId": "getCustomerByExternalId", "summary": "Get customer by external ID", "description": "Retrieve a customer using your own external ID instead of the YuvexPay UUID.", "tags": [ "Customers" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 }, "description": "Your external customer ID." } ], "responses": { "200": { "description": "Customer found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/documents/payments/{paymentId}/receipt": { "get": { "operationId": "getPaymentReceipt", "summary": "Get payment receipt", "description": "Generate a receipt document for a specific payment. Available in HTML or plain text format.", "tags": [ "Documents" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The payment ID." }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "html", "text" ], "default": "html" }, "description": "Output format." } ], "responses": { "200": { "description": "Receipt generated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "The receipt content in the requested format." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/documents/withdrawals/{withdrawalId}/receipt": { "get": { "operationId": "getWithdrawalReceipt", "summary": "Get withdrawal receipt", "description": "Generate a receipt document for a specific withdrawal. Available in HTML or plain text format.", "tags": [ "Documents" ], "parameters": [ { "name": "withdrawalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The withdrawal ID." }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "html", "text" ], "default": "html" }, "description": "Output format." } ], "responses": { "200": { "description": "Receipt generated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "The receipt content in the requested format." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/documents/statements": { "get": { "operationId": "getStatement", "summary": "Get account statement", "description": "Generate an account statement for a date range. Maximum range is 90 days.", "tags": [ "Documents" ], "parameters": [ { "name": "startDate", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "Start date in `YYYY-MM-DD` format.", "example": "2026-01-01" }, { "name": "endDate", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "End date in `YYYY-MM-DD` format.", "example": "2026-01-31" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "html", "text" ], "default": "html" }, "description": "Output format." } ], "responses": { "200": { "description": "Statement generated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "The statement content in the requested format." } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "webhooks": { "payment.paid": { "post": { "summary": "Payment paid", "description": "Triggered when a payment is confirmed and funds are received.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_abc123", "type": "PAYMENT_PAID", "data": { "id": "pay_xyz789", "txId": "YVX-20260414-ABC", "status": "PAID", "amount": 49.9 } } } } }, "responses": { "200": { "description": "Return a 2xx status to acknowledge receipt." } } } }, "payment.expired": { "post": { "summary": "Payment expired", "description": "Triggered when a payment expires before being completed.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Return a 2xx status to acknowledge receipt." } } } }, "payment.refunded": { "post": { "summary": "Payment refunded", "description": "Triggered when a payment refund is completed.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Return a 2xx status to acknowledge receipt." } } } }, "withdrawal.sent": { "post": { "summary": "Withdrawal sent", "description": "Triggered when a withdrawal is successfully processed.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Return a 2xx status to acknowledge receipt." } } } }, "withdrawal.failed": { "post": { "summary": "Withdrawal failed", "description": "Triggered when a withdrawal fails to process.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Return a 2xx status to acknowledge receipt." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API access token obtained from POST /oauth/token. Include as `Authorization: Bearer {token}`." } }, "parameters": { "IdempotencyKey": { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 100 }, "description": "A unique string to ensure the request is processed only once. Must be unique per request. Valid for 24 hours." }, "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number for pagination." }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of items per page (1-100)." } }, "schemas": { "PaymentMethod": { "type": "string", "enum": [ "PIX", "CARD", "BOLETO" ], "description": "Available public payment methods." }, "Currency": { "type": "string", "enum": [ "BRL" ], "description": "Supported currencies." }, "PaymentStatus": { "type": "string", "enum": [ "NEW", "PENDING_METHOD_SELECTION", "PROCESSING", "CONFIRMED", "PAID", "CANCELLED", "EXPIRED", "REFUNDED", "PARTIAL_REFUND", "CHARGEBACK", "MED_FROZEN" ], "description": "Possible payment statuses." }, "WithdrawalStatus": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "description": "Possible withdrawal statuses." }, "TransactionStatus": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED", "REFUNDED" ], "description": "Generic transaction status." }, "WebhookEventType": { "type": "string", "enum": [ "PAYMENT_CONFIRMED", "PAYMENT_PAID", "PAYMENT_EXPIRED", "PAYMENT_REFUNDED", "PAYMENT_REFUND_FAILED", "PAYMENT_CHARGEBACK", "MED_RECEIVED", "MED_RESOLVED", "WITHDRAWAL_REQUESTED", "WITHDRAWAL_SENT", "WITHDRAWAL_FAILED" ], "description": "Supported webhook event types." }, "CreatePaymentRequest": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "description": "Link this payment to an existing product. If set, `amount` is optional and defaults to the product price." }, "customerId": { "type": "string", "format": "uuid", "description": "Link this payment to an existing customer. For CARD and BOLETO, the linked customer must have name and CPF/CNPJ." }, "amount": { "type": "number", "minimum": 0.01, "maximum": 1000000, "description": "Payment amount. Required unless `productId` is provided." }, "methods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" }, "minItems": 1, "default": [ "PIX" ], "description": "Accepted payment methods. Headless payments must use exactly one method." }, "currency": { "$ref": "#/components/schemas/Currency", "default": "BRL" }, "mode": { "type": "string", "enum": [ "hosted", "headless" ], "default": "headless", "description": "hosted redirects the payer to a YuvexPay checkout page. headless returns method data directly for a single payment method. Headless CARD requires the card payload for direct credit card capture. Hosted or multi-method CARD flows continue through checkout/provider invoice URLs, where debit remains available." }, "returnUrl": { "type": "string", "format": "uri", "description": "URL to redirect the payer after payment (hosted mode)." }, "completionUrl": { "type": "string", "format": "uri", "description": "URL to redirect the payer after successful payment completion." }, "description": { "type": "string", "maxLength": 500, "description": "Payment description shown to the payer." }, "externalId": { "type": "string", "maxLength": 100, "description": "Your own reference ID (e.g., order number)." }, "expiresInMinutes": { "type": "integer", "minimum": 5, "maximum": 1440, "default": 60, "description": "Minutes until the payment expires (5-1440)." }, "customer": { "type": "object", "description": "Inline customer data. For CARD and BOLETO, include at least name and CPF/CNPJ unless you use customerId.", "properties": { "name": { "type": "string", "description": "Payer name. Required for CARD and BOLETO when not using customerId." }, "document": { "type": "string", "description": "CPF or CNPJ. Required for CARD and BOLETO when not using customerId." }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "description": "Payer phone number in national or international format." } } }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Arbitrary key-value pairs attached to the payment." }, "card": { "type": "object", "description": "Direct credit card charge payload. Allowed only for headless single-method CARD payments and required in that flow.", "properties": { "number": { "type": "string", "description": "Primary account number (PAN), 13-19 digits." }, "expiryMonth": { "type": "string", "description": "Expiration month as 1-2 digits." }, "expiryYear": { "type": "string", "description": "Expiration year as 4 digits." }, "ccv": { "type": "string", "description": "Card security code (3-4 digits)." }, "installments": { "type": "integer", "minimum": 1, "maximum": 12, "default": 1, "description": "Installment count for direct credit card charges." }, "remoteIp": { "type": "string", "description": "Customer IP address required by the acquiring flow." }, "holderInfo": { "type": "object", "description": "Supplemental cardholder billing data. `postalCode` and `addressNumber` are required.", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "document": { "type": "string", "description": "CPF or CNPJ for the cardholder." }, "postalCode": { "type": "string" }, "addressNumber": { "type": "string" }, "addressComplement": { "type": "string" }, "phone": { "type": "string" }, "mobilePhone": { "type": "string" } }, "required": [ "postalCode", "addressNumber" ] } }, "required": [ "number", "expiryMonth", "expiryYear", "ccv", "remoteIp", "holderInfo" ] } } }, "RefundPaymentRequest": { "type": "object", "properties": { "amount": { "type": "number", "minimum": 0.01, "description": "Refund amount. Omit for a full refund." }, "reason": { "type": "string", "maxLength": 500, "description": "Reason for the refund." } } }, "CreateWithdrawalRequest": { "type": "object", "required": [ "amount", "destination" ], "properties": { "amount": { "type": "number", "minimum": 10, "maximum": 1000000, "multipleOf": 0.01, "description": "Withdrawal amount (minimum R$10.00)." }, "method": { "type": "string", "enum": [ "PIX" ], "default": "PIX", "description": "Public withdrawals currently support PIX only." }, "currency": { "type": "string", "enum": [ "BRL" ], "default": "BRL" }, "destination": { "description": "Where to send the funds.", "type": "object", "title": "PIX destination", "required": [ "type", "pixKey" ], "properties": { "type": { "type": "string", "enum": [ "pix" ] }, "pixKey": { "type": "string", "minLength": 1, "description": "PIX key (CPF, CNPJ, email, phone, or random key)." }, "recipientDocument": { "type": "string", "minLength": 11, "maxLength": 18, "description": "Recipient CPF or CNPJ for validation." } } }, "description": { "type": "string", "maxLength": 500, "description": "Internal description for this withdrawal." } } }, "CreateProductRequest": { "type": "object", "required": [ "name" ], "properties": { "externalId": { "type": "string", "maxLength": 100, "description": "Your own product ID." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Product name." }, "description": { "type": "string", "maxLength": 1000, "description": "Product description." }, "amount": { "type": "number", "minimum": 0.01, "maximum": 1000000, "description": "Default price." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "UpdateProductRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "amount": { "type": [ "number", "null" ], "minimum": 0.01, "maximum": 1000000, "description": "Set to `null` to remove the default price." }, "isActive": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "CreateCustomerRequest": { "type": "object", "properties": { "externalId": { "type": "string", "maxLength": 100, "description": "Your own customer ID." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "document": { "type": "string", "maxLength": 20, "description": "CPF or CNPJ number." }, "documentType": { "type": "string", "enum": [ "CPF", "CNPJ" ] }, "phone": { "type": "string", "maxLength": 20 }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "UpdateCustomerRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "document": { "type": "string", "maxLength": 20 }, "documentType": { "type": "string", "enum": [ "CPF", "CNPJ" ] }, "phone": { "type": "string", "maxLength": 20 }, "isActive": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "txId": { "type": "string", "description": "YuvexPay transaction ID." }, "amount": { "type": "number" }, "feeAmount": { "type": "number" }, "netAmount": { "type": "number" }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod" }, "currency": { "$ref": "#/components/schemas/Currency" }, "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "methodData": { "type": "object", "description": "Payment method-specific data (QR code for PIX, barcode for boleto, etc.).", "properties": { "type": { "$ref": "#/components/schemas/PaymentMethod" } }, "additionalProperties": true } } }, "Refund": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "txId": { "type": "string" }, "amount": { "type": "number" }, "reason": { "type": "string" }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "processedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Withdrawal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "txId": { "type": "string" }, "grossAmount": { "type": "number" }, "feeAmount": { "type": "number" }, "netAmount": { "type": "number" }, "pixKey": { "type": "string" }, "pixKeyType": { "type": "string", "description": "Type of PIX key (CPF, CNPJ, EMAIL, PHONE, RANDOM)." }, "status": { "$ref": "#/components/schemas/WithdrawalStatus" }, "isSandbox": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "paymentMethod": { "type": "string", "enum": [ "PIX" ] }, "currency": { "type": "string", "enum": [ "BRL" ] }, "processedAt": { "type": "string", "format": "date-time", "nullable": true }, "errorMessage": { "type": "string", "nullable": true } } }, "WithdrawalLimits": { "type": "object", "properties": { "currentLimit": { "type": "number", "description": "Current daily limit in BRL." }, "used": { "type": "number", "description": "Amount already withdrawn today." }, "remaining": { "type": "number", "description": "Remaining withdrawal capacity." }, "isNightTime": { "type": "boolean", "description": "Whether reduced night limits are active." }, "fee": { "type": "number", "description": "Withdrawal fee (flat amount in BRL)." }, "dayStartHour": { "type": "integer", "description": "Hour when daytime limits begin (BRT)." }, "dayEndHour": { "type": "integer", "description": "Hour when nighttime limits begin (BRT)." } } }, "Product": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" }, "externalId": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "document": { "type": "string" }, "phone": { "type": "string" }, "externalId": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "CustomerDetail": { "allOf": [ { "$ref": "#/components/schemas/Customer" }, { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "updatedAt": { "type": "string", "format": "date-time" } } } ] }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "PaginationWithPages": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." }, "details": { "type": "object", "description": "Additional error context." } } } } }, "OAuthError": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event ID." }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "data": { "type": "object", "description": "Event payload containing the resource data." } } }, "HeadlessPaymentCreateResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "txId": { "type": "string" }, "amount": { "type": "number" }, "feeAmount": { "type": "number" }, "netAmount": { "type": "number" }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod" }, "currency": { "$ref": "#/components/schemas/Currency" }, "description": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "methodData": { "type": "object", "additionalProperties": true, "properties": { "type": { "$ref": "#/components/schemas/PaymentMethod" } }, "description": "Method-specific data. PIX returns QR data. Direct CARD returns captureType: DIRECT plus masked credit card data. Invoice-style CARD/BOLETO returns provider invoice links.", "example": { "type": "CARD", "captureType": "DIRECT", "cardSubtype": "CREDIT", "brand": "VISA", "last4Digits": "1111", "installments": 1 } } } }, "HostedPaymentCreateResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "txId": { "type": "string" }, "amount": { "type": "number" }, "feeAmount": { "type": "number" }, "netAmount": { "type": "number" }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "methods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } }, "currency": { "$ref": "#/components/schemas/Currency" }, "checkoutUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" }, "isSandbox": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "CreatePaymentResponse": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/HeadlessPaymentCreateResponse" }, { "$ref": "#/components/schemas/HostedPaymentCreateResponse" } ] } }, "required": [ "payment" ] } }, "responses": { "ValidationError": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "Invalid request body", "details": { "amount": "Must be greater than 0.01" } } } } } }, "Unauthorized": { "description": "Missing or invalid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid or expired token" } } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Resource not found" } } } } }, "IdempotencyConflict": { "description": "Idempotency conflict. The key was already used with a different payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "IDEMPOTENCY_PAYLOAD_MISMATCH", "message": "Idempotency key already used with a different request body" } } } } }, "RateLimited": { "description": "Rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit per window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests" } } } } } } } }