Skip to content

Creating escrows ​

This walkthrough runs one escrow from start to finish with two users: Budi, who sells a camera, and Rina, who buys it. Each step shows the real request and the real answer from the run. Both call the API with their own personal API keys (see Authentication and API keys).

If you are a partner platform that signs links for your buyers, the Quickstart shows the signed-link variant, POST /v1/escrows/from-link. Everything after creation is the same.

The lifecycle ​

text
pending_payment --pay--> paid --send--> sent --confirm--> released
      |                   |               |
      |                   +---------------+--dispute--> disputed --> released / refunded / hold
      |                   +---------------+--cancel by agreement--> refunded
      +--cancel--> cancelled

A manual transfer (static QRIS or bank transfer) passes through pending_review while RekberPay checks the money. GET /v1/escrows/:id returns available_actions for the caller, so your app does not need to hard-code who may do what.

Before the first escrow, each account needs a confirmed email (403 EMAIL_NOT_VERIFIED otherwise) and a complete profile: a name, a WhatsApp number and accepted Terms (409 PROFILE_INCOMPLETE otherwise). Both are done once, at rekberpay.com. An account without KYC can only take part in escrows up to set limits.

1. Attach a photo (optional) ​

Upload files first and pass their URL. Here a photo of the item is uploaded:

bash
curl -X POST https://api.rekberpay.com/v1/upload/escrow \
  -H "Authorization: Bearer $REKBERPAY_API_KEY" \
  -F "[email protected];type=image/png"
js
import { readFile } from 'node:fs/promises';

const form = new FormData();
form.append('file', new Blob([await readFile('receipt.png')], { type: 'image/png' }), 'receipt.png');

