Authentication
The base URL is https://api.rekberpay.com/v1.
RekberPay has three ways to authenticate, each for a different job:
| Mechanism | Used for | Credential |
|---|---|---|
| HMAC-signed links | Partner escrow creation via POST /v1/escrows/from-link | Your partner link secret (LINK_SIGNING_SECRET), never transmitted |
| API key (bearer) | Authenticating as a user on the REST API | Authorization: Bearer <api-key> |
| Workspace API key (bearer) | Enterprise integrations on /v1/enterprise only | Authorization: Bearer rpe_... |
Most of this page covers HMAC link signing, which is what a partner integration uses to hand a pre-filled escrow to a buyer. If you are calling the REST API directly as a user, see API keys at the bottom.
Why HMAC for links?
Traditional API keys have a problem: if they leak, an attacker can impersonate you until you rotate the key. With HMAC signing:
- No credentials in transit: the secret never leaves your server
- Tamper-proof: changing any signed field invalidates the signature
- Time-bound: every link has an
expirestimestamp, and old links are rejected - Price locked: the amount is signed, so the buyer cannot change it
- Retry-safe: a retry with the same
Idempotency-Keyreturns the first answer instead of creating a second escrow (see Replay)
Stripe uses the same pattern for webhook signatures, and AWS uses it to sign API requests.
How it works
1. You sign the request
On your backend, you build a canonical string from the request parameters, HMAC-SHA256 it with your LINK_SIGNING_SECRET, and hex-encode the result.
The canonical string is:
key1=encodeURIComponent(value1)&key2=encodeURIComponent(value2)&...where the keys are sorted alphabetically and drawn from this allowlist:
amount(required), price in rupiah as plain digits, from 1000 to 500000000buyer(optional), UUID of the buyer in RekberPay, if knowncategory(optional),goods,service, ordigitaldesc(optional), longer item descriptionexpires(required), unix timestamp when the link expiresitem(required), item or service nameref(required), your unique order/transaction IDseller(required), UUID of the seller in RekberPayv(required), signature version, always1
Example canonical string:
amount=250000&category=service&expires=1748448000&item=Jasa%20Logo%20Design&ref=ORDER_12345&seller=00000002-0000-4000-8000-000000000000&v=1Then:
const signature = crypto
.createHmac('sha256', LINK_SIGNING_SECRET)
.update(canonical)
.digest('hex');2. You POST the signed link
Build the link as https://rekberpay.com/?<canonical>&sig=<signature> and send it in the body. The buyer's session or API key authenticates the call, and that user becomes the buyer of the escrow. The escrow takes the amount from the signed link.
{
"link": "https://rekberpay.com/?amount=250000&category=service&expires=1792466500&item=Jasa%20Logo%20Design&ref=ORDER_12345&seller=aaaaaaa2-aaaa-4aaa-8aaa-aaaaaaaaaaaa&v=1&sig=7b2e94d0c1a8f3e65d4b9c0a2f7e8d1c3b6a5f4e9d8c7b0a1f2e3d4c5b6a7980"
}You may also send "amount" in the body. It is optional, and if you send it, it must equal the signed amount or the call fails with 422 AMOUNT_MISMATCH.
The values above are an example, so the signature will not verify. The Quickstart has a complete run with a real response.
3. The API verifies
RekberPay reads the link's query string, drops anything that is not on the allowlist, recomputes the signature from the rest (excluding sig itself) and compares it in constant time. The checks run in this order, and each failure returns its own code:
| Check | Status | Code |
|---|---|---|
Body is { link } with a URL, plus an optional integer amount from 1,000 to 500,000,000 | 400 | INVALID_BODY |
The link host is rekberpay.com or a partner host enabled for you | 422 | HOST_NOT_ALLOWED |
v is 1 | 422 | UNSUPPORTED_SIG_VERSION |
Any partner parameter present, amount included, means sig must be present | 400 | SIGNATURE_REQUIRED |
amount, ref, expires and v are present | 422 | SIG_INCOMPLETE |
expires is a unix timestamp, in the future, and at most 30 days away | 422 | INVALID_EXPIRES, LINK_EXPIRED, EXPIRES_TOO_FAR |
| The signature matches | 422 | SIG_MISMATCH |
amount is plain digits from 1000 to 500000000 | 422 | INVALID_AMOUNT |
A body amount, when sent, equals the signed amount | 422 | AMOUNT_MISMATCH |
seller is a UUID v4 that exists and is not the caller | 422 | INVALID_SELLER, SELLER_NOT_FOUND, SELLER_IS_BUYER |
buyer, when present, is the caller | 422 | BUYER_MISMATCH |
category is goods, service or digital | 422 | INVALID_CATEGORY |
item is present and item and desc are valid percent-encoding | 422 / 400 | INVALID_ITEM / INVALID_ENCODING |
For example, a link whose signature was altered by one character:
{
"success": false,
"error": {
"code": "SIG_MISMATCH",
"message": "Signature verification failed."
}
}ref is stored with the escrow as partner_ref, up to 64 characters (longer is 422 INVALID_REF). On a link that names a buyer, the pair seller and ref identifies that one order: see Replay for what happens when the same link is sent twice.
Implementation
Node.js
import crypto from 'node:crypto';
const SECRET = process.env.LINK_SIGNING_SECRET;
const ALLOWED = ['amount', 'buyer', 'category', 'desc', 'expires', 'item', 'ref', 'seller', 'v'];
function signLink(params) {
const canonical = ALLOWED
.filter((k) => params[k] !== undefined && params[k] !== '')
.map((k) => `${k}=${encodeURIComponent(String(params[k]))}`)
.join('&');
return crypto.createHmac('sha256', SECRET).update(canonical).digest('hex');
}
// Usage
const params = {
seller: '00000002-0000-4000-8000-000000000000',
item: 'Jasa Logo Design',
category: 'service',
expires: Math.floor(Date.now() / 1000) + 7 * 24 * 60 * 60,
ref: `ORDER_${Date.now()}`,
amount: 250000,
v: 1,
};
params.sig = signLink(params);
// Build the link from the canonical string and sig, then
// POST { link } to /v1/escrows/from-link (see the Quickstart)PHP
<?php
$SECRET = getenv('LINK_SIGNING_SECRET');
$ALLOWED = ['amount', 'buyer', 'category', 'desc', 'expires', 'item', 'ref', 'seller', 'v'];
function sign_link(array $params, string $secret, array $allowed): string {
$parts = [];
foreach ($allowed as $k) {
if (isset($params[$k]) && $params[$k] !== '') {
$parts[] = $k . '=' . rawurlencode((string) $params[$k]);
}
}
return hash_hmac('sha256', implode('&', $parts), $secret);
}
$params = [
'seller' => '00000002-0000-4000-8000-000000000000',
'item' => 'Jasa Logo Design',
'category' => 'service',
'expires' => time() + 7 * 24 * 60 * 60,
'ref' => 'ORDER_' . time(),
'amount' => 250000,
'v' => 1,
];
$params['sig'] = sign_link($params, $SECRET, $ALLOWED);Python
import hmac
import hashlib
import os
import time
from urllib.parse import quote
SECRET = os.environ['LINK_SIGNING_SECRET'].encode()
ALLOWED = ['amount', 'buyer', 'category', 'desc', 'expires', 'item', 'ref', 'seller', 'v']
def sign_link(params: dict) -> str:
parts = [
f"{k}={quote(str(params[k]), safe='')}"
for k in ALLOWED
if params.get(k) not in (None, '')
]
canonical = '&'.join(parts)
return hmac.new(SECRET, canonical.encode(), hashlib.sha256).hexdigest()
params = {
'seller': '00000002-0000-4000-8000-000000000000',
'item': 'Jasa Logo Design',
'category': 'service',
'expires': int(time.time()) + 7 * 24 * 60 * 60,
'ref': f'ORDER_{int(time.time())}',
'amount': 250000,
'v': 1,
}
params['sig'] = sign_link(params)Field reference
Required fields
| Field | Type | Description |
|---|---|---|
amount | integer | Price in rupiah (IDR), from 1000 to 500000000. Plain digits only: no decimals, separators, sign or leading zero. The escrow is created at this amount. |
seller | UUID (v4) | The seller's user ID in RekberPay. Contact support to get this. |
item | string | Item or service name. Up to 255 characters, HTML tags are stripped. Shown to the buyer on the payment page. |
expires | integer | Unix timestamp (seconds since epoch). Links expire at this time. Max 30 days in the future. |
ref | string | Your order or transaction ID, stored as partner_ref. Up to 64 characters. Not unique. |
v | integer | Signature version. Always 1. |
Optional fields
| Field | Type | Description |
|---|---|---|
buyer | UUID | The RekberPay user ID of the buyer. If present it must be the user making the call, otherwise 422 BUYER_MISMATCH. |
category | string | goods, service, or digital. Affects fee calculation and auto-release SLA. Default: goods. |
desc | string | Longer item description. Up to 1000 characters. Shown on the escrow detail page. |
Signed: amount
amount is one of the signed fields, so the price is set by you and not by whoever holds the link. To sell the same item at several prices (for example service tiers), sign one link per price.
The request body only needs link. A body amount is optional and, when sent, must equal the signed amount exactly, otherwise 422 AMOUNT_MISMATCH.
Expiry best practices
- Default: 7 days from now
- Max: 30 days. Anything further returns
422 EXPIRES_TOO_FAR - A link that has expired returns
422 LINK_EXPIRED. Sign a fresh link with a newexpires
Replay
Every signed link must carry expires (at most 30 days away) and is refused after it with 422 LINK_EXPIRED. A link without expires has always been refused (422 SIG_INCOMPLETE), so there is no older link format to phase out.
What a second call does depends on whether the link names a buyer:
- A link with
buyeris single use. The first call creates the escrow and records the link bysellerandref. Any later call with the same link, with or without anIdempotency-Key, and also two calls at the same moment, creates nothing new: the buyer gets200 OKwith the escrow the link already created and the headerPartner-Link-Replay: true. Treat200and201the same way: both carry the escrow to pay. Anyone else gets422 BUYER_MISMATCH. Use a newreffor every order you sign this way;refis matched exactly, case included. - A link without
buyeris a catalogue link. Any signed-in buyer may use it, and each call creates a newpending_paymentescrow at the signed amount. One buyer can create at most 3 escrows from one link (onesellerandref) every 10 minutes; more answers429 LINK_USE_LIMITED. A call that ends without an escrow does not count. - A retry with the same
Idempotency-Keyreturns the stored response in both cases.
So keep expires short, and put buyer in the signed link when you know who the buyer is: nobody else can use it, and a double tap never makes a second escrow.
Security notes
LINK_SIGNING_SECRET is equivalent to an API key. Anyone with it can create escrows on your behalf. Keep it server-side only. Never commit it to git, never put it in your frontend bundle, never log it.
HMAC prevents tampering, but it doesn't encrypt the payload. Always use HTTPS so the request body (including amount and item) isn't readable in transit.
The API compares signatures in constant time. This prevents timing attacks, where an attacker measures how long the comparison takes to guess the signature byte by byte. Do the same when you verify webhook signatures, for example with crypto.timingSafeEqual in Node.js.
API keys
Link signing authenticates a link. To call the REST API as a user (for example to list your escrows, fund an order or request a withdrawal), you authenticate with an API key.
GET /v1/escrows
Authorization: Bearer <your-api-key>The key is rpk_ followed by 32 random bytes, base64url-encoded (47 characters in all). Keys made before the prefix existed have no rpk_ and keep working until you rotate. RekberPay cannot show a key to you again, so if you lose it, rotate to get a new one.
Issuing and rotating
| Method | Path | Returns |
|---|---|---|
GET | /v1/auth/me/api-key | A masked preview of the current key |
POST | /v1/auth/me/api-key/rotate | The new key in plaintext, once |
Rotation revokes immediately
POST /v1/auth/me/api-key/rotate revokes every existing key for the user in the same operation, then issues the new one. There is no grace period and no overlap window: the moment you rotate, anything still using the old key starts getting 401 INVALID_TOKEN. Be ready to switch your integration to the new key as soon as you rotate.
The plaintext is returned in that response and never again. GET /v1/auth/me/api-key only ever returns a mask.
An optional label in the rotate body names the key (defaults to default). Each rotate call makes a new key, so call it once and store the answer.
Before you have a key, the preview is null:
{
"success": true,
"data": {
"has_key": false,
"api_key": null,
"created_at": null,
"last_used_at": null
}
}Rotating returns the key once, as { "api_key": "rpk_..." }. After that, the preview shows the first six and last four characters:
{
"success": true,
"data": {
"has_key": true,
"api_key": "rpk_kM•••••••••••••••••••••••••••••••••••••tN6r",
"created_at": "2026-10-18T03:04:05.000Z",
"last_used_at": null
}
}A key acts as the user who created it. It works on every route that accepts a session cookie, except the enterprise routes that are dashboard only (such as /v1/enterprise/me, creating a workspace, business verification, and member, settings, API key and webhook changes), which answer 403 KEY_NOT_ALLOWED. For the business workspace API you also send X-Enterprise-Account. See the Enterprise quickstart. The Authentication and API keys guide runs the whole setup with real answers, and the Authentication API lists every endpoint.
Workspace API keys
Enterprise workspaces have their own keys, rpe_test_... for Sandbox and rpe_live_... for Live. They belong to a workspace and one mode instead of a person, carry a read or read + write scope, and only work under /v1/enterprise (anywhere else they get 401 WORKSPACE_KEY_ONLY). They work from your server only (403 KEY_IN_BROWSER from a browser) and can be locked to your server IPs. Admins and owners create and revoke them on the Developers page of the enterprise dashboard. See Workspace API keys and the Authentication and API keys guide.
CSRF
A session is the HttpOnly cookie set by POST /v1/auth/login (__Host-rekber_session). Cookie-session requests must send X-CSRF-Token, the csrf_token from the sign-in answer, on mutating methods. Bearer/API-key callers are exempt by design: CSRF is a browser ambient-credential problem, and a bearer token is not ambient. If you are calling the API server-to-server with a key, you do not need a CSRF token.
Testing your implementation
Use the Testing guide to verify your signing logic with the failure cases you can trigger on purpose. Request your LINK_SIGNING_SECRET from [email protected].
Next steps
- Quickstart, sign your first link and create an escrow
- Creating escrows, full guide to the escrow lifecycle
- Errors, every error code and its recovery