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

# Gift Card API

> Purchase and deliver digital gift cards from global brands through the PayVessel gift card API.

The PayVessel **gift card API** lets you sell **digital gift cards** from global brands to your users. Browse available operators by country, check products and pricing, and purchase cards instantly.

## Integration flow

1. **List countries** to discover which countries have gift card products.
2. **List operators** for a country to see available gift card brands.
3. **List products** for an operator to see available values and pricing.
4. **Purchase a gift card** by creating an order; PayVessel debits your wallet.
5. **Receive a webhook** when the order status changes (e.g. completed, cancelled).
6. **Verify order** or **get order** to retrieve the gift card details (redeem code, serial number).

```mermaid theme={null}
sequenceDiagram
    participant You
    participant PayVessel

    You->>PayVessel: GET /countries
    PayVessel-->>You: Available countries
    You->>PayVessel: GET /countries/{country_code}/operators
    PayVessel-->>You: Gift card operators
    You->>PayVessel: GET /operators/{operator_id}/products
    PayVessel-->>You: Products and pricing
    You->>PayVessel: POST /orders
    PayVessel-->>You: Order created
    PayVessel--)You: Webhook (order status update)
```

## Order statuses

| Status       | Description                                |
| ------------ | ------------------------------------------ |
| `pending`    | Order received, not yet being processed    |
| `processing` | Order is being fulfilled                   |
| `completed`  | Gift card purchased; redeem code available |
| `cancelled`  | Order was cancelled                        |

## Base path

All gift card endpoints are under:

```
/vaas/api/v1/gift-cards
```

## Authentication

All requests require `api-key` and `api-secret` headers. See [Authentication](/api-basics/authentication) for details.