Overview
Every MigraPay API endpoint, parameter, response field, error and event.
This is the complete reference. For step-by-step integration, start with the Guides.
Base URL
https://business-api.migrapay.com/v1/apiEvery path in this reference is relative to it, except the two public-key calls under /v1/checkout. Sandbox and Live share the base URL: the key you send decides the environment.
Authentication
| Key | Prefix | Where | Sent as |
|---|---|---|---|
| Secret API key | mpb_live_ / mpb_test_ | Your server only | Authorization: Bearer <key> or X-API-Key: <key> |
| Public key | pk_live_ / pk_test_ | Websites and apps | X-MigraPay-Key: <key>, only for the public checkout calls and checkout.js |
| Status | message | Cause |
|---|---|---|
| 401 | missing_api_key | No key in Authorization or X-API-Key. |
| 401 | invalid_api_key | The key is unknown, revoked or malformed. |
| 403 | insufficient_scope | The key lacks the scope the endpoint requires. |
| 403 | IP_NOT_ALLOWED | A Live key was used from an IP address outside your API IP allowlist (Settings → API & integrations). Sandbox keys are never IP-restricted. |
Scopes
Each secret key carries the scopes chosen when it was created.
| Scope | Endpoints |
|---|---|
wallet.view | GET /wallets |
payment.view | GET /transactions, GET /transactions/{id}, GET /payouts, GET /payouts/{id}, GET /payouts/banks, GET /payouts/requirements, POST /payouts/validate-account, GET /payouts/estimate, GET /rates |
payment.create | POST /payouts |
recipient.view | GET /recipients |
recipient.create | POST /recipients |
collection.view | GET /collections, GET /collections/{id}, GET /collections/requirements, GET /checkout/{id} |
collection.create | POST /collections, POST /collections/{id}/mock-settle, POST /checkout |
Requests and responses
- Send JSON with
Content-Type: application/json. Field names are camelCase. - Amounts are decimal numbers in major units:
250.75is 250 dollars and 75 cents. - Currencies are ISO 4217 codes (
CAD,USD,NGN). Timestamps are ISO 8601 in UTC. - Every response uses the same envelope:
{
"status": "success",
"message": "Wallets retrieved successfully.",
"data": {}
}| Field | Type | Description |
|---|---|---|
status | "success" | "error" | success for 2xx and 3xx, error otherwise. |
message | string | A readable summary on success; the machine-readable error code on errors. |
data | object | The resource or list, or error details. |
Endpoints
| Method | Path | |
|---|---|---|
GET | /wallets | List wallets |
GET | /rates | Mid-market rates |
GET | /payouts/estimate | Estimate a payout |
GET | /transactions | List transactions |
GET | /transactions/{id} | Retrieve a transaction |
GET | /payouts/requirements | Payout methods and fields |
GET | /payouts/banks | Banks and networks |
POST | /payouts/validate-account | Validate an account |
POST | /recipients | Create a recipient |
GET | /recipients | List recipients |
POST | /payouts | Create a payout |
GET | /payouts/{id} | Retrieve a payout |
GET | /payouts | List payouts |
POST | /checkout | Create a checkout |
GET | /checkout/{id} | Retrieve a checkout |
POST | /v1/checkout/sessions | Start a checkout with a public key |
GET | /v1/checkout/config | Read checkout options |
POST | /collections | Create a collection |
GET | /collections/{id} | Retrieve a collection |
GET | /collections | List collections |
GET | /collections/requirements | Collection methods and fields |
POST | /collections/{id}/mock-settle | Settle in Sandbox |
Events are listed under Webhook events. For AI tools, the whole documentation is available as plain text at /llms.txt and /llms-full.txt.