const res = await fetch('https://api.rekberpay.com/v1/upload/escrow', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.REKBERPAY_API_KEY}`,
    },
    body: form,
});
const data = await res.json();
python
import os

import requests

resp = requests.post(
    "https://api.rekberpay.com/v1/upload/escrow",
    headers={
        "Authorization": f"Bearer {os.environ['REKBERPAY_API_KEY']}",
    },
    files={"file": ("receipt.png", open("receipt.png", "rb"), "image/png")},
    timeout=30,
)
print(resp.status_code, resp.json())
php
<?php

$ch = curl_init('https://api.rekberpay.com/v1/upload/escrow');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('REKBERPAY_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => ['file' => new CURLFile('receipt.png', 'image/png')],
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

200 OK

json
{
    "success": true,
    "filename": "1791901398283_862e8cf475cf7693efed4855a91995d0_7e10e097a2087a40e3e8e3b659df3f65.png",
    "url": "https://api.rekberpay.com/uploads/escrow/1791901398283_862e8cf475cf7693efed4855a91995d0_7e10e097a2087a40e3e8e3b659df3f65.png",
    "type": "escrow"
}

2. Create the escrow ​

Budi creates the escrow as the seller. The buyer seat stays open.

bash
curl -X POST https://api.rekberpay.com/v1/escrows \
  -H "Authorization: Bearer $REKBERPAY_API_KEY" \
  -H "Idempotency-Key: 22222220-2222-4222-8222-222222222222" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "seller",
    "item_name": "Kamera Fujifilm X-T30 bekas",
    "amount": 250000,
    "category": "goods",
    "description": "Body only, shutter count 8.000, lengkap dengan dus.",
    "attachment_url": "https://api.rekberpay.com/uploads/escrow/1791901398283_862e8cf475cf7693efed4855a91995d0_7e10e097a2087a40e3e8e3b659df3f65.png"
  }'
js
const res = await fetch('https://api.rekberpay.com/v1/escrows', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.REKBERPAY_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': '22222220-2222-4222-8222-222222222222',
    },
    body: JSON.stringify({
        role: "seller",
        item_name: "Kamera Fujifilm X-T30 bekas",
        amount: 250000,
        category: "goods",
        description: "Body only, shutter count 8.000, lengkap dengan dus.",
        attachment_url: "https://api.rekberpay.com/uploads/escrow/1791901398283_862e8cf475cf7693efed4855a91995d0_7e10e097a2087a40e3e8e3b659df3f65.png"
    }),
});
const data = await res.json();
python
import os

import requests

resp = requests.post(
    "https://api.rekberpay.com/v1/escrows",
    headers={
        "Authorization": f"Bearer {os.environ['REKBERPAY_API_KEY']}",
        "Idempotency-Key": "22222220-2222-4222-8222-222222222222",
    },
    json={
        "role": "seller",
        "item_name": "Kamera Fujifilm X-T30 bekas",
        "amount": 250000,
        "category": "goods",
        "description": "Body only, shutter count 8.000, lengkap dengan dus.",
        "attachment_url": "https://api.rekberpay.com/uploads/escrow/1791901398283_862e8cf475cf7693efed4855a91995d0_7e10e097a2087a40e3e8e3b659df3f65.png",
    },
    timeout=30,
)
print(resp.status_code, resp.json())
php
<?php

$ch = curl_init('https://api.rekberpay.com/v1/escrows');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('REKBERPAY_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: 22222220-2222-4222-8222-222222222222',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'role' => 'seller',
        'item_name' => 'Kamera Fujifilm X-T30 bekas',
        'amount' => 250000,
        'category' => 'goods',
        'description' => 'Body only, shutter count 8.000, lengkap dengan dus.',
        'attachment_url' => 'https://api.rekberpay.com/uploads/escrow/1791901398283_862e8cf475cf7693efed4855a91995d0_7e10e097a2087a40e3e8e3b659df3f65.png',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

201 Created

json
{
    "success": true,
    "data": {
        "id": "33333330-3333-4333-8333-333333333333",
        "buyer_id": null,
        "seller_id": "44444440-4444-4444-8444-444444444444",
        "item_name": "Kamera Fujifilm X-T30 bekas",
        "amount": "250000.00",
        "description": "Body only, shutter count 8.000, lengkap dengan dus.",
        "category": "goods",
        "status": "pending_payment",
        "counterparty_email": null,
        "counterparty_username": null,
        "source_url": null,
        "source_screenshot_url": null,
        "attachment_url": "https://api.rekberpay.com/uploads/escrow/1791901398283_862e8cf475cf7693efed4855a91995d0_7e10e097a2087a40e3e8e3b659df3f65.png?exp=1791979200000&sig=c0ffee5b1a9e3d7f4a2c8e6b0d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5",
        "deadline_at": null,
        "auto_release_at": null,
        "partner_ref": null,
        "partner_sig_version": null,
        "paid_at": null,
        "released_at": null,
        "refunded_at": null,
        "cancelled_at": null,
        "tracking_courier": null,
        "tracking_number": null,
        "tracking_status": null,
        "tracking_last_checked_at": null,
        "tracking_snapshot": null,
        "created_at": "2026-10-13T14:23:18.305Z",
        "updated_at": "2026-10-13T14:23:18.305Z",
        "join_code": "RBP-B91XXZY0"
    }
}

Send the other side the escrow link (https://rekberpay.com/escrow/<id>) or the join_code. Passing counterparty_email or counterparty_username also emails them an invite (never your own: that answers 400 SELF_COUNTERPARTY). Creating is limited to 20 escrows a minute per user.

3. The buyer looks and joins ​

Anyone with the link can read a small preview, signed in or not:

bash
curl https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/preview
js
const res = await fetch('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/preview', {
});
const data = await res.json();
python
import os

import requests

resp = requests.get(
    "https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/preview",
    timeout=30,
)
print(resp.status_code, resp.json())
php
<?php

$ch = curl_init('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/preview');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

200 OK

json
{
    "success": true,
    "data": {
        "id": "33333330-3333-4333-8333-333333333333",
        "item_name": "Kamera Fujifilm X-T30 bekas",
        "description": "Body only, shutter count 8.000, lengkap dengan dus.",
        "amount": "250000.00",
        "status": "pending_payment",
        "category": "goods",
        "has_buyer": false,
        "has_seller": true,
        "is_party": false,
        "buyer_full_name": null,
        "buyer_username": null,
        "buyer_email": null,
        "seller_full_name": null,
        "seller_username": "budi.santoso",
        "seller_email": null,
        "created_at": "2026-10-13T14:23:18.305Z"
    }
}

Rina takes the buyer seat. Joining works while the escrow is pending_payment, pending_review or paid. The buyer can also skip this call: paying an escrow with an empty buyer seat takes the seat first.

bash
curl -X POST https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/join \
  -H "Authorization: Bearer $REKBERPAY_API_KEY" \
  -H "Idempotency-Key: 55555550-5555-4555-8555-555555555555" \
  -H "Content-Type: application/json" \
  -d '{}'
js
const res = await fetch('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/join', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.REKBERPAY_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': '55555550-5555-4555-8555-555555555555',
    },
    body: JSON.stringify({}),
});
const data = await res.json();
python
import os

import requests

resp = requests.post(
    "https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/join",
    headers={
        "Authorization": f"Bearer {os.environ['REKBERPAY_API_KEY']}",
        "Idempotency-Key": "55555550-5555-4555-8555-555555555555",
    },
    json={},
    timeout=30,
)
print(resp.status_code, resp.json())
php
<?php

$ch = curl_init('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/join');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('REKBERPAY_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: 55555550-5555-4555-8555-555555555555',
    ],
    CURLOPT_POSTFIELDS => json_encode(new stdClass()),
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

200 OK

json
{
    "success": true,
    "data": {
        "id": "33333330-3333-4333-8333-333333333333",
        "buyer_id": "11111110-1111-4111-8111-111111111111",
        "seller_id": "44444440-4444-4444-8444-444444444444",
        "item_name": "Kamera Fujifilm X-T30 bekas",
        "amount": "250000.00",
        "description": "Body only, shutter count 8.000, lengkap dengan dus.",
        "category": "goods",
        "status": "pending_payment",
        "counterparty_email": null,
        "counterparty_username": null,
        "source_url": null,
        "source_screenshot_url": null,
        "attachment_url": "https://api.rekberpay.com/uploads/escrow/1791901398283_862e8cf475cf7693efed4855a91995d0_7e10e097a2087a40e3e8e3b659df3f65.png?exp=1791979200000&sig=c0ffee5b1a9e3d7f4a2c8e6b0d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5",
        "deadline_at": null,
        "auto_release_at": null,
        "partner_ref": null,
        "partner_sig_version": null,
        "paid_at": null,
        "released_at": null,
        "refunded_at": null,
        "cancelled_at": null,
        "tracking_courier": null,
        "tracking_number": null,
        "tracking_status": null,
        "tracking_last_checked_at": null,
        "tracking_snapshot": null,
        "created_at": "2026-10-13T14:23:18.305Z",
        "updated_at": "2026-10-13T14:23:18.320Z"
    }
}

4. The buyer pays ​

Rina pays through the checkout. The calls behind it, and how to poll the status, are in Payments and checking status. After RekberPay confirms the transfer the escrow is paid. A manual bank transfer carries a unique code, so Rina transfers pay_total, not amount (why).

5. The seller ships ​

Budi marks it sent. He can attach the courier and AWB in the same call, or later. Pick the courier slug from couriers in Get tracking. For a courier that cannot be tracked, also send custom_delivery_days (the expected transit days) so the buyer's timer has an end. A wrong AWB can be corrected once, within the edit window (limits.awb_edit_window_hours):

bash
curl -X POST https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/send \
  -H "Authorization: Bearer $REKBERPAY_API_KEY" \
  -H "Idempotency-Key: 99999990-9999-4999-8999-999999999999" \
  -H "Content-Type: application/json" \
  -d '{}'
js
const res = await fetch('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/send', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.REKBERPAY_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': '99999990-9999-4999-8999-999999999999',
    },
    body: JSON.stringify({}),
});
const data = await res.json();
python
import os

import requests

resp = requests.post(
    "https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/send",
    headers={
        "Authorization": f"Bearer {os.environ['REKBERPAY_API_KEY']}",
        "Idempotency-Key": "99999990-9999-4999-8999-999999999999",
    },
    json={},
    timeout=30,
)
print(resp.status_code, resp.json())
php
<?php

$ch = curl_init('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/send');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('REKBERPAY_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: 99999990-9999-4999-8999-999999999999',
    ],
    CURLOPT_POSTFIELDS => json_encode(new stdClass()),
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

200 OK

json
{
    "success": true,
    "data": {
        "id": "33333330-3333-4333-8333-333333333333",
        "buyer_id": "11111110-1111-4111-8111-111111111111",
        "seller_id": "44444440-4444-4444-8444-444444444444",
        "item_name": "Kamera Fujifilm X-T30 bekas",
        "amount": "250000.00",
        "description": "Body only, shutter count 8.000, lengkap dengan dus.",
        "category": "goods",
        "status": "sent",
        "counterparty_email": null,
        "counterparty_username": null,
        "source_url": null,
        "source_screenshot_url": null,
        "attachment_url": "https://api.rekberpay.com/uploads/escrow/1791901398283_862e8cf475cf7693efed4855a91995d0_7e10e097a2087a40e3e8e3b659df3f65.png?exp=1791979200000&sig=c0ffee5b1a9e3d7f4a2c8e6b0d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5",
        "deadline_at": null,
        "auto_release_at": "2026-10-16T14:23:18.383Z",
        "partner_ref": null,
        "partner_sig_version": null,
        "paid_at": "2026-10-13T14:23:18.363Z",
        "released_at": null,
        "refunded_at": null,
        "cancelled_at": null,
        "tracking_courier": null,
        "tracking_number": null,
        "tracking_status": null,
        "tracking_last_checked_at": null,
        "tracking_snapshot": null,
        "created_at": "2026-10-13T14:23:18.305Z",
        "updated_at": "2026-10-13T14:23:18.383Z",
        "user_role": "seller",
        "available_actions": [
            "dispute"
        ],
        "shipping": {
            "mode": "none",
            "courier": null,
            "tracking_number": null,
            "custom_delivery_days": null,
            "auto_release_hours": 72
        }
    }
}
bash
curl -X POST https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/tracking \
  -H "Authorization: Bearer $REKBERPAY_API_KEY" \
  -H "Idempotency-Key: aaaaaaa0-aaaa-4aaa-8aaa-aaaaaaaaaaaa" \
  -H "Content-Type: application/json" \
  -d '{
    "courier": "jne",
    "tracking_number": "CGK0123456789"
  }'
js
const res = await fetch('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/tracking', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.REKBERPAY_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': 'aaaaaaa0-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
    },
    body: JSON.stringify({
        courier: "jne",
        tracking_number: "CGK0123456789"
    }),
});
const data = await res.json();
python
import os

import requests

resp = requests.post(
    "https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/tracking",
    headers={
        "Authorization": f"Bearer {os.environ['REKBERPAY_API_KEY']}",
        "Idempotency-Key": "aaaaaaa0-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
    },
    json={
        "courier": "jne",
        "tracking_number": "CGK0123456789",
    },
    timeout=30,
)
print(resp.status_code, resp.json())
php
<?php

$ch = curl_init('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/tracking');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('REKBERPAY_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: aaaaaaa0-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'courier' => 'jne',
        'tracking_number' => 'CGK0123456789',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

200 OK

json
{
    "success": true,
    "data": {
        "courier": "jne",
        "courier_name": "JNE",
        "tracking_number": "CGK0123456789",
        "track_url": "https://www.jne.co.id/id/tracking/trace?awb=CGK0123456789",
        "changed": true
    }
}

Both sides can follow the parcel. The snapshot comes from the courier, so it can be late or missing:

bash
curl https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/tracking \
  -H "Authorization: Bearer $REKBERPAY_API_KEY"
js
const res = await fetch('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/tracking', {
    headers: {
        Authorization: `Bearer ${process.env.REKBERPAY_API_KEY}`,
    },
});
const data = await res.json();
python
import os

import requests

resp = requests.get(
    "https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/tracking",
    headers={
        "Authorization": f"Bearer {os.environ['REKBERPAY_API_KEY']}",
    },
    timeout=30,
)
print(resp.status_code, resp.json())
php
<?php

$ch = curl_init('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/tracking');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('REKBERPAY_API_KEY'),
    ],
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

200 OK

json
{
    "success": true,
    "data": {
        "tracking": {
            "courier": "jne",
            "courier_name": "JNE",
            "number": "CGK0123456789",
            "track_url": "https://www.jne.co.id/id/tracking/trace?awb=CGK0123456789"
        },
        "snapshot": {
            "found": true,
            "courier": "jne",
            "awb": "CGK0123456789",
            "status": "On Process",
            "recipient": "(On Process)",
            "origin": null,
            "destination": null,
            "events": [
                {
                    "date": "-",
                    "description": "Dalam pengiriman"
                }
            ],
            "checkedAt": "2026-10-13T14:23:18.659Z"
        },
        "couriers": [
            {
                "slug": "jne",
                "name": "JNE",
                "trackable": true
            },
            {
                "slug": "jnt",
                "name": "J&T Express",
                "trackable": true
            },
            {
                "slug": "jntcargo",
                "name": "J&T Cargo",
                "trackable": true
            }
        ],
        "limits": {
            "custom_delivery_max_days": 60,
            "awb_edit_window_hours": 12
        }
    }
}

Lists are cut to the first 3 items and long text is shortened here.

With a trackable courier, the automatic release timer starts when the courier reports delivery. If Rina needs more time after that, she can extend it once with POST /v1/escrows/:id/extend.

6. Talk in the escrow chat ​

bash
curl -X POST https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/messages \
  -H "Authorization: Bearer $REKBERPAY_API_KEY" \
  -H "Idempotency-Key: ccccccc0-cccc-4ccc-8ccc-cccccccccccc" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Paket sudah sampai di kantor pos, saya ambil sore ini."
  }'
js
const res = await fetch('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/messages', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.REKBERPAY_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': 'ccccccc0-cccc-4ccc-8ccc-cccccccccccc',
    },
    body: JSON.stringify({
        content: "Paket sudah sampai di kantor pos, saya ambil sore ini."
    }),
});
const data = await res.json();
python
import os

import requests

resp = requests.post(
    "https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/messages",
    headers={
        "Authorization": f"Bearer {os.environ['REKBERPAY_API_KEY']}",
        "Idempotency-Key": "ccccccc0-cccc-4ccc-8ccc-cccccccccccc",
    },
    json={
        "content": "Paket sudah sampai di kantor pos, saya ambil sore ini.",
    },
    timeout=30,
)
print(resp.status_code, resp.json())
php
<?php

$ch = curl_init('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/messages');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('REKBERPAY_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: ccccccc0-cccc-4ccc-8ccc-cccccccccccc',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'content' => 'Paket sudah sampai di kantor pos, saya ambil sore ini.',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

201 Created

json
{
    "success": true,
    "data": {
        "id": "ddddddd0-dddd-4ddd-8ddd-dddddddddddd",
        "escrow_id": "33333330-3333-4333-8333-333333333333",
        "sender_id": "11111110-1111-4111-8111-111111111111",
        "body": "Paket sudah sampai di kantor pos, saya ambil sore ini.",
        "attachment_url": null,
        "is_system": 0,
        "created_at": "2026-10-13T14:23:18.734Z",
        "sender_email": "[email protected]",
        "sender_full_name": "Rina Wijaya",
        "sender_role": "user",
        "sender_participant_role": "buyer"
    }
}

7. The buyer confirms ​

Rina confirms the camera arrived as described. The escrow is released in the same call and Budi's balance is credited with the amount minus the fee:

bash
curl -X POST https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/confirm \
  -H "Authorization: Bearer $REKBERPAY_API_KEY" \
  -H "Idempotency-Key: fffffff0-ffff-4fff-8fff-ffffffffffff" \
  -H "Content-Type: application/json" \
  -d '{}'
js
const res = await fetch('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/confirm', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.REKBERPAY_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': 'fffffff0-ffff-4fff-8fff-ffffffffffff',
    },
    body: JSON.stringify({}),
});
const data = await res.json();
python
import os

import requests

resp = requests.post(
    "https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/confirm",
    headers={
        "Authorization": f"Bearer {os.environ['REKBERPAY_API_KEY']}",
        "Idempotency-Key": "fffffff0-ffff-4fff-8fff-ffffffffffff",
    },
    json={},
    timeout=30,
)
print(resp.status_code, resp.json())
php
<?php

$ch = curl_init('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/confirm');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('REKBERPAY_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: fffffff0-ffff-4fff-8fff-ffffffffffff',
    ],
    CURLOPT_POSTFIELDS => json_encode(new stdClass()),
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

200 OK

json
{
    "success": true,
    "data": {
        "id": "33333330-3333-4333-8333-333333333333",
        "buyer_id": "11111110-1111-4111-8111-111111111111",
        "seller_id": "44444440-4444-4444-8444-444444444444",
        "item_name": "Kamera Fujifilm X-T30 bekas",
        "amount": "250000.00",
        "description": "Body only, shutter count 8.000, lengkap dengan dus.",
        "category": "goods",
        "status": "released",
        "counterparty_email": null,
        "counterparty_username": null,
        "source_url": null,
        "source_screenshot_url": null,
        "attachment_url": "https://api.rekberpay.com/uploads/escrow/1791901398283_862e8cf475cf7693efed4855a91995d0_7e10e097a2087a40e3e8e3b659df3f65.png?exp=1791979200000&sig=c0ffee5b1a9e3d7f4a2c8e6b0d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5",
        "deadline_at": null,
        "auto_release_at": null,
        "partner_ref": null,
        "partner_sig_version": null,
        "paid_at": "2026-10-13T14:23:18.363Z",
        "released_at": "2026-10-13T14:23:18.000Z",
        "refunded_at": null,
        "cancelled_at": null,
        "tracking_courier": "jne",
        "tracking_number": "CGK0123456789",
        "tracking_status": "On Process",
        "tracking_last_checked_at": "2026-10-13T14:23:18.721Z",
        "tracking_snapshot": "{\"found\":true,\"courier\":\"jne\",\"awb\":\"CGK0123456789\",\"status\":\"On Process\",\"recipient\":\"(On Process)\",\"origin\":null,\"destination\":null,\"events\":[{\"date\":\"-\",\"description\":\"Dalam pengiriman\"}],\"checkedAt\":\"2026-10-13T14:23:18.720Z\"}",
        "created_at": "2026-10-13T14:23:18.305Z",
        "updated_at": "2026-10-13T14:23:18.753Z",
        "user_role": "buyer",
        "available_actions": []
    }
}

8. Rate each other ​

bash
curl -X POST https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/rate \
  -H "Authorization: Bearer $REKBERPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stars": 5,
    "review": "Barang sesuai deskripsi, penjual responsif."
  }'
js
const res = await fetch('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/rate', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.REKBERPAY_API_KEY}`,
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        stars: 5,
        review: "Barang sesuai deskripsi, penjual responsif."
    }),
});
const data = await res.json();
python
import os

