{"openapi":"3.1.0","info":{"title":"Tagali Partner API","version":"1.1.0","summary":"Pay out international remittances to Tagali tags in XOF.","description":"Licensed money-transfer operators use this API to credit Tagali customers instantly by their @tag, in XOF. See the guides at /developers for authentication, the sandbox, webhooks and going live.","contact":{"name":"Tagali partner support","email":"partners@tagali.example"}},"servers":[{"url":"https://tigali.money/partner/v1","description":"Same URL for sandbox and live. Test keys (pk_test_…) reach the sandbox; live keys (pk_live_…) move real money."}],"security":[{"TagaliKey":[],"TagaliTimestamp":[],"TagaliNonce":[],"TagaliSignature":[]}],"tags":[{"name":"Recipients","description":"Find a Tagali customer by tag and show your sender a masked name to confirm."},{"name":"Quotes","description":"Lock the amount and your fee for 15 minutes."},{"name":"Payouts","description":"Credit the recipient. Payouts are final once `successful`."},{"name":"Account","description":"Credentials check, prefunded balance and statement."},{"name":"Sandbox","description":"Simulation helpers. Test keys only."}],"paths":{"/ping":{"get":{"operationId":"ping","tags":["Account"],"summary":"Check credentials","description":"Verifies your key and signature. Use it to test your signing code first.","responses":{"200":{"description":"Signature valid","content":{"application/json":{"example":{"ok":true,"partner":{"id":"ptn_3kq…","name":"EuroSend"},"environment":"sandbox","time":"2026-11-18T10:00:00.000Z"}}}},"401":{"description":"`UNAUTHORIZED`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"UNAUTHORIZED","message":"Key unknown or revoked, bad signature, stale timestamp or reused nonce."}}}}},"403":{"description":"`IP_NOT_ALLOWED`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"IP_NOT_ALLOWED","message":"The request came from an IP address outside your allow-list."}}}}}}}},"/recipients/{tag}":{"get":{"operationId":"lookupRecipient","tags":["Recipients"],"summary":"Look up a tag","description":"Returns a masked display name for your sender to confirm, and a `lookupId` valid for 30 minutes. The full name is never returned. Pass `name` (the name your sender typed) to get a match level.\n\nThe lookup binds to the person behind the tag at this moment. If the tag changes hands before you pay out, the payout fails with `RECIPIENT_CHANGED`.","parameters":[{"name":"tag","in":"path","required":true,"schema":{"type":"string","pattern":"^@?[a-z0-9._]{3,20}$"},"description":"Tag with or without the leading @","example":"moussa"},{"name":"name","in":"query","required":false,"schema":{"type":"string"},"description":"Recipient name as given by your sender","example":"Moussa Traoré"}],"responses":{"200":{"description":"Recipient found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lookup"},"example":{"lookupId":"lku_8Jb2kq0Zx1","tag":"moussa","displayName":"Moussa T.","canReceive":true,"currency":"XOF","nameMatch":"exact","expiresAt":"2026-11-18T10:30:00.000Z"}}}},"400":{"description":"`INVALID_TAG`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_TAG","message":"The tag is not a valid Tagali tag."}}}}},"404":{"description":"`RECIPIENT_NOT_FOUND`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RECIPIENT_NOT_FOUND","message":"No Tagali customer uses this tag."}}}}},"422":{"description":"`RECIPIENT_UNAVAILABLE`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RECIPIENT_UNAVAILABLE","message":"The tag exists but cannot receive payments right now."}}}}},"429":{"description":"`RATE_LIMITED`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"Too many requests. Wait for Retry-After seconds."}}}}}}}},"/quotes":{"post":{"operationId":"createQuote","tags":["Quotes"],"summary":"Create a quote","description":"Fixes the XOF amount and your fee for 15 minutes. The recipient always receives `amount` in full; your fee is added to `totalDebited` from your prefunded balance.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lookupId","amount"],"properties":{"lookupId":{"type":"string","description":"From the lookup"},"amount":{"type":"integer","minimum":100,"description":"Whole XOF the recipient receives"},"currency":{"type":"string","enum":["XOF"],"description":"Always XOF"}}},"example":{"lookupId":"lku_8Jb2kq0Zx1","amount":65000,"currency":"XOF"}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"},"example":{"quoteId":"pq_Wm3t9aQe7c","currency":"XOF","amount":65000,"recipientReceives":65000,"recipientFee":0,"partnerFee":525,"totalDebited":65525,"expiresAt":"2026-11-18T10:15:00.000Z"}}}},"400":{"description":"`INVALID_AMOUNT`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_AMOUNT","message":"Amount is not a whole number of XOF within limits."}}}}},"404":{"description":"`LOOKUP_NOT_FOUND`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"LOOKUP_NOT_FOUND","message":"Unknown lookupId."}}}}},"410":{"description":"`LOOKUP_EXPIRED`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"LOOKUP_EXPIRED","message":"The lookup is older than 30 minutes."}}}}}}}},"/payouts":{"post":{"operationId":"createPayout","tags":["Payouts"],"summary":"Create a payout","description":"Credits the recipient instantly (`successful`) unless compliance screening holds it (`pending_review`). Tagali compliance approves or rejects held payouts; you get a webhook either way.\n\nAlways send an `Idempotency-Key`. Retrying with the same key and body returns the original payout with `replayed: true`.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"},"example":"7f1c2a9e-4d3b-4b8e-9a51-1f0c3e2d7b6a"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutRequest"},"example":{"quoteId":"pq_Wm3t9aQe7c","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"}}}},"responses":{"200":{"description":"Idempotent replay of the original payout","content":{"application/json":{"example":{"replayed":true,"payout":{"id":"po_Q8x1Lr5vNw","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","status":"successful","holdReason":null,"recipient":{"tag":"moussa","displayName":"Moussa T."},"amount":65000,"fee":525,"totalDebited":65525,"currency":"XOF","sender":{"name":"Aminata Diallo","country":"FR"},"purpose":"family_support","message":"Pour la rentrée scolaire","environment":"live","thanks":null,"createdAt":"2026-11-18T10:02:11.000Z","updatedAt":"2026-11-18T10:02:11.000Z"}}}}},"201":{"description":"Payout created","content":{"application/json":{"schema":{"type":"object","properties":{"replayed":{"type":"boolean"},"payout":{"$ref":"#/components/schemas/Payout"}}},"example":{"replayed":false,"payout":{"id":"po_Q8x1Lr5vNw","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","status":"successful","holdReason":null,"recipient":{"tag":"moussa","displayName":"Moussa T."},"amount":65000,"fee":525,"totalDebited":65525,"currency":"XOF","sender":{"name":"Aminata Diallo","country":"FR"},"purpose":"family_support","message":"Pour la rentrée scolaire","environment":"live","thanks":null,"createdAt":"2026-11-18T10:02:11.000Z","updatedAt":"2026-11-18T10:02:11.000Z"}}}}},"400":{"description":"`INVALID_FIELD`, `IDEMPOTENCY_KEY_REQUIRED`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_FIELD","message":"A field is missing or malformed. error.field names it."}}}}},"402":{"description":"`INSUFFICIENT_PREFUNDING`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INSUFFICIENT_PREFUNDING","message":"Your prefunded balance cannot cover the payout total. Fund your account."}}}}},"404":{"description":"`QUOTE_NOT_FOUND`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"QUOTE_NOT_FOUND","message":"Unknown quoteId."}}}}},"409":{"description":"`RECIPIENT_CHANGED`, `DUPLICATE_REFERENCE`, `IDEMPOTENCY_CONFLICT`, `QUOTE_USED`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RECIPIENT_CHANGED","message":"The person behind the tag changed after your lookup. Look up again and re-confirm with your sender. No money moved."}}}}},"410":{"description":"`QUOTE_EXPIRED`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"QUOTE_EXPIRED","message":"The quote is older than 15 minutes."}}}}}}},"get":{"operationId":"listPayouts","tags":["Payouts"],"summary":"List payouts","description":"Newest first. Filter by `status` or find one by your `partnerReference`.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["successful","pending_review","rejected","cancelled"]}},{"name":"partnerReference","in":"query","schema":{"type":"string"},"example":"TRX-2026-000123"},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"before","in":"query","schema":{"type":"integer"},"description":"Cursor: pass `nextBefore` from the previous page"}],"responses":{"200":{"description":"Page of payouts","content":{"application/json":{"example":{"items":[{"id":"po_Q8x1Lr5vNw","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","status":"successful","holdReason":null,"recipient":{"tag":"moussa","displayName":"Moussa T."},"amount":65000,"fee":525,"totalDebited":65525,"currency":"XOF","sender":{"name":"Aminata Diallo","country":"FR"},"purpose":"family_support","message":"Pour la rentrée scolaire","environment":"live","thanks":null,"createdAt":"2026-11-18T10:02:11.000Z","updatedAt":"2026-11-18T10:02:11.000Z"}],"nextBefore":1763460131000}}}}}}},"/payouts/{id}":{"get":{"operationId":"getPayout","tags":["Payouts"],"summary":"Get a payout","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Payout `id` or Tagali `reference`","example":"po_Q8x1Lr5vNw"}],"responses":{"200":{"description":"Payout","content":{"application/json":{"example":{"payout":{"id":"po_Q8x1Lr5vNw","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","status":"successful","holdReason":null,"recipient":{"tag":"moussa","displayName":"Moussa T."},"amount":65000,"fee":525,"totalDebited":65525,"currency":"XOF","sender":{"name":"Aminata Diallo","country":"FR"},"purpose":"family_support","message":"Pour la rentrée scolaire","environment":"live","thanks":null,"createdAt":"2026-11-18T10:02:11.000Z","updatedAt":"2026-11-18T10:02:11.000Z"}}}}},"404":{"description":"`PAYOUT_NOT_FOUND`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PAYOUT_NOT_FOUND","message":"Unknown payout id or reference."}}}}}}}},"/payouts/{id}/cancel":{"post":{"operationId":"cancelPayout","tags":["Payouts"],"summary":"Cancel a held payout","description":"Only `pending_review` payouts can be cancelled; the reserved total returns to your balance. Successful payouts are final.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Payout `id` or Tagali `reference`","example":"po_Q8x1Lr5vNw"}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"example":{"payout":{"id":"po_Q8x1Lr5vNw","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","status":"cancelled","holdReason":"AMOUNT_REVIEW","recipient":{"tag":"moussa","displayName":"Moussa T."},"amount":65000,"fee":525,"totalDebited":65525,"currency":"XOF","sender":{"name":"Aminata Diallo","country":"FR"},"purpose":"family_support","message":"Pour la rentrée scolaire","environment":"live","thanks":null,"createdAt":"2026-11-18T10:02:11.000Z","updatedAt":"2026-11-18T10:02:11.000Z"}}}}},"404":{"description":"`PAYOUT_NOT_FOUND`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PAYOUT_NOT_FOUND","message":"Unknown payout id or reference."}}}}},"409":{"description":"`NOT_CANCELLABLE`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_CANCELLABLE","message":"Only payouts in pending_review can be cancelled."}}}}}}}},"/balance":{"get":{"operationId":"getBalance","tags":["Account"],"summary":"Get your balance","description":"Available prefunded balance and the amount reserved for payouts under review.","responses":{"200":{"description":"Balance","content":{"application/json":{"example":{"currency":"XOF","environment":"live","available":4850000,"heldForReview":1200000}}}}}}},"/statement":{"get":{"operationId":"getStatement","tags":["Account"],"summary":"Get a statement","description":"Every movement on your balance with a running balance. Defaults to the last 30 days.","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"example":"2026-11-01T00:00:00Z"},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"example":"2026-11-18T23:59:59Z"}],"responses":{"200":{"description":"Statement","content":{"application/json":{"example":{"currency":"XOF","from":"2026-11-01T00:00:00.000Z","to":"2026-11-18T23:59:59.000Z","openingBalance":3000000,"closingBalance":2934475,"lines":[{"at":"2026-11-18T10:02:11.000Z","amount":-65525,"balance":2934475,"type":"payout","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","bankReference":null}]}}}}}}},"/sandbox/top-up":{"post":{"operationId":"sandboxTopUp","tags":["Sandbox"],"summary":"Add test money","description":"Adds simulated XOF to your sandbox balance. Live balances are funded by bank transfer only.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","minimum":1,"maximum":100000000,"default":10000000}}},"example":{"amount":10000000}}}},"responses":{"200":{"description":"New balance","content":{"application/json":{"example":{"currency":"XOF","available":60000000}}}},"403":{"description":"`SANDBOX_ONLY`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"SANDBOX_ONLY","message":"Simulation endpoints only accept test keys."}}}}}}}},"/sandbox/payouts/{id}/approve":{"post":{"operationId":"sandboxApprove","tags":["Sandbox"],"summary":"Approve a held payout","description":"Plays the role of Tagali compliance. Sends `payout.completed`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Payout `id` or Tagali `reference`","example":"po_Q8x1Lr5vNw"}],"responses":{"200":{"description":"Approved","content":{"application/json":{"example":{"payout":{"id":"po_Q8x1Lr5vNw","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","status":"successful","holdReason":null,"recipient":{"tag":"moussa","displayName":"Moussa T."},"amount":65000,"fee":525,"totalDebited":65525,"currency":"XOF","sender":{"name":"Aminata Diallo","country":"FR"},"purpose":"family_support","message":"Pour la rentrée scolaire","environment":"live","thanks":null,"createdAt":"2026-11-18T10:02:11.000Z","updatedAt":"2026-11-18T10:02:11.000Z"}}}}},"403":{"description":"`SANDBOX_ONLY`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"SANDBOX_ONLY","message":"Simulation endpoints only accept test keys."}}}}},"404":{"description":"`PAYOUT_NOT_FOUND`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PAYOUT_NOT_FOUND","message":"Unknown payout id or reference."}}}}}}}},"/sandbox/payouts/{id}/reject":{"post":{"operationId":"sandboxReject","tags":["Sandbox"],"summary":"Reject a held payout","description":"Refunds the total to your sandbox balance and sends `payout.rejected`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Payout `id` or Tagali `reference`","example":"po_Q8x1Lr5vNw"}],"responses":{"200":{"description":"Rejected","content":{"application/json":{"example":{"payout":{"id":"po_Q8x1Lr5vNw","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","status":"rejected","holdReason":null,"recipient":{"tag":"moussa","displayName":"Moussa T."},"amount":65000,"fee":525,"totalDebited":65525,"currency":"XOF","sender":{"name":"Aminata Diallo","country":"FR"},"purpose":"family_support","message":"Pour la rentrée scolaire","environment":"live","thanks":null,"createdAt":"2026-11-18T10:02:11.000Z","updatedAt":"2026-11-18T10:02:11.000Z"}}}}},"403":{"description":"`SANDBOX_ONLY`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"SANDBOX_ONLY","message":"Simulation endpoints only accept test keys."}}}}},"404":{"description":"`PAYOUT_NOT_FOUND`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PAYOUT_NOT_FOUND","message":"Unknown payout id or reference."}}}}}}}},"/sandbox/payouts/{id}/thank":{"post":{"operationId":"sandboxThank","tags":["Sandbox"],"summary":"Simulate a thank-you","description":"Plays the recipient sending a thank-you message. Sends `payout.thanked`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Payout `id` or Tagali `reference`","example":"po_Q8x1Lr5vNw"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","maxLength":140}}},"example":{"message":"Jërëjëf, merci beaucoup !"}}}},"responses":{"200":{"description":"Thanked","content":{"application/json":{"example":{"payout":{"id":"po_Q8x1Lr5vNw","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","status":"successful","holdReason":null,"recipient":{"tag":"moussa","displayName":"Moussa T."},"amount":65000,"fee":525,"totalDebited":65525,"currency":"XOF","sender":{"name":"Aminata Diallo","country":"FR"},"purpose":"family_support","message":"Pour la rentrée scolaire","environment":"live","thanks":{"message":"Jërëjëf, merci beaucoup !","at":"2026-11-18T10:05:00.000Z"},"createdAt":"2026-11-18T10:02:11.000Z","updatedAt":"2026-11-18T10:02:11.000Z"}}}}},"403":{"description":"`SANDBOX_ONLY`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"SANDBOX_ONLY","message":"Simulation endpoints only accept test keys."}}}}},"404":{"description":"`PAYOUT_NOT_FOUND`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PAYOUT_NOT_FOUND","message":"Unknown payout id or reference."}}}}}}}}},"webhooks":{"payout.completed":{"post":{"summary":"payout.completed","requestBody":{"content":{"application/json":{"example":{"id":"evt_2m…","type":"payout.completed","createdAt":"2026-11-18T10:02:12.000Z","data":{"id":"po_Q8x1Lr5vNw","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","status":"successful","holdReason":null,"recipient":{"tag":"moussa","displayName":"Moussa T."},"amount":65000,"fee":525,"totalDebited":65525,"currency":"XOF","sender":{"name":"Aminata Diallo","country":"FR"},"purpose":"family_support","message":"Pour la rentrée scolaire","environment":"live","thanks":null,"createdAt":"2026-11-18T10:02:11.000Z","updatedAt":"2026-11-18T10:02:11.000Z"}}}}},"responses":{"200":{"description":"Acknowledge with any 2xx"}}}},"payout.held":{"post":{"summary":"payout.held","requestBody":{"content":{"application/json":{"example":{"id":"evt_2m…","type":"payout.held","createdAt":"2026-11-18T10:02:12.000Z","data":{"id":"po_Q8x1Lr5vNw","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","status":"successful","holdReason":null,"recipient":{"tag":"moussa","displayName":"Moussa T."},"amount":65000,"fee":525,"totalDebited":65525,"currency":"XOF","sender":{"name":"Aminata Diallo","country":"FR"},"purpose":"family_support","message":"Pour la rentrée scolaire","environment":"live","thanks":null,"createdAt":"2026-11-18T10:02:11.000Z","updatedAt":"2026-11-18T10:02:11.000Z"}}}}},"responses":{"200":{"description":"Acknowledge with any 2xx"}}}},"payout.rejected":{"post":{"summary":"payout.rejected","requestBody":{"content":{"application/json":{"example":{"id":"evt_2m…","type":"payout.rejected","createdAt":"2026-11-18T10:02:12.000Z","data":{"id":"po_Q8x1Lr5vNw","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","status":"successful","holdReason":null,"recipient":{"tag":"moussa","displayName":"Moussa T."},"amount":65000,"fee":525,"totalDebited":65525,"currency":"XOF","sender":{"name":"Aminata Diallo","country":"FR"},"purpose":"family_support","message":"Pour la rentrée scolaire","environment":"live","thanks":null,"createdAt":"2026-11-18T10:02:11.000Z","updatedAt":"2026-11-18T10:02:11.000Z"}}}}},"responses":{"200":{"description":"Acknowledge with any 2xx"}}}},"payout.cancelled":{"post":{"summary":"payout.cancelled","requestBody":{"content":{"application/json":{"example":{"id":"evt_2m…","type":"payout.cancelled","createdAt":"2026-11-18T10:02:12.000Z","data":{"id":"po_Q8x1Lr5vNw","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","status":"successful","holdReason":null,"recipient":{"tag":"moussa","displayName":"Moussa T."},"amount":65000,"fee":525,"totalDebited":65525,"currency":"XOF","sender":{"name":"Aminata Diallo","country":"FR"},"purpose":"family_support","message":"Pour la rentrée scolaire","environment":"live","thanks":null,"createdAt":"2026-11-18T10:02:11.000Z","updatedAt":"2026-11-18T10:02:11.000Z"}}}}},"responses":{"200":{"description":"Acknowledge with any 2xx"}}}},"payout.thanked":{"post":{"summary":"payout.thanked","requestBody":{"content":{"application/json":{"example":{"id":"evt_2m…","type":"payout.thanked","createdAt":"2026-11-18T10:02:12.000Z","data":{"id":"po_Q8x1Lr5vNw","reference":"RMT-20261118-9F2A11C0","partnerReference":"TRX-2026-000123","status":"successful","holdReason":null,"recipient":{"tag":"moussa","displayName":"Moussa T."},"amount":65000,"fee":525,"totalDebited":65525,"currency":"XOF","sender":{"name":"Aminata Diallo","country":"FR"},"purpose":"family_support","message":"Pour la rentrée scolaire","environment":"live","thanks":null,"createdAt":"2026-11-18T10:02:11.000Z","updatedAt":"2026-11-18T10:02:11.000Z"}}}}},"responses":{"200":{"description":"Acknowledge with any 2xx"}}}},"webhook.test":{"post":{"summary":"webhook.test","requestBody":{"content":{"application/json":{"example":{"id":"evt_2m…","type":"webhook.test","createdAt":"2026-11-18T10:02:12.000Z","data":{"message":"Test event"}}}}},"responses":{"200":{"description":"Acknowledge with any 2xx"}}}}},"x-tagali":{"errors":[{"status":400,"code":"INVALID_FIELD","description":"A field is missing or malformed. `error.field` names it."},{"status":400,"code":"INVALID_AMOUNT","description":"Amount is not a whole number of XOF within limits."},{"status":400,"code":"INVALID_TAG","description":"The tag is not a valid Tagali tag."},{"status":400,"code":"IDEMPOTENCY_KEY_REQUIRED","description":"`POST /payouts` needs an `Idempotency-Key` header (16–64 letters, digits, - or _)."},{"status":401,"code":"UNAUTHORIZED","description":"Key unknown or revoked, bad signature, stale timestamp or reused nonce."},{"status":402,"code":"INSUFFICIENT_PREFUNDING","description":"Your prefunded balance cannot cover the payout total. Fund your account."},{"status":403,"code":"IP_NOT_ALLOWED","description":"The request came from an IP address outside your allow-list."},{"status":403,"code":"PARTNER_SUSPENDED","description":"Your account is suspended. Contact partner support."},{"status":403,"code":"SANDBOX_ONLY","description":"Simulation endpoints only accept test keys."},{"status":404,"code":"RECIPIENT_NOT_FOUND","description":"No Tagali customer uses this tag."},{"status":404,"code":"LOOKUP_NOT_FOUND","description":"Unknown `lookupId`."},{"status":404,"code":"QUOTE_NOT_FOUND","description":"Unknown `quoteId`."},{"status":404,"code":"PAYOUT_NOT_FOUND","description":"Unknown payout id or reference."},{"status":409,"code":"RECIPIENT_CHANGED","description":"The person behind the tag changed after your lookup. Look up again and re-confirm with your sender. No money moved."},{"status":409,"code":"DUPLICATE_REFERENCE","description":"`partnerReference` was already used for another payout."},{"status":409,"code":"IDEMPOTENCY_CONFLICT","description":"Same `Idempotency-Key` with a different body."},{"status":409,"code":"QUOTE_USED","description":"This quote already produced a payout."},{"status":409,"code":"NOT_CANCELLABLE","description":"Only payouts in `pending_review` can be cancelled."},{"status":410,"code":"LOOKUP_EXPIRED","description":"The lookup is older than 30 minutes."},{"status":410,"code":"QUOTE_EXPIRED","description":"The quote is older than 15 minutes."},{"status":422,"code":"RECIPIENT_UNAVAILABLE","description":"The tag exists but cannot receive payments right now."},{"status":429,"code":"RATE_LIMITED","description":"Too many requests. Wait for `Retry-After` seconds."}],"sandboxRecipients":[{"tag":"test.moussa","name":"Moussa Traoré","behaviour":"Verified customer in Dakar. Payouts succeed."},{"tag":"test.fatou","name":"Fatou Ndiaye","behaviour":"Verified customer in Thiès. Payouts succeed."},{"tag":"test.koffi","name":"Koffi Kouassi","behaviour":"Verified customer in Abidjan. Payouts succeed."},{"tag":"test.awa","name":"Awa Diop","behaviour":"Identity not verified: payouts above 200 000 XOF are held (RECIPIENT_KYC)."},{"tag":"test.review","name":"Aya Koné","behaviour":"Every payout is held for review. Use the simulate endpoints to approve or reject."},{"tag":"test.changed","name":"Ibrahima Sow","behaviour":"The tag changes hands after lookup: payouts fail with RECIPIENT_CHANGED."},{"tag":"test.closed","name":null,"behaviour":"Restricted tag: lookups fail with RECIPIENT_UNAVAILABLE."}],"purposes":["family_support","education","medical","housing","business","gift","savings","other"]},"components":{"securitySchemes":{"TagaliKey":{"type":"apiKey","in":"header","name":"X-Tagali-Key","description":"Your key id: pk_test_… or pk_live_…"},"TagaliTimestamp":{"type":"apiKey","in":"header","name":"X-Tagali-Timestamp","description":"Unix seconds, within 5 minutes of our clock"},"TagaliNonce":{"type":"apiKey","in":"header","name":"X-Tagali-Nonce","description":"16–64 random characters, never reused"},"TagaliSignature":{"type":"apiKey","in":"header","name":"X-Tagali-Signature","description":"v1=hex(HMAC_SHA256(secret, \"{ts}.{nonce}.{METHOD}.{path?query}.{sha256_hex(body)}\"))"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine code"},"message":{"type":"string","description":"Human message; may change"},"field":{"type":"string","description":"Offending field, when relevant"}}}}},"Lookup":{"type":"object","properties":{"lookupId":{"type":"string","description":"Pass to POST /quotes"},"tag":{"type":"string"},"displayName":{"type":"string","description":"First name and initial, e.g. \"Moussa T.\""},"canReceive":{"type":"boolean"},"currency":{"const":"XOF"},"nameMatch":{"type":["string","null"],"enum":["exact","strong","partial","none",null],"description":"Present when you pass `name`"},"expiresAt":{"type":"string","format":"date-time"}}},"Quote":{"type":"object","properties":{"quoteId":{"type":"string"},"currency":{"const":"XOF"},"amount":{"type":"integer"},"recipientReceives":{"type":"integer","description":"Always equals amount"},"recipientFee":{"const":0},"partnerFee":{"type":"integer","description":"Your fee in XOF"},"totalDebited":{"type":"integer","description":"amount + partnerFee"},"expiresAt":{"type":"string","format":"date-time"}}},"PayoutRequest":{"type":"object","required":["quoteId","partnerReference","sender","purpose"],"properties":{"quoteId":{"type":"string"},"partnerReference":{"type":"string","maxLength":64,"description":"Your unique transfer id"},"sender":{"type":"object","required":["fullName","country"],"description":"The person who paid you. Used for screening; never shown in full to the recipient.","properties":{"fullName":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"address":{"type":"string"},"dateOfBirth":{"type":"string","format":"date"},"idType":{"type":"string"},"idNumber":{"type":"string"},"phone":{"type":"string"}}},"purpose":{"type":"string","enum":["family_support","education","medical","housing","business","gift","savings","other"]},"message":{"type":"string","maxLength":140,"description":"Shown to the recipient"}}},"Payout":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string","description":"Tagali reference. TST-… in the sandbox"},"partnerReference":{"type":"string"},"status":{"type":"string","enum":["successful","pending_review","rejected","cancelled"]},"holdReason":{"type":["string","null"],"description":"Comma-separated: AMOUNT_REVIEW, RECIPIENT_KYC, SANCTIONS_SCREENING"},"recipient":{"type":"object","properties":{"tag":{"type":"string"},"displayName":{"type":"string"}}},"amount":{"type":"integer"},"fee":{"type":"integer"},"totalDebited":{"type":"integer"},"currency":{"const":"XOF"},"sender":{"type":"object","properties":{"name":{"type":"string"},"country":{"type":"string"}}},"purpose":{"type":"string"},"message":{"type":"string"},"environment":{"type":"string","enum":["sandbox","live"]},"thanks":{"type":["object","null"],"description":"Set when the recipient sends a thank-you, which you can pass to your sender","properties":{"message":{"type":"string"},"at":{"type":"string"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}