Disputes on a workspace deal

A dispute freezes one milestone while RekberPay arbitration looks at what happened. Either company on a deal can open one. This guide covers workspace deals. Disputes on consumer escrows work differently and are in Handling disputes.

When you can dispute

A milestone can be disputed while it is funded, evidence_submitted or approved. That means money is held and has not been released yet.

Milestone status	Can dispute?
`draft`, `awaiting_funding`	No. Edit or cancel the deal instead
`funded`, `evidence_submitted`, `approved`	Yes
`revision_requested`	No. Deliver the milestone again, or ask the other side to
`released`, `cancelled`	No. The money has moved or the milestone is closed

Opening a dispute on any other status answers 409 INVALID_STATE.

1. Open the dispute

You need the operator role or above in your workspace.

As the payer, in the dashboard

Open the deal and choose Open dispute in the header, or use the milestone row.
In Open a dispute, pick the milestone.
Under What went wrong, write 10 to 700 characters. Be specific: what was agreed, what happened, dates and quantities. For example "the goods arrived damaged and the inspection report shows 40 units short".
Under Files for RekberPay, tick documents that are already on the deal, up to 10, or choose Upload a file to add new ones. Files can be PDF, JPG, PNG or WebP, up to 10 MB each. An uploaded file is saved to the deal's Documents as type dispute, linked to the milestone.
Choose Open dispute.

As the partner, in the dashboard

Open Shared deals, open the deal and choose Dispute on the milestone.
Fill in What went wrong (10 to 700 characters) and choose Open dispute. This form takes text only. RekberPay contacts both sides if it needs files or more detail.

With the API

bash

# The payer
curl -X POST https://api.rekberpay.com/v1/enterprise/deals/$DEAL_ID/milestones/$MILESTONE_ID/dispute \
  -H "Authorization: Bearer $REKBERPAY_WORKSPACE_KEY" \
  -H "Idempotency-Key: $(uuidgen | tr 'A-Z' 'a-z')" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Supplier has not sent the inspection report after two requests.",
    "document_ids": ["'"$DOCUMENT_ID"'"]
  }'

# The linked partner
curl -X POST https://api.rekberpay.com/v1/enterprise/shared-deals/$DEAL_ID/milestones/$MILESTONE_ID/dispute \
  -H "Authorization: Bearer $REKBERPAY_WORKSPACE_KEY" \
  -H "Idempotency-Key: $(uuidgen | tr 'A-Z' 'a-z')" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Delivery was completed on 12 October and the payer has not reviewed it." }'

200 OK

json

{
    "success": true,
    "data": {
        "milestone_id": "11111115-1111-4111-8111-111111111111",
        "status": "disputed",
        "deal_status": "disputed"
    }
}

document_ids is optional: up to 10 documents of your workspace that belong to this deal or to no deal yet, and are not marked for RekberPay only. They are linked to the milestone. An unknown or wrong document answers 400 INVALID_DOCUMENTS. The partner's request takes reason only.

A partner cannot dispute a live deal from Sandbox (409 SANDBOX_WORKSPACE): it switches to Live first. A closed deal is read only (409 DEAL_ARCHIVED).

2. What happens when it opens

The milestone and the deal become disputed. The money stays held. Nothing can be approved or released on that milestone.
The evidence on the milestone is locked. It cannot be deleted while the dispute is open.
The paying workspace's team is notified, whichever side opened the dispute.
The dispute appears in RekberPay's arbitration queue. RekberPay reviews it and contacts both sides.
A partner on a linked deal sees the milestone as disputed, and its history shows "Dispute opened on #n".
A dispute.opened event is written to the paying workspace's activity feed and sent to its webhooks.

The milestone row shows In arbitration with a countdown to the dispute SLA, for example "1d 22h left", or "SLA passed 2d 2h ago". The SLA is the Dispute SLA (hours) in Settings, Approval policy. The default is 24 hours and an admin can set 1 to 168. A dispute past its SLA raises an alert in the paying workspace's overview.

3. Give RekberPay the evidence

A workspace dispute has no chat thread. You give your side in these ways, when you open the dispute and while it is open:

The reason. Everything RekberPay needs to start goes in the 10 to 700 characters of the reason. Write it as if the reader has never seen the deal.
Files when you open it. Pick documents already on the deal or upload new ones in the same dialog, as in step 1 above.
More evidence later. While the milestone is In arbitration, an operator or above chooses Add evidence on its row. In Add evidence to the dispute, write What the files show (3 to 700 characters), add files the same way and choose Send to RekberPay. The deal history records "Dispute evidence added" and RekberPay sees it at once. You can do this as often as you need until RekberPay decides. The milestone stays held.
Documents on the milestone. Add contracts, delivery notes, inspection reports and photos to the deal, linked to the milestone, before you open the dispute. Under Documents, or POST /v1/enterprise/documents with deal_id, milestone_id and a file uploaded from your workspace. See the documents reference.
A note shared with RekberPay. On the deal, add a note and tick Share with RekberPay ops. Use this for context that is not a document, such as a summary of a call. With the API, POST /v1/enterprise/deals/:id/notes with "visibility": "rekberpay". Notes without that option stay inside your workspace.
Answer when RekberPay contacts you. Arbitration may ask either side for more.

