Create and link users

Every buyer and seller in a marketplace order is a RekberPay user linked to your platform. You create or link them with one call, POST /v1/enterprise/platform/users, and from then on you name them only by your own partner_user_ref.

You need a workspace key with the users and write scopes (Keep your keys safe). Every example uses sandbox values; in the sandbox an email address must be on a test domain (example.com or a subdomain, example.test, or any .test or .example domain), or the call answers 422 SANDBOX_EMAIL_REQUIRED.

What happens when you send an email

The email	What RekberPay does	Link status	Answer
Has no RekberPay account	Creates an account with no password, linked to you at once	active, origin: created	201
Already has a RekberPay account	Links nothing yet. Emails the person "Hubungkan dengan [your name]?" at the address on file	pending_consent, origin: linked	201
Belongs to RekberPay staff, or a blocked or closing account	The same request as for any known email, but no email goes out and it can never be accepted	pending_consent, origin: linked	201
Is the one you already linked under this partner_user_ref	Nothing new (your retry). A still pending link gets its email again, at most once per 10 minutes	unchanged	200

Staff and blocked accounts get exactly what any existing RekberPay user gets who has not answered yet: the same request, the same answers when you send it again or read it with GET, the same email limits. It is never emailed and never accepted, so it simply stays pending_consent. That way the API never tells anyone who works at RekberPay or whose account is blocked.

1. Create a user

curl -X POST https://api.rekberpay.com/v1/enterprise/platform/users \
  -H "Authorization: Bearer $REKBERPAY_WORKSPACE_KEY" \
  -H "Idempotency-Key: 6f1d2c3b-4a5e-4f60-8a7b-1c2d3e4f5a60" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_user_ref": "seller-2001",
    "email": "[email protected]",
    "full_name": "Budi Santoso",
    "phone": "+6281234567890"
  }'

201 Created

{
    "success": true,
    "data": {
        "id": "7c1e2d3f-4a5b-4c6d-8e7f-901a2b3c4d5e",
        "partner_user_ref": "seller-2001",
        "link_status": "active",
        "origin": "created",
        "claimed": false,
        "kyc_status": "none",
        "balance_scope": "partner_funds",
        "limits": {
            "capped": true,
            "kyc_status": "none",
            "per_escrow_max": 10000000,
            "daily_max": 25,
            "lifetime_max": 25000000,
            "max_order_now": 10000000
        },
        "email_masked": "b***@example.com"
    }
}

• id is the link id. Keep partner_user_ref; every other call uses it.
• claimed: false means the person has not set a password yet. They can still pay and get paid through you. A linked account (one the person already had) is always claimed: true.
• limits are the limits for accounts without KYC: per_escrow_max rupiah per order, daily_max orders per 24 hours and lifetime_max rupiah in total. One budget covers the person's orders with you, with other partners and on RekberPay itself. max_order_now is the largest order total that fits right now (0 once the person used up their orders for the last 24 hours). You never see how much the person used, since that includes what they do outside your platform. Verify the person (KYC through the API) to lift them. The numbers above are examples; RekberPay sets them.
• RekberPay sends a platform.user.linked webhook.

One ref is one person, and one person has one ref with you. Sending a ref you already use with a different email answers 409 REF_IN_USE. Sending a person you already linked under another ref answers 409 USER_ALREADY_LINKED.

2. Link someone who already has an account

Send the same call. When the email is known, the link starts as pending_consent and nothing about the person is shown to you yet:

201 Created

{
    "success": true,
    "data": {
        "id": "8d2f3e4a-5b6c-4d7e-9f80-1a2b3c4d5e6f",
        "partner_user_ref": "buyer-1001",
        "link_status": "pending_consent",
        "origin": "linked",
        "claimed": null,
        "kyc_status": null,
        "balance_scope": "partner_funds",
        "limits": null,
        "email_masked": null
    }
}

1. RekberPay emails the person at the address on its file, never at an address you send. The link is valid for 24 hours.
2. The person opens it, signs in to RekberPay as that account and chooses Hubungkan or declines. They can also tick "allow [your name] to manage my whole balance", which sets balance_scope to full_balance.
3. You get platform.user.linked (accepted) or platform.user.consent_declined. Until then every call about this ref except GET /users/:ref answers 404.

No email arrived? Send the same POST /users again: a pending link is re-sent at most once per 10 minutes, and the answer is the same either way.

So nobody can use RekberPay to flood an inbox, live emails are limited:

• One link gets at most 3 of these emails a day. You have one link per person, so in practice you can send one person 3 a day. Other partners have their own limit, so they never use up yours. On top of that one address gets at most 20 a day from all partners together. Past any of these you get 429 MAIL_LIMIT_REACHED with a Retry-After header (seconds until 00:00 UTC). A new request refused this way is not stored, so send it again later. Calls refused past your own limit do not count toward the shared 20.
• If the person declined, or removed you from their connected partners, a new request waits 7 days: 429 USER_DECLINED_RECENTLY with Retry-After.

In the sandbox no email is sent and these limits do not apply. The answer carries connect_url; open it in a browser signed in as the test user. The test user must be a real RekberPay account on a test domain. An account a Sandbox key creates can never sign in (see the sandbox claim), so it cannot stand in for a person who already has an account.

3. Read a user

curl https://api.rekberpay.com/v1/enterprise/platform/users/seller-2001 \
  -H "Authorization: Bearer $REKBERPAY_WORKSPACE_KEY"

You get the same object as above. claimed, kyc_status, limits and email_masked are filled only while the link is active.

4. Let the user claim the account

An account you created has no password. The person claims it with a code sent to the email on file, then sets a password and uses RekberPay like anyone else.

