Quickstart
Get from zero to a paid escrow. You sign a partner link on your backend, create the escrow, send the buyer to the hosted checkout and poll until the payment settles. Every request and response on this page was captured from a running API. IDs are replaced with sample UUIDs.
- A partner link secret from RekberPay, kept in your env as
LINK_SIGNING_SECRET(request it at [email protected]). It only signs partner links. - The seller's RekberPay user ID (a UUID, your platform's seller as it exists in RekberPay)
- An API key for the user who will be the buyer. The caller of
POST /v1/escrows/from-linkbecomes the buyer of the escrow - A backend that can compute HMAC-SHA256
Looking for the business workspace instead? Start with Get started with Enterprise to open a sandbox workspace and invite your team, then follow the Enterprise quickstart for the API flow.
The base URL is https://api.rekberpay.com/v1.
1. Sign the link
The signature covers the escrow details in the link, including the price. If anyone changes the amount, the item, the seller or the reference after you sign it, the API rejects the call.
The canonical string is built by:
- Take the allowlisted fields:
amount,buyer,category,desc,expires,item,ref,seller,v. Drop any that are empty.amountis the price in rupiah as plain digits, from 1000 to 500000000, andvis always1. - Sort the remaining keys alphabetically (the order above is already sorted).
- Format as
key=encodeURIComponent(value)pairs joined by&.
Then HMAC-SHA256 the result with your LINK_SIGNING_SECRET and hex-encode it. The signed link is https://rekberpay.com/?<canonical>&sig=<hex>. Only rekberpay.com and the partner hosts RekberPay enabled for you are accepted as the link host.
2. Create the escrow
POST the signed link to /v1/escrows/from-link as { "link": "..." }. The escrow is created at the amount in the signed link. You can also send amount in the body, but it is optional and must match the signed amount exactly, or the call fails with 422 AMOUNT_MISMATCH. Always send an Idempotency-Key so a retry cannot create a duplicate.
The scripts below sign the link and create the escrow in one go. Set LINK_SIGNING_SECRET, SELLER_ID and BUYER_API_KEY, and REKBERPAY_BASE_URL if you are not using production. They create a real escrow each time you run them.
import crypto from 'node:crypto';
const BASE = process.env.REKBERPAY_BASE_URL ?? 'https://api.rekberpay.com';
const SECRET = process.env.LINK_SIGNING_SECRET;
const ALLOWED = ['amount', 'buyer', 'category', 'desc', 'expires', 'item', 'ref', 'seller', 'v'];
function canonicalString(params) {
return ALLOWED.filter((k) => params[k] !== undefined && params[k] !== '')
.map((k) => `${k}=${encodeURIComponent(String(params[k]))}`)
.join('&');
}
const params = {
seller: process.env.SELLER_ID, // the seller's RekberPay user id
item: 'iPhone 15 Pro 256GB',
category: 'goods',
expires: Math.floor(Date.now() / 1000) + 7 * 24 * 60 * 60, // 7 days
ref: 'MARKETPLACE_98765',
amount: 22500000, // rupiah, signed with the rest
v: 1,
};
const canonical = canonicalString(params);
const sig = crypto.createHmac('sha256', SECRET).update(canonical).digest('hex');
const link = `https://rekberpay.com/?${canonical}&sig=${sig}`;
// The caller becomes the buyer, so send the buyer's API key.
const res = await fetch(`${BASE}/v1/escrows/from-link`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BUYER_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({ link }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
const escrow = body.data;
console.log('escrow', escrow.id, escrow.status);
console.log('checkout', `https://rekberpay.com/escrow/${escrow.id}/pay`);import hashlib
import hmac
import os
import time
import uuid
from urllib.parse import quote
import requests
BASE = os.environ.get("REKBERPAY_BASE_URL", "https://api.rekberpay.com")
SECRET = os.environ["LINK_SIGNING_SECRET"].encode()
ALLOWED = ["amount", "buyer", "category", "desc", "expires", "item", "ref", "seller", "v"]
def canonical_string(params):
return "&".join(
f"{k}={quote(str(params[k]), safe='')}"
for k in ALLOWED
if params.get(k) not in (None, "")
)
params = {
"seller": os.environ["SELLER_ID"], # the seller's RekberPay user id
"item": "iPhone 15 Pro 256GB",
"category": "goods",
"expires": int(time.time()) + 7 * 24 * 60 * 60, # 7 days
"ref": "MARKETPLACE_98765",
"amount": 22500000, # rupiah, signed with the rest
"v": 1,
}
canonical = canonical_string(params)
sig = hmac.new(SECRET, canonical.encode(), hashlib.sha256).hexdigest()
link = f"https://rekberpay.com/?{canonical}&sig={sig}"
# The caller becomes the buyer, so send the buyer's API key.
res = requests.post(
f"{BASE}/v1/escrows/from-link",
headers={
"Authorization": f"Bearer {os.environ['BUYER_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"link": link},
timeout=30,
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {body['error']['code']}: {body['error']['message']}")
escrow = body["data"]
print("escrow", escrow["id"], escrow["status"])
print("checkout", f"https://rekberpay.com/escrow/{escrow['id']}/pay")<?php
$base = getenv('REKBERPAY_BASE_URL') ?: 'https://api.rekberpay.com';
$secret = getenv('LINK_SIGNING_SECRET');
$allowed = ['amount', 'buyer', 'category', 'desc', 'expires', 'item', 'ref', 'seller', 'v'];
function canonical_string(array $params, array $allowed): string {
$parts = [];
foreach ($allowed as $k) {
if (isset($params[$k]) && $params[$k] !== '') {
$parts[] = $k . '=' . rawurlencode((string) $params[$k]);
}
}
return implode('&', $parts);
}
function uuid_v4(): string {
$b = random_bytes(16);
$b[6] = chr((ord($b[6]) & 0x0f) | 0x40);
$b[8] = chr((ord($b[8]) & 0x3f) | 0x80);
return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($b), 4));
}
$params = [
'seller' => getenv('SELLER_ID'), // the seller's RekberPay user id
'item' => 'iPhone 15 Pro 256GB',
'category' => 'goods',
'expires' => time() + 7 * 24 * 60 * 60, // 7 days
'ref' => 'MARKETPLACE_98765',
'amount' => 22500000, // rupiah, signed with the rest
'v' => 1,
];
$canonical = canonical_string($params, $allowed);
$sig = hash_hmac('sha256', $canonical, $secret);
$link = 'https://rekberpay.com/?' . $canonical . '&sig=' . $sig;
// The caller becomes the buyer, so send the buyer's API key.
$ch = curl_init($base . '/v1/escrows/from-link');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('BUYER_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: ' . uuid_v4(),
],
CURLOPT_POSTFIELDS => json_encode(['link' => $link]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$body = json_decode($raw, true);
if ($status >= 400) {
throw new RuntimeException("$status {$body['error']['code']}: {$body['error']['message']}");
}
$escrow = $body['data'];
echo 'escrow ' . $escrow['id'] . ' ' . $escrow['status'] . "\n";
echo 'checkout https://rekberpay.com/escrow/' . $escrow['id'] . "/pay\n";A successful run prints:
escrow eeeeeee1-eeee-4eee-8eee-eeeeeeeeeeee pending_payment
checkout https://rekberpay.com/escrow/eeeeeee1-eeee-4eee-8eee-eeeeeeeeeeee/payHere is the same call with curl, and the real response:
curl -X POST https://api.rekberpay.com/v1/escrows/from-link \
-H "Authorization: Bearer $BUYER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 55555552-5555-4555-8555-555555555555" \
-d '{
"link": "https://rekberpay.com/?amount=22500000&category=goods&expires=1792466500&item=iPhone%2015%20Pro%20256GB&ref=MARKETPLACE_98765&seller=fffffff1-ffff-4fff-8fff-ffffffffffff&v=1&sig=<hex signature>"
}'{
"success": true,
"data": {
"id": "66666662-6666-4666-8666-666666666666",
"buyer_id": "77777772-7777-4777-8777-777777777777",
"seller_id": "88888882-8888-4888-8888-888888888888",
"item_name": "iPhone 15 Pro 256GB",
"amount": "22500000.00",
"description": "",
"category": "goods",
"status": "pending_payment",
"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": "MARKETPLACE_98765",
"partner_sig_version": 1,
"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-13T03:21:40.087Z",
"updated_at": "2026-10-13T03:21:40.087Z"
}
}amount comes back as a string with two decimals. The escrow id is what you store against your order. The API does not return a checkout URL.
Sending the same Idempotency-Key again returns the same 201 and body with an Idempotent-Replay: true header, and creates nothing new.
3. Send the buyer to the checkout
The hosted checkout for an escrow lives at https://rekberpay.com/escrow/<id>/pay. The buyer must be signed in. They see the item, the seller, the total and the payment methods that are enabled right now (see GET /v1/gateways/available-methods).
Anyone can read a public preview of an escrow without signing in, which is useful for an order summary page:
curl https://api.rekberpay.com/v1/escrows/eeeeeee1-eeee-4eee-8eee-eeeeeeeeeeee/preview{
"success": true,
"data": {
"id": "66666662-6666-4666-8666-666666666666",
"item_name": "iPhone 15 Pro 256GB",
"description": "",
"amount": "22500000.00",
"status": "pending_payment",
"category": "goods",
"has_buyer": true,
"has_seller": true,
"is_party": false,
"buyer_full_name": null,
"buyer_username": null,
"buyer_email": null,
"seller_full_name": null,
"seller_username": "ownernorthline",
"seller_email": null,
"created_at": "2026-10-13T03:21:40.087Z"
}
}4. Poll for the payment
Poll for now
Escrow payment updates are not pushed to partners. Poll payment-status. See Webhooks for what is and is not delivered.
Once the buyer has started checkout, the payment appears. The buyer or the seller can read it:
curl https://api.rekberpay.com/v1/escrows/eeeeeee1-eeee-4eee-8eee-eeeeeeeeeeee/payment-status \
-H "Authorization: Bearer $BUYER_API_KEY"{
"success": true,
"data": {
"id": "99999992-9999-4999-8999-999999999999",
"escrow_id": "66666662-6666-4666-8666-666666666666",
"provider": "manual_qris",
"method": "qris",
"gateway_order_id": "RBP-48ea70f3-1791861715106-2daf81ca",
"amount": "22500000.00",
"status": "pending",
"qr_url": "https://api.rekberpay.com/uploads/escrow/1779846015565_f14a5645.jpg",
"va_number": null,
"redirect_url": null,
"expires_at": "2026-10-13T04:21:55.106Z",
"created_at": "2026-10-13T03:21:55.106Z",
"updated_at": "2026-10-13T03:21:55.106Z",
"paid_at": null
}
}While nothing has been started you get 404 NO_PAYMENT, which is not a failure:
{
"success": false,
"error": {
"code": "NO_PAYMENT",
"message": "No payment found for this escrow"
}
}status is one of pending, paid, expired, failed or awaiting_confirmation. Poll every 5 seconds while the checkout is open, stop when it is paid, failed or expired, and give up after a couple of minutes. A manual QRIS or bank transfer stays pending until the buyer taps "Saya sudah bayar", then the escrow moves to pending_review until RekberPay confirms the money.
When the escrow itself changes (paid, sent, released), read it with GET /v1/escrows/:id. Its status is the lifecycle state, and available_actions lists what the caller can do next.
// Poll until the payment settles. Run it with the buyer's key.
async function waitForPayment(escrowId, apiKey) {
for (let attempt = 0; attempt < 24; attempt++) {
const res = await fetch(`https://api.rekberpay.com/v1/escrows/${escrowId}/payment-status`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
if (res.ok && ['paid', 'failed', 'expired'].includes(body.data.status)) {
return body.data.status;
}
await new Promise((resolve) => setTimeout(resolve, 5000));
}
return 'pending';
}5. Fulfil
When payment-status says paid, the escrow moves to paid and the money is held. The seller ships or delivers, the buyer confirms, and the funds are released. See Creating escrows for each step.
Swap LINK_SIGNING_SECRET, the API keys and the base URL. Paths and response shapes are the same.