spout

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).

Checkout after initializeScreenshot
Customer checkout page with spout transaction reference

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

MethodPathUse
POST/api/v1/transactions/initializeLocal / NGN (default currency NGN)
POST/api/v1/transactions/initialize-intlInternational (default currency USD)
GET/api/v1/transactions/initialize/:ref/:typeFetch 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).

HeaderRequired?Description
AuthorizationYeslive_secret_key or test_secret_key from POST /api/v1/settings/apikey
Content-TypeYesapplication/json
Idempotency-KeyRecommendedStable UUID per logical charge. If omitted, merchant_tx_ref is used. Retries return the same response; concurrent duplicates may return 409.
X-Request-IdOptionalClient 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.

ParamRequired?Description
customer_nameYesCustomer full name
email_addressYesCustomer email
phone_numberYesCustomer phone
currencyYesCharge currency (e.g. NGN, USD)
amountYesAmount in major units for the currency (e.g. 1000 = ₦1,000)
merchant_tx_refYesYour unique order/reference. Duplicate refs for the same merchant return 409.
redirect_urlYesWhere checkout should return the customer after payment
request_typeYesPayment channel, e.g. CARD, PAYATTITUDE
descriptionYesShort payment description
user_bear_chargeNoWhether the customer bears gateway charges (defaults true on local initialize)
organization_keyNoOptional 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

Dashboard transaction trackingScreenshot
Transaction list with merchant and spout references

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.

  1. Store your merchant_tx_ref and the response data.transactionRef (SP-…) plus requestId.
  2. Redirect to data.redirectUrl — checkout uses txn_ref.
  3. Prefer webhooks (charge.processing / charge.completed / charge.failed keyed by spout_tx_ref / merchant_tx_ref).
  4. Optionally poll GET /api/v1/transactions/initialize/:ref/:type where :ref is SP-….
  5. For support, look up requestId in observability request / error logs.

Related

  • Webhooks — final status without polling
  • Refunds — refund a paid transaction_id
  • Payouts — withdraw wallet balance