Products
Cards and disputes
Customers freeze a lost card and report a wrong payment in WhatsApp, without calling you. You work disputes on the Disputes page in Motion 5, or in your own system with this API and webhooks.
What customers can do
- Freeze a card from My cards. It happens at once, without the PIN, because freezing only ever protects the customer. Unfreezing needs their PIN. Motion 5 asks your core banking system to do both; we never see more than the last four digits.
- Report a transaction: a payment they didn't make, one that failed but debited them, one that never arrived, the wrong amount, a double charge, or something else. After a payment they didn't make, they're offered to freeze a card straight away.
Both are in the WhatsApp menu, and customers can also type things like "I lost my card" or "I was debited twice".
A dispute, step by step
- 1
The customer reports a payment
They tap Report a transaction and enter their PIN. They pick a payment from the last 90 days (older ones go to a person), then what went wrong. Something else asks for a short note.
- 2
Motion 5 logs it
The customer gets a reference like
DSP-7KQ3M9XA, and you getdispute.created. Reporting the same payment again gives them the same reference instead of a second dispute. - 3
You look into it
Set
status: "investigating". The customer is told you're on it. Send updates with amessagewhenever you have news. - 4
You close it
Set
resolvedorrejectedwith a message saying what happened. The customer gets it on WhatsApp with the reference. A closed dispute can't change.
Statuses
openinvestigatingresolvedrejectedTelling the customer
notification.sent: false with reason: "window_closed"; tell them through another channel or when they next write./v1/disputes403 live_key_required.Query
statusopen (default: open and investigating), closed (resolved and rejected), all, or one status.limit{
"object": "list",
"data": [
{
"object": "dispute",
"id": "dsp_01JD4A7C2M9Q3R5T8V1W4X6Y0Z",
"reference": "DSP-7KQ3M9XA",
"status": "open",
"reason": "failed_debited",
"note": null,
"customer": {
"id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"name": "Ada Okon",
"phone": "+2348031234567",
"wa_id": "2348031234567"
},
"account": {
"reference": "ACC-0012345678",
"number": "••••5678"
},
"transaction": {
"reference": "FT26314AB12C",
"date": "2026-11-14T10:42:00.000Z",
"amount": -250000,
"currency": "NGN",
"narration": "Transfer to Tunde A."
},
"resolution": null,
"created_at": "2026-11-16T09:12:44.207Z",
"updated_at": "2026-11-16T09:12:44.207Z",
"resolved_at": null
}
]
}/v1/disputes/{id}dsp_…) or by the reference the customer quotes (DSP-…), so your contact centre can look one up from a call.{
"object": "dispute",
"id": "dsp_01JD4A7C2M9Q3R5T8V1W4X6Y0Z",
"reference": "DSP-7KQ3M9XA",
"status": "open",
"reason": "failed_debited",
"note": null,
"customer": {
"id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"name": "Ada Okon",
"phone": "+2348031234567",
"wa_id": "2348031234567"
},
"account": {
"reference": "ACC-0012345678",
"number": "••••5678"
},
"transaction": {
"reference": "FT26314AB12C",
"date": "2026-11-14T10:42:00.000Z",
"amount": -250000,
"currency": "NGN",
"narration": "Transfer to Tunde A."
},
"resolution": null,
"created_at": "2026-11-16T09:12:44.207Z",
"updated_at": "2026-11-16T09:12:44.207Z",
"resolved_at": null
}/v1/disputes/{id}Body
statusinvestigating, resolved or rejected. Leave it out to send an update without changing the status.messageagent{ id, name } of the person updating it, as in the helpdesk API. Shown in the Motion 5 inbox; the customer sees the bank's name.curl https://motion5.dev/v1/disputes/DSP-7KQ3M9XA \
-H "Authorization: Bearer $MOTION5_LIVE_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "status": "resolved", "message": "Your ₦2,500 has been reversed. It shows on your account within 24 hours." }'The customer reads:
Update on your complaint *DSP-7KQ3M9XA* (−₦2,500.00 on 14 Nov):
Your ₦2,500 has been reversed. It shows on your account within 24 hours.
Status: resolved ✅Returns the dispute, with whether the customer was told:
{
"object": "dispute",
"id": "dsp_01JD4A7C2M9Q3R5T8V1W4X6Y0Z",
"reference": "DSP-7KQ3M9XA",
"status": "resolved",
"reason": "failed_debited",
"note": null,
"customer": {
"id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"name": "Ada Okon",
"phone": "+2348031234567",
"wa_id": "2348031234567"
},
"account": {
"reference": "ACC-0012345678",
"number": "••••5678"
},
"transaction": {
"reference": "FT26314AB12C",
"date": "2026-11-14T10:42:00.000Z",
"amount": -250000,
"currency": "NGN",
"narration": "Transfer to Tunde A."
},
"resolution": "Your ₦2,500 has been reversed. It shows on your account within 24 hours.",
"created_at": "2026-11-16T09:12:44.207Z",
"updated_at": "2026-11-16T15:03:10.551Z",
"resolved_at": "2026-11-16T15:03:10.551Z",
"notification": {
"sent": true,
"reason": null
}
}Errors
422 invalid_status422 message_required422 nothing_to_update409 dispute_closed409 no_change404 not_foundThe dispute object
iddsp_.referencestatusreasonunauthorised (didn't make it), failed_debited, not_received, wrong_amount, duplicate or other.noteother.customeraccountreference is your core banking system's ID for the account; number is masked.transactionreference, date, amount in kobo (negative for money out), currency and narration.resolutioncreated_at, updated_at, resolved_atCard freezes
There's no card API to call: customers freeze and unfreeze cards in WhatsApp, and Motion 5 asks your core banking system through your bank adapter. Subscribe to card.frozen and card.unfrozen to log them, alert your fraud team, or follow up about a replacement.
{
"card": {
"id": "card_8f31c2d0",
"brand": "Verve",
"last4": "4821",
"expires": "08/28",
"status": "frozen"
},
"account": {
"reference": "ACC-0012345678",
"number": "••••5678"
},
"customer": {
"id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"name": "Ada Okon",
"phone": "+2348031234567",
"wa_id": "2348031234567"
}
}Events
dispute.createddispute.updatedcard.frozencard.unfrozenSee Webhooks to set up an endpoint and check signatures.