With the API, add evidence to an open dispute as the payer:

bash

curl -X POST https://api.rekberpay.com/v1/enterprise/deals/$DEAL_ID/milestones/$MILESTONE_ID/dispute-evidence \
  -H "Authorization: Bearer $REKBERPAY_WORKSPACE_KEY" \
  -H "Idempotency-Key: $(uuidgen | tr 'A-Z' 'a-z')" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "The inspection report from 14 October shows 40 units short of the purchase order.",
    "document_ids": ["'"$DOCUMENT_ID"'"]
  }'

note is 3 to 700 characters and document_ids takes up to 10 documents, as when you open a dispute. The answer is 200 OK with the milestone id and the document ids. A milestone that is not disputed any more answers 409 NOT_DISPUTED ("Evidence can only be added while the dispute is open."). Adding evidence is a payer action. The linked partner has no equivalent call and sends further material when RekberPay asks for it. Field details are in the deals reference.

As the payer you can share a document with your partner by choosing Your workspace and the counterparty when you add it ("visibility": "counterparty"). The partner then sees it on the shared deal.

4. The outcomes

Only RekberPay staff decide a dispute. They choose one of three outcomes and write a note.

Outcome	What it does to the milestone	The money
Funded	Back to `funded`. The work carries on	Still held. The counterparty can deliver the milestone again and the normal approval and release follow
Released	`released`	The counterparty is paid the milestone amount minus its fee share, to a verified payout instruction of the payer for that counterparty. A payout is queued and settled like any other. See Approve, release and settle. A live release also needs the counterparty to have completed business verification, or it is refused and the dispute stays open
Cancelled	`cancelled`	Nothing is paid to the counterparty for that milestone. The payer is refunded the milestone amount plus the fee share it funded. See Refunds when a dispute cancels a milestone

After the decision:

The deal's status is recalculated from its milestones. A deal whose other milestones are all released becomes completed.
The paying workspace is notified with the outcome and the note. The email carries the outcome only. The note stays in the dashboard.
The partner sees "Dispute on #n resolved by RekberPay" in its history. A dispute.resolved event is written to the paying workspace's activity feed and sent to its webhooks.

On a Sandbox (test) deal RekberPay can choose any of the three outcomes too, so you can see the whole flow before going live. A Released outcome is a simulation: the milestone and the deal move exactly as on a live release, the payout to a verified Sandbox payout instruction settles at once as test data, and no real money moves. No bank, gateway or payout queue is involved, and no second RekberPay approver is needed. The events carry livemode: false, and the notices go to workspace members only, tagged [Sandbox] (a linked partner sees them in the dashboard, not by email). A Cancelled outcome marks the test money refunded.

For a Cancelled milestone the payer's refund is created in the same step. The notice tells the payer the amount, the milestone then shows Refund queued, and the deal reads Refund pending until RekberPay has sent the money by bank transfer to the bank account on the payer's approved business verification. RekberPay operations process it and the payer is notified when it is sent. The statuses and the notices are in Refunds when a dispute cancels a milestone. If you are the payer and need more, ask your account manager or write to RekberPay support.

When a large decision needs a second RekberPay approver

For a large amount, a Released or Cancelled decision is not applied by one person. RekberPay's own rules ask a second approver to confirm it first. The limit is a platform setting, and the amount that counts is the milestone for a release, or the milestone plus the payer's fee share for a cancellation. A decision of Funded moves no money and never waits.

Your workspace sees nothing of this step:

The milestone still reads In arbitration. The dispute SLA countdown keeps running.
No notice is sent and no refund or payout exists yet. The money stays held.
When the second approver confirms, the decision is applied and the usual notices go out. If they refuse it, or the request lapses, the dispute stays open and RekberPay decides again.

This can add some time to a large dispute, beyond the SLA you see on the row. The SLA is shown to help you plan, and a dispute past it is raised to RekberPay's team. A refund is created only when the decision is applied.

What you cannot do

Cancel a deal that has a funded milestone. Open a dispute on the milestone instead.
Decide your own dispute. In a workspace only RekberPay resolves one.
Dispute a released milestone.

Next steps

Approve, release and settle
Polling events to follow dispute.opened and dispute.resolved
Deals and milestones reference

Disputes on a workspace deal ​

When you can dispute ​

1. Open the dispute ​

2. What happens when it opens ​

3. Give RekberPay the evidence ​

4. The outcomes ​

When a large decision needs a second RekberPay approver ​

What you cannot do ​

Next steps ​