import requests

resp = requests.post(
    "https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/rate",
    headers={
        "Authorization": f"Bearer {os.environ['REKBERPAY_API_KEY']}",
    },
    json={
        "stars": 5,
        "review": "Barang sesuai deskripsi, penjual responsif.",
    },
    timeout=30,
)
print(resp.status_code, resp.json())
php
<?php

$ch = curl_init('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/rate');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('REKBERPAY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'stars' => 5,
        'review' => 'Barang sesuai deskripsi, penjual responsif.',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

201 Created

json
{
    "success": true,
    "data": {
        "id": "33333331-3333-4333-8333-333333333333",
        "stars": 5,
        "review": "Barang sesuai deskripsi, penjual responsif.",
        "published_at": null
    }
}

The rating stays private until both sides have rated, or until 3 days have passed. Budi can now withdraw his balance.

9. Save where the money goes ​

Budi's share is in his RekberPay balance. To withdraw it without typing the bank details each time, save the account once. His KYC must be verified, and the account holder must match the name on it (422 NAME_MISMATCH otherwise). A saved bank account can be paid to right away.

bash
curl -X POST https://api.rekberpay.com/v1/user/payout-accounts \
  -H "Authorization: Bearer $REKBERPAY_API_KEY" \
  -H "Idempotency-Key: 55555552-5555-4555-8555-555555555555" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bank",
    "bank_code": "bca",
    "account_number": "1234567890",
    "holder_name": "Budi Santoso"
  }'
