Tagali Partner API

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

  1. Look up the tag. GET /recipients/{tag} returns a masked name like Moussa T. for your sender to confirm.
  2. Quote. POST /quotes fixes the XOF amount and your fee for 15 minutes.
  3. Pay out. POST /payouts credits the recipient instantly from your prefunded balance.
  4. Track. Webhooks tell you when a payout completes, is held for review, or when the recipient says thank you.
ItemValue
Base URLhttps://api.tagali.example/partner/v1 (one URL for sandbox and live)
CurrencyXOF only, whole francs. Convert EUR, USD, GBP… on your side.
FormatJSON over HTTPS, UTF-8. Timestamps are ISO 8601 UTC.
EnvironmentsTest keys pk_test_… reach the sandbox. Live keys pk_live_… move real money.
Recipients payNothing. 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.

  1. Create a developer account. Sign up with your work email. Your sandbox comes with 50 000 000 XOF of test money.
  2. Create a sandbox key. In the dashboard, open API keys and select Create key. Copy the secret; it is shown once.
  3. Download a client. Copy partner-client.js (Node 18+) or tagali_client.py (Python 3.8+). Both have no dependencies.
  4. 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.

HeaderValue
X-Tagali-KeyYour key id, pk_test_… or pk_live_…
X-Tagali-TimestampCurrent Unix time in seconds. Must be within 5 minutes of our clock.
X-Tagali-Nonce16 to 64 random characters, never reused.
X-Tagali-Signaturev1= 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}"}
Sign the exact bytes you send. If you re-serialise the JSON after signing, the hash will not match and you get 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.

Always show 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 partnerReference must 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

StatusMeaningFinal?
successfulThe recipient has the money. They got an SMS and an in-app notification.Yes
pending_reviewHeld by compliance screening. The total is reserved from your balance.No
rejectedCompliance refused it. The total is returned to your balance.Yes
cancelledYou cancelled a held payout. The total is returned to your balance.Yes

Hold reasons

holdReasonWhy
AMOUNT_REVIEWThe amount is at or above the review threshold (1 000 000 XOF).
RECIPIENT_KYCThe recipient has not verified their identity and the amount is above 200 000 XOF.
SANCTIONS_SCREENINGThe 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.

EventWhen
payout.completedThe recipient was credited (immediately, or after a hold was approved).
payout.heldThe payout is waiting for compliance review.
payout.rejectedA held payout was rejected and refunded to your balance.
payout.cancelledYou cancelled a held payout.
payout.thankedThe recipient sent a thank-you message. Pass it on to your sender.
webhook.testYou 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." } }
StatusCodeWhat 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

TagNameBehaviour

Magic values

InputResult
Amount ≥ 1 000 000 XOFHeld with AMOUNT_REVIEW
Sender fullName containing WatchlistHeld with SANCTIONS_SCREENING
Any tag not in the table above404 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})
Sandbox references start with 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 deposit line.
  • Low balance: payouts fail with 402 INSUFFICIENT_PREFUNDING and nothing is held. Watch GET /balance and top up early.

Going live

  1. Finish your sandbox integration. Successful payouts, a held payout you approve and one you reject, RECIPIENT_CHANGED handling, idempotent retries and verified webhooks.
  2. Apply for live access from the dashboard: company details, money-transfer licence and regulator, sending countries, expected volumes and your AML programme.
  3. Review. Our compliance team checks your licence and may ask for more information. You get an email at each step.
  4. Create live keys once approved, set your live webhook and restrict keys to your server IPs.
  5. Fund your account by bank transfer and notify the deposit in the dashboard.
  6. Launch with a small payout to a colleague's real tag, then open to your customers.
Live and sandbox are separate: different keys, webhooks, balances and logs. Your sandbox stays available for testing after you go live.

Client libraries

Both clients are single files with no dependencies. Copy them into your project; they sign requests, handle errors and verify webhooks.

LanguageFileNeeds
Node.jspartner-client.jsNode 18+
Pythontagali_client.pyPython 3.8+
Any languageopenapi.jsonOpenAPI 3.1 generators (add the signing step)

Questions? Write to [email protected].