> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nova.money/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments API — Create Payments and Issue Refunds

> Create checkout payments via POST /payments and refund them with POST /payments/{id}/refund. Supports credit card, Pix, bank slip, and two-card splits.

The Payments API is the core of Nova.Pay's checkout flow. Use `POST /payments` to initiate a payment for a hosted checkout page — supporting credit card (single or two-card split), Pix, and bank slip — and use `POST /payments/{id}/refund` to issue full or partial refunds against any completed payment.

***

## POST /payments

<Note>
  If any product in the order has `subscription: true`, the payment is processed as a recurring subscription rather than a one-time charge.
</Note>

Create a checkout payment. This is the primary endpoint for hosted checkout pages. The method (credit card, Pix, or bank slip) is determined by the payment plan referenced in `payment_plan_id`.

**Base URL:** `https://pay.nova.money/api/v1`

### Request Body

<ParamField body="payment_plan_id" type="string" required>
  The payment plan identifier retrieved from `GET /payment_plans`. Must follow the format `"{plan_id}-{installments}"` — for example, `"42-3"` means plan 42 paid in 3 installments.
</ParamField>

#### Card Fields (Pagar.me)

<Note>
  For a two-card split, include both `credit_card_0_*` and `credit_card_1_*` fields and provide an `amount` for each card. The two amounts must sum to the order total.
</Note>

<ParamField body="credit_card_0_token" type="string">
  Card token obtained from client-side Pagar.me tokenization. Use this **or** `credit_card_0_card_id`, not both.
</ParamField>

<ParamField body="credit_card_0_card_id" type="string">
  Saved card ID from a previous transaction (alternative to `credit_card_0_token`).
</ParamField>

<ParamField body="credit_card_0_payment_plan" type="string">
  Payment plan for this card, in `"{plan_id}-{installments}"` format. Required when using a two-card split.
</ParamField>

<ParamField body="credit_card_0_amount" type="number">
  Amount charged to this card, in the order's currency. Required when performing a two-card split.
</ParamField>

<ParamField body="credit_card_1_token" type="string">
  Card token for the second card in a split payment (Pagar.me tokenization).
</ParamField>

<ParamField body="credit_card_1_card_id" type="string">
  Saved card ID for the second card (alternative to `credit_card_1_token`).
</ParamField>

<ParamField body="credit_card_1_payment_plan" type="string">
  Payment plan for the second card, in `"{plan_id}-{installments}"` format.
</ParamField>

<ParamField body="credit_card_1_amount" type="number">
  Amount charged to the second card. Required when performing a two-card split.
</ParamField>

#### Card Fields (Stripe)

<ParamField body="confirmation_token_id" type="string">
  A Stripe `ConfirmationToken` ID generated client-side using the Stripe.js SDK. Use this field when `gateway` is set to `"stripe"`.
</ParamField>

#### Customer

<ParamField body="customer_id" type="integer">
  ID of an existing Nova.Pay customer. When provided, customer contact fields are optional.
</ParamField>

<ParamField body="customer_email" type="string">
  Customer's email address.
</ParamField>

<ParamField body="customer_phone" type="string">
  Customer's phone number (digits only, including area code).
</ParamField>

<ParamField body="customer_address" type="object">
  Customer's billing or shipping address.

  <Expandable title="customer_address fields">
    <ParamField body="city" type="string">
      City name.
    </ParamField>

    <ParamField body="neighborhood" type="string">
      Neighborhood or district.
    </ParamField>

    <ParamField body="number" type="string">
      Street number.
    </ParamField>

    <ParamField body="state" type="string">
      State or province (two-letter code recommended).
    </ParamField>

    <ParamField body="street" type="string">
      Street name.
    </ParamField>

    <ParamField body="zipcode" type="string">
      Postal / ZIP code.
    </ParamField>
  </Expandable>
</ParamField>

#### Checkout Context

<ParamField body="checkout_page_id" type="string">
  UUID of the Nova.Pay checkout page associated with this order.
</ParamField>

<ParamField body="main_product_id" type="integer">
  ID of the primary product being purchased.
</ParamField>

<ParamField body="products" type="array">
  List of products included in the order. Each item must contain an `id` and a `quantity`.

  <Expandable title="products item fields">
    <ParamField body="id" type="integer">
      Product ID.
    </ParamField>

    <ParamField body="quantity" type="integer">
      Number of units.
    </ParamField>
  </Expandable>
</ParamField>

#### Optional Fields

<ParamField body="coupon" type="string">
  Coupon or discount code to apply to the order.
</ParamField>

<ParamField body="gateway" type="string">
  Payment gateway to use. Accepted values: `pagarme`, `stripe`. Defaults to the checkout page's configured gateway.
</ParamField>

<ParamField body="tags" type="string">
  Arbitrary tag string for internal labeling or filtering.
</ParamField>

<ParamField body="scheduled_at" type="string">
  ISO 8601 datetime to schedule the charge for a future date and time.
</ParamField>

<ParamField body="observation" type="string">
  Free-text note attached to the order.
</ParamField>

<ParamField body="meta" type="object">
  Arbitrary key/value metadata stored alongside the order. Useful for tracking campaign sources, funnel steps, or custom attributes.
</ParamField>

***

### Response — PaymentResult