js
const res = await fetch('https://api.rekberpay.com/v1/user/payout-accounts', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.REKBERPAY_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': '55555552-5555-4555-8555-555555555555',
    },
    body: JSON.stringify({
        type: 'bank',
        bank_code: 'bca',
        account_number: '1234567890',
        holder_name: 'Budi Santoso',
    }),
});
const account = (await res.json()).data;
python
import os

import requests

resp = requests.post(
    "https://api.rekberpay.com/v1/user/payout-accounts",
    headers={
        "Authorization": f"Bearer {os.environ['REKBERPAY_API_KEY']}",
        "Idempotency-Key": "55555552-5555-4555-8555-555555555555",
    },
    json={
        "type": "bank",
        "bank_code": "bca",
        "account_number": "1234567890",
        "holder_name": "Budi Santoso",
    },
    timeout=30,
)
account = resp.json()["data"]
php
<?php

$ch = curl_init('https://api.rekberpay.com/v1/user/payout-accounts');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('REKBERPAY_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: 55555552-5555-4555-8555-555555555555',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'type' => 'bank',
        'bank_code' => 'bca',
        'account_number' => '1234567890',
        'holder_name' => 'Budi Santoso',
    ]),
]);
$account = json_decode(curl_exec($ch), true)['data'];
curl_close($ch);