curl -X POST https://api.rekberpay.com/v1/enterprise/platform/users/seller-2001/claim-link \
  -H "Authorization: Bearer $REKBERPAY_WORKSPACE_KEY" \
  -H "Idempotency-Key: 0a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3d" \
  -H "Content-Type: application/json" \
  -d '{ "delivery": "email" }'

delivery	What happens	Answer
email	RekberPay emails a claim link valid for 24 hours. You never see the link or the code. At most one email per 2 minutes and 10 a day per account; a throttled request gets the same answer	202 with { "delivery": "email" }
link	You get a single use link valid for 30 minutes, to show in your app	200 with url and expires_at

Either way the person still needs the 6 digit code from the email, so a leaked link alone cannot take the account. Codes are rationed: one new code per 2 minutes, 5 an hour and 10 a day (429 TOO_MANY_CODES), and 10 wrong codes in 24 hours lock the claim for a day.

What the claim page does

The link opens rekberpay.com/claim/<token>. The page is RekberPay's, so you build nothing. Behind it are three calls that need no key, only the token (20 a minute per IP address):

1. GET /api/platform/claim/:token shows who made the account: partner_name, partner_logo_url and expires_at. It spends nothing and sends nothing. A used, expired or unknown link answers 410 LINK_EXPIRED.
2. POST /api/platform/claim/:token/otp passes a security check, then emails the 6 digit code to the address on file. The code is good for 5 minutes.
3. POST /api/platform/claim/:token/verify takes the code, a password and the Terms, claims the account and signs the person in.

429 TOO_MANY_CODES means a code was requested in the last 2 minutes by anyone holding the link, or the hourly or daily limit is reached. The person should use the code already sent, or wait. The same spacing applies in the sandbox, where the otp answer carries the code as sandbox_code instead of an email.

After the claim you get platform.user.claimed, and claimed turns true. A password reset or a Google sign-in with that email also counts as a claim.

In the sandbox no email is sent. delivery: "email" answers 202 with a 30 minute claim_url, and delivery: "link" answers as in live. The claim page gets the code back as sandbox_code instead of an email.

A sandbox claim is only a simulation. Finishing it answers { "claimed": true, "sandbox": true }, you get platform.user.claimed, and the user reads claimed: true, so you can try everything that changes after a claim. But no password is kept, no session opens and the RekberPay account itself never changes: a sandbox test account can never sign in to RekberPay, and your workspace can never claim it later from Live. A sandbox link you reopened after an unlink is claimed and confirmed in one step through its connect_url.

A claimed account belongs to the person. From then on you cannot change its name, phone or email, or submit KYC for it (409 USER_MANAGED_BY_OWNER). The same is true for a linked account from the start.

An account you created has no public RekberPay profile until it is claimed: it is not on rekberpay.com/u, and its reviews show no username. A workspace admin can change that in the dashboard (Settings, Public profiles): switch on Show public profiles for accounts not claimed yet and tick the consent statement. A claimed or linked account always follows the normal public rules. See Unclaimed accounts.

5. Change a user's details

PATCH /v1/enterprise/platform/users/:ref works only for an account you created that is not claimed yet.

curl -X PATCH https://api.rekberpay.com/v1/enterprise/platform/users/seller-2001 \
  -H "Authorization: Bearer $REKBERPAY_WORKSPACE_KEY" \
  -H "Idempotency-Key: 1b2c3d4e-5f60-4b7c-8d8e-9f0a1b2c3d4e" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+6281299998888" }'

• Name and phone change at once.
• The name locks once the person's KYC is approved, or once they have a partner balance or a paid marketplace order with any partner, or a payout bank account with you. After that a new name answers 409 NAME_LOCKED. The name is the one every payout bank account is checked against, so this protects the seller's money. Ask RekberPay support if a locked name is wrong.
• Email never changes on your word. RekberPay emails a confirmation link (24 hours) to the new address, and the change applies only when it is opened. The answer adds "email_change": "verification_sent" whether or not the new address is free, so the call cannot be used to find accounts. In the sandbox the answer carries email_change_url instead.
• Email changes are limited in live mode: 3 a day per user, 3 confirmation emails a day from you to one new address, and 10 a day to that address from all partners together. Past that the whole call answers 429 MAIL_LIMIT_REACHED with Retry-After and nothing in it is saved.

6. Unlink, and link again

curl -X DELETE https://api.rekberpay.com/v1/enterprise/platform/users/seller-2001 \
  -H "Authorization: Bearer $REKBERPAY_WORKSPACE_KEY" \
  -H "Idempotency-Key: 2c3d4e5f-6071-4c8d-9e9f-0a1b2c3d4e5f"

• The link becomes revoked and you get platform.user.unlinked. The account and every rupiah in it stay with the person.
• The person can also remove you on RekberPay, under Pengaturan > Partner Terhubung (Settings, Connected partners). A user who becomes RekberPay staff loses every link automatically.
• To link again, send POST /users with the same email. The link reopens as pending_consent and the person must confirm again, even for an account you created. If you created it and the person never claimed it, they claim it first, from the same link. A link that RekberPay itself revoked cannot be reopened (422 USER_NOT_AVAILABLE). A link the person declined or ended can be asked again after 7 days (429 USER_DECLINED_RECENTLY before that).
• The person's balance with you and their payout bank accounts stay as they were. While the link is revoked the person can still withdraw their own balance (When the user withdraws by themselves).

Checklist

• Store partner_user_ref next to your own user record. It is the only id you need.
• Treat pending_consent as "not linked yet". Wait for platform.user.linked.
• Never collect a RekberPay password or the claim code in your app.
• Fix a seller's name before their first sale. It locks after that.

Next steps

• Run a marketplace order end to end
• KYC through the API
• Users reference