Documentation

Tamsey Payment APIs

The Tamsey API enables partners to integrate merchant payments and fund disbursements directly into their platforms. All integrations use HTTPS and authenticate with a per-partner API key issued during onboarding.

This reference covers two product areas:

Merchant Payments — generate scannable EMV QR codes so your merchants can accept payments from Tamsey Wallet, MTN MoMo, and Orange Money.
Disbursements — programmatically send funds to merchant or supplier wallets and query wallet balances.

💬

API access requires a signed partnership agreement. To apply, contact partners@tamsey.com. Sandbox credentials are provided upon approval.

Authentication

Every API request must carry your API key in the Authorization header as a Bearer token.

⚠

Keep your API key secret. Do not commit it to source control or expose it in client-side code. Rotate it immediately if you believe it has been compromised.

Header format

HEADER Authorization: Bearer YOUR_API_KEY

Requests without a valid key return 401 Unauthorized. Keys are scoped to a single partner account and carry the permissions assigned during onboarding.

Environments

Environment	Base URL	Notes
Sandbox	https://sandbox-api.tamsey.com/v1	Test with simulated payments. No real funds move.
Production	https://api.tamsey.com/v1	Live environment. Requires production API key.

Sandbox behaves identically to production for all API calls. In sandbox, payment webhook events are triggered automatically after a short delay to simulate a completed transaction.

Error Handling

Tamsey returns standard HTTP status codes. Error responses always include a JSON body with a message field describing the problem.

Status	Meaning
`400`	Bad Request — missing or invalid parameters.
`401`	Unauthorized — API key missing or invalid.
`403`	Forbidden — action not permitted for this key.
`404`	Not Found — wallet or resource does not exist.
`422`	Unprocessable — validation failed (see `errors` field).
`429`	Rate Limited — slow down and retry after the indicated delay.
`502`	Upstream Error — a payment network is temporarily unreachable.

Merchant Payments

Generate Merchant QR Code

Returns an EMV-compliant QR code string for a merchant identified by their Tamsey Wallet ID. The QR code encodes all payment routing data and is scannable by any mobile money app that supports the GIMAC/EMV standard.

POST /v1/payments/qr/generate

Request body

Parameter	Type	Description
merchant_id required	string	The merchant's Tamsey Wallet ID. Provided to the merchant during their Tamsey onboarding.

Response

Returns a JSON object containing the emv_string — the raw EMV payload to encode into a QR image — and confirming the merchant's identity.

Field	Type	Description
status	boolean	`true` on success.
emv_string	string	EMV QR payload. Encode this as a QR code image.
merchant_id	string	Echo of the requested merchant ID.
merchant_name	string	Verified name of the merchant.

Dynamic QR (Fixed Amount)

You can generate a QR code pre-loaded with a specific amount. When a customer scans a dynamic QR, the amount is pre-filled in their mobile money app — reducing entry errors and speeding up checkout.

To generate a dynamic QR, include the optional amount field in your request body.

POST /v1/payments/qr/generate

Additional parameter

Parameter	Type	Description
amount	number	Amount in XAF (Central African Franc). Omit for a static/open-amount QR. Must be greater than 0.

💡

Static QRs (no amount) can be printed on physical materials. Dynamic QRs are typically generated per-transaction and should expire or be regenerated each session.

Payment Status

After a QR payment is completed, Tamsey sends a webhook to your registered endpoint. You can also query the payment status directly using the payment_ref returned in the webhook payload.

GET /v1/payments/{payment_ref}

Field	Type	Description
payment_ref	string	Unique reference for this payment.
status	string	`pending`, `completed`, or `failed`.
amount	number	Amount received in XAF.
merchant_id	string	Tamsey Wallet ID of the receiving merchant.
completed_at	string	ISO 8601 timestamp when the payment settled. Null if still pending.

Disbursements

Wallet Balance

Check the available balance of a Tamsey wallet before initiating a disbursement. This is useful to validate that sufficient funds are available without triggering a transaction.

GET /v1/wallets/{wallet_id}/balance

Path parameters

Parameter	Type	Description
wallet_id required	string	The Tamsey Wallet ID to query. Your API key must have read access to this wallet.

Response

Field	Type	Description
wallet_id	string	The wallet queried.
balance	number	Available balance in the wallet's currency.
currency	string	ISO 4217 currency code, e.g. `XAF`.
as_of	string	ISO 8601 timestamp of the balance snapshot.

Initiate Disbursement

Send funds to a recipient via a Tamsey wallet, mobile money account, or bank account. Tamsey handles all routing and network selection automatically — you specify the destination and amount, we handle delivery.

POST /v1/disbursements

⚠

Disbursements are irreversible once submitted. Always verify the destination and amount before calling this endpoint. We recommend checking the wallet balance first and including a confirmation step in your UI.

Request body

Parameter	Type	Description
payout_method required	string	How to deliver funds. One of: `wallet`, `mobile_money`, `bank_transfer`. See Payout Methods.
amount required	number	Amount to disburse. Must be positive and not exceed your available settlement balance.
currency required	string	ISO 4217 currency code, e.g. `XAF`, `USD`. Must be supported for the destination country.
destination required	object	Destination details. Fields vary by `payout_method` — see below.
reference	string	Your internal reference. Returned in all webhooks for reconciliation. Max 64 characters.
description	string	A note visible to the recipient. Max 128 characters.

Response