Then request the withdrawal with payout_account_id set to the saved account's id. For crypto, add the address with Add a crypto address: Budi confirms it from the emailed link, and it can be used 24 hours later.

Cancelling before payment ​

Either side can cancel while the escrow is pending_payment:

bash
curl -X POST https://api.rekberpay.com/v1/escrows/ddddddd1-dddd-4ddd-8ddd-dddddddddddd/cancel \
  -H "Authorization: Bearer $REKBERPAY_API_KEY" \
  -H "Idempotency-Key: eeeeeee1-eeee-4eee-8eee-eeeeeeeeeeee" \
  -H "Content-Type: application/json" \
  -d '{}'
js
const res = await fetch('https://api.rekberpay.com/v1/escrows/ddddddd1-dddd-4ddd-8ddd-dddddddddddd/cancel', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.REKBERPAY_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': 'eeeeeee1-eeee-4eee-8eee-eeeeeeeeeeee',
    },
    body: JSON.stringify({}),
});
const data = await res.json();
python
import os

import requests

resp = requests.post(
    "https://api.rekberpay.com/v1/escrows/ddddddd1-dddd-4ddd-8ddd-dddddddddddd/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['REKBERPAY_API_KEY']}",
        "Idempotency-Key": "eeeeeee1-eeee-4eee-8eee-eeeeeeeeeeee",
    },
    json={},
    timeout=30,
)
print(resp.status_code, resp.json())
php
<?php

