Price a collection before charging

curl --request POST \
  --url https://api.pay.aptahq.com/v1/collections/quote \
  --header 'Content-Type: application/json' \
  --header 'X-AptaPay-Signature: <api-key>' \
  --data '
{
  "amount_minor": 20000,
  "currency": "UGX",
  "country": "UG",
  "method": "momo"
}
'

const options = {
  method: 'POST',
  headers: {'X-AptaPay-Signature': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({amount_minor: 20000, currency: 'UGX', country: 'UG', method: 'momo'})
};

fetch('https://api.pay.aptahq.com/v1/collections/quote', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.pay.aptahq.com/v1/collections/quote"

payload = {
    "amount_minor": 20000,
    "currency": "UGX",
    "country": "UG",
    "method": "momo"
}
headers = {
    "X-AptaPay-Signature": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "code": 200,
  "message": "OK",
  "data": {
    "amount_minor": 20000,
    "fee_minor": 300,
    "total_to_pay_minor": 20300,
    "currency": "UGX",
    "method": "momo",
    "min_amount_minor": 500,
    "max_amount_minor": 4000000
  }
}

{
  "code": 200,
  "message": "OK",
  "data": "<unknown>",
  "error": {
    "code": "payout_rejected_by_provider",
    "message": "<string>",
    "terminal": true,
    "retriable": true,
    "ambiguous": true,
    "details": {}
  }
}

{
  "code": 200,
  "message": "OK",
  "data": "<unknown>",
  "error": {
    "code": "payout_rejected_by_provider",
    "message": "<string>",
    "terminal": true,
    "retriable": true,
    "ambiguous": true,
    "details": {}
  }
}

Collections

Price a collection before charging

What will this collection cost? 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 and 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. The OTP -> charge flow never consults it, so a quote is never “used up” and can never expire out from under a customer.

total_to_pay_minor comes from the provider, not from amount_minor + fee_minor computed here. Show that figure: it is what the customer is actually billed.

Amounts in and out are integer minor units, and UGX/RWF/XAF/XOF are zero-decimal. momo and bank can be quoted; card cannot, and answers 501.

POST

collections

quote

Price a collection before charging

curl --request POST \
  --url https://api.pay.aptahq.com/v1/collections/quote \
  --header 'Content-Type: application/json' \
  --header 'X-AptaPay-Signature: <api-key>' \
  --data '
{
  "amount_minor": 20000,
  "currency": "UGX",
  "country": "UG",
  "method": "momo"
}
'

const options = {
  method: 'POST',
  headers: {'X-AptaPay-Signature': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({amount_minor: 20000, currency: 'UGX', country: 'UG', method: 'momo'})
};

fetch('https://api.pay.aptahq.com/v1/collections/quote', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.pay.aptahq.com/v1/collections/quote"

payload = {
    "amount_minor": 20000,
    "currency": "UGX",
    "country": "UG",
    "method": "momo"
}
headers = {
    "X-AptaPay-Signature": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "code": 200,
  "message": "OK",
  "data": {
    "amount_minor": 20000,
    "fee_minor": 300,
    "total_to_pay_minor": 20300,
    "currency": "UGX",
    "method": "momo",
    "min_amount_minor": 500,
    "max_amount_minor": 4000000
  }
}

{
  "code": 200,
  "message": "OK",
  "data": "<unknown>",
  "error": {
    "code": "payout_rejected_by_provider",
    "message": "<string>",
    "terminal": true,
    "retriable": true,
    "ambiguous": true,
    "details": {}
  }
}

{
  "code": 200,
  "message": "OK",
  "data": "<unknown>",
  "error": {
    "code": "payout_rejected_by_provider",
    "message": "<string>",
    "terminal": true,
    "retriable": true,
    "ambiguous": true,
    "details": {}
  }
}

Authorizations

X-AptaPay-Signature

string

header

required

v1={hex HMAC-SHA256} over the ten-field canonical string. Sent alongside X-AptaPay-Key, X-AptaPay-Timestamp and X-AptaPay-Nonce — all four are required. OpenAPI can only model one header per scheme, so the other three are described in the Authentication section above.

Body

application/json

amount_minor

integer

required

An integer count of the currency's smallest unit. NEVER a float, and never a decimal major amount. The _minor suffix on a field name is part of the contract: amount could be read as 20.00 or 2000, whereas amount_minor can only be read one way.

The exponent is PER CURRENCY. There is no universal "cents":

Exponent	Currencies	`2000` means
0 (zero-decimal)	UGX, RWF, XAF, XOF	2,000 shillings/francs
2	KES, GHS, NGN, TZS, ZMW, USD, EUR, GBP	20.00

So 2000 UGX is two thousand shillings, while 2000 KES is twenty. Applying a blanket x100 to a zero-decimal currency is a 100x money error — the kind that reconciles to nothing months later.

To send an amount, multiply the major amount by 10^exponent and confirm the result is an exact integer (KES 19.99 -> 1999). To display one, divide by 10^exponent for presentation only — keep the minor-unit integer as the value you store, compare, and sum.

Rules the gateway enforces:

An unknown currency is rejected, never defaulted. A currency with no declared exponent fails with unknown_currency rather than assuming 2, because a silent wrong exponent is worse than a loud failure.
A non-exact amount is rejected, never rounded. KES 19.999 fails with inexact_amount. AptaPay will not decide on your behalf which way to round someone's money.
Amounts are never floats internally. Providers send amounts as strings ("2000") AND sometimes as numbers, so parsing is deliberate at the adapter boundary and converts to an exact integer or fails.

A field's exponent always follows the currency named alongside it. On an FX quote, source_amount_minor and destination_amount_minor routinely use DIFFERENT exponents in the same response.

Example:

2000

currency

enum<string>

required

Available options:

UGX,

RWF,

XAF,

XOF,

KES,

GHS,

NGN,

TZS,

ZMW,

USD,

EUR,

GBP

country

string

required

Example:

"UG"

method

enum<string>

required

Available options:

momo,

bank

Response

The fee quote. Nothing was reserved and nothing expires.

The single response envelope, used by EVERY endpoint so a consuming app parses one shape everywhere.

code

integer

required

Example:

200

message

string

required

Example:

"OK"

data

any

Present on success. Shape varies per endpoint.

error

object

Machine-readable error classification. EXACTLY ONE of terminal/retriable/ ambiguous is true. laces_api inferred this from the HTTP status and got it wrong, stranding real money twice (2026-08-15, 2026-08-16). Branch on these booleans, never on the status code:

terminal -> the provider refused. Reverse the debit and tell the user. retriable -> safe to retry with the SAME Idempotency-Key. ambiguous -> the outcome is UNKNOWN. Do NOT reverse. Poll instead.

Show child attributes

Collections

Payouts

Refunds

Beneficiaries

Transactions

FX

Float

Reference

Webhooks

Ops

Price a collection before charging

Authorizations

Body

Response