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

# API Reference

> PayVessel REST API reference for virtual card API, virtual account API, BVN and NIN verification API, credit score API, payments, transfers, and wallets.

**Code samples, request/response payloads, and endpoint reference.** Use this tab for HTTP methods, headers, body schemas, and example code. For concepts, integration flows, and when-to-use guidance, see the **Guides** tab.

PayVessel's REST API provides programmatic access to accept payments, send money, verify identities, manage wallets, issue **USD virtual cards**, and more. Our API is organized around REST principles with predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

<CardGroup cols={2}>
  <Card title="🚀 Getting Started" icon="rocket">
    **Base URL**: `https://api.payvessel.com`

    **Sandbox URL**: `https://sandbox.payvessel.com`
  </Card>

  <Card title="📊 Rate Limits" icon="gauge-high">
    **Live**: 100 requests per minute

    **Sandbox**: 1000 requests per minute
  </Card>
</CardGroup>

## Authentication

All API requests must be authenticated with your **API key** and **secret key**. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.payvessel.com/transaction/initialize \
    -H "api-key: YOUR_API_KEY" \
    -H "api-secret: YOUR_SECRET_KEY" \
    -H "Content-Type: application/json"
  ```

  ```javascript Node.js theme={null}
  const payvessel = require('payvessel')(YOUR_SECRET_KEY);
  ```

  ```php PHP theme={null}
  <?php
  $payvessel = new \Payvessel\Payvessel(YOUR_SECRET_KEY);
  ?>
  ```

  ```python Python theme={null}
  import payvessel
  payvessel.api_key = "YOUR_SECRET_KEY"
  ```
</CodeGroup>

<Warning>
  **Keep your API keys secure!** Your secret API key can perform any API request to PayVessel without restriction. Store your secret key securely and never expose it in client-side code.
</Warning>

## API Categories

Our API is organized into logical groups of functionality, matching the navigation:

<AccordionGroup>
  <Accordion title="💳 Transactions" icon="credit-card">
    Initialize, confirm, and verify payments, and retrieve transaction lists.

    **Key Endpoints:**

    * `POST /transaction/initialize` - Initialize a payment
    * `POST /transaction/confirm` - Confirm transaction
    * `GET /transaction/verify/{reference}` - Verify transaction status
    * `GET /transaction/list` - List transactions
  </Accordion>

  <Accordion title="💸 Send Money & Transfers" icon="paper-plane">
    Send money to bank accounts and mobile money users with instant transfers.

    **Key Endpoints:**

    * `POST /transfer/recipient` - Create transfer recipient
    * `POST /transfer/initiate` - Initialize transfer
  </Accordion>

  <Accordion title="👛 Wallets" icon="wallet">
    Create and manage digital wallets, check balances, and generate statements.

    **Key Endpoints:**

    * `POST /wallets/create` - Create new wallet
    * `GET /pms/api/external/request/wallet/balance/` - Check wallet balance
    * `GET /wallets/{wallet_id}/statement` - Generate statement
  </Accordion>

  <Accordion title="🏦 Virtual Accounts" icon="building-columns">
    Create and manage reserved virtual accounts for automated collections.

    **Key Endpoints:**

    * `POST /reserved-account/create` - Create virtual account
    * `GET /reserved-account/{account_number}` - Get account details
  </Accordion>
</AccordionGroup>

## Request & Response Format

### Authentication

All API requests require `api-key`, `api-secret`, and `Content-Type: application/json`. See [Authentication](/api-basics/authentication) for details.

### Response Structure

All API responses follow a consistent structure:

```json theme={null}
{
  "status": true,false,
  "message": "Descriptive message",
  "data": {
    // Response data here
  }
}
```

### HTTP Status Codes

| Code  | Description                                                           |
| ----- | --------------------------------------------------------------------- |
| `200` | **OK** - The request was successful                                   |
| `201` | **Created** - The resource was successfully created                   |
| `400` | **Bad Request** - The request was invalid or malformed                |
| `401` | **Unauthorized** - Authentication credentials were missing or invalid |
| `403` | **Forbidden** - The request is understood, but not authorized         |
| `404` | **Not Found** - The requested resource could not be found             |
| `429` | **Too Many Requests** - Rate limit exceeded                           |
| `500` | **Internal Server Error** - An error occurred on PayVessel's servers  |

## Idempotency

The PayVessel API supports [idempotency](https://en.wikipedia.org/wiki/Idempotence) for safely retrying requests without accidentally performing the same operation twice. When creating or modifying objects, provide an additional `Idempotency-Key: <key>` header to the request.

<Note>
  **Best Practice**: Use a UUID or other random string as your idempotency key. PayVessel will return the same response for repeated requests with the same key for 24 hours.
</Note>

## Webhooks

PayVessel uses webhooks to notify your application when events occur in your account. Learn more about webhook integration in our [webhook documentation](/api-basics/webhooks).

Common webhook events:

* `transaction.success` - Payment completed successfully
* `transaction.failed` - Payment failed or was declined
* `transfer.success` - Transfer completed successfully
* `verification.completed` - Identity verification completed

## Testing

Use our sandbox environment to test your integration without real money. The sandbox mirrors the production API but with test data.

**Sandbox Base URL**: `https://sandbox.payvessel.com`

<Tip>
  Check out our [testing guide](/api-basics/testing) for test card numbers, bank accounts, and complete testing scenarios.
</Tip>

***

**Ready to start building?** Explore the endpoint documentation below or jump to our [quickstart guide](/quickstart) for step-by-step integration instructions.