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
pending_payment --pay--> paid --send--> sent --confirm--> released
| | |
| +---------------+--dispute--> disputed --> released / refunded / hold
| +---------------+--cancel by agreement--> refunded
+--cancel--> cancelledA 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:
curl -X POST https://api.rekberpay.com/v1/upload/escrow \
-H "Authorization: Bearer $REKBERPAY_API_KEY" \
-F "[email protected];type=image/png"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();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
$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
{
"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.
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"
}'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();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
$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
{
"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:
curl https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/previewconst res = await fetch('https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/preview', {
});
const data = await res.json();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
$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
{
"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.
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 '{}'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();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
$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
{
"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):
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 '{}'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();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
$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
{
"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
}
}
}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"
}'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();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
$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
{
"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:
curl https://api.rekberpay.com/v1/escrows/33333330-3333-4333-8333-333333333333/tracking \
-H "Authorization: Bearer $REKBERPAY_API_KEY"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();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
$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
{
"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
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."
}'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();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
$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
{
"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:
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 '{}'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();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
$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
{
"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
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."
}'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();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
$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
{
"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.
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"
}'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;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
$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:
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 '{}'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();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
$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
{
"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
refundedand 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_LIMITafter 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:
| Case | Default window |
|---|---|
| Goods with tracking | 48 hours after the courier reports delivery |
| Goods without tracking | 72 hours after sent |
| Goods with a declared delivery time | The declared days plus 48 hours |
| Service and digital | 36 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
| Error | Cause |
|---|---|
400 INVALID_BODY | A field failed validation, for example an amount below 1,000 |
400 INVALID_TRANSITION | The action does not fit the status or your side, for example the buyer calling send |
409 ALREADY_PARTY | You are already in the escrow |
409 FULL | Both seats are taken |
409 PROFILE_INCOMPLETE | The account has no name or WhatsApp number yet, or has not accepted the Terms |
403 EMAIL_NOT_VERIFIED | The account has not confirmed its email |
409 PAYMENT_IN_PROGRESS | A 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
{
"success": false,
"error": {
"code": "INVALID_BODY",
"message": "Validasi gagal",
"details": {
"formErrors": [],
"fieldErrors": {
"amount": [
"Too small: expected number to be >=1000"
]
}
}
}
}Next steps
- Escrows reference: every endpoint and field
- Payments and checking status
- Idempotency and retries: make every write safe to retry