Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dubupay.com/llms.txt

Use this file to discover all available pages before exploring further.

Every request to a protected Dubu Pay endpoint must carry valid credentials. Dubu Pay offers two authentication methods: a short-lived JWT bearer token issued on login, and a long-lived API key you create and manage from your account. Understanding when to use each method will help you build a secure integration.

​
Authentication methods

​
JWT bearer token

When you call POST /auth/login, the API returns an access_token and a refresh_token. Include the access token in the Authorization header for subsequent requests: 
Authorization: Bearer <access_token>
PropertyValue
Access token lifetime15 minutes
Refresh token lifetime7 days
Header nameAuthorization
Header value formatBearer <token>
When to use JWT tokens: Use bearer tokens for dashboard-style applications where a user actively signs in, or for any short-lived session where you want automatic expiry. Because access tokens expire in 15 minutes, they limit the blast radius if a token is intercepted. 
curl --request GET \
  --url https://api.dubupay.com/api/v1/auth/me \
  --header 'Authorization: Bearer eyJhbGci...'

​
API key

API keys are long-lived credentials tied to your merchant account. Pass one in the X-Api-Key header: 
X-Api-Key: dubu_sk_live_<32chars>
PropertyValue
Key formatsdubu_sk_live_<32chars> or dubu_sk_test_<32chars>
Header nameX-Api-Key
ExpiryNone (until revoked)
When to use API keys: Use API keys for server-side integrations — background jobs, webhooks, backend services — where there is no interactive login flow. The key must never be exposed in client-side JavaScript or mobile app bundles. 
curl --request GET \
  --url https://api.dubupay.com/api/v1/payments/customers \
  --header 'X-Api-Key: dubu_sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345'

​
Refreshing an access token

When your access token expires, use the refresh token to obtain a new pair without requiring the user to log in again. Each refresh call issues a new access token and rotates the refresh token. Request body
​
refresh_token
string
required
The refresh token returned by /auth/login or a previous /auth/refresh call.
curl --request POST \
  --url https://api.dubupay.com/api/v1/auth/refresh \
  --header 'Content-Type: application/json' \
  --data '{
    "refresh_token": "eyJhbGci..."
  }'
Example response 
{
  "success": true,
  "data": {
    "access_token": "eyJhbGci...",
    "refresh_token": "eyJhbGci..."
  }
}
Refresh tokens rotate on every use. Store the new refresh_token returned from each /auth/refresh call and discard the previous one. Using an old refresh token will result in a 401 error.

​
Authentication priority

When a request includes both an X-Api-Key header and an Authorization: Bearer header, Dubu Pay evaluates the API key first. If the API key is valid and active, the bearer token is ignored.

​
Error responses

HTTP statusError codeCause
401UNAUTHORIZEDNo credentials provided, token has expired, or token signature is invalid.
403IP_WHITELIST_REQUIREDYour account has no whitelisted IPs configured and IP enforcement is enabled.
403IP_NOT_WHITELISTEDThe request originated from an IP address not on your whitelist.
Example 401 response 
{
  "success": false,
  "error": {
    "message": "Authentication required",
    "code": "UNAUTHORIZED"
  }
}
If you receive a 403 IP_NOT_WHITELISTED error, add your server’s outbound IP address to the IP whitelist in your account settings.

​
Logging out

To invalidate a session and revoke the active refresh token, call POST /auth/logout with a valid bearer token. 
curl --request POST \
  --url https://api.dubupay.com/api/v1/auth/logout \
  --header 'Authorization: Bearer eyJhbGci...'
Example response 
{
  "success": true,
  "message": "Logged out successfully"
}

​
Next steps

API keys

Create and manage long-lived API keys for server-side integrations.

Quickstart

Follow the end-to-end guide to issue your first virtual bank account.