Collect a payment

A collection is the money-in entry point: what your app calls when a user taps “Pay”. You hand over an amount, a country, a method and the payer’s identifier, and the gateway asks the routed provider to debit them. Typical uses are a checkout, a wallet top-up or an entry fee. The customer-facing prompt — the mobile money PIN, the redirect page, the SMS code — belongs to the provider. You get back a canonical status to branch on instead of a provider-shaped payload.

A charge does not settle synchronously. POST /v1/collections returns 201 with status: "pending", which means the request reached the provider, not that the customer has paid. Treat the webhook, or a poll of GET /v1/collections/{reference}, as the real answer. Never treat the 201 as settlement.

Before you start

Amounts are integer minor units. Every amount field ends in _minor. UGX, RWF, XAF and XOF are zero-decimal, so 2,000 UGX is 2000, not 200000. Getting this wrong is a 100x error. See Money and minor units.
Check the corridor. Capability is per (country, currency, direction, method). Call GET /v1/reference/corridors and render your UI against it.
Idempotency-Key is required. This call moves money. See Idempotency.

The flow

Quote the charge (optional)

POST /v1/collections/quote returns the fee and the total the customer must pay, so a confirm screen can show real numbers before anyone commits.This is a standalone call that holds no state. It moves no money, needs no Idempotency-Key, and returns no token to redeem — quote as often as you like, or skip it entirely. A quote is never “used up” and can never expire out from under a customer.Show total_to_pay_minor rather than adding amount_minor and fee_minor yourself. That figure comes from the provider and is what the customer is actually billed.

Quote a collection

curl -sS https://api.pay.aptahq.com/v1/collections/quote \
  -H "X-AptaPay-Key: $APP_ID.$KEY_ID.$API_KEY" \
  -H "X-AptaPay-Timestamp: $TS" \
  -H "X-AptaPay-Nonce: $NONCE" \
  -H "X-AptaPay-Signature: v1=$SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": 2000,
    "currency": "UGX",
    "country": "UG",
    "method": "momo"
  }'

momo and bank can be quoted. card cannot, and answers 501.

Charge the customer

One call. Send the amount, the corridor and the payer’s number.

Charge a Uganda mobile money wallet

curl -sS https://api.pay.aptahq.com/v1/collections \
  -H "X-AptaPay-Key: $APP_ID.$KEY_ID.$API_KEY" \
  -H "X-AptaPay-Timestamp: $TS" \
  -H "X-AptaPay-Nonce: $NONCE" \
  -H "X-AptaPay-Signature: v1=$SIG" \
  -H "Idempotency-Key: 6b1f2c34-8a0e-4d1b-9f77-2c5a8e0b4d31" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": 2000,
    "currency": "UGX",
    "country": "UG",
    "method": "momo",
    "source": {
      "type": "momo",
      "msisdn": "0781234567",
      "network": "MTN",
      "country": "UG"
    },
    "narration": "Race entry",
    "metadata": { "order_id": "ord_8813" }
  }'

The response carries a gateway reference. Persist it: it is your handle for polling, for the webhook you will receive, and for a later refund.

Response

{
  "code": 201,
  "message": "OK",
  "data": {
    "reference": "APT-LCS-oRUZWq8fyn9DttNb3SN3B",
    "provider": "eversend",
    "status": "pending",
    "observed_amount_minor": 2000,
    "observed_currency": "UGX"
  }
}

The customer now sees a prompt on their handset and approves it there.

Branch on next_action

Most charges go straight to the provider and come back pending. Some corridors need a second step from the customer first, and those come back status: "requires_action" with a next_action object.Always branch on the presence of next_action rather than assuming it is absent. That way your integration keeps working if a corridor changes, or if you deploy against a provider that does require a step.

`next_action.type`	What to do
absent	Nothing. Wait for the webhook.
`redirect`	Send the customer to `next_action.redirect_url`.
`otp`	Collect the code and post it to the authorize endpoint.

Ghana (GHS) requires redirect_url on the request and answers requires_action with a next_action.redirect_url. Send the user there to finish.

Wait for the real answer

