---
title: "Create a payment"
method: POST
path: "/v1/payments"
tags: ["Payments"]
---

# Create a payment

`POST /v1/payments`

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.

## Headers

- `X-Idempotency-Key` string, required

## Request body

- CreatePaymentRequest
  - `productId` string, uuid — Link this payment to an existing product. If set, `amount` is optional and defaults to the product price.
  - `customerId` string, uuid — Link this payment to an existing customer. For CARD and BOLETO, the linked customer must have name and CPF/CNPJ.
  - `amount` number — Payment amount. Required unless `productId` is provided.
  - `methods` PaymentMethod[] — Accepted payment methods. Headless payments must use exactly one method.
  - `currency` 'BRL' — Supported currencies.
  - `mode` 'hosted' | 'headless' — 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` string, uri — URL to redirect the payer after payment (hosted mode).
  - `completionUrl` string, uri — URL to redirect the payer after successful payment completion.
  - `description` string — Payment description shown to the payer.
  - `externalId` string — Your own reference ID (e.g., order number).
  - `expiresInMinutes` integer — Minutes until the payment expires (5-10080, i.e. up to 7 days).
  - `enforcePayerDocument` boolean — 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` object — Inline customer data. For CARD and BOLETO, include at least name and CPF/CNPJ unless you use customerId.
    - `name` string — Payer name. Required for CARD and BOLETO when not using customerId.
    - `document` string — CPF or CNPJ. Required for CARD and BOLETO when not using customerId.
    - `email` string, email
    - `phone` string — Payer phone number in national or international format.
  - `metadata` object — Arbitrary key-value pairs attached to the payment.
  - `passFeeToPayer` boolean — 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` object — Direct credit card charge payload. Allowed only for headless single-method CARD payments and required in that flow.
    - `number` string, required — Primary account number (PAN), 13-19 digits.
    - `expiryMonth` string, required — Expiration month as 1-2 digits.
    - `expiryYear` string, required — Expiration year as 4 digits.
    - `ccv` string, required — Card security code (3-4 digits).
    - `installments` integer — Installment count for direct credit card charges.
    - `remoteIp` string, required — Customer IP address required by the acquiring flow.
    - `holderInfo` object, required — Supplemental cardholder billing data. `postalCode` and `addressNumber` are required.
      - `name` string
      - `email` string, email
      - `document` string — CPF or CNPJ for the cardholder.
      - `postalCode` string, required
      - `addressNumber` string, required
      - `addressComplement` string
      - `phone` string
      - `mobilePhone` string
  - `boleto` object — 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.
    - `dueDate` string, date — 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` object — Fine (multa) charged once when the boleto is paid after the due date.
      - `value` number, required — Fine amount (must be greater than 0), interpreted per `type`.
      - `type` 'FIXED' | 'PERCENTAGE' — Whether `value` is a fixed BRL amount or a percentage of the boleto value.
    - `interest` object — Monthly interest (juros) accrued while the boleto is overdue.
      - `value` number, required — Monthly interest percentage (must be greater than 0).
    - `discount` object — Discount granted when the boleto is paid on or before the discount deadline.
      - `value` number, required — Discount amount (must be greater than 0), interpreted per `type`.
      - `type` 'FIXED' | 'PERCENTAGE' — Whether `value` is a fixed BRL amount or a percentage of the boleto value.
      - `dueDateLimitDays` integer — Number of days before the due date up to which the discount applies. 0 means the discount applies only until the due date.

## Response `201`

Payment created.

- CreatePaymentResponse
  - `payment` union, required
    - HeadlessPaymentCreateResponse
      - `id` string, uuid
      - `txId` string
      - `amount` number — Merchant-requested base amount. Seller receivable when `feePassedToPayer` is true.
      - `feeAmount` number — YuvexPay platform fee.
      - `netAmount` number — Merchant's net receivable.
      - `feePassedToPayer` boolean — Resolved decision on whether the fee was added on top for the payer.
      - `payerFeeAmount` number, nullable — Fee added to payer's total when `feePassedToPayer` is true; null otherwise.
      - `isSandbox` boolean
      - `status` 'NEW' | 'PENDING_METHOD_SELECTION' | 'PROCESSING' | 'CONFIRMED' | 'PAID' | 'CANCELLED' | 'EXPIRED' | 'REFUNDED' | 'PARTIAL_REFUND' | 'CHARGEBACK' | 'MED_FROZEN' — Possible payment statuses.
      - `paymentMethod` 'PIX' | 'CARD' | 'BOLETO' — Available public payment methods.
      - `currency` 'BRL' — Supported currencies.
      - `description` string, nullable
      - `expiresAt` string, date-time
      - `createdAt` string, date-time
      - `methodData` object — 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.
        - `type` 'PIX' | 'CARD' | 'BOLETO' — Available public payment methods.
    - HostedPaymentCreateResponse
      - `id` string, uuid
      - `txId` string
      - `amount` number — Merchant-requested base amount. Seller receivable when `feePassedToPayer` is true.
      - `feeAmount` number — YuvexPay platform fee.
      - `netAmount` number — Merchant's net receivable.
      - `feePassedToPayer` boolean — Resolved decision on whether the fee was added on top for the payer.
      - `payerFeeAmount` number, nullable — Fee added to payer's total when `feePassedToPayer` is true; null otherwise.
      - `status` 'NEW' | 'PENDING_METHOD_SELECTION' | 'PROCESSING' | 'CONFIRMED' | 'PAID' | 'CANCELLED' | 'EXPIRED' | 'REFUNDED' | 'PARTIAL_REFUND' | 'CHARGEBACK' | 'MED_FROZEN' — Possible payment statuses.
      - `methods` PaymentMethod[]
      - `currency` 'BRL' — Supported currencies.
      - `checkoutUrl` string, uri
      - `expiresAt` string, date-time
      - `isSandbox` boolean
      - `createdAt` string, date-time

## Other responses

- `400` — Validation error.
- `401` — Missing or invalid authentication token.
- `409` — Idempotency conflict. The key was already used with a different payload.
- `429` — Rate limit exceeded.

---

[API](https://skmtc.net/yuvexpay/apis/yuvexpay-api.md) · [All operations](https://skmtc.net/yuvexpay/apis/yuvexpay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yuvexpay/yuvexpay-api/revisions/0d036504e049/schema)