# Select Payment Method

Select a payment method for a checkout session. Returns the payment details the customer needs to complete the transfer.

```
POST /v1/checkout/session/:sessionId/payment-method
```

**Required permission:** `checkout`

## Authentication

Requires an API key. Origin/domain validation is enforced for public keys.

## Path parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `sessionId` | string | The checkout session ID |

## Request body

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `payment_method` | string | Yes | `"bank_transfer"` or `"payid"` |

## Example request

```bash
curl -X POST https://api.zevpaycheckout.com/v1/checkout/session/ecc48011-e36e-4741-9b99-657f4a1ee86e/payment-method \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_test_your_public_key" \
  -d '{"payment_method": "bank_transfer"}'
```

## Response — Bank Transfer

When `payment_method` is `"bank_transfer"`, a temporary virtual account is created:

```json
{
  "success": true,
  "data": {
    "payment_method": "bank_transfer",
    "account_number": "5000973258",
    "bank_name": "VFD Microfinance Bank",
    "account_name": "Your Business Name",
    "amount": 500000,
    "expires_at": "2026-03-07T19:37:00.000Z"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `payment_method` | string | Always `"bank_transfer"` |
| `account_number` | string | Virtual account number for the transfer |
| `bank_name` | string | Always `"VFD Microfinance Bank"` |
| `account_name` | string | Merchant's business name (or `"ZevPay Checkout"` if not configured) |
| `amount` | integer | Amount in kobo the customer should transfer |
| `expires_at` | string | ISO 8601 timestamp — when the virtual account expires |

## Response — PayID

When `payment_method` is `"payid"`, a dynamic PayID is created:

```json
{
  "success": true,
  "data": {
    "payment_method": "payid",
    "pay_id": "5de2.dypid",
    "qr_data": "https://zevpay.me/5de2.dypid",
    "amount": 500000,
    "expires_at": "2026-03-07T19:37:00.000Z"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `payment_method` | string | Always `"payid"` |
| `pay_id` | string | Dynamic PayID for the payment |
| `qr_data` | string | URL for QR code generation (`https://zevpay.me/{payId}`) |
| `amount` | integer | Amount in kobo |
| `expires_at` | string | ISO 8601 timestamp — when the dynamic PayID expires |

## Behavior

- Calling this endpoint multiple times for the **same method** reuses the existing virtual account or PayID (as long as it's still active/pending)
- Switching methods (e.g., from `bank_transfer` to `payid`) logs a `method_switched` event and increments the attempt counter
- The session must be `active` — expired, completed, or failed sessions return an error

## Errors

| Status | Message | Cause |
|--------|---------|-------|
| `400` | Session is {status}. | Session is not active (e.g., `"Session is completed."`) |
| `400` | Session has expired. | Session's expiry time has passed |
| `400` | Unsupported payment method: {method} | Invalid `payment_method` value |
| `400` | Session does not belong to this API key. | API key mismatch |
| `401` | Invalid API key | Key not found or inactive |
| `404` | Session not found. | Invalid session ID |

## Try it

<ApiPlayground
  method="POST"
  endpoint="/v1/checkout/session/:sessionId/payment-method"
  :pathParams="[
    { name: 'sessionId', type: 'string', required: true, placeholder: 'ecc48011-e36e-4741-9b99-657f4a1ee86e' },
  ]"
  :bodyFields="[
    { name: 'payment_method', type: 'select', required: true, options: [{ label: 'Bank Transfer', value: 'bank_transfer' }, { label: 'PayID', value: 'payid' }] },
  ]"
/>