Your webhook handler is the primary signal and the source of truth for settlement. See Webhooks.As a fallback, poll GET /v1/collections/{reference}. By default that reads the gateway’s own ledger — a database read, not a provider call — so polling is cheap and safe.Pass live=true when a customer is watching a payment screen. The gateway then asks the provider what it currently holds and applies the answer before responding, so a charge the customer just approved is reported as successful on that very poll rather than a minute later. Upstream calls are collapsed to at most one per reference every few seconds however many callers ask, so polling on a timer and from several tabs at once is safe.

Poll with a live upstream check

curl -sS "https://api.pay.aptahq.com/v1/collections/APT-LCS-oRUZWq8fyn9DttNb3SN3B?live=true" \
  -H "X-AptaPay-Key: $APP_ID.$KEY_ID.$API_KEY" \
  -H "X-AptaPay-Timestamp: $TS" \
  -H "X-AptaPay-Nonce: $NONCE" \
  -H "X-AptaPay-Signature: v1=$SIG"

A live check never changes the response shape and never fails the read. An unreachable provider, an unlookupable transaction, an already-terminal record or a caller inside the cooldown all return the stored record with a 200. The only difference is that the status may be fresher.

`status`	Meaning
`pending`	Keep waiting.
`requires_action`	The customer still owes an OTP or a redirect.
`successful`	Terminal. The money arrived.
`failed`	Terminal. It did not.

A complete Node example

collect.js

import { randomUUID } from "node:crypto";
import { signedFetch } from "./aptapay-client.js";

const BASE = "https://api.pay.aptahq.com";

// 1. Charge. The Idempotency-Key is generated once per user intent,
//    not once per HTTP attempt — reuse it if you retry.
const idempotencyKey = randomUUID();

const charge = await signedFetch(`${BASE}/v1/collections`, {
  method: "POST",
  headers: { "Idempotency-Key": idempotencyKey },
  body: {
    amount_minor: 2000, // UGX is zero-decimal: 2,000 shillings
    currency: "UGX",
    country: "UG",
    method: "momo",
    source: { type: "momo", msisdn: "0781234567", network: "MTN", country: "UG" },
    narration: "Race entry",
    metadata: { order_id: "ord_8813" },
  },
});

const { reference, status, next_action: nextAction } = charge.data;
await saveOrderReference("ord_8813", reference);

// 2. Branch on next_action rather than assuming it is absent.
if (nextAction?.type === "redirect") {
  return redirectCustomerTo(nextAction.redirect_url);
}
if (nextAction?.type === "otp") {
  return promptForOtp({ reference, pinId: nextAction.pin_id });
}

// 3. `pending` is the normal answer. The webhook settles it; this poll
//    is what keeps the waiting customer informed in the meantime.
if (status === "pending") {
  const fresh = await signedFetch(
    `${BASE}/v1/collections/${reference}?live=true`,
    { method: "GET" },
  );
  return fresh.data.status;
}

Correlate on metadata, not on the reference

Put your own order id in metadata at charge time. It is stored on the transaction and echoed back on every webhook delivery as data.metadata, which is how you map a gateway reference to one of your own. Our reference is opaque. It looks like APT-LCS-oRUZWq8fyn9DttNb3SN3B, and while that shape is APT-{prefix}-{nanoid} today, it carries no field you are meant to parse.

Never parse the reference to recover your own identifiers. Match on data.metadata instead. metadata must serialize to at most 4096 bytes, because it is re-sent on every delivery attempt.

OTP is not required

This account is whitelisted for phone verification, so no corridor currently requires an OTP. requires_otp is false for every corridor. A mobile money charge goes to the provider on the single POST /v1/collections call and the customer approves it on their handset prompt alone — Kenya, Rwanda, Uganda and Ghana alike. There is nothing to collect and nothing to post back. The ladder behind it is retained, and can be re-enabled per corridor through configuration. If a corridor is configured to demand a code, a charge sent without an otp texts the customer one, records the transaction, and answers 201 with status: "requires_action" and a next_action of type otp carrying a pin_id.

Finishing a charge that came back requires_action

Collect the code in your UI and submit it against the transaction’s reference. pin_id comes from the next_action on the charge; pin is what the customer typed.