$ch = curl_init('https://api.rekberpay.com/v1/escrows/ddddddd1-dddd-4ddd-8ddd-dddddddddddd/cancel');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('REKBERPAY_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: eeeeeee1-eeee-4eee-8eee-eeeeeeeeeeee',
    ],
    CURLOPT_POSTFIELDS => json_encode(new stdClass()),
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

200 OK

json
{
    "success": true,
    "data": {
        "id": "ddddddd1-dddd-4ddd-8ddd-dddddddddddd",
        "buyer_id": "11111110-1111-4111-8111-111111111111",
        "seller_id": null,
        "item_name": "Sepatu lari ukuran 42",
        "amount": "450000.00",
        "description": "",
        "category": "goods",
        "status": "cancelled",
        "counterparty_email": null,
        "counterparty_username": null,
        "source_url": null,
        "source_screenshot_url": null,
        "attachment_url": null,
        "deadline_at": null,
        "auto_release_at": null,
        "partner_ref": null,
        "partner_sig_version": null,
        "paid_at": null,
        "released_at": null,
        "refunded_at": null,
        "cancelled_at": "2026-10-13T14:23:18.874Z",
        "tracking_courier": null,
        "tracking_number": null,
        "tracking_status": null,
        "tracking_last_checked_at": null,
        "tracking_snapshot": null,
        "created_at": "2026-10-13T14:23:18.869Z",
        "updated_at": "2026-10-13T14:23:18.874Z",
        "user_role": "buyer",
        "available_actions": []
    }
}

