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

# Overview

> Redirect to hosted checkout, or collect card and transfer on your own pay screen.

Every payment starts with initialize. After that you choose how the customer pays.

## Redirect

1. POST `/v1/payment/initialize` with your secret key.
2. Redirect the browser to `data.checkoutUrl`.
3. The customer picks card or transfer (and any other enabled channel).
4. We send them to `callbackUrl` when checkout is done.
5. Confirm with a webhook and [verify](/payments/verify).

## Custom checkout

1. Initialize. Keep `data.accessCode` and `data.reference`.
2. For **card**, start a hosted card session, mount the processor fields, then charge. See [Pay with card](/payments/card).
3. For **transfer**, request a virtual account and show bank name, account number, and expiry. See [Pay with transfer](/payments/transfer).
4. Subscribe to `GET /v1/payment/checkout/events` if the pay page should update live.

Checkout calls after initialize use the access code.

## What initialize accepts

| Field             | Required     | Notes                                                                                             |
| ----------------- | ------------ | ------------------------------------------------------------------------------------------------- |
| amount            | Yes          | Major units as a string, `"250.00"`.                                                              |
| currency          | No           | Defaults to NGN.                                                                                  |
| email             | For transfer | Used on receipts. Required for bank transfer.                                                     |
| customerName      | No           | Shown on checkout.                                                                                |
| callbackUrl       | No           | Browser return URL after pay.                                                                     |
| description       | No           | Shown on checkout.                                                                                |
| metadata          | No           | JSON object. Echoed on verify.                                                                    |
| distribution      | No           | Map of service key → amount. Sum must not exceed `amount`. Remainder goes to the primary account. |
| merchantBearsCost | No           | Override who pays the fee for this transaction.                                                   |

Initialize returns `data.reference` (`VPY_TXN_…`). Store it on the order.

## Callback query string

When checkout finishes, the browser hits your `callbackUrl`:

```
https://yourapp.com/paid?status=success&reference=VPY_TXN_…&amount=100.00&currency=NGN
```

| Query       | Meaning                                   |
| ----------- | ----------------------------------------- |
| `status`    | Checkout outcome.                         |
| `reference` | Pass this to verify.                      |
| `amount`    | Amount shown at checkout.                 |
| `currency`  | Usually `NGN`.                            |
| `error`     | Present when checkout surfaces a message. |

Confirm with [verify](/payments/verify).

## Metadata

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "amount": "100.00",
  "email": "customer@email.com",
  "metadata": {
    "orderId": "ORD_12345",
    "customerId": "CUST_67890"
  }
}
```

`metadata` is returned on verify.

## Split (distribution)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "amount": "100.00",
  "email": "customer@email.com",
  "distribution": { "utility": 70, "logistics": 30 }
}
```

₦70 goes to the utility group, ₦30 to logistics. Remainder settles to the primary account. The sum must not exceed `amount`. Verify includes `split` when a distribution was applied.

## Fees

| Field                         | Meaning                                                           |
| ----------------------------- | ----------------------------------------------------------------- |
| `amount`                      | What you asked to collect.                                        |
| `cardFee` / `transferFee`     | Fee for that channel.                                             |
| `cardTotal` / `transferTotal` | What the customer pays on that channel when they bear the fee.    |
| `merchantBearsCost`           | If true, the customer pays `amount` and the fee comes out of you. |

## Channels

Initialize echoes channels for the merchant: `card`, `bank_transfer`, `bank_payment`, and `ussd`. Hosted checkout shows the ones enabled for you.