Send money home to a @tag
Licensed money-transfer operators in Europe, North America and worldwide use the Tagali API to pay remittances straight into a customer's Tagali wallet in Senegal, Côte d'Ivoire and the rest of the UEMOA zone. Your sender types @moussa, confirms the name, and the money arrives in seconds.
How it works
- Look up the tag.
GET /recipients/{tag}returns a masked name like Moussa T. for your sender to confirm. - Quote.
POST /quotesfixes the XOF amount and your fee for 15 minutes. - Pay out.
POST /payoutscredits the recipient instantly from your prefunded balance. - Track. Webhooks tell you when a payout completes, is held for review, or when the recipient says thank you.
| Item | Value |
|---|---|
| Base URL | https://api.tagali.example/partner/v1 (one URL for sandbox and live) |
| Currency | XOF only, whole francs. Convert EUR, USD, GBP… on your side. |
| Format | JSON over HTTPS, UTF-8. Timestamps are ISO 8601 UTC. |
| Environments | Test keys pk_test_… reach the sandbox. Live keys pk_live_… move real money. |
| Recipients pay | Nothing. They receive the full amount. |
Quickstart
You'll create a developer account, get sandbox keys and send a test payout to test.moussa, a simulated customer in Dakar.
- Create a developer account. Sign up with your work email. Your sandbox comes with 50 000 000 XOF of test money.
- Create a sandbox key. In the dashboard, open API keys and select Create key. Copy the secret; it is shown once.
- Download a client. Copy partner-client.js (Node 18+) or tagali_client.py (Python 3.8+). Both have no dependencies.
- Send your first payout.
import { createTagaliClient } from './partner-client.js';
const tagali = createTagaliClient({
baseUrl: 'https://api.tagali.example/partner/v1',
keyId: process.env.TAGALI_KEY, // pk_test_…
secret: process.env.TAGALI_SECRET, // sk_test_…
});
// 1. Look up the tag and show the masked name to your sender
const r = await tagali.lookup('test.moussa', 'Moussa Traoré');
console.log(r.displayName, r.nameMatch); // "Moussa T." "exact"
// 2. Quote 65 000 XOF (about 99 EUR)
const q = await tagali.quote(r.lookupId, 65000);
// 3. Pay out. Keep the idempotency key to retry safely after a timeout.
const p = await tagali.payout({
quoteId: q.quoteId,
partnerReference: 'TRX-2026-000123',
sender: { fullName: 'Aminata Diallo', country: 'FR', dateOfBirth: '1988-04-12', idType: 'passport', idNumber: '19FR12345' },
purpose: 'family_support',
message: 'Pour la rentrée scolaire',
});
console.log(p.payout.status, p.payout.reference); // "successful" "TST-20261118-…"
import os
from tagali_client import TagaliClient
tagali = TagaliClient("https://api.tagali.example/partner/v1",
os.environ["TAGALI_KEY"], os.environ["TAGALI_SECRET"])
# 1. Look up the tag and show the masked name to your sender
r = tagali.lookup("test.moussa", "Moussa Traoré")
print(r["displayName"], r["nameMatch"]) # Moussa T. exact
# 2. Quote 65 000 XOF (about 99 EUR)
q = tagali.quote(r["lookupId"], 65000)
# 3. Pay out. Keep the idempotency key to retry safely after a timeout.
p = tagali.payout({
"quoteId": q["quoteId"],
"partnerReference": "TRX-2026-000123",
"sender": {"fullName": "Aminata Diallo", "country": "FR", "dateOfBirth": "1988-04-12",
"idType": "passport", "idNumber": "19FR12345"},
"purpose": "family_support",
"message": "Pour la rentrée scolaire",
})
print(p["payout"]["status"], p["payout"]["reference"])
# 1. Look up (GET has an empty body) TS=$(date +%s); NONCE=$(openssl rand -hex 16) EMPTY=$(printf '' | openssl dgst -sha256 -hex | sed 's/^.* //') SIG=$(printf '%s' "$TS.$NONCE.GET./partner/v1/recipients/test.moussa.$EMPTY" \ | openssl dgst -sha256 -hmac "$TAGALI_SECRET" -hex | sed 's/^.* //') curl "$TAGALI_HOST/partner/v1/recipients/test.moussa" \ -H "X-Tagali-Key: $TAGALI_KEY" -H "X-Tagali-Timestamp: $TS" \ -H "X-Tagali-Nonce: $NONCE" -H "X-Tagali-Signature: v1=$SIG" # Each call needs a fresh timestamp, nonce and signature. # See the API reference for signed cURL samples of every endpoint.
Next: receive webhooks, then try the sandbox scenarios for holds and errors before you go live.
Authentication & signing
Every request is signed with your secret key using HMAC-SHA256. Secrets never travel over the network, and a captured request cannot be replayed.
| Header | Value |
|---|---|
X-Tagali-Key | Your key id, pk_test_… or pk_live_… |
X-Tagali-Timestamp | Current Unix time in seconds. Must be within 5 minutes of our clock. |
X-Tagali-Nonce | 16 to 64 random characters, never reused. |
X-Tagali-Signature | v1= followed by the hex HMAC-SHA256 of the signing string. |
Signing string
Join five parts with dots: timestamp, nonce, HTTP method in capitals, the path with its query string, and the hex SHA-256 of the raw body (the hash of an empty string for GET).
{timestamp}.{nonce}.{METHOD}.{path?query}.{sha256_hex(body)}
1763460000.9f86d081884c7d65.POST./partner/v1/quotes.5e0f1c…
import { createHmac, createHash, randomBytes } from 'node:crypto';
function sign(secret, method, pathWithQuery, rawBody = '') {
const ts = String(Math.floor(Date.now() / 1000));
const nonce = randomBytes(16).toString('hex');
const bodyHash = createHash('sha256').update(rawBody).digest('hex');
const sig = createHmac('sha256', secret).update(`${ts}.${nonce}.${method}.${pathWithQuery}.${bodyHash}`).digest('hex');
return { 'X-Tagali-Timestamp': ts, 'X-Tagali-Nonce': nonce, 'X-Tagali-Signature': `v1=${sig}` };
}
import hashlib, hmac, secrets, time
def sign(secret: str, method: str, path_with_query: str, raw_body: bytes = b"") -> dict:
ts = str(int(time.time()))
nonce = secrets.token_hex(16)
body_hash = hashlib.sha256(raw_body).hexdigest()
msg = f"{ts}.{nonce}.{method}.{path_with_query}.{body_hash}".encode()
sig = hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()
return {"X-Tagali-Timestamp": ts, "X-Tagali-Nonce": nonce, "X-Tagali-Signature": f"v1={sig}"}
401 UNAUTHORIZED. Call GET /ping to test your signing code.Keeping keys safe
- Store secrets in a secrets manager, never in source control or in a mobile app.
- Restrict live keys to your servers' IP addresses in the dashboard.
- You can hold up to 5 active keys per environment. Create the new key, deploy it, then revoke the old one.
Recipient binding
A lookup is tied to the person behind the tag at that moment, not just to the text of the tag. When you create the payout we check, inside the same database transaction, that the tag still belongs to that person and that their verified name has not changed.
If anything changed, the payout fails with 409 RECIPIENT_CHANGED and no money moves. Look the tag up again and ask your sender to confirm the new name.
displayName to your sender and ask "Is this the right person?" before you pay out. Pass the name your sender typed as ?name= to get nameMatch: exact, strong, partial or none. We never return the full name or any linked account.Idempotency & retries
POST /payouts requires an Idempotency-Key header (16 to 64 letters, digits, - or _; a UUID works well). If a request times out, retry with the same key and the same body: you get the original payout back with "replayed": true and the recipient is never paid twice.
- Same key, different body →
409 IDEMPOTENCY_CONFLICT. - Your
partnerReferencemust also be unique →409 DUPLICATE_REFERENCE. - A quote produces at most one payout →
409 QUOTE_USED. - Not sure whether a payout went through?
GET /payouts?partnerReference=TRX-…
Retry network errors and 5xx responses with exponential back-off. Do not retry 4xx responses without fixing the request, except 429.
Payout statuses & holds
| Status | Meaning | Final? |
|---|---|---|
successful | The recipient has the money. They got an SMS and an in-app notification. | Yes |
pending_review | Held by compliance screening. The total is reserved from your balance. | No |
rejected | Compliance refused it. The total is returned to your balance. | Yes |
cancelled | You cancelled a held payout. The total is returned to your balance. | Yes |
Hold reasons
holdReason | Why |
|---|---|
AMOUNT_REVIEW | The amount is at or above the review threshold (1 000 000 XOF). |
RECIPIENT_KYC | The recipient has not verified their identity and the amount is above 200 000 XOF. |
SANCTIONS_SCREENING | The sender or recipient name is close to a watch-list entry. |
Most holds are decided within a few business hours. You can cancel a held payout with POST /payouts/{id}/cancel.
Webhooks
Set an HTTPS endpoint in the dashboard (one per environment). We POST a JSON event each time a payout changes.
| Event | When |
|---|---|
payout.completed | The recipient was credited (immediately, or after a hold was approved). |
payout.held | The payout is waiting for compliance review. |
payout.rejected | A held payout was rejected and refunded to your balance. |
payout.cancelled | You cancelled a held payout. |
payout.thanked | The recipient sent a thank-you message. Pass it on to your sender. |
webhook.test | You selected Send test event in the dashboard. |
{
"id": "evt_2mQ8x1Lr5v",
"type": "payout.thanked",
"createdAt": "2026-11-18T10:05:00.000Z",
"data": {
"id": "po_Q8x1Lr5vNw",
"reference": "RMT-20261118-9F2A11C0",
"partnerReference": "TRX-2026-000123",
"status": "successful",
"amount": 65000,
"currency": "XOF",
"recipient": { "tag": "moussa", "displayName": "Moussa T." },
"thanks": { "message": "Jërëjëf ! Merci beaucoup tata Aminata", "at": "2026-11-18T10:05:00.000Z" }
}
}
Verify the signature
Each delivery carries X-Tagali-Event, X-Tagali-Timestamp and X-Tagali-Signature: v1=HMAC_SHA256(webhookSecret, "{timestamp}.{rawBody}"). Verify it on the raw body before parsing, and reject timestamps older than 5 minutes.
import express from 'express';
import { verifyTagaliWebhook } from './partner-client.js';
app.post('/tagali/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
const ok = verifyTagaliWebhook({
rawBody: req.body.toString('utf8'),
timestamp: req.get('X-Tagali-Timestamp'),
signature: req.get('X-Tagali-Signature'),
webhookSecret: process.env.TAGALI_WEBHOOK_SECRET,
});
if (!ok) return res.sendStatus(400);
const event = JSON.parse(req.body);
// Deduplicate on event.id, then update your transfer
res.sendStatus(200);
});
from flask import Flask, request, abort
from tagali_client import verify_tagali_webhook
@app.post("/tagali/webhooks")
def tagali_webhook():
if not verify_tagali_webhook(request.get_data(), request.headers.get("X-Tagali-Timestamp"),
request.headers.get("X-Tagali-Signature"), os.environ["TAGALI_WEBHOOK_SECRET"]):
abort(400)
event = request.get_json()
# Deduplicate on event["id"], then update your transfer
return "", 200
Delivery and retries
Reply with any 2xx within 10 seconds. Otherwise we retry after 30 s, 2 min, 10 min, 30 min, 1 h, 6 h, 12 h and 24 h. Events can arrive more than once or out of order: deduplicate on id and use GET /payouts/{id} as the source of truth. The dashboard shows every delivery and lets you resend one.
Errors
Errors use standard HTTP status codes and a JSON body with a stable code you can branch on. The message is for people and may change.
{ "error": { "code": "RECIPIENT_CHANGED", "message": "The recipient behind this tag has changed since the lookup. Look the tag up again and confirm the name with your sender." } }
| Status | Code | What to do |
|---|
Rate limits
Each account can make 600 requests per minute in total, of which up to 120 lookups. Over the limit you get 429 RATE_LIMITED with a Retry-After header in seconds. Contact us before a big campaign and we'll raise your limits.
Sandbox & test data
The sandbox behaves like production with simulated customers and simulated money. Use your pk_test_… key with the same base URL. Real customers cannot be reached with test keys, and nothing you do in the sandbox moves real money.
Test recipients
| Tag | Name | Behaviour |
|---|
Magic values
| Input | Result |
|---|---|
| Amount ≥ 1 000 000 XOF | Held with AMOUNT_REVIEW |
Sender fullName containing Watchlist | Held with SANCTIONS_SCREENING |
| Any tag not in the table above | 404 RECIPIENT_NOT_FOUND |
Simulate what Tagali and the recipient do
In production, Tagali compliance decides held payouts and recipients choose whether to say thank you. In the sandbox you trigger these yourself, from the dashboard or the API. Each sends the matching webhook.
await tagali.sandbox.approve(payoutId); // → payout.completed await tagali.sandbox.reject(payoutId); // → payout.rejected, money refunded await tagali.sandbox.thank(payoutId, 'Jërëjëf !'); // → payout.thanked await tagali.sandbox.topUp(10000000); // add 10 000 000 XOF of test money
tagali.request("POST", f"/sandbox/payouts/{payout_id}/approve", {}) # payout.completed
tagali.request("POST", f"/sandbox/payouts/{payout_id}/reject", {}) # payout.rejected
tagali.request("POST", f"/sandbox/payouts/{payout_id}/thank", {"message": "Jërëjëf !"})
tagali.request("POST", "/sandbox/top-up", {"amount": 10000000})
TST- and every payout carries "environment": "sandbox". Sandbox data may be reset; don't rely on it long term.Fees & prefunding
Live payouts are paid from a prefunded XOF balance that you hold with Tagali. Each payout debits amount + partnerFee. The recipient always receives the full amount for free.
- Your fee is agreed when you go live: a fixed part plus a percentage, shown in every quote as
partnerFee. - Funding: send a bank transfer to the Tagali settlement account shown in your dashboard, quoting your partner ID. Then select Notify a deposit so our finance team can match it faster.
- Crediting: two people on our finance team confirm each deposit before it is credited. You see it on your statement as a
depositline. - Low balance: payouts fail with
402 INSUFFICIENT_PREFUNDINGand nothing is held. WatchGET /balanceand top up early.
Going live
- Finish your sandbox integration. Successful payouts, a held payout you approve and one you reject,
RECIPIENT_CHANGEDhandling, idempotent retries and verified webhooks. - Apply for live access from the dashboard: company details, money-transfer licence and regulator, sending countries, expected volumes and your AML programme.
- Review. Our compliance team checks your licence and may ask for more information. You get an email at each step.
- Create live keys once approved, set your live webhook and restrict keys to your server IPs.
- Fund your account by bank transfer and notify the deposit in the dashboard.
- Launch with a small payout to a colleague's real tag, then open to your customers.
Client libraries
Both clients are single files with no dependencies. Copy them into your project; they sign requests, handle errors and verify webhooks.
| Language | File | Needs |
|---|---|---|
| Node.js | partner-client.js | Node 18+ |
| Python | tagali_client.py | Python 3.8+ |
| Any language | openapi.json | OpenAPI 3.1 generators (add the signing step) |
Questions? Write to [email protected].