Authentication
Authenticate every request with your secret key.
Send your secret key as a bearer token on every request:
Authorization: Bearer sk_test_your_secret_keyThe Business API accepts secret keys only. Public keys (pk_) return 401 Invalid API Key.
What Payinto checks
Each request passes these checks in order. The first failure is the error you receive.
| Check | Status | Message |
|---|---|---|
| A bearer token is present | 401 | Authorization token is required |
| The key exists | 401 | Invalid API Key |
| Your IP is allowed | 403 | IP address not allowed |
| The business is active and verified | 403 | Integration is not live. |
| API access is enabled for the business | 403 | API access is not enabled for this business. |
| The key's environment is enabled | 403 | LIVE environment access is not enabled for this business API integration. |
| The key has not expired | 401 | API Key has expired |
| The endpoint's module is enabled | 403 | Transfer API access is not enabled for this business API integration. |
IP allowlist
Each key has an IP allowlist.
- Live keys need an allowlist. A live key with an empty allowlist rejects every request.
- Test keys work from any IP until you add an address to their allowlist. After that, only listed addresses work.
Call GET / with your key to see the IP address Payinto sees, returned as your-ip. A successful response needs an allowed IP, so use a test key without an allowlist if you are checking a new server.
Modules
Payinto enables API modules per business. A request to a disabled module returns 403, even with a valid key.
| Module | Endpoints |
|---|---|
accounts | /accounts |
customers | /customers |
verification | /customers/{id}/identity/*, /addons/bvn-verification |
static_virtual_accounts | /virtual-accounts/static, and all virtual account reads |
dynamic_virtual_accounts | /virtual-accounts/dynamic, and all virtual account reads |
transfers | /transfers |
bulk_transfers | /bulk-transfers, /scheduled-bulk-transfers |
vas | /vas |
otp | /addons/otps |
credit_check | /addons/credit-check |
GET /, GET /whoami, and GET /transactions/tsq/{reference} need no module.
Keep your key secret
Secret keys can move money. Never put one in a browser, a mobile app, or source control.
Call the API from your server only, and load the key from a secret manager or an environment variable.