Skip to main content
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.
Documentation status:
Detailed endpoints for moving funds to recipients:
If a section is unclear or missing, contact support.
PayVessel’s REST API provides programmatic access to accept payments, send money, verify identities, manage wallets, 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.

🚀 Getting Started

Base URL: https://api.payvessel.comSandbox URL: https://sandbox.payvessel.com

📊 Rate Limits

Live: 100 requests per minuteSandbox: 1000 requests per minute

​
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. 
curl https://api.payvessel.com/transaction/initialize \
  -H "api-key: YOUR_API_KEY" \
  -H "api-secret: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
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.

​
API Categories

Our API is organized into logical groups of functionality, matching the navigation:
Initialize and verify payments, and retrieve transaction lists.Key Endpoints:
  • POST /transaction/initialize - Initialize a payment
  • GET /transaction/verify/{reference} - Verify transaction status
  • GET /transaction/list - List transactions
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
Create and manage digital wallets, check balances, and generate statements.Key Endpoints:
  • POST /wallets/create - Create new wallet
  • GET /wallets/{wallet_id}/balance - Check wallet balance
  • GET /wallets/{wallet_id}/statement - Generate statement
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
PayVessel Hosted Checkout operations for verifying and confirming transactions.Key Endpoints:
  • POST /checkout/initialize - Initialize hosted checkout
  • POST /checkout/confirm - Confirm transaction

​
Request & Response Format

​
Request Headers

All requests should include these headers: 
api-key: YOUR_API_KEY
api-secret: YOUR_SECRET_KEY
Content-Type: application/json

​
Response Structure

All API responses follow a consistent structure: 
{
  "status": "success|error",
  "message": "Descriptive message",
  "data": {
    // Response data here
  },
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}

​
HTTP Status Codes

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

​
Idempotency

The PayVessel API supports idempotency 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.
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.

​
Webhooks

PayVessel uses webhooks to notify your application when events occur in your account. Learn more about webhook integration in our webhook documentation. 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
Check out our testing guide for test card numbers, bank accounts, and complete testing scenarios.
Ready to start building? Explore the endpoint documentation below or jump to our quickstart guide for step-by-step integration instructions.