> ## 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.

# API responses

> Success and failure JSON from the Vestrapay API.

## Success

HTTP 2xx:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "success",
  "data": { }
}
```

The resource is in `data`. Initialize is HTTP 201. Verify is HTTP 200.

## Failure

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "failed",
  "error": "invalid_credentials",
  "message": "A human-readable explanation"
}
```

Branch on `error`. Include `X-Request-Id` from the response headers when you contact support.

## Payment status on checkout charges

Checkout charges return HTTP 201 with outer `status` `success`. The payment state is `data.status`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "success",
  "data": {
    "status": "awaiting_transfer",
    "reference": "VPY_TXN_…",
    "accountNumber": "0012345678"
  }
}
```

| Outer `status` | `data.status`                                                                        | Meaning                                         |
| -------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------- |
| `success`      | `pending`, `awaiting_transfer`, `fingerprint_required`, `3ds_required`, `processing` | Continue the flow.                              |
| `success`      | `success`                                                                            | Paid. [Verify](/payments/verify) on the server. |
| `success`      | `failed`                                                                             | Charge failed. Customer can retry.              |
| `failed`       | —                                                                                    | The HTTP call failed. Read `error`.             |

## Webhooks

Webhook bodies are `{ "event", "data", "timestamp" }`. See [Webhooks](/payments/webhooks).

## Auth

| Call                     | Auth                               |
| ------------------------ | ---------------------------------- |
| Initialize, verify       | Secret key (`x-api-key` or Bearer) |
| Checkout card / transfer | Access code (`x-access-code`)      |