While a payment is still open (a QRIS or virtual account that has not expired, or a manual transfer RekberPay is checking) the cancel answers 409 PAYMENT_IN_PROGRESS; wait until it completes or expires. Once money is held, neither side can cancel alone. Ask the other side to cancel by agreement (below), or open a dispute.

Cancelling by agreement after payment ​

While the escrow is paid or sent, either side can ask the other to cancel it with POST /v1/escrows/:id/cancel-request and an optional reason. The other side answers with /accept or /decline, and the one who asked can /withdraw it.

  • Accepted: the escrow ends refunded and the escrow amount goes back to the buyer's RekberPay balance. The payment fee and any unique code are not refunded.
  • Declined, withdrawn or not answered within 48 hours: the escrow goes on as before.
  • Each side can ask at most twice per escrow (409 CANCEL_REQUEST_LIMIT after that). A dispute is always available, and opening one closes an open request.
  • While a request is open, the escrow is not released automatically.

GET /v1/escrows/:id shows the open request as cancel_request.

Auto-release ​

If the buyer does nothing, a timer releases the money to the seller. These are the default windows; RekberPay can change them, so read auto_completion on GET /v1/escrows/:id for the real time of a given escrow:

CaseDefault window
Goods with tracking48 hours after the courier reports delivery
Goods without tracking72 hours after sent
Goods with a declared delivery timeThe declared days plus 48 hours
Service and digital36 hours after sent