Authorize with the customer's code

curl -sS https://api.pay.aptahq.com/v1/collections/APT-LCS-oRUZWq8fyn9DttNb3SN3B/authorize \
  -H "X-AptaPay-Key: $APP_ID.$KEY_ID.$API_KEY" \
  -H "X-AptaPay-Timestamp: $TS" \
  -H "X-AptaPay-Nonce: $NONCE" \
  -H "X-AptaPay-Signature: v1=$SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "otp": { "pin_id": "a435fdbc-a0b3-4412-848c-2dbc0956e5c6", "pin": "445123" },
    "source": {
      "type": "momo",
      "msisdn": "0781234567",
      "network": "MTN",
      "country": "UG"
    }
  }'

This call validates the code and charges. There is no separate authorize step upstream: authorizing re-sends the charge with the code attached, so a correct code debits the customer immediately. Expect pending here too, and treat the webhook as the answer. A wrong code fails this call without failing the transaction — prompt again and retry.You must resupply source. Re-sending the charge needs the payer’s full number, and the gateway never stores one — only its last four digits, so a leaked database cannot become a list of customer phone numbers. The last4 of what you send is checked against the transaction, so a reference cannot be redirected to a different payer. Amount, currency and country come from the stored transaction and cannot be changed here.

Requesting an OTP yourself

You almost certainly do not need this. POST /v1/collections/otp triggers an SMS one-time PIN for a mobile money collection and is kept for corridors configured to demand a code, and for deployments on an un-whitelisted account.When you do need it: call it first, show the user an “enter the code we texted you” field, then pass what they type back on the charge. It returns a pin_id; send it with the code as otp: {pin_id, pin} — on POST /v1/collections for a fresh charge, or on the authorize endpoint for one already sitting at requires_action.No money moves, so no Idempotency-Key. Calling it again simply sends another code.

The double-charge guard

Before charging, the gateway checks whether a mobile money charge to this same number is already live for your tenant within the last 15 minutes. If one is, it asks the provider what actually happened.

Earlier charge	Result
Succeeded, but its webhook was lost	`409 duplicate_charge_in_flight` with `already_succeeded: "true"` and the earlier `reference`. Show that as a receipt; do not retry.
Failed or expired	It is settled, and this charge proceeds normally.
Still live, or the provider is unreachable	`409 duplicate_charge_in_flight`. Wait and poll `GET /v1/collections/{reference}`.

This is separate from Idempotency-Key. That protects a retried API call; this protects a retried customer action, which arrives with a brand-new key.

Phone numbers

Send the number in whatever form the customer typed. All of 0772123456, 256772123456, +256772123456 and the bare national 772123456 are accepted, with spaces, dashes and parentheses ignored. The gateway normalises to E.164 with a leading + using the country code of the resolved corridor, so a missing country code is supplied rather than guessed from the digits. On a collection, source.country is optional and defaults to the request’s top-level country.

Errors worth handling

Code	Meaning
`duplicate_charge_in_flight`	A charge to this number is already live. See above.
`unknown_currency`	The currency has no declared exponent. Never defaulted.
`inexact_amount`	The minor amount is not an exact integer for that currency.
`invalid_msisdn`	The number is not valid for the resolved corridor.
`mode_mismatch`	A body `mode` field disagreed with the key. See Testing.

Full list and response shape: Errors.

Next steps

Send a payout

The money-out side, and how float and fees work.

Test your integration

Test keys, the amount ceiling, and the Postman collection.

Getting started

Core concepts

Integration

Collect a payment

Before you start

The flow

A complete Node example

Correlate on metadata, not on the reference

OTP is not required

The double-charge guard

Phone numbers

Errors worth handling

Next steps

Send a payout

Test your integration

​Before you start

​The flow

​A complete Node example

​Correlate on metadata, not on the reference

​OTP is not required

​The double-charge guard

​Phone numbers

​Errors worth handling

​Next steps

Send a payout

Test your integration

Before you start

The flow

A complete Node example

Correlate on metadata, not on the reference

OTP is not required

The double-charge guard

Phone numbers

Errors worth handling

Next steps