Skip to main content

4pay API Documentation

4pay is a B2B platform for issuing and managing virtual and physical payment cards. The REST API is scoped to your merchant: each request is authenticated and only returns data for accounts and cards that belong to you.

You can:

  • Authenticate with an API token or JWT (merchant portal login)
  • List accounts (balance containers) and move funds between them
  • Create cardholders and issue cards with optional BIN and spending limits
  • Top up or withdraw card balance from the parent account
  • List card and account transactions with filters
  • Configure webhooks to receive forwarded provider events

Base URL​

Use the base URL you were given for your environment (production or sandbox), for example:

https://api.4pay.cc

Interactive OpenAPI (Swagger UI) is usually available at {baseUrl}/api/docs when enabled. The machine-readable schema is at {baseUrl}/api/openapi.json.

API version​

Current version: v2. All endpoints are under /api/v2/.

Quick overview​

AreaDescription
AuthenticationAPI token (X-API-Token) or Bearer JWT
AccountsBalances, BINs, fees, transfers between your accounts
CardholdersPeople linked to cards
CardsIssue, list, PAN/CVV, freeze, close, top-up
TransactionsCard and account transaction history
WebhooksReceive provider events on your HTTPS endpoint

Typical integration flow​

1. Obtain API token          →  issued when your merchant is created (store securely)
2. List accounts             →  GET /api/v2/accounts
3. Create cardholder         →  POST /api/v2/accounts/{account_uuid}/cardholders
4. Issue card                →  POST /api/v2/accounts/{account_uuid}/cards
5. Poll card until active    →  GET /api/v2/accounts/{account_uuid}/cards/{card_uuid}
6. Top up card               →  POST .../cards/{card_uuid}/topup
7. Get PAN / CVV             →  GET .../cards/{card_uuid}/sensitive
8. (Optional) Webhooks       →  PUT /api/v2/webhooks/config

Choose cardProviderBinId or binCategoryId from the binList on the account details response when issuing a card.

Pagination and list responses​

Most list endpoints return:

{
  "items": [ ... ]
}

Use query parameters limit (default often 100, max 1000) and offset for pagination. Some legacy-style responses may differ; always refer to the OpenAPI schema for your deployment.

Async behaviour​

Card issuance and some money movements can be asynchronous. After a successful response, poll GET card until status is active or creating_failed, or rely on webhooks (card_state, card_transaction) when configured.

Support​