Motion 5Book a demo

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. 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. 2

    Motion 5 logs it

    The customer gets a reference like DSP-7KQ3M9XA, and you get dispute.created. Reporting the same payment again gives them the same reference instead of a second dispute.

  3. 3

    You look into it

    Set status: "investigating". The customer is told you're on it. Send updates with a message whenever you have news.

  4. 4

    You close it

    Set resolved or rejected with a message saying what happened. The customer gets it on WhatsApp with the reference. A closed dispute can't change.

Statuses

open
Just reported. Nobody has picked it up yet.
investigating
Your team is on it.
resolved
Closed in the customer's favour, or explained to their satisfaction.
rejected
Closed without a change: the payment was right.

Telling the customer

Every update with a message goes to the customer on WhatsApp, which only allows it within 24 hours of their last message. Outside that window the update is still saved, and the response says notification.sent: false with reason: "window_closed"; tell them through another channel or when they next write.
GET/v1/disputes
Disputes, newest first. Needs a live key: disputes are real customers, so test keys get 403 live_key_required.

Query

status
stringoptional
open (default: open and investigating), closed (resolved and rejected), all, or one status.
limit
integeroptional
1 to 200. Default 50.
Response
{
  "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
    }
  ]
}
GET/v1/disputes/{id}
One dispute, by its ID (dsp_…) or by the reference the customer quotes (DSP-…), so your contact centre can look one up from a call.
Response
{
  "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
}
POST/v1/disputes/{id}
Move a dispute on, tell the customer, or both. Use an Idempotency-Key so a retry never messages the customer twice.

Body

status
stringoptional
investigating, resolved or rejected. Leave it out to send an update without changing the status.
message
stringoptional
What the customer reads on WhatsApp, up to 1,000 characters. Needed to resolve or reject. Setting investigating without one sends a short holding message.
agent
objectoptional
{ 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:

WhatsApp
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:

Response
{
  "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_status
status isn't investigating, resolved or rejected (a dispute can't go back to open).
422 message_required
Resolving or rejecting without a message.
422 nothing_to_update
Neither a status nor a message.
409 dispute_closed
The dispute is already resolved or rejected.
409 no_change
It already has that status, and there's no message.
404 not_found
No dispute with that ID or reference at your bank.

The dispute object

id
string
Starts with dsp_.
reference
string
What the customer quotes: DSP- and 8 letters and digits, without 0, O, 1, I, L or U so it reads clearly over the phone.
reason
string
unauthorised (didn't make it), failed_debited, not_received, wrong_amount, duplicate or other.
note
string or null
The customer's own words, for other.
customer
object
id is the conversation ID, so you can open the chat. Also name, phone and wa_id.
account
object
reference is your core banking system's ID for the account; number is masked.
transaction
object
The payment as your system reported it when the customer chose it: reference, date, amount in kobo (negative for money out), currency and narration.
resolution
string or null
The last message you sent the customer about it.
created_at, updated_at, resolved_at
time
resolved_at is set when it's resolved or rejected.

Card 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.frozen data
{
  "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.created
A customer reported a payment. data.dispute is the new dispute.
dispute.updated
The status changed or an update was sent, from the Disputes page or the API. Order by data.dispute.updated_at.
card.frozen
A customer froze a card.
card.unfrozen
A customer unfroze a card, after their PIN.

See Webhooks to set up an endpoint and check signatures.