Skip to content

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.

What you need
  • 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-link becomes 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.

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:

  1. Take the allowlisted fields: amount, buyer, category, desc, expires, item, ref, seller, v. Drop any that are empty. amount is the price in rupiah as plain digits, from 1000 to 500000000, and v is always 1.
  2. Sort the remaining keys alphabetically (the order above is already sorted).
  3. 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.

js
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`);
python
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
<?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:

text
escrow eeeeeee1-eeee-4eee-8eee-eeeeeeeeeeee pending_payment
checkout https://rekberpay.com/escrow/eeeeeee1-eeee-4eee-8eee-eeeeeeeeeeee/pay

Here is the same call with curl, and the real response:

bash
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>"
  }'
json
{
    "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:

bash
curl https://api.rekberpay.com/v1/escrows/eeeeeee1-eeee-4eee-8eee-eeeeeeeeeeee/preview
json
{
    "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:

bash
curl https://api.rekberpay.com/v1/escrows/eeeeeee1-eeee-4eee-8eee-eeeeeeeeeeee/payment-status \
  -H "Authorization: Bearer $BUYER_API_KEY"
json
{
    "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:

json
{
    "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.

js
// 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.

Ready for production?

Swap LINK_SIGNING_SECRET, the API keys and the base URL. Paths and response shapes are the same.

Escrow, payment services and B2B deals for Indonesian businesses.