Accept Payments
Create a transaction with the SpoutPay API, then send the customer to the returned checkout redirectUrl to complete payment. Auth uses your merchant live_secret_key / test_secret_key (not a dashboard JWT — that is for refunds and payouts).
Customer is sent to data.redirectUrl (?txn_ref=SP-…).
Why a screenshot helps: Helps merchants map the API redirectUrl to what the payer sees before card entry.
Endpoints
| Method | Path | Use |
|---|---|---|
POST | /api/v1/transactions/initialize | Local / NGN (default currency NGN) |
POST | /api/v1/transactions/initialize-intl | International (default currency USD) |
GET | /api/v1/transactions/initialize/:ref/:type | Fetch a transaction by Spout reference (type selects local vs intl store) |
Successful initialize emits charge.initialize. Final status arrives via webhooks.
Authentication & headers
Do not put your secret key in the JSON body. Send it as the Authorization header value (no Bearer prefix for merchant secret keys).
| Header | Required? | Description |
|---|---|---|
Authorization | Yes | live_secret_key or test_secret_key from POST /api/v1/settings/apikey |
Content-Type | Yes | application/json |
Idempotency-Key | Recommended | Stable UUID per logical charge. If omitted, merchant_tx_ref is used. Retries return the same response; concurrent duplicates may return 409. |
X-Request-Id | Optional | Client correlation UUID. Echoed in the response as requestId. |
Use test_secret_key for sandbox — charges are simulated and live processors are not called. See test mode.
Request body
All fields below are required by validation for initialize.
| Param | Required? | Description |
|---|---|---|
customer_name | Yes | Customer full name |
email_address | Yes | Customer email |
phone_number | Yes | Customer phone |
currency | Yes | Charge currency (e.g. NGN, USD) |
amount | Yes | Amount in major units for the currency (e.g. 1000 = ₦1,000) |
merchant_tx_ref | Yes | Your unique order/reference. Duplicate refs for the same merchant return 409. |
redirect_url | Yes | Where checkout should return the customer after payment |
request_type | Yes | Payment channel, e.g. CARD, PAYATTITUDE |
description | Yes | Short payment description |
user_bear_charge | No | Whether the customer bears gateway charges (defaults true on local initialize) |
organization_key | No | Optional org key (local initialize) |
Sample request
JSON body (initialize)
1{
2 "customer_name": "Jane Doe",
3 "email_address": "jane@example.com",
4 "phone_number": "08012345678",
5 "currency": "NGN",
6 "amount": 1000,
7 "merchant_tx_ref": "order_1001",
8 "redirect_url": "https://merchant.example.com/payment/return",
9 "request_type": "CARD",
10 "description": "Order 1001"
11}Local / NGN — POST /transactions/initialize
1curl -X POST https://api.spoutpay.com/api/v1/transactions/initialize \
2 -H "Content-Type: application/json" \
3 -H "Authorization: SPT_LIVE_SK..." \
4 -H "Idempotency-Key: 9f3c2a1b-...." \
5 -H "X-Request-Id: 7e1d...." \
6 -d '{
7 "customer_name": "Jane Doe",
8 "email_address": "jane@example.com",
9 "phone_number": "08012345678",
10 "currency": "NGN",
11 "amount": 1000,
12 "merchant_tx_ref": "order_1001",
13 "redirect_url": "https://merchant.example.com/payment/return",
14 "request_type": "CARD",
15 "description": "Order 1001"
16 }'International — POST /transactions/initialize-intl
Same auth and fields; default currency USD.
1curl -X POST https://api.spoutpay.com/api/v1/transactions/initialize-intl \
2 -H "Content-Type: application/json" \
3 -H "Authorization: SPT_LIVE_SK..." \
4 -H "Idempotency-Key: 9f3c2a1b-...." \
5 -H "X-Request-Id: 7e1d...." \
6 -d '{
7 "customer_name": "Jane Doe",
8 "email_address": "jane@example.com",
9 "phone_number": "+14155552671",
10 "currency": "USD",
11 "amount": 25.5,
12 "merchant_tx_ref": "order_1001_intl",
13 "redirect_url": "https://merchant.example.com/payment/return",
14 "request_type": "CARD",
15 "description": "Order 1001"
16 }'Sample responses
Spout generates transactionRef as SP-********. Redirect the customer to redirectUrl. Persist merchant_tx_ref, transactionRef, and requestId for tracking.
Success (200) — live
1{
2 "status": 200,
3 "data": {
4 "status": "success",
5 "transactionRef": "SP-a1b2c3d4",
6 "redirectUrl": "https://checkout.spoutpay.com/checkout?txn_ref=SP-a1b2c3d4",
7 "mode": "live"
8 },
9 "requestId": "...",
10 "responseId": "..."
11}Success (200) — test secret key
1{
2 "status": 200,
3 "data": {
4 "status": "success",
5 "transactionRef": "SP-a1b2c3d4",
6 "redirectUrl": "https://checkout.spoutpay.com/checkout?txn_ref=SP-a1b2c3d4",
7 "mode": "test",
8 "message": "Test mode: charge will be simulated; live processors will not be called."
9 },
10 "requestId": "..."
11}Failure (422)
Failures use a non-2xx status with a client-safe error / message, stable code, and requestId. Internal details are only in server error logs / Errors tab.
1{
2 "status": 422,
3 "error": "Unable to initialize payment. Please try again.",
4 "code": "PAYMENT_INIT_FAILED",
5 "data": {
6 "status": "failed",
7 "transactionRef": "SP-a1b2c3d4",
8 "redirectUrl": null,
9 "message": "Unable to initialize payment. Please try again."
10 },
11 "requestId": "...",
12 "responseId": "..."
13}Duplicate merchant_tx_ref (409)
Reusing the same merchant_tx_ref for a merchant returns an explicit conflict — not a generic "try again" message. Code: DUPLICATE_MERCHANT_TX_REF.
1{
2 "status": 409,
3 "error": "Duplicate merchant_tx_ref \"order_1001\". This reference was already used for another transaction. Please use a unique merchant_tx_ref.",
4 "code": "DUPLICATE_MERCHANT_TX_REF",
5 "data": {
6 "status": "failed",
7 "merchant_tx_ref": "order_1001",
8 "existingTransactionRef": "SP-a1b2c3d4",
9 "redirectUrl": null,
10 "message": "Duplicate merchant_tx_ref \"order_1001\". This reference was already used for another transaction. Please use a unique merchant_tx_ref."
11 },
12 "requestId": "..."
13}Other common statuses: 403 invalid/missing secret key, 409 concurrent idempotency conflict (in-progress key).
How to track a payment
Match merchant_tx_ref ↔ spout_tx_ref ↔ requestId across API, dashboard, and webhooks.
Why a screenshot helps: Gives support and merchants a visual of which IDs to search when a customer asks about an order.
- Store your
merchant_tx_refand the responsedata.transactionRef(SP-…) plusrequestId. - Redirect to
data.redirectUrl— checkout usestxn_ref. - Prefer webhooks (
charge.processing/charge.completed/charge.failedkeyed byspout_tx_ref/merchant_tx_ref). - Optionally poll
GET /api/v1/transactions/initialize/:ref/:typewhere:refisSP-…. - For support, look up
requestIdin observability request / error logs.