> ## Documentation Index > Fetch the complete documentation index at: https://docs.yuvexpay.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a payment > 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. ## OpenAPI ````yaml POST /v1/payments 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: >- Same base URL serves both sandbox and production. Send a `ypk_test_*` key for sandbox or a `ypk_live_*` key for production. security: - bearerAuth: [] tags: - name: Authentication description: Inspect the API key in use - 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 - name: Balance description: Inspect the current account balance paths: /v1/payments: post: tags: - Payments 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. operationId: createPayment 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: Pedro Álvares Cabral email: user@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: Pedro Álvares Cabral email: user@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: Pedro Álvares Cabral email: user@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: 5d0f8b6e-3a02-4f5b-9e1c-7c6a4a1b8c9d txId: PAY3f2a8b9c4e6d1f5a7b3c8d2e9f4a6b1c amount: 49.9 feeAmount: 2.99 netAmount: 46.91 status: NEW paymentMethod: PIX currency: BRL description: 'Order #1234' expiresAt: '2026-05-03T15:00:00.000Z' createdAt: '2026-05-03T14:30:00.000Z' methodData: type: PIX pixCopyPaste: 00020126... qrCodeBase64: data:image/png;base64,... qrCodeUrl: null headlessCardDirect: summary: Headless direct credit CARD payment value: payment: id: 8f3c0a85-7c29-4e3a-9e07-5b1a7b6d1234 txId: PAYa1b2c3d4e5f60718293a4b5c6d7e8f90 amount: 149.9 feeAmount: 8.25 netAmount: 141.65 status: PROCESSING paymentMethod: CARD currency: BRL description: 'Order #5678' expiresAt: '2026-05-03T15:00:00.000Z' createdAt: '2026-05-03T14:30:00.000Z' methodData: type: CARD captureType: DIRECT cardSubtype: CREDIT brand: VISA last4Digits: '1111' installments: 1 hostedCheckout: summary: Hosted multi-method checkout value: payment: id: fa1c0a85-7c29-4e3a-9e07-5b1a7b6d1234 txId: PAY9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e amount: 49.9 feeAmount: 2.99 netAmount: 46.91 status: PENDING_METHOD_SELECTION methods: - PIX - CARD currency: BRL checkoutUrl: >- https://checkout.yuvexpay.com/checkout/fa1c0a85-7c29-4e3a-9e07-5b1a7b6d1234 expiresAt: '2026-05-03T15:00:00.000Z' isSandbox: true createdAt: '2026-05-03T14:30:00.000Z' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/IdempotencyConflict' '429': $ref: '#/components/responses/RateLimited' components: 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. schemas: 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: 10080 default: 60 description: Minutes until the payment expires (5-10080, i.e. up to 7 days). enforcePayerDocument: type: boolean default: false description: >- PIX only. Opt-in request that the charge be paid from an account whose CPF/CNPJ matches the customer's document (same-document payment). Best-effort: when the provider cannot enforce it, the charge is still created and paid normally. 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. passFeeToPayer: type: boolean description: >- Whether the YuvexPay fee should be added on top of `amount` and charged to the payer instead of being deducted from the merchant's net. When omitted, the company-level `passFeeToPayerDefault` setting applies. Note: payments with a resolved amount below R$1,00 are always charged to the payer regardless of this value (forced passthrough to keep merchant net positive). The final decision is reflected back as `feePassedToPayer` on the Payment object. 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 boleto: type: object description: >- Boleto-specific options, applied only when `BOLETO` is one of the `methods`. Fine, interest, and discount mirror the boleto configuration registered with the bank and are settled against the amount the payer actually pays. properties: dueDate: type: string format: date description: >- Boleto due date (vencimento) as `YYYY-MM-DD`. Must be today or a future date within one year. Defaults to 3 business days out when omitted. The boleto can still be paid after this date unless the account is configured to reject post-due payment. fine: type: object description: >- Fine (multa) charged once when the boleto is paid after the due date. properties: value: type: number description: >- Fine amount (must be greater than 0), interpreted per `type`. type: type: string enum: - FIXED - PERCENTAGE default: PERCENTAGE description: >- Whether `value` is a fixed BRL amount or a percentage of the boleto value. required: - value interest: type: object description: Monthly interest (juros) accrued while the boleto is overdue. properties: value: type: number description: Monthly interest percentage (must be greater than 0). required: - value discount: type: object description: >- Discount granted when the boleto is paid on or before the discount deadline. properties: value: type: number description: >- Discount amount (must be greater than 0), interpreted per `type`. type: type: string enum: - FIXED - PERCENTAGE default: PERCENTAGE description: >- Whether `value` is a fixed BRL amount or a percentage of the boleto value. dueDateLimitDays: type: integer minimum: 0 maximum: 60 default: 0 description: >- Number of days before the due date up to which the discount applies. 0 means the discount applies only until the due date. required: - value CreatePaymentResponse: type: object properties: payment: oneOf: - $ref: '#/components/schemas/HeadlessPaymentCreateResponse' - $ref: '#/components/schemas/HostedPaymentCreateResponse' required: - payment PaymentMethod: type: string enum: - PIX - CARD - BOLETO description: Available public payment methods. Currency: type: string enum: - BRL description: Supported currencies. HeadlessPaymentCreateResponse: type: object properties: id: type: string format: uuid txId: type: string amount: type: number description: >- Merchant-requested base amount. Seller receivable when `feePassedToPayer` is true. feeAmount: type: number description: YuvexPay platform fee. netAmount: type: number description: Merchant's net receivable. feePassedToPayer: type: boolean description: Resolved decision on whether the fee was added on top for the payer. payerFeeAmount: type: number nullable: true description: >- Fee added to payer's total when `feePassedToPayer` is true; null otherwise. isSandbox: type: boolean 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 description: >- Merchant-requested base amount. Seller receivable when `feePassedToPayer` is true. feeAmount: type: number description: YuvexPay platform fee. netAmount: type: number description: Merchant's net receivable. feePassedToPayer: type: boolean description: Resolved decision on whether the fee was added on top for the payer. payerFeeAmount: type: number nullable: true description: >- Fee added to payer's total when `feePassedToPayer` is true; null otherwise. 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 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. PaymentStatus: type: string enum: - NEW - PENDING_METHOD_SELECTION - PROCESSING - CONFIRMED - PAID - CANCELLED - EXPIRED - REFUNDED - PARTIAL_REFUND - CHARGEBACK - MED_FROZEN description: Possible payment statuses. 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: INVALID_API_KEY message: Invalid or revoked API key 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 securitySchemes: bearerAuth: type: http scheme: bearer description: >- YuvexPay API key. Include as `Authorization: Bearer ypk___` where `` is `test` (sandbox) or `live` (production). Create and manage keys in the dashboard under **Settings > API Keys**. ````