Field	Type	Description
disbursement_id	string	Unique identifier. Store this — it is required to query status and is included in all webhooks.
status	string	`processing` on acceptance. Final status is delivered via webhook.
payout_method	string	Echo of the method used.
estimated_arrival	string	Estimated delivery window, e.g. `"within 2 minutes"` or `"1–2 business days"`.
reference	string	Echo of your reference, if provided.
created_at	string	ISO 8601 timestamp.

Payout Methods

The destination object structure depends on the chosen payout_method.

wallet

Send directly to a recipient's Tamsey Wallet. Fastest option — typically instant.

Field	Type	Description
destination.wallet_id required	string	The recipient's Tamsey Wallet ID.

mobile_money

Send to a mobile money account (MTN MoMo, Orange Money, and others). Delivery is typically within minutes. See Supported Networks for available countries and operators.

Field	Type	Description
destination.phone required	string	Recipient phone number in E.164 format, e.g. `+237612345678`.
destination.network	string	Mobile network operator, e.g. `MTN`, `ORANGE`. If omitted, Tamsey detects it automatically from the phone number.
destination.country required	string	ISO 3166-1 alpha-2 country code, e.g. `CM` for Cameroon.
destination.recipient_name	string	Full name of the recipient. Recommended for compliance.

bank_transfer

Send to a bank account. Processing time is typically 1–2 business days. Available for select countries — contact your integration manager to confirm coverage.

Field	Type	Description
destination.account_number required	string	Bank account number or IBAN.
destination.bank_code required	string	BIC/SWIFT code of the receiving bank.
destination.recipient_name required	string	Full legal name of the account holder.
destination.country required	string	ISO 3166-1 alpha-2 country code of the receiving bank.

Supported Networks

The following countries and mobile money networks are currently supported for disbursements. Coverage expands regularly — contact your integration manager for the latest list.

Country	Code	Networks	Currency
Cameroon	`CM`	MTN MoMo, Orange Money	XAF
Gabon	`GA`	Airtel Money, Moov Money	XAF
Congo (DRC)	`CD`	MTN MoMo, Airtel Money	CDF
Senegal	`SN`	Orange Money, Wave, Free Money	XOF
Côte d'Ivoire	`CI`	MTN MoMo, Orange Money, Wave	XOF
Ghana	`GH`	MTN MoMo, Vodafone Cash, AirtelTigo	GHS
Nigeria	`NG`	Bank Transfer, OPay	NGN
Kenya	`KE`	M-Pesa	KES

💡

For international payouts where the sender and recipient currencies differ, Tamsey applies the mid-market exchange rate at the time of submission. The fx_rate and recipient_amount fields in the disbursement response confirm the exact rate locked in.

Webhooks

Receiving Webhooks

Tamsey sends real-time event notifications to a URL you register during onboarding. Webhooks allow your system to respond immediately to payment completions and disbursement updates without polling the API.

Provide a publicly accessible HTTPS URL to your Tamsey integration contact.
Your endpoint must respond with HTTP 200 within 10 seconds. Otherwise the event is retried.
Verify the X-Tamsey-Signature header on every incoming request before processing.
Acknowledge immediately, then process asynchronously to avoid timeouts.

Event Types

Event	Trigger
`payment.completed`	A merchant QR payment was received and settled.
`payment.failed`	A payment attempt was declined or timed out.
`disbursement.completed`	Funds have been delivered to the recipient wallet, mobile money account, or bank.
`disbursement.failed`	Delivery failed (e.g. invalid phone number, network unavailable). Funds are returned to your settlement wallet.
`disbursement.returned`	A completed disbursement was reversed by the recipient's network. Rare — usually affects bank transfers.

Webhook payload structure

All events share a common envelope. The data object contains event-specific fields.

Signature Verification

Each webhook delivery includes a X-Tamsey-Signature header containing an HMAC-SHA256 signature of the raw request body, signed with your webhook secret. Always verify this before trusting the payload.

⚠

Never skip signature verification in production. An unverified endpoint can be spoofed to fraudulently trigger disbursements or update order status in your system.

To verify: compute HMAC-SHA256(rawBody, webhookSecret), hex-encode the result, and compare it to the signature header using a constant-time comparison function.

Reference

Error Codes

Machine-readable error codes appear in the code field of error responses alongside the human-readable message.

Code	Description
INVALID_API_KEY	The API key is missing, malformed, or revoked.
WALLET_NOT_FOUND	The wallet ID does not exist or is not accessible with this key.
MERCHANT_NOT_FOUND	No active Tamsey merchant account is linked to this merchant ID.
INSUFFICIENT_BALANCE	The settlement wallet does not have enough funds for this disbursement.
INVALID_AMOUNT	Amount is zero, negative, or not a number.
UNSUPPORTED_CURRENCY	The provided currency code is not supported for this wallet.
RATE_LIMITED	Too many requests. Respect the `Retry-After` header.
UPSTREAM_TIMEOUT	A mobile money network did not respond in time. Retry with exponential backoff.

Supported Currencies

Code	Name	Region
`XAF`	Central African CFA Franc	Cameroon, Gabon, Congo, Chad, CAR, Equatorial Guinea
`XOF`	West African CFA Franc	Senegal, Côte d'Ivoire, Mali, Burkina Faso, and others
`USD`	US Dollar	International settlements

Support

For integration support, contact the Tamsey partnerships team:

Email: partners@tamsey.com
For urgent production issues, use the priority channel provided in your onboarding pack.

🔐

Never include your API key or webhook secret in support emails. Our team will never ask for them.