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

# Create checkout session

> Create a Pasteaza-hosted checkout page for a customer payment.

Create a hosted checkout session from your backend. Pasteaza returns a checkout URL that you can redirect your customer to.

You can also pass the returned `reference` to the Pasteaza browser SDK to open checkout in a modal.

<Info>
  Payment methods can be configured from your Pasteaza dashboard. You can choose the exact methods you want to offer on checkout, and Bank Transfer is enabled by default.
</Info>

## Endpoint

```http theme={null}
POST /v1/checkout/sessions
```

## Headers

```http theme={null}
Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxx
Content-Type: application/json
```

## Request body

| Field            | Type    | Required | Description                                                        |
| ---------------- | ------- | -------- | ------------------------------------------------------------------ |
| `amount`         | integer | Yes      | Amount to collect in kobo. Must be divisible by 100.               |
| `currency`       | string  | No       | Currency code. Only `NGN` is supported in Phase 1.                 |
| `description`    | string  | Yes      | Product, service, invoice, or order description shown on checkout. |
| `customer.name`  | string  | No       | Customer display name.                                             |
| `customer.email` | string  | No       | Customer email address.                                            |
| `customer.phone` | string  | No       | Customer phone number.                                             |
| `redirectUrl`    | string  | No       | URL to send the customer to after successful payment.              |
| `metadata`       | object  | No       | Your custom metadata, such as order IDs.                           |
| `expiresAt`      | string  | No       | ISO date string. Defaults to 30 minutes from creation.             |

## Example request

```bash theme={null}
curl https://api.oyapasteaza.com/v1/checkout/sessions \
  -X POST \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "NGN",
    "description": "Premium subscription",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "redirectUrl": "https://merchant.com/success",
    "metadata": {
      "orderId": "ORD_123"
    }
  }'
```

## Successful response

```json theme={null}
{
  "status": true,
  "message": "Checkout session created successfully",
  "data": {
    "reference": "ch_Fb8z7rX8r9w2",
    "checkoutUrl": "https://checkout.oyapasteaza.com/ch_Fb8z7rX8r9w2",
    "expiresAt": "2026-07-22T12:30:00.000Z"
  }
}
```

## Integration flow

<Steps>
  <Step title="Create session">
    Create the checkout session from your backend using your secret key.
  </Step>

  <Step title="Redirect customer">
    Redirect your customer to the `checkoutUrl` returned by Pasteaza, or pass the `reference` to `PasteAZA.checkout`.
  </Step>

  <Step title="Customer pays">
    The hosted page displays enabled payment methods. In Phase 1, Bank Transfer generates a dedicated virtual account.
  </Step>

  <Step title="Receive webhook">
    Pasteaza confirms payment, credits your primary Pasteaza wallet, and sends `checkout.payment.success`.
  </Step>
</Steps>

## Error responses

```json theme={null}
{
  "status": false,
  "message": "amount must be a positive integer in kobo and divisible by 100.",
  "code": "validation_failed"
}
```

Common errors include invalid API key, unsupported currency, invalid redirect URL, expired session, and disabled payment method.