The buyer can push the timer back with POST /v1/escrows/:id/extend (once, by 48 hours, by default). The other way round, when a paid escrow is not shipped in time, the buyer can be refunded automatically: auto_completion.kind is then auto_refund_unshipped with the deadline in at. The kinds are listed in the reference.

Common errors ​

ErrorCause
400 INVALID_BODYA field failed validation, for example an amount below 1,000
400 INVALID_TRANSITIONThe action does not fit the status or your side, for example the buyer calling send
409 ALREADY_PARTYYou are already in the escrow
409 FULLBoth seats are taken
409 PROFILE_INCOMPLETEThe account has no name or WhatsApp number yet, or has not accepted the Terms
403 EMAIL_NOT_VERIFIEDThe account has not confirmed its email
409 PAYMENT_IN_PROGRESSA cancel while a payment is still open
400/403/429 NONKYC_LIMIT_*An account without KYC is over a limit

A real validation error:

400 Bad Request

json
{
    "success": false,
    "error": {
        "code": "INVALID_BODY",
        "message": "Validasi gagal",
        "details": {
            "formErrors": [],
            "fieldErrors": {
                "amount": [
                    "Too small: expected number to be >=1000"
                ]
            }
        }
    }
}

Next steps ​

Escrow, payment services and B2B deals for Indonesian businesses.