# List Bank Branches
Source: https://docs.platnova.com/api-reference/banks/branches
GET /v1/banks/{country_code}/{bank_code}
Branches of a bank, for countries whose transfers need a branch_code (Ghana and Kenya do; Nigeria does not). The branch code goes into info.branch_code on the send request.
## Overview
Some countries route transfers by branch as well as bank. Ghana and Kenya do; Nigeria does not. For those countries, pick a branch here and send its `branch_code` in `info.branch_code` on [Send payment](/api-reference/payments/send).
# List Banks
Source: https://docs.platnova.com/api-reference/banks/list
GET /v1/banks/{country_code}
Banks you can send to in a country, with the bank_code each one needs. Codes are specific to our payment provider for that country: a Nigerian bank's code here can differ from its CBN code, so always take the code from this list. Cache it for at most a day.
## Overview
Every bank you can send to in a country, with the `code` each one needs. That `code` is the `bank_code` you pass to [Verify a bank account](/api-reference/banks/verify) and in `info.bank_code` on [Send payment](/api-reference/payments/send).
Codes are specific to our payment provider in each country. A Nigerian bank's code here can differ from the CBN code you may hold from another provider, so always take the code from this list rather than a list of your own. Cache it for at most a day.
# Suggest Banks for an Account Number
Source: https://docs.platnova.com/api-reference/banks/suggest
POST /v1/banks/suggest
When you have an account number but not the bank: returns banks we have previously paid this account number through. A hint, not a lookup; still call verify with the code you pick.
## Overview
When you have an account number but not the bank, this returns the banks we have previously paid that account number through. It is a hint from past transfers, not a lookup against the banking network: the list can be empty, and you should still [verify](/api-reference/banks/verify) with the code you pick.
# Verify a Bank Account
Source: https://docs.platnova.com/api-reference/banks/verify
POST /v1/banks/verify
Resolves an account number at a bank to the account holder's name so you can show it before sending. Call this before every bank transfer; a wrong bank_code or account number is refused here rather than after the money has moved.
## Overview
Resolves an account number at a bank to the account holder's name. Show the name to whoever is paying before you send: a wrong `bank_code` or a mistyped account number is refused here, rather than after the money has moved.
`bank_code` must come from [List banks](/api-reference/banks/list) for the same `country_code`.
# Create Card
Source: https://docs.platnova.com/api-reference/cards/create
POST /v1/cards/create
Create a virtual card for a customer with optional initial funding.
## Overview
Create a USD virtual card for a customer. This endpoint allows you to issue a new virtual card with a specified currency, brand, and initial funding amount. A wallet\_id and amount can be optionally specified to change the default currency funding wallet and initial amount in the card respectively. The card will be linked to the customer's account and can be used for online and in-store purchases.
# Deposit to Card
Source: https://docs.platnova.com/api-reference/cards/deposit
POST /v1/cards/{card_id}/deposit
Add funds to a card from your wallet.
## Overview
Add funds to a specific card. This endpoint allows you to deposit money into a card from your business wallet. The deposit will be processed and the card balance will be updated accordingly.
# Get Card Events
Source: https://docs.platnova.com/api-reference/cards/events
GET /v1/cards/{card_id}/events
Retrieve transaction and event history for a card.
## Overview
Retrieve a paginated list of all events (transactions, deposits, withdrawals, etc.) associated with a specific card. This endpoint provides a complete history of card activity.
# Freeze Card
Source: https://docs.platnova.com/api-reference/cards/freeze
PUT /v1/cards/{card_id}/freeze
Temporarily disable a card so it cannot be used for purchases.
## Overview
Freeze a card to temporarily prevent it from being used for transactions. A frozen card cannot be used until it is unfrozen. This is useful for security purposes or when you need to temporarily disable a card.
# Get Card
Source: https://docs.platnova.com/api-reference/cards/get
GET /v1/cards/{id}
Retrieve a specific card by ID including balance and status.
## Overview
Retrieve detailed information about a specific card by its ID. This endpoint returns comprehensive card details including balance, status, card information, and metadata.
# List Cards
Source: https://docs.platnova.com/api-reference/cards/list
GET /v1/cards
Retrieve a list of cards, optionally filtered by customer.
## Overview
Retrieve a list of all cards belonging to a specific customer. This endpoint returns cards with their basic information, balance, and recent events.
# Reveal Card Details
Source: https://docs.platnova.com/api-reference/cards/reveal
GET /v1/cards/{card_id}/reveal
Retrieve full card number and CVV. Rate-limited for security.
## Overview
Retrieve sensitive card details including the full card number and CVV. This endpoint is rate limited for security purposes and should only be called when you need to display card details to the cardholder.
# Unfreeze Card
Source: https://docs.platnova.com/api-reference/cards/unfreeze
PUT /v1/cards/{card_id}/unfreeze
Restore a frozen card so it can be used again.
## Overview
Unfreeze a previously frozen card to restore its functionality. Once unfrozen, the card can be used for transactions again.
# Withdraw from Card
Source: https://docs.platnova.com/api-reference/cards/withdraw
POST /v1/cards/{card_id}/withdraw
Withdraw funds from a card back to your wallet.
## Overview
Withdraw funds from a specific card back to your business wallet. This endpoint allows you to retrieve money from a card, reducing the card balance accordingly.
# Create Checkout
Source: https://docs.platnova.com/api-reference/checkout/create
POST /v1/checkout
Initiate a hosted checkout session for a customer.
## Overview
Create a hosted checkout session for a customer. This endpoint returns a checkout ID and checkout URL that you can use to redirect the customer and complete payment.
# Get Checkout
Source: https://docs.platnova.com/api-reference/checkout/get
GET /v1/checkout/{id}
Retrieve checkout details by checkout ID.
## Overview
Retrieve an existing checkout session by ID, including current status, payment URL, and checkout metadata.
# Create Customer
Source: https://docs.platnova.com/api-reference/customers/create
POST /v1/customers
Create a new individual customer profile with identification details, address information, and KYC compliance data.
## Overview
Create a new individual customer profile. This endpoint allows you to onboard customers with identification details, address information, and KYC (Know Your Customer) compliance data. The response confirms successful creation or returns relevant validation errors.
## Required fields
| Field | Description |
| - | - |
| `email` | Valid email address |
| `first_name` | Customer first name |
| `last_name` | Customer last name |
| `phone` | Phone number |
| `date_of_birth` | `YYYY-MM-DD` |
| `country_code` | ISO country code |
## Optional fields
| Field | Description |
| - | - |
| `gender` | Customer gender |
| `documents` | Array of identity documents (recommended; see [Identity documents](#identity-documents)) |
| `address` | Residential or mailing address: `street`, `city`, `state`, `postal_code`, `country`, optional `document` (base64-encoded proof-of-address file) |
| `proof_of_funds` | Employment and source-of-funds object (`employment_status`, `occupation`, `primary_purpose`, `source_of_funds`, `expected_monthly_pay`). Allowed **field** values and meanings are in [Proof of funds options](/customers/proof-of-funds-options). |
## Identity documents
Each entry in the `documents` array uses the same shape:
* **`id_type`** — Any of: `passport`, `resident_id`, `drivers_license`, `national_id`, `voters_card`, `nin`, `bvn`, or a tax ID type (see [Tax ID document](#tax-id-document))
* **`id_number`** — The number on the document
* **`front_doc`** — Base64-encoded image of the front
* **`back_doc`** — Base64-encoded image of the back when applicable
For `passport`, `resident_id`, `drivers_license`, `national_id`, `voters_card`, and `nin`, you need **at most** `front_doc` (base64); `back_doc` is not required for those types.
To change documents or proof-of-funds after creation, use [Update customer](/api-reference/customers/update).
### Tax ID document
A tax ID document is required when creating virtual accounts for a customer. Submit it as an entry in the `documents` array. The tax ID value is always passed in `id_number`; the `id_type` depends on the customer's country:
| Country | Country Code | `id_type` |
| - | - | - |
| Algeria | `DZ` | `nif` |
| Angola | `AO` | `nif` |
| Canada | `CA` | `sin` |
| France | `FR` | `spi` |
| Indonesia | `ID` | `npwp` |
| Italy | `IT` | `cf` |
| Kenya | `KE` | `pin` |
| Mexico | `MX` | `rfc` |
| Nepal | `NP` | `pan` |
| Nigeria | `NG` | `bvn` |
| Pakistan | `PK` | `ntn` |
| Romania | `RO` | `cnp` |
| Tunisia | `TN` | `mf` |
| Turkey | `TR` | `tckn` |
| United Kingdom | `GB` | `nino` |
| United States | `US` | `ssn` |
| All other countries | — | `tin` |
For any country not listed above, use `id_type: "tin"`.
# Get Customer
Source: https://docs.platnova.com/api-reference/customers/get
GET /v1/customers/{id}
Retrieve a specific customer by ID.
## Overview
Retrieve detailed information about an individual customer based on their unique ID. This endpoint allows you to view the customer's profile, including status, KYC information, and associated metadata.
# List Customers
Source: https://docs.platnova.com/api-reference/customers/list
GET /v1/customers
Retrieve a paginated list of customers.
## Overview
Retrieve a paginated list of all customers associated with your account. This endpoint allows you to view all customers with their basic information and status.
# Update Customer
Source: https://docs.platnova.com/api-reference/customers/update
PATCH /v1/customers/{id}
Partially update a customer. All body fields are optional; include only fields you want to change. Use documents and proof_of_funds for KYC updates.
## Overview
Update an existing customer with a partial JSON body. Only include fields you want to change. Typical uses include correcting profile data, refreshing identity documents, and submitting proof-of-funds details.
## Request body
All fields are optional:
| Field | Description |
| - | - |
| `date_of_birth` | `YYYY-MM-DD` |
| `address` | Same shape as on [create customer](/api-reference/customers/create); `address.document` is a base64 string when provided |
| `first_name`, `last_name`, `phone`, `gender`, `country_code` | Profile fields |
| `documents` | Array of document objects (see below) |
| `proof_of_funds` | Employment and source-of-funds fields |
### `documents` items
Each element uses the same shape as on create (see [Identity documents](/api-reference/customers/create#identity-documents)):
* `id_type` — One of: `passport`, `resident_id`, `drivers_license`, `national_id`, `voters_card`, `nin`, `bvn`, or a tax ID type (see [Tax ID document](/api-reference/customers/create#tax-id-document))
* `id_number` — Value on the document
* `front_doc` — Base64-encoded image of the front
* `back_doc` — Base64-encoded image of the back when needed
For `passport`, `resident_id`, `drivers_license`, `national_id`, `voters_card`, and `nin`, you need at most `front_doc` (base64); `back_doc` is not required for those types.
### `proof_of_funds`
Optional object with: `employment_status`, `occupation`, `primary_purpose`, `source_of_funds`, `expected_monthly_pay`.
Use the **Field** values from the reference tables in your JSON (not free-text labels). See [Proof of funds options](/customers/proof-of-funds-options).
# Introduction
Source: https://docs.platnova.com/api-reference/introduction
Welcome to the Platnova Business API Reference. Our RESTful API provides programmatic access to virtual accounts, cards, payments, and other financial services, allowing you to integrate Platnova's capabilities into your business applications.
## Base URL
All API requests should be made to:
**Production:**
```
https://api.platnova.com
```
**Sandbox:**
```
https://sandbox.api.platnova.co
```
## Authentication
All API requests require authentication using your API key. You can include it either in the request headers or as a query parameter.
### Header Authentication (Recommended)
```bash theme={null}
X-API-KEY: YOUR_API_KEY
```
### Query Parameter Authentication
```bash theme={null}
?api-key=YOUR_API_KEY
```
Some endpoints require JWT authentication in addition to API key authentication. See our [Authentication guide](../authentication) for details on obtaining and using your API key.
## Request Format
All requests should include the following headers:
* `Content-Type: application/json`
* `X-API-KEY: YOUR_API_KEY` (or include as query parameter)
## Response Format
All API responses are returned in JSON format with the following structure:
### Success Response
```json theme={null}
{
"status": true,
"data": {
// Response data here
},
"error": [],
"message": "operation was successful"
}
```
### Error Response
```json theme={null}
{
"status": false,
"data": {},
"error": [],
"message": "Error message here"
}
```
### Validation Error Response
```json theme={null}
{
"status": "error",
"message": "Validation failed",
"errors": {
"field_name": [
"This field is required"
]
}
}
```
## Rate Limits
Rate limits vary by endpoint and are indicated in response headers:
* `X-Ratelimit-Limit`: Maximum requests per window
* `X-Ratelimit-Remaining`: Remaining requests in current window
* `X-Ratelimit-Reset`: Time when the rate limit resets (Unix timestamp)
Some endpoints have specific rate limits:
* Card creation: 4 requests per window
* Card reveal: 10 requests per window
* Virtual account creation: 2 requests per window
## Error Handling
The API uses standard HTTP status codes:
* `200` - Success
* `400` - Bad Request (invalid parameters or resource not found)
* `401` - Unauthorized (invalid API key)
* `403` - Forbidden (insufficient permissions)
* `404` - Not Found
* `422` - Unprocessable Entity (validation errors)
* `429` - Too Many Requests (rate limit exceeded)
* `500` - Internal Server Error
See our [Error Handling guide](../errors) for detailed error information.
## Pagination
List endpoints support pagination using query parameters:
* `page`: 0-indexed page number (default: 0)
* `size`: Number of items per page (default: 10)
* `sort`: Sort order (optional)
* `filters`: Filter criteria (optional)
Response includes pagination metadata:
```json theme={null}
{
"page": 0,
"size": 10,
"max_page": 5,
"total_pages": 6,
"total": 60,
"last": false,
"first": true,
"visible": 10
}
```
## Getting Started
1. **Get your API key** from the [dashboard](https://business.platnova.com/settings/developer)
2. **Create a customer** using the [Customers API](./customers/create)
3. **Issue a virtual account** using the [Virtual Accounts API](./virtual-accounts/create)
4. **Create a card** using the [Cards API](./cards/create)
5. **Explore the endpoints** to understand all available features
## Support
Need help with the API? Check out our:
* [Authentication Guide](../authentication)
* [Error Handling](../errors) documentation
* [Support](mailto:support@platnova.com) team
# Create Invoice
Source: https://docs.platnova.com/api-reference/invoices/create
POST /v1/invoices
## Overview
Create an invoice for a customer. Invoices allow you to bill customers and track payments. This endpoint creates a new invoice that can be sent to customers for payment.
# Get Invoice
Source: https://docs.platnova.com/api-reference/invoices/get
GET /v1/invoices/view/{number}
## Overview
Retrieve invoice details by invoice number. This endpoint can be used by customers to view their invoices or by your system to retrieve invoice information.
# List Invoices
Source: https://docs.platnova.com/api-reference/invoices/list
GET /v1/invoices
## Overview
Retrieve a paginated list of all invoices associated with your account. This endpoint allows you to view all invoices with filtering and sorting options.
# Update Invoice Status
Source: https://docs.platnova.com/api-reference/invoices/update-status
PATCH /v1/invoices/{uid}/status
## Overview
Update the status of an invoice. This endpoint allows you to mark invoices as paid, cancelled, or update their status as needed.
# Create Payment Link
Source: https://docs.platnova.com/api-reference/links/create
POST /v1/links
Create a shareable payment link
## Overview
Create a payment link that can be shared with customers to collect payments. Payment links allow you to generate shareable URLs that customers can use to make payments without requiring them to have an account.
# Get Payment Link
Source: https://docs.platnova.com/api-reference/links/get
GET /v1/links/{uid}/stats
Retrieve a payment link by UID including statistics (total_revenue, total_transactions, total_users, total_views, payment_details).
## Overview
Retrieve detailed information about a payment link including statistics and payment history. This endpoint allows you to view link performance and track payments made through the link.
# List Payment Links
Source: https://docs.platnova.com/api-reference/links/list
GET /v1/links
Retrieve a paginated list of payment links for the authenticated entity.
## Overview
Retrieve a paginated list of all payment links associated with your account. This endpoint allows you to view all links with their status and basic information.
# Send Payment
Source: https://docs.platnova.com/api-reference/payments/send
POST /v1/payments/send
Initiate a payment transfer. Supports instant, scheduled, and recurring payments
## Overview
Send a payment using the specified payment method. Supported methods include **bank\_transfer**, **card**, **mobile\_money**, **tag\_transfer** (wallet-to-wallet), **defi**, **revolut**, **paypal**, **ussd**, **cashapp**, and **zelle**. Provide `from_amount`, `from_wallet_id`, `to_currency`, `payment_method`, and `info` (recipient details; fields depend on the method). For tag transfer, `info` must include `tag_id`. Payments can be instant, scheduled, or recurring.
# Verify Payment
Source: https://docs.platnova.com/api-reference/payments/verify
POST /v1/payments/verify
Check the status and details of a payment by its reference.
## Overview
Verify a payment by its reference. Send a JSON body with **`reference`**: the transaction or payment reference returned when you sent the payment (for example a `UTR_…` value). The response includes status, amount, and related transaction details.
# List Transactions
Source: https://docs.platnova.com/api-reference/transactions/list
GET /v1/transactions
Retrieve a paginated list of transactions for the entity. Supports filtering by customer, sorting, and optional CSV export.
## Overview
Retrieve a paginated list of all transactions associated with your account. This endpoint allows you to view transaction history with filtering and sorting options.
# Generate Receipt
Source: https://docs.platnova.com/api-reference/transactions/receipt
GET /v1/transactions/{id}/receipt
Generate a receipt for a transaction by ID. Returns base64-encoded receipt data (e.g. PDF).
## Overview
Generate a receipt for a specific transaction. This endpoint returns receipt data that can be used to display or download a transaction receipt.
# Create Virtual Account
Source: https://docs.platnova.com/api-reference/virtual-accounts/create
POST /v1/virtual-accounts/create
Create a virtual bank account for a customer in the specified currency. Requires customer_id and currency. For NGN, id_number (BVN) may be required.
## Overview
Create a virtual account for a customer. Virtual accounts allow customers to receive payments directly into their account. This endpoint creates a bank account that can be used for receiving funds. To generate USD virtual accounts, ensure a default USD settlement wallet is set on your [dashboard settings](https://business.platnova.com/settings?section=settlements). This wallet will be billed for USD account creation fees if applicable. For NGN virtual accounts, you can optionally specify an `id_number` parameter in the request body, which corresponds to a valid BVN.
# Generate Dynamic Virtual Account
Source: https://docs.platnova.com/api-reference/virtual-accounts/dynamic
POST /v1/virtual-accounts/dynamic
Generate a dynamic, single-use virtual account for a customer with a fixed amount and configurable expiry. The account automatically expires after the specified lifespan and can only receive a payment matching the exact amount.
## Overview
Generate a dynamic, single-use virtual account for a customer with a fixed receivable amount and a configurable expiry window. The account is tied to an exact amount - it will only accept a payment matching that value - and automatically becomes inactive once the lifespan elapses or the payment is received.
This is ideal for checkout flows, invoice payments, or any scenario where you need a guaranteed, one-time payment collection without reusing a permanent account.
# List Virtual Accounts
Source: https://docs.platnova.com/api-reference/virtual-accounts/list
GET /v1/virtual-accounts
Retrieve a list of virtual accounts, optionally filtered by currency or customer.
## Overview
Retrieve a list of all virtual accounts for a specific customer. This endpoint returns all virtual accounts associated with the customer, including account details and metadata.
# List Wallets
Source: https://docs.platnova.com/api-reference/wallets/list
GET /v1/wallets
## Overview
Retrieve a list of all wallets associated with your account. This endpoint returns all wallets with their balances, currencies, and status information.
# Authentication
Source: https://docs.platnova.com/authentication
Start using Platnova's Business API by working with our support and compliance team. We'll help you get set up with the right plan and ensure all compliance requirements are met.
## Getting Started
Our onboarding process is handled by our dedicated support and compliance team to ensure proper verification and setup. Contact us to begin your integration journey.
All new accounts go through our compliance verification process to ensure secure and compliant financial operations.
## Set Up Your Workspace
Once your account is created by our team, you'll have access to your workspace where you can manage your API keys, view usage analytics, and configure your integration settings.
For business accounts and enterprise integrations, our team provides dedicated onboarding support to ensure a smooth setup process.
## Get Your API Key
Create an API key for your workspace. You can find it in the [API Keys section](https://business.platnova.com/settings/developer) of your dashboard.
Contact our support team at [support@platnova.com](mailto:support@platnova.com) for personalized onboarding assistance, especially if you're integrating with high transaction volumes or need custom configurations.
### Using Your API Key
Include your API key in the `Authorization` header of your requests:
```bash theme={null}
curl -X POST https://api.platnova.com/v1/cards \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id": "user_123", "spending_limit": 1000}'
```
## Security Best Practices
* **Keep your API key secure** - Never expose it in client-side code or public repositories
* **Use environment variables** - Store your API key in secure environment variables
* **Rotate keys regularly** - Generate new keys periodically for enhanced security
* **Monitor usage** - Check your dashboard regularly for unusual activity
* **Use webhooks securely** - Validate webhook signatures to ensure data integrity
## Rate Limits
Account creation is free. Paid plans include higher limits and priority processing. Check your current plan in the [dashboard](https://business.platnova.com/settings/billing).
## Need Help?
* **Onboarding**: Contact [support@platnova.com](mailto:support@platnova.com) to start your account setup and compliance verification
* **Documentation**: Explore our [API reference](./api-reference) for detailed examples
* **Support**: Reach out to [support@platnova.com](mailto:support@platnova.com) for technical assistance and integration help
* **Community**: Join our [Slack](https://slack.platnova.com) for developer discussions
# Funding & Withdrawals
Source: https://docs.platnova.com/card/funding
Manage card balances by depositing funds from your wallet or withdrawing funds back to your wallet. These operations help you control spending and manage card balances effectively.
## Funding Cards
Add funds to a card from your business wallet. Deposits are processed instantly and the card balance is updated immediately.
### Depositing Funds
```bash theme={null}
curl -X POST https://api.platnova.com/v1/cards/{card_id}/deposit \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": "250.00"
}'
```
### Deposit Requirements
* Funds must be available in your wallet
* Wallet currency must match card currency
* Minimum deposit amounts may apply depending on currency
### Deposit Response
```json theme={null}
{
"status": true,
"data": {
"transaction_id": "txn_123",
"card_id": "card_456",
"amount": "250.00",
"currency": "USD",
"previous_balance": "100.00",
"new_balance": "350.00",
"status": "success"
},
"message": "Deposit successful"
}
```
## Withdrawing Funds
Retrieve funds from a card back to your business wallet. Withdrawals reduce the card balance accordingly.
### Withdrawing Funds
```bash theme={null}
curl -X POST https://api.platnova.com/v1/cards/{card_id}/withdraw \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": "150.00"
}'
```
### Withdrawal Requirements
* Card must have sufficient balance
* Card must be in active status (not frozen or cancelled)
* Minimum withdrawal amounts may apply
### Withdrawal Response
```json theme={null}
{
"status": true,
"data": {
"transaction_id": "txn_789",
"card_id": "card_456",
"amount": "150.00",
"currency": "USD",
"previous_balance": "350.00",
"new_balance": "200.00",
"status": "success"
},
"message": "Withdrawal successful"
}
```
## Checking Card Balance
View the current balance of a card:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/cards/{card_id} \
-H "X-API-KEY: YOUR_API_KEY"
```
The response includes the current balance in the card's currency.
## Transaction History
View all deposit and withdrawal transactions for a card:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/cards/{card_id}/events \
-H "X-API-KEY: YOUR_API_KEY"
```
This returns all card events including deposits, withdrawals, and purchases.
## Best Practices
* Monitor card balances regularly
* Set appropriate funding limits based on expected usage
* Withdraw unused funds to optimize cash flow
* Keep track of all deposit and withdrawal transactions
## Next Steps
* Learn about [Card Management](/card/management) for freezing and unfreezing cards
* Explore the [Cards API Reference](/api-reference/cards/deposit) for detailed documentation
# Card Management
Source: https://docs.platnova.com/card/management
Manage your cards effectively with freeze, unfreeze, and status controls. These features help you maintain security and control over card usage.
## Freezing Cards
Freeze a card to temporarily disable it. Frozen cards cannot be used for purchases until they are unfrozen.
### When to Freeze a Card
* Suspected unauthorized activity
* Employee termination or leave
* Lost or stolen card reports
* Temporary spending restrictions needed
### Freezing a Card
```bash theme={null}
curl -X PUT https://api.platnova.com/v1/cards/{card_id}/freeze \
-H "X-API-KEY: YOUR_API_KEY"
```
The card status will change to "frozen" and all attempts to use it will be declined.
## Unfreezing Cards
Unfreeze a card to restore its functionality. The card can be used immediately after unfreezing.
### Unfreezing a Card
```bash theme={null}
curl -X PUT https://api.platnova.com/v1/cards/{card_id}/unfreeze \
-H "X-API-KEY: YOUR_API_KEY"
```
The card status will change back to "active" and normal usage can resume.
## Checking Card Status
Retrieve the current status of a card:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/cards/{card_id} \
-H "X-API-KEY: YOUR_API_KEY"
```
### Card Statuses
* **active** - Card is active and can be used
* **frozen** - Card is frozen and cannot be used
* **cancelled** - Card has been cancelled permanently
## Card Information
View complete card details including masked card number, expiration date, and balance:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/cards/{card_id} \
-H "X-API-KEY: YOUR_API_KEY"
```
## Revealing Card Details
For security, card numbers and CVVs are masked by default. Use the reveal endpoint to get the full card details:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/cards/{card_id}/reveal \
-H "X-API-KEY: YOUR_API_KEY"
```
**Note:** The reveal endpoint is rate-limited to prevent abuse. Use it only when necessary.
## Best Practices
* Freeze cards immediately if suspicious activity is detected
* Regularly review card status and balances
* Use unfreeze only when you're certain the card should be active
* Keep card details secure and never expose CVVs unnecessarily
## Next Steps
* Learn about [Funding & Withdrawals](/card/funding) for managing card balances
* Explore the [Cards API Reference](/api-reference/cards/freeze) for detailed documentation
# Overview
Source: https://docs.platnova.com/card/overview
Virtual cards allow you to issue cards to your customers, employees, or vendors with spending controls and real-time transaction monitoring. Cards can be created instantly and managed programmatically through our API.
## What Are Virtual Cards?
Virtual cards are digital payment cards that can be used for online and in-store purchases. Each card is linked to a customer and can be funded from your business wallet. Cards support multiple currencies and can be frozen, unfrozen, or have funds withdrawn as needed.
## Key Features
### Instant Card Creation
Create cards instantly for your customers with a simple API call. Cards are provisioned immediately and can be used right away for online purchases.
### Multi-Currency Support
Issue cards in multiple currencies including USD, NGN, and other supported currencies. Each card operates in a single currency, but you can create multiple cards for different currencies.
### Spending Controls
Manage card spending through various controls including balance limits, transaction limits, and merchant restrictions. Cards can be frozen instantly to prevent unauthorized use.
### Real-Time Monitoring
Track all card activity in real-time including purchases, deposits, withdrawals, and card events. Get detailed transaction history with merchant information and categorization.
### Card Management
Full lifecycle management including card creation, funding, withdrawal, freezing, and unfreezing. Cards can be updated with new spending limits or restrictions as needed.
## Card Lifecycle
### Creating Cards
When you create a card, you specify the currency, brand (Mastercard or Visa), initial funding amount, and the customer it's assigned to. The card is created instantly and can be used immediately.
### Funding Cards
Add funds to cards from your business wallet at any time. Deposits are processed instantly and the card balance is updated immediately.
### Card Usage
Cards can be used for online purchases, in-store payments, and other transactions. All transactions are tracked and reported in real-time.
### Withdrawing Funds
Retrieve funds from cards back to your business wallet when needed. Withdrawals reduce the card balance accordingly.
### Freezing and Unfreezing
Temporarily disable cards by freezing them. Frozen cards cannot be used until they are unfrozen. This is useful for security purposes or when you need to temporarily disable a card.
## Card Information
Each card includes detailed information such as:
* Card number (masked for security)
* Expiration date
* CVV (available through reveal endpoint)
* Cardholder name
* Billing address
* Card status (active, frozen, cancelled)
## Security
### Sensitive Data Protection
Card numbers and CVVs are protected and only revealed through a secure, rate-limited endpoint. The reveal endpoint is rate limited to prevent abuse.
### Transaction Monitoring
All card transactions are monitored and logged. Unusual activity can trigger alerts and automatic card freezing.
## Getting Started
Ready to start issuing cards? Check out our [API Reference](/api-reference/cards/create) for detailed endpoint documentation, or see our [Quick Start Guide](/card/quickstart) to create your first card in minutes.
# Quickstart
Source: https://docs.platnova.com/card/quickstart
Get started with virtual cards in just a few minutes. This guide will walk you through creating your first card, funding it, and making a purchase.
## Prerequisites
* A Platnova account ([sign up here](https://business.platnova.com))
* An API key (see [Authentication](/authentication))
* A customer created in your system
## Step 1: Create a Customer
Before creating a card, you need to have a customer in your system:
```bash theme={null}
curl -X POST https://api.platnova.com/v1/customers \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890",
"date_of_birth": "1990-05-15",
"country_code": "US"
}'
```
## Step 2: Create a Card
Create a virtual card for your customer:
```bash theme={null}
curl -X POST https://api.platnova.com/v1/cards/create \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "customer_id_from_step_1",
"currency": "USD",
"brand": "mastercard",
"wallet_id": "defaults_to_currency_funding_wallet",
"amount": "100.00" // optional
}'
```
## Step 3: Fund the Card
Add funds to your card from your wallet:
```bash theme={null}
curl -X POST https://api.platnova.com/v1/cards/{card_id}/deposit \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": "500.00"
}'
```
## Step 4: View Card Details
Retrieve card information including card number and CVV:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/cards/{card_id}/reveal \
-H "X-API-KEY: YOUR_API_KEY"
```
## Step 5: Monitor Card Activity
View all transactions and events for your card:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/cards/{card_id}/events \
-H "X-API-KEY: YOUR_API_KEY"
```
## Example Response
```json theme={null}
{
"status": true,
"data": {
"id": "card_123",
"customer_id": "customer_456",
"currency": "USD",
"balance": "500.00",
"status": "active",
"brand": "mastercard",
"created_at": "2025-01-30T10:00:00Z"
},
"message": "Card created successfully"
}
```
## Next Steps
* Learn about [Card Management](/card/management) for freezing and unfreezing cards
* Explore [Funding & Withdrawals](/card/funding) for managing card balances
* Check out the [Cards API Reference](/api-reference/cards/create) for detailed documentation
# Initiating Checkout
Source: https://docs.platnova.com/checkout/initiating-checkout
Start a checkout session with `POST /v1/checkout`. This creates a hosted payment page and returns a checkout `id` and `url`.
## Example request
```bash theme={null}
curl --location 'https://sandbox.api.platnova.co/v1/checkout' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data-raw '{
"email": "jonathanemma121@gmail.com",
"amount": 2000.15,
"currency": "ngn",
"payment_options": [
{
"id": "defi"
}
]
}'
```
## Request fields
* **email**: Customer email for the checkout.
* **amount**: Amount to collect.
* **currency**: Currency code (for example `ngn`).
* **payment\_options**: Optional. The ways the payer may pay. **Leave it out to offer every method that is live for the currency** — that is the recommended default, and new methods reach your payers as we switch them on. Send it only to restrict the checkout to specific methods. Supported `id` values:
| `id` | What the payer does | Currencies |
| - | - | - |
| `tag_transfer` | Pays from their Platnova wallet by scanning a QR code | all |
| `bank_transfer` | Transfers to a one-time account number | NGN |
| `card` | Enters their card on a secure page | NGN, USD, EUR, GBP, CAD |
| `apple_pay` | One tap on an iPhone, iPad or Mac | USD, EUR, GBP, CAD (NGN soon) |
| `google_pay` | One tap in Chrome or on Android | USD, EUR, GBP, CAD (NGN soon) |
| `opay` | Approves the payment in their OPay app | NGN |
| `bank_account` | Picks their bank and approves in that bank's own app or online banking | NGN |
| `ussd` | Dials a code from any phone, no internet banking needed | NGN |
| `mobile_money` | Approves a prompt on their phone, paying from a Ghanaian, Kenyan, Ugandan, Rwandan or Tanzanian wallet in that currency at Platnova's rate | all |
| `crypto` | Pays in crypto | all |
A method that is not live for the checkout's currency is left off the page even if you list it. Mobile money is cross-currency: the payer sees what they will pay in their own currency, you are settled the checkout amount in yours, and the conversion is Platnova's, not yours. `novatag` and `defi` are accepted as older spellings of `tag_transfer` and `crypto`.
## Payment option values
To restrict a checkout, list the methods you want:
```json theme={null}
[
{ "id": "bank_transfer" },
{ "id": "ussd" },
{ "id": "opay" },
{ "id": "card" }
]
```
To offer everything, omit `payment_options` from the request.
## Example response
```json theme={null}
{
"status": true,
"data": {
"amount": 2000.15,
"currency": "ngn",
"id": "3e584f08-6a55-4b15-a97f-364a7d21071e",
"email": "jonathanemma121@gmail.com",
"url": "https://pay.platnova.com/3e584f08-6a55-4b15-a97f-364a7d21071e",
"status": "pending",
"success_url": "https://platnova.com/process?status=successful",
"cancel_url": "https://platnova.com/process?status=cancelled",
"source": "platform",
"entity": {
"category": "Technology",
"country_code": "NG",
"created_at": "2025-09-14T20:00:41.114031Z",
"description": "A leading technology solutions provider g",
"dial_code": "+234",
"id": "67fa2a59-5d73-4f9c-be49-2a3a8c391cde",
"legal_name": "Techies 2 Ltd",
"name": "Techies 2 Ltd",
"phone": "8012345678",
"status": "ACTIVE",
"username": "techies2ltd"
},
"payment_options": [
{
"id": "defi"
}
],
"created_at": "2026-05-05T15:57:19Z"
},
"error": [],
"message": "operation was successful"
}
```
Use `data.url` to redirect your customer to complete payment. Keep `data.id` so you can retrieve this checkout later with the get endpoint.
# Overview
Source: https://docs.platnova.com/checkout/overview
Checkout lets your business create a hosted payment session for a customer and redirect them to a Platnova payment page. You create the checkout with amount, currency, and payment options, then send the generated `url` to the customer to complete payment.
## How checkout works
1. **Create checkout** using `POST /v1/checkout` with customer email, amount, currency, and payment options.
2. **Redirect customer** to the returned hosted checkout `url`.
3. **Track status** by fetching the checkout with `GET /v1/checkout/{id}`.
## Next steps
* Build your first request in [Initiating checkout](/checkout/initiating-checkout)
* Fetch an existing checkout in [Retrieving checkout](/checkout/retrieving-checkout)
* See full request/response schemas in [Create checkout](/api-reference/checkout/create) and [Get checkout](/api-reference/checkout/get)
# Retrieving Checkout
Source: https://docs.platnova.com/checkout/retrieving-checkout
Retrieve an existing checkout with `GET /v1/checkout/{id}` to confirm its latest state and details.
## Example request
```bash theme={null}
curl --location 'https://sandbox.api.platnova.co/v1/checkout/3e584f08-6a55-4b15-a97f-364a7d21071e' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN'
```
## Example response
```json theme={null}
{
"status": true,
"data": {
"amount": 2000.15,
"currency": "ngn",
"id": "3e584f08-6a55-4b15-a97f-364a7d21071e",
"email": "jonathanemma121@gmail.com",
"url": "https://pay.platnova.com/3e584f08-6a55-4b15-a97f-364a7d21071e",
"status": "pending",
"success_url": "https://platnova.com/process?status=successful",
"cancel_url": "https://platnova.com/process?status=cancelled",
"source": "platform",
"entity": {
"category": "Technology",
"country_code": "NG",
"created_at": "2025-09-14T20:00:41.114031Z",
"description": "A leading technology solutions provider g",
"dial_code": "+234",
"id": "67fa2a59-5d73-4f9c-be49-2a3a8c391cde",
"legal_name": "Techies 2 Ltd",
"name": "Techies 2 Ltd",
"phone": "8012345678",
"status": "ACTIVE",
"username": "techies2ltd"
},
"payment_options": [
{ "id": "tag_transfer" },
{ "id": "bank_transfer" },
{ "id": "card" },
{ "id": "opay" },
{ "id": "ussd" },
{ "id": "crypto" }
],
"created_at": "2026-05-05T15:57:19Z"
},
"error": [],
"message": "operation was successful"
}
```
The response payload mirrors the create response and includes the latest checkout `status`. Use this endpoint when you need to fetch checkout details on demand in your backend.
# KYC & Verification
Source: https://docs.platnova.com/customers/kyc
Know Your Customer (KYC) verification ensures compliance with financial regulations and helps prevent fraud. This guide covers the KYC process and how to manage customer verification.
## What is KYC?
KYC (Know Your Customer) is a process that verifies the identity of customers before they can use financial services. It helps ensure compliance with anti-money laundering (AML) regulations and prevents fraud.
## KYC Requirements
KYC verification typically requires:
* **Identity Verification** - Government-issued ID (passport, driver's license, national ID)
* **Address Verification** - Proof of address (utility bill, bank statement)
* **Biometric Verification** - In some cases, biometric data may be required
## Customer Status and KYC
Customer status reflects their KYC verification state:
* **Approval Pending** - Customer created but KYC not yet verified
* **Active** - KYC verified, customer can use services
* **Locked** - KYC verification failed or account locked
* **Restricted** - Customer has restrictions due to KYC issues
## Checking Customer Status
Monitor customer KYC status:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/customers/{customer_id} \
-H "X-API-KEY: YOUR_API_KEY"
```
The response includes the customer's current status and any KYC-related information.
## KYC Verification Process
### Step 1: Customer Creation
Create the customer with basic information:
```bash theme={null}
curl -X POST https://api.platnova.com/v1/customers \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890",
"date_of_birth": "1990-05-15",
"country_code": "US"
}'
```
### Step 2: Submit KYC Documents
Include identity documents in the `documents` array on create, add them with [Update customer](/api-reference/customers/update), or submit through your dashboard. Verification may be automatic or manual depending on your configuration.
### Step 3: Verification Complete
Once verified, the customer status changes to "active" and they can receive cards, virtual accounts, and other services.
## KYC Compliance
### Why KYC Matters
* **Regulatory Compliance** - Required by financial regulations
* **Fraud Prevention** - Helps prevent identity theft and fraud
* **Risk Management** - Reduces risk of money laundering and other illegal activities
### Best Practices
* Collect all required KYC information during onboarding
* Verify documents promptly to avoid delays
* Keep KYC documents secure and confidential
* Monitor customer status regularly
* Update KYC information when customer details change
## Handling KYC Failures
If KYC verification fails:
1. Customer status may change to "locked" or "restricted"
2. Review the reason for failure
3. Request additional documentation if needed
4. Resubmit for verification
## Next Steps
* Learn about [Customer Onboarding](/customers/onboarding) for creating customers
* Explore the [Customers API Reference](/api-reference/customers/get) for detailed documentation
# Customer Onboarding
Source: https://docs.platnova.com/customers/onboarding
Onboard customers quickly and efficiently with our streamlined customer creation process. This guide covers the essential steps for creating customer profiles and preparing them for service.
## Creating a Customer
Create a new customer with basic information:
```bash theme={null}
curl -X POST https://api.platnova.com/v1/customers \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890",
"date_of_birth": "1990-05-15",
"country_code": "US"
}'
```
## Required Information
### Basic Details
* **First Name** - Customer's first name
* **Last Name** - Customer's last name
* **Email** - Valid email address
* **Phone** - Phone number with country code
* **Date of Birth** - `YYYY-MM-DD` for age verification
* **Country Code** - ISO country code (e.g., US, NG, GB)
### Optional Information
* **Gender** - Customer gender
* **Documents** - Identity documents including tax ID, passed as the `documents` array (see [Create Customer](/api-reference/customers/create)). See [Tax ID document](#tax-id-document) below.
* **Address** - Billing or residential address
* **Proof of funds** - Employment and source-of-funds fields (see below)
### Tax ID document
A tax ID is required when creating virtual accounts for a customer. Pass it as an entry in the `documents` array with the `id_type` that matches the customer's country, and the tax ID number in `id_number`.
The `id_type` varies by country — for example `ssn` for US customers, `nino` for UK customers, and `bvn` for Nigerian customers. Countries not covered by a specific type use `tin` as the default.
See the full country-to-type mapping in [Create Customer — Tax ID document](/api-reference/customers/create#tax-id-document).
**Example** — adding a tax ID for a US customer:
```json theme={null}
{
"documents": [
{
"id_type": "ssn",
"id_number": "123-45-6789"
}
]
}
```
### Proof of funds values
Each `proof_of_funds` property must use an exact **field value** from the reference (for example `employment_status`: `employed`). Occupation uses identifiers such as `151252` for software developer.
See the full reference: **[Proof of funds options](/customers/proof-of-funds-options)**.
## Customer Response
```json theme={null}
{
"status": true,
"data": {
"id": "customer_123",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890",
"country_code": "US",
"status": "approval_pending",
"created_at": "2025-01-30T10:00:00Z"
},
"message": "Customer created successfully"
}
```
## Customer Status
After creation, customers typically start with "approval\_pending" status. This means they're created but may need KYC verification before they can receive services.
### Status Flow
1. **Approval Pending** - Customer created, awaiting verification
2. **Active** - Customer verified and can receive services
3. **Locked** - Customer account is locked
4. **Restricted** - Customer has restrictions on their account
## Next Steps After Creation
Once a customer is created, you can:
* Issue cards to the customer
* Create virtual accounts for the customer
* Send payments to the customer
* Track customer transactions
## Retrieving Customer Information
Get customer details at any time:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/customers/{customer_id} \
-H "X-API-KEY: YOUR_API_KEY"
```
## Listing Customers
View all your customers:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/customers \
-H "X-API-KEY: YOUR_API_KEY"
```
## Best Practices
* Collect all required information during onboarding
* Verify email addresses and phone numbers
* Keep customer data up to date
* Monitor customer status for compliance
## Next Steps
* Use [Proof of funds options](/customers/proof-of-funds-options) when collecting `proof_of_funds` field values
* Learn about [KYC & Verification](/customers/kyc) for compliance requirements
* Explore the [Customers API Reference](/api-reference/customers/create) for detailed documentation
# Overview
Source: https://docs.platnova.com/customers/overview
Customers are the individuals or businesses that use your services. The Customers API allows you to onboard customers, manage their profiles, and handle KYC (Know Your Customer) or KYB (Know Your Business) compliance requirements.
## What Are Customers?
Customers are the end users of your platform who receive cards, virtual accounts, or other services. Each customer has a profile with identification information, contact details, and compliance data required for financial services.
## Key Features
### Customer Onboarding
Create customer profiles with necessary identification and contact information. Customer creation includes KYC data collection for compliance purposes.
### Profile Management
Manage customer profiles including personal information, contact details, and status. Update customer information as needed and track customer status.
### KYC Compliance
Collect and manage KYC information including identification documents, addresses, and compliance data. Customer status reflects KYC verification progress.
### Customer Status
Track customer status including approval pending, active, locked, and restricted states. Status indicates the customer's current state in your system.
## Customer Lifecycle
### Creating Customers
When you create a customer, you provide basic information including name, email, phone, and country code. Additional KYC information can be provided during creation or updated later.
### KYC Verification
Customers go through KYC verification after creation. The verification process includes document verification, address verification, and other compliance checks.
### Customer Activation
Once KYC verification is complete, customers are activated and can receive cards, virtual accounts, and other services. Active customers can use all available features.
## Customer Information
Each customer includes:
* Customer ID
* Personal information (name, email, phone)
* Country and dial code
* Customer status
* KYC information (documents, address, compliance data)
* Creation and update timestamps
## Customer Status
Customers can have different statuses:
* Approval Pending - Customer is awaiting KYC verification
* Active - Customer is verified and active
* Locked - Customer account is locked
* Restricted - Customer has restrictions on their account
## Getting Started
Ready to start managing customers? Check out our [API Reference](/api-reference/customers/create) for detailed endpoint documentation.
# Proof of funds options
Source: https://docs.platnova.com/customers/proof-of-funds-options
Allowed values for proof_of_funds fields when creating or updating customers.
When you send `proof_of_funds` on [create customer](/api-reference/customers/create) or [update customer](/api-reference/customers/update), set each property to one of the **Field** values below. The **Description** explains what each value represents.
## employment\_status
How the customer describes their current work situation.
| Field | Description |
| - | - |
| `employed` | Employed — works in traditional paid employment. |
| `homemaker` | Homemaker — primary role is running the household and family care. |
| `retired` | Retired — no longer in the workforce. |
| `self_employed` | Self-employed — works for themselves or runs their own business. |
| `student` | Student — primarily in education or training. |
| `unemployed` | Unemployed — not currently employed. |
## expected\_monthly\_pay
Rough band for how much the customer expects to move through the account each month (or their income band, as applicable to your flow).
| Field | Description |
| - | - |
| `0_4999` | Less than five thousand US dollars per month. |
| `5000_9999` | Five thousand US dollars or more per month. |
## primary\_purpose
Why the customer is using the product or moving money.
| Field | Description |
| - | - |
| `charitable_donations` | Charitable donations — giving to nonprofits or causes. |
| `ecommerce_retail_payments` | Ecommerce and retail payments — shopping and online or retail purchases. |
| `investment_purposes` | Investment purposes — building or managing investments. |
| `operating_a_company` | Operating a company — business operations and company-related activity. |
| `payments_to_friends_or_family_abroad` | Payments to friends or family abroad — remittances or personal transfers overseas. |
| `personal_or_living_expenses` | Personal or living expenses — day-to-day personal spending. |
| `protect_wealth` | Protect wealth — preserving or safeguarding assets. |
| `purchase_goods_and_services` | Purchase goods and services — general buying of goods and services. |
| `receive_payment_for_freelancing` | Receive payment for freelancing — income from freelance or contract work. |
## source\_of\_funds
Where the customer’s money primarily comes from.
| Field | Description |
| - | - |
| `company_funds` | Company funds — money originating from a business entity. |
| `gifts` | Gifts — funds received as gifts. |
| `government_benefits` | Government benefits — state or government assistance programs. |
| `inheritance` | Inheritance — money or assets from an estate. |
| `pension_retirement` | Pension or retirement funds — pension, annuity, or retirement savings. |
| `salary` | Salary — regular wages or salary from employment. |
| `sale_of_assets_real_estate` | Sale of assets or real estate — proceeds from selling property or other assets. |
| `savings` | Savings — accumulated personal savings. |
## occupation
Standard occupation identifier. Use the **Field** value as the `occupation` string; the **Description** is the role title that value represents.
| Field | Description |
| - | - |
| `151252` | Software developer. |
| `291141` | Registered nurse. |
| `2912XX` | Other physician. |
| `21109X` | Other community and social service specialist. |
| `151299` | Other computer occupation. |
| `434051` | Customer service representative. |
| `1320XX` | Other financial specialist. |
| `131082` | Project management specialist. |
| `151255` | Web and digital interface designer. |
| `273099` | Other media and communication worker. |
| `119111` | Medical and health services manager. |
| `231011` | Lawyer. |
| `232099` | Other legal support worker. |
| `119199` | Other manager. |
| `131161` | Market research analyst and marketing specialist. |
| `112021` | Marketing manager. |
| `17302X` | Other engineering technologist and technician. |
| `132011` | Accountant and auditor. |
| `151211` | Computer systems analyst. |
| `999999` | Unemployed with no work experience in the last five years, earlier, or never worked. |
## Next steps
* [Customer onboarding](/customers/onboarding) — end-to-end create flow
* [Create customer (API)](/api-reference/customers/create) — request schema
# Environments
Source: https://docs.platnova.com/environments
Platnova provides two distinct environments to support your development workflow: a sandbox environment for testing and a live environment for production use.
## Environment Comparison
| Feature | Sandbox Environment | Live Environment |
| - | - | - |
| **Base URL** | `https://sandbox.api.platnova.co` | `https://api.platnova.com` |
| **Purpose** | Development, testing, and integration | Production use with real transactions |
| **Data Type** | Test data (simulated) | Real data (actual money and accounts) |
| **Approval** | No approval needed | Production approval required |
Always test your integration thoroughly in the sandbox environment before moving to production.
Only use the live environment after thorough testing in sandbox and receiving approval from our compliance team.
```bash theme={null}
# Sandbox API calls
curl -X POST https://sandbox.api.platnova.co/v1/cards \
-H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id": "test_user_123", "spending_limit": 1000}'
```
```bash theme={null}
# Live API calls
curl -X POST https://api.platnova.com/v1/cards \
-H "Authorization: Bearer YOUR_LIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id": "user_123", "spending_limit": 1000}'
```
## API Keys
Each environment requires separate API keys. Your sandbox and live API keys are managed independently in your dashboard.
Sandbox API keys are clearly marked and cannot be used in the live environment. Similarly, live API keys cannot be used in sandbox.
## Webhooks
Both environments support Webhooks.
Configure webhooks for both environments to ensure your integration works seamlessly when moving to production.
## Rate Limits
Rate limits are more generous in the sandbox environment to support development and testing:
* **Sandbox**: Higher limits for testing and development
* **Live**: Standard production limits based on your plan
## Getting Started
Reach out to [support@platnova.com](mailto:support@platnova.com) to begin your onboarding process and get access to both environments.
Start with the sandbox environment to test your integration and verify all functionality works as expected.
Complete all compliance requirements and receive approval for live environment access.
Once approved, deploy your integration using the live environment for real transactions.
## Need Help?
* **Environment Setup**: Contact [support@platnova.com](mailto:support@platnova.com) for environment access
* **Testing Support**: Get help with sandbox testing and integration verification
* **Production Approval**: Work with our compliance team for live environment access
# Error Handling
Source: https://docs.platnova.com/errors
Platnova uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a request failed, etc.). Codes in the 5xx range indicate an error with Platnova's servers (these are rare).
| Code | Description |
| - | - |
| **200 - OK** | Everything worked as expected. |
| **400 - Bad Request** | The request was unacceptable, often due to missing a required parameter. |
| **401 - Unauthorized** | No valid API key was provided. |
| **402 - Request Failed** | The parameters were valid but the request failed. |
| **403 - Forbidden** | The API key doesn't have permission to perform the request. |
| **404 - Not Found** | The requested resource doesn't exist. |
| **409 - Conflict** | The request conflicts with another request. |
| **429 - Too Many Requests** | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
| **500, 502, 503, 504 - Server Errors** | Something went wrong on Platnova's end. These are rare and if they happen, please contact us immediately. |
## Error Response Format
Platnova uses two types of error response formats:
### Field Validation Errors
When validation fails for specific fields:
```json theme={null}
{
"error": {
"field_name": [
"This field is required"
]
}
}
```
### General Errors
For authentication and other general errors:
```json theme={null}
{
"error": "Unauthorized access"
}
```
## Common Error Scenarios
### Missing Required Field
```json theme={null}
{
"error": {
"field_name": [
"This field is required"
]
}
}
```
### Unauthorized Access
```json theme={null}
{
"error": "Unauthorized access"
}
```
### Invalid API Key
```json theme={null}
{
"error": "Invalid API key"
}
```
## Best Practices
* **Handle 429 errors gracefully** - Implement exponential backoff when you receive rate limit errors
* **Validate input data** - Check your request parameters before sending to avoid 400 errors
* **Keep API keys secure** - Ensure your API key is valid and has the necessary permissions
* **Monitor for 5xx errors** - Contact support immediately if you encounter server errors
## Need Help?
If you're encountering persistent errors or need assistance with error handling, please contact our support team at [support@platnova.com](mailto:support@platnova.com) with your request details and error responses.
# Introduction
Source: https://docs.platnova.com/index
Platnova's Business API empowers businesses to streamline their financial operations through a comprehensive suite of financial services. Our platform provides virtual accounts, cards, digital wallets, payment processing, and user management capabilities to help you build and scale your financial infrastructure.
We've built a powerful financial platform that enables businesses to create, manage, and monitor virtual accounts, cards, wallets, and payment systems programmatically. Whether you're looking to issue cards for expense management, create virtual accounts for vendors, process payments globally, or manage digital wallets, our API provides the flexibility and security you need to scale your financial operations.
You can start integrating with our API once you have [signed up](https://business.platnova.com) on our dashboard.
Create and manage virtual cards with spending limits, real-time tracking, and multi-currency support.
Create virtual bank accounts for users to receive payments and facilitate transfers seamlessly.
Manage customer onboarding, profiles, and identity verification with comprehensive compliance features.
Process domestic and international money transfers with currency conversion capabilities.
Create digital wallets supporting multiple currencies with balance tracking and management.
Configure webhooks to receive real-time notifications for transactions, account updates, and system events.
## API Reference
In addition to the documentation, we also provide a detailed API reference to help you integrate. Every endpoint is accompanied by a description as well as descriptive request and response examples.
The API reference also covers general information such as [authentication](./api-reference/introduction#authentication), [error handling](./api-reference/introduction#error-handling), and [rate limits](./api-reference/introduction#rate-limits).
***
# Creating Invoices
Source: https://docs.platnova.com/invoices/creating
Create an invoice with `POST /v1/invoices`. You must send the customer’s **email** (a user in your entity), at least one **items** entry, and a **payment\_schedule** (due date, send date, payment methods, optional reminders). You can add **charges** (tax, discount, fee, shipping) and a **note**.
## Required fields
* **email** — Email of the user you’re invoicing (they must exist in your entity).
* **items** — Array of line items. Each has **name**, **unit\_price**, **quantity**, **currency**, **total** (usually unit\_price × quantity).
* **payment\_schedule** — Object with:
* **type** — `"one_time"` or `"re_occurring"`.
* **due\_date** — When payment is due (ISO date-time).
* **send\_date** — When the invoice is considered sent (ISO date-time).
* **payment\_methods** — Array of `{ "id": "bank_transfer", "value": "058" }` (or other method + value).
* Optionally **reminders** (boolean) and **reminder\_timing** (e.g. `{ "type": "before_due_date", "days": 3 }`).
* For re\_occurring: **repeat**, **interval** (daily, weekly, monthly, yearly), **end**.
## Example request
```bash theme={null}
curl -X POST https://api.platnova.com/v1/invoices \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "customer@example.com",
"note": "Thank you for your business",
"items": [
{
"name": "Consulting",
"unit_price": 150,
"quantity": 2,
"currency": "NGN",
"total": 300
},
{
"name": "Setup fee",
"unit_price": 50,
"quantity": 1,
"currency": "NGN",
"total": 50
}
],
"charges": {
"discount": { "amount": "0", "type": "flat", "enabled": false },
"tax": { "amount": "7.5", "type": "percentage", "enabled": true },
"fee": { "amount": "0", "type": "flat", "enabled": false },
"shipping": { "amount": "0", "type": "flat", "enabled": false }
},
"payment_schedule": {
"type": "one_time",
"due_date": "2026-02-15T23:59:59Z",
"send_date": "2026-01-30T00:00:00Z",
"payment_methods": [
{ "id": "bank_transfer", "value": "058" }
],
"reminders": true,
"reminder_timing": { "type": "before_due_date", "days": 3 }
}
}'
```
## Response
The response **data** includes **id** (invoice UID), **invoice\_number** (e.g. INV20260130001), **items**, **subtotal**, **total**, **charges**, **note**, **status** (e.g. pending, paid, cancelled), **payment\_schedule**, and **created\_at**. Share the **invoice\_number** with the customer so they can view and pay (e.g. GET `/v1/invoices/view/INV20260130001`).
## Line items and charges
* **items** — Each item needs name, unit\_price, quantity, currency, and total. Subtotal/total can be derived from these; the API may apply **charges** (tax, discount, etc.) when configured.
* **charges** — Optional. Each charge has **amount**, **type** (flat or percentage), and **enabled**. Use this for tax, discount, fee, or shipping.
For full schema and validation errors, see the [Create invoice](/api-reference/invoices/create) API reference. To list invoices or update status, see [Invoice management](/invoices/management).
# Invoice Management
Source: https://docs.platnova.com/invoices/management
You can view an invoice by its number, list all invoices with pagination and filters, and update an invoice’s status (e.g. mark it paid or cancel it). The invoice number is what you share with the customer; the invoice **uid** is what you use for the status update.
## View an invoice by number
Anyone with the invoice number can load the invoice (e.g. for a “view/pay” page). No auth required for the customer; you may expose this endpoint behind your own UX.
```bash theme={null}
curl -X GET "https://api.platnova.com/v1/invoices/view/INV20260130001"
```
Replace `INV20260130001` with the **invoice\_number** from the create response. The response **data** includes the invoice (id, invoice\_number, items, subtotal, total, charges, note, status, payment\_schedule, created\_at) and, when relevant, **payment\_details** (e.g. account\_name, account\_number, bank\_name, currency, swift\_code) so the customer can pay by transfer.
## List invoices
To list your entity’s invoices with pagination and optional filters:
```bash theme={null}
curl -X GET "https://api.platnova.com/v1/invoices?page=0&size=20" \
-H "X-API-KEY: YOUR_API_KEY"
```
Use **page**, **size**, **sort**, and **filters** as needed. The response is a standard paginated list: **data.items**, **data.page**, **data.size**, **data.total**, etc. Each item has the same shape as a single invoice (id, invoice\_number, items, subtotal, total, status, payment\_schedule, created\_at, etc.).
## Update invoice status
To change an invoice’s status (e.g. mark paid or cancel), use the invoice **uid** (the **id** from create or list), not the invoice number:
```bash theme={null}
curl -X PATCH "https://api.platnova.com/v1/invoices/inv_43a2b75e5c59429e872a/status" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "paid" }'
```
Allowed **status** values are **pending**, **paid**, and **cancelled**. Use this when you record payment outside the platform or when you cancel an invoice. If payments are recorded automatically when the customer pays, status may be updated for you.
## Tracking payments
Invoice payments show up in your [transactions](/transactions/viewing). List transactions and filter (e.g. by type or reference) to see which payments correspond to which invoices. You can also use the invoice **id** or invoice\_number in your own records to match payments to invoices.
For full request/response details, see the [Get invoice by number](/api-reference/invoices/get), [List invoices](/api-reference/invoices/list), and [Update invoice status](/api-reference/invoices/update-status) API reference.
# Overview
Source: https://docs.platnova.com/invoices/overview
Invoices let you bill a customer by email with line items, due date, and payment methods. You create an invoice (who to bill, what for, when it’s due, how they can pay); we generate an invoice number; the customer can view the invoice by that number and pay using the methods you configured. Status (pending, paid, cancelled) can be updated via the API or automatically when payment is received.
## What an invoice is
An invoice is a bill you send to a user in your entity—identified by **email**. It has **items** (name, quantity, unit price, currency, total), optional **charges** (tax, discount, fee, shipping), and a **payment\_schedule**: when it’s due, when it’s sent, which payment methods are allowed, and optional reminders. Each invoice gets a unique **invoice\_number** (e.g. INV20260130001) that the customer uses to view and pay.
## Lifecycle
1. **Create** — You send email, items, and payment\_schedule (and optionally charges, note). The API returns the invoice with id, invoice\_number, and status (e.g. pending).
2. **Customer views** — They open the invoice by number (e.g. GET `/v1/invoices/view/INV20260130001`) and see line items, total, and payment instructions.
3. **Payment** — They pay using one of the methods you set; when payment is received, status can move to paid (depending on your setup).
4. **Manage** — You can list invoices, get one by number, and update status (e.g. mark paid or cancel) with PATCH `/v1/invoices/{uid}/status`.
## What you need to create one
* **email** — The user (customer) in your entity to invoice.
* **items** — At least one line item: name, unit\_price, quantity, currency, total.
* **payment\_schedule** — type (one\_time or re\_occurring), due\_date, send\_date, payment\_methods (e.g. bank\_transfer + bank code), and optionally reminders and reminder\_timing.
Optional: **charges** (tax, discount, fee, shipping with amount, type, enabled) and **note**. For full request shape, see [Creating invoices](/invoices/creating) and the [Create invoice](/api-reference/invoices/create) API reference.
# Link Analytics
Source: https://docs.platnova.com/payment-links/analytics
To see how a payment link is doing, call `GET /v1/links/{uid}/stats`. You get the link details plus stats: total revenue, number of transactions, number of unique payers, and view count. Use the link **uid** you got when creating the link (e.g. from the **id** or **url** in the create response).
## Get link with stats
```bash theme={null}
curl -X GET "https://api.platnova.com/v1/links/lnk_43a2b75e5c59429e872a/stats" \
-H "X-API-KEY: YOUR_API_KEY"
```
Replace `lnk_43a2b75e5c59429e872a` with your link UID.
## What you get back
The response **data** includes the link (id, title, description, amount, url, status, expires\_at, created\_at, updated\_at) and:
* **total\_revenue** — Sum of amounts paid through this link.
* **total\_transactions** — Number of successful payments.
* **total\_users** — Number of unique payers.
* **total\_views** — How many times the link was viewed.
* **payment\_details** — Extra payment-related data (structure may vary).
So you can answer: how much was collected, how many payments, how many people paid, and how many times the link was opened.
## Listing all links
To list your payment links with pagination and optional filters, use `GET /v1/links` with query params **page**, **size**, **sort**, and **filters**. The response is a paginated list of links (without per-link stats). For per-link stats, call the stats endpoint above for each link UID.
## Using the numbers
* **total\_revenue** and **total\_transactions** — Track how much a link has collected and how many payments.
* **total\_views** — Gauge interest; if views are high but payments low, the amount or copy might need adjusting.
* **total\_users** — See whether one person paid multiple times or many people paid once.
For full request/response details, see the [Get payment link (with stats)](/api-reference/links/get) API reference.
# Creating Links
Source: https://docs.platnova.com/payment-links/creating-links
You create a payment link with `POST /v1/links`. The request needs a title, currency, and payment configuration (which methods are allowed). You can set a fixed amount, let the payer choose the amount, and optionally set an expiry.
## Required fields
* **title** — Short label for the link (e.g. "Invoice #1001").
* **currency** — Currency code (e.g. NGN, USD).
* **payment** — Object with **payment\_methods**: an array of `{ "id": "bank_transfer", "value": "058" }` (or other method + value, e.g. bank code). This defines how the payer can pay.
If the payer is not allowed to set the amount, you must also send **amount** (number). If you set **customer.can\_set\_price** to `true`, the payer can choose the amount and **amount** can be omitted.
## Example request
```bash theme={null}
curl -X POST https://api.platnova.com/v1/links \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Invoice #1001",
"description": "Payment for services",
"amount": 50000,
"currency": "NGN",
"expires_at": "2026-02-28T23:59:59Z",
"customer": {
"can_set_price": false
},
"payment": {
"limit": 1,
"payment_methods": [
{ "id": "bank_transfer", "value": "058" }
]
}
}'
```
* **description** — Optional text shown to the payer.
* **expires\_at** — Optional ISO 8601 datetime; after this the link won’t accept new payments.
* **customer.can\_set\_price** — `false`: you must provide **amount**. `true`: payer can enter the amount; **amount** can be omitted.
* **payment.limit** — Optional; max number of payments per link.
## Response
The response includes the new link in **data**: **id**, **title**, **url** (the shareable URL), **amount**, **currency**, **status**, **expires\_at**, **created\_at**, **updated\_at**. Share the **url** with the payer.
```json theme={null}
{
"status": true,
"data": {
"id": "lnk_43a2b75e5c59429e872a",
"title": "Invoice #1001",
"url": "/link/lnk_43a2b75e5c59429e872a",
"amount": 50000,
"currency": "NGN",
"status": 1,
"expires_at": "2026-02-28T23:59:59Z",
"created_at": "2026-01-30T12:00:00Z",
"updated_at": "2026-01-30T12:00:00Z"
},
"error": [],
"message": "operation was successful"
}
```
Build the full URL for the payer using your payment-host base URL + **data.url**. If you need stats (revenue, transaction count, views), use [Get payment link with stats](/payment-links/analytics). Full schema and errors are in the [Create payment link](/api-reference/links/create) API reference.
# Overview
Source: https://docs.platnova.com/payment-links/overview
Payment links are shareable URLs you create so someone can pay you without signing up or going through your checkout. You get a link; you send it (email, SMS, chat); the payer opens it and pays with the methods you allow. Good for one-off payments, donations, fees, or anything where you want a simple “pay this amount” flow.
## What you get
When you create a link, the API returns a unique URL. Share that URL with whoever should pay. You choose the amount (or let the payer choose), the currency, and which payment methods are allowed (e.g. bank transfer for a given bank code). You can set an expiry so the link stops accepting payments after a date.
Each link has a status and, when you fetch it with stats, you get totals: revenue, number of transactions, number of payers, and views. That lets you see how a link is performing without building a dashboard yourself.
## How it fits together
1. **Create a link** — You send title, currency, payment methods, and optionally a fixed amount and expiry. If you allow the payer to set the amount, you omit the amount.
2. **Share the URL** — You get back a URL; share it however you like.
3. **Payer pays** — They open the link and pay with one of the methods you enabled.
4. **Track results** — Use the same link UID to get stats (revenue, transactions, users, views) and payment details.
## When to use payment links
* One-time payments (invoices, fees, donations).
* Simple “pay me” flows where you don’t need a full checkout.
* Sharing a single URL by email or message and tracking how much was paid.
To create a link and see the exact request body, go to [Creating links](/payment-links/creating-links). For the API spec, see [Create payment link](/api-reference/links/create).
# Overview
Source: https://docs.platnova.com/payments/overview
The Payments API allows you to send money transfers to bank accounts, wallets, mobile money, cards, and other destinations; verify payment status; and manage payment operations. Payments can be sent domestically and internationally with support for multiple currencies and payment methods.
## What Are Payments?
Payments are money transfers sent from your business wallet to external recipients—including bank accounts, wallets (tag transfer), mobile money, cards, Revolut, PayPal, Cash App, Zelle, and other supported methods. You can verify the status of payments in real-time.
### Payment Verification
Verify payment status using payment references. Check whether payments have been processed, are pending, or have failed.
### Multi-Currency Support
Send payments in multiple currencies. Currency conversion is handled automatically when needed.
### Payment Methods
Support for multiple payment methods including bank transfer, card, mobile money, tag transfer (wallet-to-wallet), DeFi, Revolut, PayPal, Cash App, and Zelle. The method and recipient details (`info`) depend on the chosen `payment_method`.
## Payment Lifecycle
### Sending Payments
When you send a payment, you specify the amount, currency, recipient bank account details, and source wallet. The payment is processed and a transaction reference is returned.
### Payment Processing
Payments are processed asynchronously. The initial response indicates that the payment has been initiated, and the status will update as processing completes.
### Payment Verification
Use the payment reference to check the status of a payment. Status can be "processing", "success", or "failed".
## Payment Information
Each payment includes:
* Transaction reference
* Amount and currency
* Recipient bank account details
* Payment status
* Processing timestamp
## Supported Payment Methods
Payments support multiple methods; required fields in `info` depend on the method:
* **bank\_transfer** – Bank transfers (NGN, USD, and other currencies); ACH, RTP, wire for USD
* **card** – Card payments
* **mobile\_money** – Mobile money (e.g. Ghana)
* **tag\_transfer** – Wallet-to-wallet transfer (use `tag_id` in `info`)
* **wallet** – Wallet payments
* **defi** – DeFi payments
* **revolut** – Revolut transfers
* **paypal** – PayPal
* **ussd** – USSD
* **cashapp** – Cash App
* **zelle** – Zelle
Availability varies by currency and region. Use the [Send Payment](/api-reference/payments/send) endpoint with the appropriate `payment_method` and `info` payload.
## Getting Started
Ready to start sending payments? Check out our [API Reference](/api-reference/payments/send) for detailed endpoint documentation.
# Sending Payments
Source: https://docs.platnova.com/payments/sending-payments
Send money transfers using multiple payment methods. This guide covers how to send payments and track their status.
## Sending a Payment
Send a payment by specifying the payment method and recipient details in `info`. Example for a bank transfer:
```bash theme={null}
curl -X POST https://api.platnova.com/v1/payments/send \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_amount": 500.00,
"from_wallet_id": "wl_your_wallet_id",
"to_currency": "NGN",
"payment_method": "bank_transfer",
"info": {
"account_number": "0123456789",
"bank_code": "058",
"account_name": "Jane Smith"
},
"reference": "PAY001",
"payment_type": { "type": "instant" }
}'
```
## Payment Parameters
### Required Fields
* **from\_amount** – Amount to send (source currency)
* **from\_wallet\_id** – Wallet ID to debit from
* **to\_currency** – Destination currency (e.g. NGN, USD)
* **payment\_method** – One of: `bank_transfer`, `card`, `mobile_money`, `wallet`, `tag_transfer`, `defi`, `revolut`, `paypal`, `cashapp`, `zelle`
* **info** – Recipient details; required fields depend on `payment_method` (e.g. for `bank_transfer`: `account_number`, `bank_code`, `account_name`; for `tag_transfer`: `tag_id`)
### Optional Fields
* **reference** – Your payment reference for idempotency or tracking
* **payment\_type** – `instant`, `scheduled`, or `recurring` (default: instant)
* **is\_save\_to\_beneficiary** – Save recipient as beneficiary
## Finding the bank\_code
`bank_code` is not a CBN or SWIFT code; it is the code our payment provider uses for that bank in that country. Get it from [List banks](/api-reference/banks/list) for the recipient's country, and use it as-is:
1. `GET /v1/banks/{country_code}` lists every bank with its `code`.
2. For Ghana and Kenya, `GET /v1/banks/{country_code}/{bank_code}` lists branches; pass the chosen `branch_code` in `info.branch_code`.
3. `POST /v1/banks/verify` resolves the account number to the holder's name before you send.
4. If you only have an account number, `POST /v1/banks/suggest` returns banks we have paid it through before.
Cache the bank list for at most a day. All four endpoints need your API key.
## Payment Response
```json theme={null}
{
"status": true,
"data": {
"transaction_id": "txn_123",
"payment_reference": "PAY001",
"amount": "500.00",
"currency": "USD",
"recipient_account_number": "1234567890",
"recipient_name": "Jane Smith",
"status": "processing",
"created_at": "2025-01-30T10:00:00Z"
},
"message": "Payment initiated successfully"
}
```
## Payment Status
Payments are processed asynchronously. Status can be:
* **Processing** - Payment is being processed
* **Success** - Payment completed successfully
* **Failed** - Payment failed (check error details)
## Verifying Payment Status
Check payment status using the transaction reference returned from send:
```bash theme={null}
curl -X POST https://api.platnova.com/v1/payments/verify \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reference": "UTR_xxxx"
}'
```
## Payment Methods
The API supports multiple payment methods; pass `payment_method` and the matching `info` shape:
| Method | Description | Example info fields |
| - | - | - |
| **bank\_transfer** | Bank transfers (NGN, USD, etc.); ACH, RTP, wire for USD | `account_number`, `bank_code`, `account_name` |
| **card** | Card payments | Card-specific recipient details |
| **mobile\_money** | Mobile money (e.g. Ghana) | Phone, provider, etc. |
| **tag\_transfer** | Wallet-to-wallet transfer | `tag_id` |
| **wallet** | Wallet payments | Wallet identifier |
| **defi** | DeFi | Asset, network, address, etc. |
| **revolut** | Revolut | Revolut recipient details |
| **paypal** | PayPal | PayPal identifier |
| **ussd** | USSD | USSD channel details |
| **cashapp** | Cash App | Cash App identifier |
| **zelle** | Zelle | Zelle recipient details |
Availability depends on currency and region. See the [Send Payment API](/api-reference/payments/send) for the exact `info` fields per method.
## Payment Limits
Payment limits may apply based on:
* Account tier
* Currency
* Payment method
* Regulatory requirements
## Payment Fees
Fees may apply depending on:
* Payment amount
* Currency
* Payment method
* Destination country
## Best Practices
* Verify recipient account details before sending
* Include payment references for easy tracking
* Monitor payment status regularly
* Keep sufficient wallet balance
* Handle failed payments appropriately
## Next Steps
* Learn about [Payment Verification](/payments/verification) for checking payment status
* Explore the [Payments API Reference](/api-reference/payments/send) for detailed documentation
# Payment Verification
Source: https://docs.platnova.com/payments/verification
Verify payment status and track payment processing. This guide covers how to check payment status and handle payment verification.
## Verifying Payment Status
Check the status of a payment using its reference:
```bash theme={null}
curl -X POST https://api.platnova.com/v1/payments/verify \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reference": "PAY001"
}'
```
## Verification Response
```json theme={null}
{
"status": true,
"data": {
"transaction_id": "txn_123",
"payment_reference": "PAY001",
"amount": "500.00",
"currency": "USD",
"recipient_account_number": "1234567890",
"recipient_name": "Jane Smith",
"status": "success",
"processed_at": "2025-01-30T10:05:00Z",
"created_at": "2025-01-30T10:00:00Z"
},
"message": "Payment verified successfully"
}
```
## Payment Statuses
### Processing
Payment has been initiated and is being processed. This is the initial status for most payments.
```json theme={null}
{
"status": "processing",
"message": "Payment is being processed"
}
```
### Success
Payment completed successfully. Funds have been transferred to the recipient.
```json theme={null}
{
"status": "success",
"processed_at": "2025-01-30T10:05:00Z"
}
```
### Failed
Payment failed. Check error details for the reason.
```json theme={null}
{
"status": "failed",
"error": "Insufficient funds",
"error_code": "INSUFFICIENT_FUNDS"
}
```
## Common Failure Reasons
* **Insufficient Funds** - Not enough balance in source wallet
* **Invalid Account** - Recipient account number or bank code invalid
* **Account Mismatch** - Account name doesn't match account number
* **Bank Rejection** - Recipient bank rejected the payment
* **Network Error** - Temporary network or processing error
## Verification Best Practices
### When to Verify
* After sending a payment
* Periodically for pending payments
* Before showing payment confirmation to users
* When handling payment webhooks
### Verification Frequency
* Check immediately after sending
* Retry failed verifications after a delay
* Don't poll too frequently (respect rate limits)
* Use webhooks for real-time updates when possible
## Handling Payment Status
### Processing Payments
* Show "processing" status to users
* Set up retry logic for status checks
* Don't mark as complete until status is "success"
### Successful Payments
* Update your records
* Send confirmation to users
* Generate receipts if needed
### Failed Payments
* Log error details
* Notify users of failure
* Provide retry options if appropriate
* Handle refunds if needed
## Webhook Integration
Set up webhooks to receive real-time payment status updates:
```json theme={null}
{
"event": "payment.status.updated",
"data": {
"transaction_id": "txn_123",
"payment_reference": "PAY001",
"status": "success",
"processed_at": "2025-01-30T10:05:00Z"
}
}
```
## Next Steps
* Learn about [Sending Payments](/payments/sending-payments) for initiating transfers
* Explore the [Payments API Reference](/api-reference/payments/verify) for detailed documentation
# Overview
Source: https://docs.platnova.com/transactions/overview
See everything that moves money in your account—card spend, payments out, deposits, withdrawals, and more—in one place.
## What you can do
**List and filter** — Pull transaction history with filters (customer, date, type, status). Paginate through results or export to CSV.
**Check status** — Each transaction has a status: success, processing, or failed.
**Get receipts** — Generate a receipt for any transaction to share or keep for records.
## What shows up
Transactions include card activity (purchases, deposits, withdrawals), bank and other outbound payments, virtual account deposits, payment link and invoice payments, and similar activity. Each row has an ID, reference, amount, currency, type, status, timestamp, and optional customer or description details.
## Next step
[List transactions](/api-reference/transactions/list) in the API reference for the exact request and response.
# Receipts
Source: https://docs.platnova.com/transactions/receipts
You can generate a receipt for any transaction. The API returns a receipt as base64-encoded data (typically a PDF), which you can decode, save, or send to your customer.
## How it works
Call `GET /v1/transactions/{id}/receipt` with the transaction ID (the same `id` you get when listing transactions). The response is JSON: the `data` field contains the receipt as a base64 string. Decode it to get the PDF (or other format) and store or email it as needed.
## Request
```bash theme={null}
curl -X GET "https://api.platnova.com/v1/transactions/trx_43a2b75e-5c59-429e-872a-2a54c7b17e34/receipt" \
-H "X-API-KEY: YOUR_API_KEY"
```
Use the transaction UID from your [transaction list](/transactions/viewing)—for example `trx_43a2b75e-5c59-429e-872a-2a54c7b17e34`.
## Response
The response body is standard API envelope: `status`, `data`, `error`, `message`. The receipt content is in `data` as a base64-encoded string (e.g. a PDF). Decode it in your app to save or display the file.
```json theme={null}
{
"status": true,
"data": "JVBERi0xLjQKJeLjz9MK...",
"error": [],
"message": "operation was successful"
}
```
If the transaction is not found or the ID is invalid, you get a 400 with an error message.
## When to use it
* **Customer records** — Generate a receipt after a successful payment and email or show it to the payer.
* **Accounting** — Decode and store receipts in your system for reconciliation and audits.
* **Disputes** — Use the receipt as proof of transaction details when handling chargebacks or support.
For full request/response details, see the [Generate receipt](/api-reference/transactions/receipt) API reference.
# Viewing Transactions
Source: https://docs.platnova.com/transactions/viewing
Call `GET /v1/transactions` to list transactions. Use query params to page, sort, narrow by customer, or export.
## Basic request
```bash theme={null}
curl -X GET "https://api.platnova.com/v1/transactions" \
-H "X-API-KEY: YOUR_API_KEY"
```
## Pagination
Results are paginated. Use:
* **page** — Page number (0-based). Default `0`.
* **size** — Items per page. Default `20`.
Example: `?page=0&size=50`
## Filtering and sorting
* **customer\_id** — Restrict to one customer (UUID).
* **sort** — Sort field and direction (e.g. newest first).
* **filters** — Filter expression for type, status, date range, etc. See the [List transactions](/api-reference/transactions/list) reference for the exact filter format.
## Export
Pass the **export** query parameter to get results as CSV instead of JSON.
## Response shape
The response wraps everything in `data`:
* **data.items** — Array of transactions (id, ref, amount, fee, type, status, entry, message, created\_at, plus wallet and payment\_transfer when relevant).
* **data.page**, **data.size**, **data.max\_page**, **data.total\_pages**, **data.total**, **data.last**, **data.first**, **data.visible** — Pagination info.
Example:
```json theme={null}
{
"status": true,
"data": {
"items": [
{
"id": "trx_43a2b75e-5c59-429e-872a-2a54c7b17e34",
"ref": "UTR_7HeRoy4CRl6hcOOqAzwAeo0WLLMMbt",
"amount": "100.50",
"fee": "10.00",
"type": "transfer",
"status": "success",
"entry": "debit",
"message": "Bank transfer to John Doe",
"created_at": "2026-01-30T14:22:00Z",
"wallet": {},
"payment_transfer": {}
}
],
"page": 0,
"size": 20,
"max_page": 5,
"total_pages": 6,
"total": 112,
"last": false,
"first": true,
"visible": 20
},
"error": [],
"message": "operation was successful"
}
```
## Next
* [Generate a receipt](/api-reference/transactions/receipt) for a transaction by ID.
* [List transactions](/api-reference/transactions/list) in the API reference for full request/response details.
# Creating Accounts
Source: https://docs.platnova.com/virtual-accounts/creating-accounts
Create virtual bank accounts instantly for your customers. This guide covers the account creation process and how to retrieve account details.
## Creating a Virtual Account
Create a virtual account for a customer:
```bash theme={null}
curl -X POST https://api.platnova.com/v1/virtual-accounts/create \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "customer_123",
"currency": "USD"
}'
```
## Account Creation Parameters
### Required Fields
* **Customer ID** - The ID of the customer who will own the account
* **Currency** - The currency for the account (USD, NGN, etc.)
### Optional Fields
* **Account Type** - Current or savings account (defaults based on currency)
* **Account Name** - Custom account name (defaults to customer name)
* **Codes** - For NGN accounts, an array of provider bank codes used to select which provider issues the account (see [Choosing a Provider](#choosing-a-provider-ngn-accounts) below)
## Choosing a Provider (NGN Accounts)
For NGN virtual accounts, you can select which provider issues the account by passing its bank code in the `codes` field:
| Provider | Bank Code |
| - | - |
| Palmpay | `100033` |
| Paga | `100002` |
```bash theme={null}
curl -X POST https://api.platnova.com/v1/virtual-accounts/create \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "customer_123",
"currency": "NGN",
"id_number": "22123456789",
"codes": ["100033"]
}'
```
## Account Response
```json theme={null}
{
"status": true,
"data": {
"id": "va_123",
"customer_id": "customer_456",
"account_number": "1234567890",
"account_name": "John Doe",
"bank_name": "Platnova Bank",
"bank_code": "123",
"currency": "USD",
"routing_numbers": {
"ach": "123456789",
"rtp": "987654321",
"wire": "111222333"
},
"swift_code": "PLATUS33",
"status": "active",
"created_at": "2025-01-30T10:00:00Z"
},
"message": "Virtual account created successfully"
}
```
## Account Details
Each virtual account includes complete bank account information:
### Account Information
* **Account Number** - The bank account number for receiving payments
* **Account Name** - Name associated with the account
* **Bank Name** - Name of the bank
* **Bank Code** - Bank identification code
### Routing Information (USD Accounts)
* **ACH Routing Number** - For ACH transfers
* **RTP Routing Number** - For real-time payments
* **Wire Routing Number** - For wire transfers
### International Transfers
* **SWIFT Code** - For international wire transfers
## Account Types
Virtual accounts support different account types depending on the currency:
* **Current Account** - Standard checking account
* **Savings Account** - Interest-bearing account
The account type is determined automatically based on currency and provider capabilities.
## Multiple Accounts
Customers can have multiple virtual accounts in different currencies. Each account operates independently with its own account number and routing information.
## Listing Accounts
View all virtual accounts:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/virtual-accounts \
-H "X-API-KEY: YOUR_API_KEY"
```
Filter by customer or currency as needed.
## Best Practices
* Create accounts in the currencies your customers need
* Store account details securely
* Share account information with customers securely
* Monitor account activity regularly
## Next Steps
* Learn about [Receiving Payments](/virtual-accounts/receiving-payments) for payment collection
* Explore the [Virtual Accounts API Reference](/api-reference/virtual-accounts/create) for detailed documentation
# Dynamic Accounts
Source: https://docs.platnova.com/virtual-accounts/dynamic-accounts
Dynamic virtual accounts are single-use bank accounts generated on demand for a specific customer and a fixed payment amount. Unlike permanent virtual accounts, they expire automatically — either after the configured lifespan or once a matching payment is received.
## What Are Dynamic Virtual Accounts?
A dynamic virtual account is a time-bound, amount-locked bank account. When you create one, you specify:
* The **customer** it belongs to
* The **exact amount** it should accept
* The **lifespan** in minutes before it expires
Once a payment matching the exact amount is received, or the lifespan elapses, the account is no longer usable.
## Key Features
### Amount-Locked Payments
Each dynamic account is created for a specific amount. This guarantees that the exact expected amount is collected, making reconciliation straightforward with no partial or overpayments to handle.
### Automatic Expiry
Dynamic accounts expire after the lifespan you configure. This reduces exposure and ensures abandoned payment sessions do not leave open accounts indefinitely.
### Unique Reference per Session
Every generated account includes a unique `reference` field, allowing you to track and correlate payment sessions in your system. This reference is sent along with a webhook when the deposit is successful.
### Instant Provisioning
Accounts are created and ready to receive payments immediately. The full bank details — account number, account name, and bank name — are returned in the response and can be displayed directly to the payer.
## When to Use Dynamic Accounts
* **Checkout flows** — Generate a fresh account per order so each payment is uniquely tied to a transaction.
* **Invoice collection** — Issue a single-use account alongside an invoice to ensure the exact invoice amount is paid.
* **Time-sensitive requests** — Set a short lifespan to enforce payment deadlines (e.g., hold a booking for 20 minutes).
## Generating a Dynamic Account
```bash theme={null}
curl -X POST https://api.platnova.com/v1/virtual-accounts/dynamic \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "aad8aff0-00db-48b0-9bb0-9b399c313438",
"amount": 200,
"lifespan_minutes": 20
}'
```
## Response
```json theme={null}
{
"status": true,
"data": {
"account_name": "PLATNOVA TECHNOLOGIES LTD/PLATNOVA ",
"account_no": "9000043059",
"amount": 200,
"currency": "ngn",
"bank_name": "BEAMER (GABSYN) MICROFINANCE BANK",
"reference": "BDEPSTbdpLERjSmvg2XbF9iTA0bXxrX8E88BOI",
"email": "emmrysjonathan@gmail.com",
"expires_at": "2026-03-19T23:13:03.140476016Z",
"payment_session_id": "",
"usage": "integration",
"created_at": "2026-03-19T22:53:03.140476016Z",
"customer_id": "aad8aff0-00db-48b0-9bb0-9b399c313438"
},
"error": [],
"message": "operation was successful"
}
```
## Response Fields
| Field | Description |
| - | - |
| `account_name` | The name on the generated account |
| `account_no` | The bank account number to display to the payer |
| `amount` | The exact amount the account will accept |
| `currency` | Currency of the account (lowercase ISO code) |
| `bank_name` | Name of the bank that issued the account |
| `reference` | Unique reference for this payment session |
| `email` | Email address of the customer |
| `expires_at` | Timestamp when the account becomes inactive |
| `payment_session_id` | Session identifier for tracking (may be empty) |
| `usage` | Usage context identifier |
| `created_at` | Timestamp when the account was created |
| `customer_id` | ID of the customer this account belongs to |
## Account Lifecycle
1. **Created** — Account is provisioned instantly with full bank details.
2. **Active** — Account is live and can receive the specified amount during the lifespan window.
3. **Expired** — The lifespan elapses without a payment; the account becomes inactive.
4. **Completed** — A matching payment is received; the account closes.
## Best Practices
* Keep `lifespan_minutes` short (10–30 minutes) for checkout use cases to minimise open sessions.
* Always display `expires_at` to the payer so they know the deadline.
* Use the `reference` field to link the payment to your internal order or invoice record.
* If a session expires before payment, generate a new dynamic account rather than reusing the old one.
## Next Steps
* See the [API Reference](/api-reference/virtual-accounts/dynamic) for full request and response details.
* Learn how permanent virtual accounts work in [Creating Accounts](/virtual-accounts/creating-accounts).
# Overview
Source: https://docs.platnova.com/virtual-accounts/overview
Virtual accounts allow you to create bank accounts for your customers that can receive payments directly. Each virtual account is linked to a customer and can receive funds from any source, making it easy to collect payments from customers, vendors, or other parties.
## What Are Virtual Accounts?
Virtual accounts are bank accounts created programmatically for your customers. They function like regular bank accounts and can receive payments from any source. Funds received into virtual accounts are automatically credited to your business wallet, giving you full control over the funds.
## Key Features
### Instant Account Creation
Create virtual accounts instantly for your customers with a simple API call. Accounts are provisioned immediately and can receive payments right away.
### Multi-Currency Support
Create accounts in multiple currencies including USD, NGN, and other supported currencies. Each account operates in a single currency, but customers can have multiple accounts in different currencies.
### Multiple Account Types
Virtual accounts support different account types including current accounts and savings accounts. The account type depends on the currency and provider.
### Bank Account Details
Each virtual account includes complete bank account details such as account number, account name, bank name, routing numbers (for USD accounts), and SWIFT codes for international transfers.
### Payment Collection
Customers can receive payments directly into their virtual accounts. Funds are automatically credited to your business wallet, giving you full visibility and control.
## Account Lifecycle
### Creating Accounts
When you create a virtual account, you specify the currency and the customer it's assigned to. The account is created instantly with complete bank details that can be shared with payers.
### Receiving Payments
Payments can be sent to virtual accounts from any source. The account details (account number, bank name, routing numbers) are provided to the payer, who can then send funds using standard bank transfer methods.
### Account Management
Each customer can have multiple virtual accounts in different currencies. Accounts can be listed, queried, and managed through the API.
## Account Details
Each virtual account includes:
* Account number
* Account name
* Bank name and code
* Routing numbers (ACH, RTP, Wire for USD accounts)
* SWIFT code for international transfers
* Bank address
## Supported Currencies
Virtual accounts are available in multiple currencies. The specific currencies available depend on your account configuration and the providers available in your region.
## Getting Started
Ready to start creating virtual accounts? Check out our [API Reference](/api-reference/virtual-accounts/create) for detailed endpoint documentation.
# Receiving Payments
Source: https://docs.platnova.com/virtual-accounts/receiving-payments
Virtual accounts can receive payments from any source. This guide explains how payments work and how to track incoming payments.
## How Payments Work
When a payment is sent to a virtual account:
1. The payer uses the account details (account number, bank name, routing numbers)
2. The payment is processed through the banking network
3. Funds are automatically credited to your business wallet
4. You receive a notification of the payment
## Account Details for Payers
Share these account details with payers:
* **Account Number** - The bank account number
* **Account Name** - Name on the account
* **Bank Name** - Name of the bank
* **Routing Numbers** - For ACH, RTP, or Wire transfers (USD accounts)
* **SWIFT Code** - For international transfers
## Payment Methods
Payments can be sent using various methods:
### Domestic Transfers
* **Bank Transfer** - Standard bank-to-bank transfer
* **ACH Transfer** - Automated Clearing House (USD)
* **RTP Transfer** - Real-Time Payments (USD)
### International Transfers
* **Wire Transfer** - International wire transfer using SWIFT code
* **International ACH** - Cross-border ACH transfers
## Payment Processing
### Payment Flow
1. Payer initiates transfer using account details
2. Payment is processed by the banking network
3. Funds arrive in the virtual account
4. Funds are automatically credited to your business wallet
5. Transaction appears in your transaction history
### Processing Times
* **RTP** - Real-time (instant)
* **ACH** - 1-3 business days
* **Wire** - Same day or next business day
* **Bank Transfer** - Varies by country and method
## Tracking Payments
Monitor incoming payments through the Transactions API:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/transactions \
-H "X-API-KEY: YOUR_API_KEY" \
-G \
-d "type=deposit" \
-d "virtual_account_id=va_123"
```
## Payment Notifications
Set up webhooks to receive real-time notifications when payments are received:
```json theme={null}
{
"event": "account.funded",
"data": {
"transaction_id": "txn_123",
"virtual_account_id": "va_456",
"amount": "1000.00",
"currency": "USD",
"payer_name": "Jane Smith",
"reference": "PAY123456",
"timestamp": "2025-01-30T10:00:00Z"
}
}
```
## Payment Limits
Payment limits may apply depending on:
* Account type
* Currency
* Payer's bank
* Regulatory requirements
## Best Practices
* Share account details securely with payers
* Include payment references for tracking
* Monitor transactions regularly
* Set up webhooks for real-time notifications
* Keep account information up to date
## Next Steps
* Learn about [Creating Accounts](/virtual-accounts/creating-accounts) for account setup
* Explore the [Transactions API Reference](/api-reference/transactions/list) for transaction tracking
# Wallet Management
Source: https://docs.platnova.com/wallets/management
Manage your wallets effectively to support your financial operations. This guide covers wallet operations, balance tracking, and best practices.
## Viewing Wallets
List all wallets:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/wallets \
-H "X-API-KEY: YOUR_API_KEY"
```
## Wallet Information
Each wallet includes:
* **ID** - Unique wallet identifier
* **Currency** - Wallet currency
* **Balance** - Current balance
* **Status** - Wallet status (active, locked, etc.)
* **Created At** - Wallet creation timestamp
## Wallet Status
Wallets can have different statuses:
* **Active** - Wallet is active and can be used
* **Locked** - Wallet is locked and cannot be used
* **Restricted** - Wallet has restrictions
## Balance Management
### Checking Balances
Monitor wallet balances regularly:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/wallets \
-H "X-API-KEY: YOUR_API_KEY"
```
### Balance Updates
Balances update automatically when:
* Funds are received
* Payments are sent
* Cards are funded
* Withdrawals are made
* Transactions are processed
## Funding Wallets
Fund wallets through:
* Bank transfers
* Card deposits
* Payment receipts
* Virtual account deposits
* Other payment methods
## Using Wallets
Wallets are used as the source of funds for:
### Card Operations
* Creating cards
* Funding cards
* Card-related transactions
### Payments
* Sending payments
* Processing transfers
* Payment operations
### Other Operations
* Various financial operations
* Transaction processing
## Transaction History
View wallet transactions through the Transactions API:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/transactions \
-H "X-API-KEY: YOUR_API_KEY" \
-G \
-d "wallet_id=wallet_123"
```
## Best Practices
### Balance Management
* Keep sufficient balances for operations
* Monitor balances regularly
* Set up balance alerts
* Plan for expected transactions
### Security
* Protect wallet access
* Use secure API keys
* Monitor transactions
* Review wallet activity
### Operations
* Use appropriate wallets for operations
* Match wallet currency to operation currency
* Track wallet usage
* Optimize wallet utilization
## Next Steps
* Learn about [Multi-Currency Wallets](/wallets/multi-currency) for multi-currency operations
* Explore the [Wallets API Reference](/api-reference/wallets/list) for detailed documentation
# Multi-Currency Wallets
Source: https://docs.platnova.com/wallets/multi-currency
Manage wallets in multiple currencies to support global operations. This guide covers creating and managing wallets across different currencies.
## Multi-Currency Support
Platnova supports wallets in multiple currencies, allowing you to:
* Operate in different markets
* Hold funds in local currencies
* Avoid currency conversion fees
* Simplify multi-currency operations
## Supported Currencies
Wallets are available in various currencies including:
* **USD** - US Dollar
* **NGN** - Nigerian Naira
* And other supported currencies
Check available currencies for your account through the API.
## Listing Wallets
View all your wallets:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/wallets \
-H "X-API-KEY: YOUR_API_KEY"
```
## Wallet Response
```json theme={null}
{
"status": true,
"data": [
{
"id": "wallet_123",
"currency": "USD",
"balance": "10000.00",
"status": "active",
"created_at": "2025-01-01T00:00:00Z"
},
{
"id": "wallet_456",
"currency": "NGN",
"balance": "5000000.00",
"status": "active",
"created_at": "2025-01-01T00:00:00Z"
}
]
}
```
## Wallet Operations
### Funding Wallets
Fund wallets through various methods:
* Bank transfers
* Card deposits
* Payment receipts
* Other payment methods
### Using Wallets
Wallets serve as the source of funds for:
* Card creation and funding
* Payment sending
* Other financial operations
## Currency-Specific Operations
### USD Wallets
* Create USD cards
* Send USD payments
* Receive USD payments
* Process USD transactions
### NGN Wallets
* Create NGN cards
* Send NGN payments
* Receive NGN payments
* Process NGN transactions
## Wallet Balance Management
### Checking Balances
Monitor balances across all wallets:
```bash theme={null}
curl -X GET https://api.platnova.com/v1/wallets \
-H "X-API-KEY: YOUR_API_KEY"
```
### Balance Tracking
* View current balances
* Track balance changes
* Monitor transaction history
* Set up balance alerts
## Best Practices
* Create wallets in currencies you need
* Monitor balances regularly
* Keep sufficient balances for operations
* Track currency-specific transactions
* Plan for currency conversion when needed
## Next Steps
* Learn about [Wallet Management](/wallets/management) for wallet operations
* Explore the [Wallets API Reference](/api-reference/wallets/list) for detailed documentation
# Overview
Source: https://docs.platnova.com/wallets/overview
Wallets are digital accounts that hold funds in various currencies. Each wallet belongs to your business and can be used to fund cards, send payments, and manage balances across multiple currencies.
## What Are Wallets?
Wallets are digital accounts that store funds in specific currencies. Your business can have multiple wallets, one for each supported currency. Wallets are used as the source of funds for card creation, payments, and other operations.
## Key Features
### Multi-Currency Wallets
Create wallets in multiple currencies including USD, NGN, and other supported currencies. Each wallet operates independently in its own currency.
### Balance Management
Track balances across all your wallets. View current balances, transaction history, and balance changes over time.
### Funding Source
Wallets serve as the funding source for cards, payments, and other operations. Funds are deducted from wallets when you create cards or send payments.
### Currency Support
Wallets support a wide range of currencies. The specific currencies available depend on your account configuration and the regions you operate in.
## Wallet Lifecycle
### Wallet Creation
Wallets are typically created automatically when you set up your account. You can have multiple wallets, one for each currency you need to operate in.
### Funding Wallets
Fund wallets through various methods including bank transfers, card deposits, or other payment methods. Funds are credited to the appropriate wallet based on currency.
### Using Wallets
Wallets are used as the source of funds for:
* Card creation and funding
* Payment sending
* Other financial operations
## Wallet Information
Each wallet includes:
* Wallet ID
* Currency
* Current balance
* Transaction history
* Wallet status
## Supported Currencies
Wallets support multiple currencies including:
* USD (US Dollar)
* NGN (Nigerian Naira)
* And other supported currencies
## Getting Started
Ready to start managing wallets? Check out our [API Reference](/api-reference/wallets/list) for detailed endpoint documentation.
# Overview
Source: https://docs.platnova.com/webhooks/overview
Receive real-time notifications for card activity, virtual account funding, and payment transfers by configuring webhooks in your [dashboard](https://business.platnova.com). Events are sent as **POST** requests to the URL you configure.
## How Webhooks Work
1. **Configure your endpoint** – In the dashboard, set the URL that will receive webhook events.
2. **Set your secret** – Provide a secret value used to sign each request. Use it to verify that events come from Platnova.
3. **Receive events** – We send a POST request to your URL for each subscribed event. Your endpoint must respond with **HTTP 200** to acknowledge receipt.
4. **Retries** – If your endpoint does not return 200, we retry the delivery up to **5 times** at intermittent intervals until successful.
Your endpoint must return HTTP 200 for the request to be considered delivered. Non-2xx responses (including 4xx and 5xx) trigger retries.
## Request Details
| Property | Description |
| - | - |
| **Method** | `POST` |
| **URL** | The endpoint URL you configure in the dashboard |
| **Headers** | `X-WEBHOOK-SECRET`: the secret value you provided when configuring the webhook |
| **Body** | JSON payload (see event payloads below) |
Always validate the `X-WEBHOOK-SECRET` header in your handler to ensure the request is from Platnova and has not been tampered with.
## Supported Events
You can subscribe to specific events or patterns when configuring your webhook:
| Event ID | Label |
| - | - |
| `*` | All |
| `card.*` | All Card Events |
| `card.created` | Card Created |
| `card.terminated` | Card Terminated |
| `card.withdrawal` | Card Withdrawal |
| `card.charged` | Card Charged |
| `card.refund` | Card Refund |
| `card.funded` | Card Funded |
| `card.declined` | Card Declined |
| `account.issued` | Virtual Account Issued |
| `account.funded` | Account Funded |
| `customer.approved` | Customer Approved |
| `customer.rejected` | Customer Rejected |
| `transfer.success` | Transfer Success |
| `transfer.failed` | Transfer Failed |
## Event Payloads
Every webhook payload includes top-level fields:
* **event** – Event type (e.g. `card.created`, `transfer.success`).
* **timestamp** – ISO 8601 timestamp when the event occurred.
* **customer\_id** – Customer ID associated with the event (may be empty for entity-level events).
* **data** – Event-specific payload (see below).
### card.created
Sent when a new card is created.
```json theme={null}
{
"event": "card.created",
"timestamp": "2024-01-01T12:00:00Z",
"customer_id": "user_id",
"data": {
"card_id": "card_uid",
"card_holder_name": "John Doe",
"card_status": "active",
"currency": "USD",
"amount": 0.00,
"card_info": {
"masked_pan": "**** **** **** 1234",
"last4": "1234",
"expiry_month": "12",
"expiry_year": "2025",
"type": "virtual",
"brand": "visa",
"name_on_card": "John Doe",
"address": "123 Main St",
"city": "New York",
"state": "NY",
"zip_code": "10001"
},
"transaction_ref": "TXN123456",
"metadata": {
"merchant": {
"name": "Merchant Name",
"category": "retail"
},
"terminal": {
"id": "terminal_id",
"location": "Location"
},
"channel": "online",
"narration": "Card creation",
"charge_amount": "0.00"
}
}
}
```
### card.terminated
Sent when a card is terminated.
```json theme={null}
{
"event": "card.terminated",
"timestamp": "2024-01-01T12:00:00Z",
"customer_id": "user_id",
"data": {
"card_id": "card_uid",
"card_holder_name": "John Doe",
"card_status": "terminated",
"currency": "USD",
"amount": 0.00,
"card_info": {
"masked_pan": "**** **** **** 1234",
"last4": "1234",
"expiry_month": "12",
"expiry_year": "2025",
"type": "virtual",
"brand": "visa",
"name_on_card": "John Doe",
"address": "123 Main St",
"city": "New York",
"state": "NY",
"zip_code": "10001"
},
"transaction_ref": "TXN123456",
"metadata": {
"merchant": null,
"terminal": null,
"channel": "online",
"narration": "Card termination",
"charge_amount": "0.00"
}
}
}
```
### card.withdrawal
Sent when funds are withdrawn from a card.
```json theme={null}
{
"event": "card.withdrawal",
"timestamp": "2024-01-01T12:00:00Z",
"customer_id": "user_id",
"data": {
"card_id": "card_uid",
"card_holder_name": "John Doe",
"card_status": "active",
"currency": "USD",
"amount": 100.00,
"fee": 2.50,
"transaction_ref": "TXN123456",
"metadata": {
"merchant": {
"name": "ATM",
"category": "atm"
},
"terminal": {
"id": "terminal_id",
"location": "ATM Location"
},
"channel": "atm",
"narration": "ATM withdrawal",
"charge_amount": "100.00"
}
}
}
```
### card.charged
Sent when a card is charged (purchase).
```json theme={null}
{
"event": "card.charged",
"timestamp": "2024-01-01T12:00:00Z",
"customer_id": "user_id",
"data": {
"card_id": "card_uid",
"card_holder_name": "John Doe",
"card_status": "active",
"currency": "USD",
"amount": 50.00,
"fee": 1.50,
"transaction_ref": "TXN123456",
"description": "Purchase at Store",
"metadata": {
"merchant": {
"name": "Store Name",
"category": "retail"
},
"terminal": {
"id": "terminal_id",
"location": "Store Location"
},
"channel": "pos",
"narration": "Purchase",
"charge_amount": "50.00"
}
}
}
```
### card.refund
Sent when a card charge is refunded.
```json theme={null}
{
"event": "card.refund",
"timestamp": "2024-01-01T12:00:00Z",
"customer_id": "user_id",
"data": {
"card_id": "card_uid",
"card_holder_name": "John Doe",
"card_status": "active",
"currency": "USD",
"amount": 50.00,
"fee": 0.00,
"original_transaction_ref": "TXN123456",
"refund_transaction_ref": "TXN789012",
"metadata": {
"merchant": {
"name": "Store Name",
"category": "retail"
},
"terminal": {
"id": "terminal_id",
"location": "Store Location"
},
"channel": "pos",
"narration": "Refund",
"charge_amount": "50.00"
}
}
}
```
### card.funded
Sent when a card is funded (deposit).
```json theme={null}
{
"event": "card.funded",
"timestamp": "2024-01-01T12:00:00Z",
"customer_id": "user_id",
"data": {
"card_id": "card_uid",
"card_holder_name": "John Doe",
"card_status": "active",
"currency": "USD",
"amount": 200.00,
"fee": 0.00,
"transaction_ref": "TR_N123456"
}
}
```
### card.declined
Sent when a card transaction is declined.
```json theme={null}
{
"event": "card.declined",
"timestamp": "2024-01-01T12:00:00Z",
"customer_id": "user_id",
"data": {
"card_id": "card_uid",
"card_holder_name": "John Doe",
"card_status": "active",
"currency": "USD",
"amount": 50.00,
"fee": 0.00,
"transaction_ref": "TXN123456",
"description": "Insufficient funds",
"metadata": {
"merchant": {
"name": "Store Name",
"category": "retail"
},
"terminal": {
"id": "terminal_id",
"location": "Store Location"
},
"channel": "pos",
"narration": "Declined transaction",
"charge_amount": "50.00"
}
}
}
```
### account.funded
Sent when a virtual account receives funds.
```json theme={null}
{
"event": "account.funded",
"timestamp": "2024-01-01T12:00:00Z",
"customer_id": "user_id",
"data": {
"virtual_account_id": "va_uid",
"amount": 495.00,
"paid_amount": 500.00,
"fee": 5.00,
"currency": "USD",
"transaction_ref": "TXN123456",
"description": "Deposit to virtual account"
}
}
```
### account.issued
Sent when a virtual account is issued.
```json theme={null}
{
"event": "account.issued",
"timestamp": "2024-01-01T12:00:00Z",
"customer_id": "user_id",
"data": {
"virtual_account_id": "va_uid",
"currency": "USD",
"account_number": "1234567890",
"account_name": "John Doe",
"bank_name": "Bank Name",
"bank_code": "001",
"ach_routing_number": "123456789",
"rtp_routing_number": "123456789",
"wire_routing_number": "123456789",
"swift_code": "SWIFT123",
"bank_address": "123 Bank St, New York, NY 10001"
}
}
```
### customer.approved
Sent when a customer's documents are approved for virtual account creation.
```json theme={null}
{
"event": "customer.approved",
"timestamp": "2024-01-01T12:00:00Z",
"customer_id": "cus_123",
"data": {
"id": "cus_123",
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"phone": "+1234567890"
}
}
```
### customer.rejected
Sent when a customer's documents are rejected for virtual account creation.
```json theme={null}
{
"event": "customer.rejected",
"timestamp": "2024-01-01T12:00:00Z",
"customer_id": "cus_123",
"data": {
"id": "cus_123",
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"phone": "+1234567890",
"reason": "Document is blurry"
}
}
```
### transfer.success
Sent when a transfer completes successfully.
```json theme={null}
{
"event": "transfer.success",
"timestamp": "2024-01-01T12:00:00Z",
"customer_id": "",
"data": {
"reference": "TXN123456",
"amount": 1000.00,
"currency": "USD",
"fee": 5.00,
"status": "success",
"metadata": {
"account_number": "1234567890",
"phone_number": "+1234567890",
"bank_code": "001",
"bank_name": "Bank Name",
"account_name": "John Doe",
"beneficiary_name": "Jane Doe",
"beneficiary_country": "US",
"routing_number": "123456789",
"swift_code": "SWIFT123",
"branch_code": "001",
"country_code": "US",
"street": "123 Main St",
"city": "New York",
"state": "NY",
"postal_code": "10001",
"receiver": "receiver_id",
"sender_username": "sender_username",
"iban": "GB82WEST12345698765432",
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"recipient_address": "123 Main St, New York, NY 10001",
"mobile_number": "+1234567890",
"address": "123 Main St",
"asset": "BTC",
"network": "bitcoin",
"transit_number": "12345",
"institution_number": "001",
"bsb_code": "123456",
"revtag": "@username",
"zelle_id": "zelle@example.com",
"cashapp_id": "$cashapp",
"paypal_id": "paypal@example.com",
"note": "Payment for services"
}
}
}
```
### transfer.failed
Sent when a transfer fails.
```json theme={null}
{
"event": "transfer.failed",
"timestamp": "2024-01-01T12:00:00Z",
"customer_id": "",
"data": {
"reference": "TXN123456",
"amount": 1000.00,
"currency": "USD",
"fee": 5.00,
"status": "failed",
"reason": "Insufficient funds",
"metadata": {
"account_number": "1234567890",
"phone_number": "+1234567890",
"bank_code": "001",
"bank_name": "Bank Name",
"account_name": "John Doe",
"beneficiary_name": "Jane Doe",
"beneficiary_country": "US",
"routing_number": "123456789",
"swift_code": "SWIFT123",
"branch_code": "001",
"country_code": "US",
"street": "123 Main St",
"city": "New York",
"state": "NY",
"postal_code": "10001",
"receiver": "receiver_id",
"sender_username": "sender_username",
"iban": "GB82WEST12345698765432",
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"recipient_address": "123 Main St, New York, NY 10001",
"mobile_number": "+1234567890",
"address": "123 Main St",
"asset": "BTC",
"network": "bitcoin",
"transit_number": "12345",
"institution_number": "001",
"bsb_code": "123456",
"revtag": "@username",
"zelle_id": "zelle@example.com",
"cashapp_id": "$cashapp",
"paypal_id": "paypal@example.com",
"note": "Payment for services"
}
}
}
```
## Best Practices
* **Verify the secret** – Always check `X-WEBHOOK-SECRET` against your configured value before processing.
* **Respond quickly** – Return 200 as soon as you have received and validated the payload; process asynchronously if needed.
* **Handle duplicates** – Use `transaction_ref` or event idempotency keys to avoid processing the same event more than once.
* **Log for debugging** – Log incoming webhook requests and responses to troubleshoot delivery or retry issues.
For API endpoints to create or manage webhook configurations programmatically, see the [Webhooks API reference](/api-reference/endpoint/webhook).