<ResponseField name="order_status" type="string">
  Current status of the order. Possible values:

  | Value                | Description                                                   |
  | -------------------- | ------------------------------------------------------------- |
  | `pending`            | Order created but not yet submitted to the gateway.           |
  | `waiting_payment`    | Awaiting customer payment (e.g., Pix or boleto not yet paid). |
  | `partially_paid`     | A partial payment has been received.                          |
  | `paid`               | Payment confirmed in full.                                    |
  | `cancelled`          | Order cancelled.                                              |
  | `partially_refunded` | A partial refund has been issued.                             |
  | `refunded`           | Full refund has been issued.                                  |
  | `billed`             | Order has been invoiced.                                      |
</ResponseField>

<ResponseField name="payments" type="array of strings">
  List of gateway-side payment IDs (e.g., Pagar.me charge IDs or Stripe PaymentIntent IDs) associated with this order.
</ResponseField>

<ResponseField name="bank_slip_url" type="string (uri)">
  URL to the printable bank slip (boleto). Present only when the payment method is `bank_slip`.
</ResponseField>

<ResponseField name="pix_qr_code" type="string">
  Base64-encoded Pix QR code image. Present only for Pix payments.
</ResponseField>

<ResponseField name="pix_qr_code_url" type="string (uri)">
  URL to a hosted Pix QR code page. Present only for Pix payments.
</ResponseField>

<ResponseField name="pix_expires_at" type="string (datetime)">
  ISO 8601 datetime after which the Pix QR code is no longer valid. Present only for Pix payments.
</ResponseField>

<ResponseField name="redirect_url" type="string (uri)">
  Success redirect URL, if a post-payment redirect is configured on the checkout page.
</ResponseField>

<ResponseField name="offer" type="string">
  Signed GlobalID (SGID) for a one-click upsell offer. Present only when the checkout page has an upsell configured **and** the payment succeeded. Pass this value to `POST /upsell` to confirm the offer.
</ResponseField>

<ResponseField name="is_subscription" type="boolean">
  `true` when the order was processed as a subscription (i.e., at least one product has `subscription: true`).
</ResponseField>

***

### Request Examples

<Tabs>
  <Tab title="Credit Card">
    ```json theme={null}
    {
      "payment_plan_id": "42-1",
      "checkout_page_id": "550e8400-e29b-41d4-a716-446655440000",
      "customer_email": "customer@example.com",
      "customer_phone": "11999998888",
      "credit_card_0_token": "tok_test_abc123",
      "credit_card_0_payment_plan": "42-1"
    }
    ```
  </Tab>

  <Tab title="Pix">
    ```json theme={null}
    {
      "payment_plan_id": "43-1",
      "checkout_page_id": "550e8400-e29b-41d4-a716-446655440000",
      "customer_email": "customer@example.com",
      "customer_phone": "11999998888"
    }
    ```
  </Tab>

  <Tab title="Boleto">
    ```json theme={null}
    {
      "payment_plan_id": "44-1",
      "checkout_page_id": "550e8400-e29b-41d4-a716-446655440000",
      "customer_email": "customer@example.com",
      "customer_phone": "11999998888"
    }
    ```
  </Tab>
</Tabs>

#### Two-Card Split

When splitting a payment across two cards, include both `credit_card_0_*` and `credit_card_1_*` fields. The `amount` values must sum to the full order total.

```json theme={null}
{
  "payment_plan_id": "42-2",
  "checkout_page_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_email": "customer@example.com",
  "customer_phone": "11999998888",
  "credit_card_0_token": "tok_test_card1",
  "credit_card_0_payment_plan": "42-1",
  "credit_card_0_amount": 60.00,
  "credit_card_1_token": "tok_test_card2",
  "credit_card_1_payment_plan": "42-1",
  "credit_card_1_amount": 40.00
}
```

***

## POST /payments/\{id}/refund

<Warning>
  This endpoint requires authentication. Include your API key as `Authorization: Bearer <api_key>` in the request headers.
</Warning>

Issue a full or partial refund for a completed payment. To refund the full amount, omit the `amount` field.

### Path Parameters

<ParamField path="id" type="integer" required>
  The numeric ID of the payment to refund.
</ParamField>

### Request Body

<ParamField body="amount" type="number">
  Amount to refund, in the payment's currency. Omit this field to issue a **full refund**.
</ParamField>

<ParamField body="date" type="string (datetime)">
  ISO 8601 datetime for the refund. Defaults to the current date and time if omitted.
</ParamField>

<ParamField body="type" type="string">
  Refund type identifier. Consult your Nova.Pay account configuration for accepted values.
</ParamField>

<ParamField body="transaction_id" type="string">
  Gateway-side transaction ID to target for the refund (useful when an order has multiple charges).
</ParamField>

### Response

Returns `200 OK` with an empty body on success.

### Request Examples

<CodeGroup>
  ```bash Full Refund theme={null}
  curl --request POST \
    --url https://pay.nova.money/api/v1/payments/1234/refund \
    --header "Authorization: Bearer <api_key>" \
    --header "Content-Type: application/json" \
    --data '{}'
  ```

  ```bash Partial Refund theme={null}
  curl --request POST \
    --url https://pay.nova.money/api/v1/payments/1234/refund \
    --header "Authorization: Bearer <api_key>" \
    --header "Content-Type: application/json" \
    --data '{
      "amount": 25.00
    }'
  ```
</CodeGroup>


## Related topics

- [Order Lifecycle and Status Transitions in Nova.Pay](/concepts/orders-lifecycle.md)
- [Webhooks API — Handle Payment Gateway Event Callbacks](/api-reference/webhooks.md)
- [Create and Process Your First Payment with Nova.Pay](/guides/create-payment.md)
- [Nova.Pay API: Payments, Checkout & Order Management](/introduction.md)
- [Orders API — List, Retrieve, Create, and Manage Orders](/api-reference/orders.md)