Getting Started

Portal Preparation

Issue API keys, configure a webhook, and register your IP in the Portal before integrating S2S

Before integrating the S2S API from your server, prepare your credentials and settings in the Portal (UnknownPay's dashboard) — all through the UI, no code required.

The Portal is for configuration (issuing API keys, setting up webhooks); the S2S API is for real transactions using an API key + HMAC signature. They are separate.

Overview checklist

#	Step	Where	Who can do it
1	Sign in to the Portal (+ 2FA if enabled)	Portal	Any merchant user
2	Create / rotate the API secret (live & test)	Portal	Owner/admin
3	Configure a webhook (URL + events + secret)	Portal	Owner/admin
4	Register the server IP for the allowlist	Notify the platform team	Platform team sets it

Pending confirmation — the role / button names shown in the Portal UI

Confirm these match what users actually see.

Open the Portal and sign in with the username + password provided by the team.

Diagram coming soon — Portal login screen

Depending on the account settings, sign-in may have extra steps:

2FA enabled: if two-factor authentication is on, you'll enter a 6-digit code from your authenticator app (or a recovery code) before continuing.
Forced password change: on first sign-in or when a password expires, you'll set a new password first.

Diagram coming soon — 2FA code entry screen (6-digit OTP) after login

Enable 2FA for every account with Portal access — scan the QR with an authenticator app and store the recovery codes somewhere safe.

Diagram coming soon — 2FA setup page (QR code + verification field + recovery codes)

Pending confirmation — confirm the Portal UI actually has this 2FA setup page

2. Create/rotate the API secret — live / test separated

The API key + secret are the credentials your server uses to sign HMAC when calling the S2S API. Open the API credential page in the Portal and click "Issue / rotate secret" to generate a new pair.

The secret is shown only once, at issue/rotate time (show-once). It is never displayed again — copy it into your secret store immediately. If you lose it, you must rotate again (which invalidates the old secret).

Who can do it: owner/admin only — operator/viewer cannot.
Live / test separated: you can issue both a live (real transactions) and a test (sandbox) key — you can hold 1 active live + 1 active test at the same time.
You receive a key id (prefixed unk_live_ or unk_test_) paired with a secret. Keep both to sign requests.

The live/test mode is bound to the key itself — when calling S2S you don't send a mode; the server derives it from the signing key.

Diagram coming soon — API credential page with the Rotate secret button + show-once secret popup

3. Configure a webhook

A webhook is the channel UnknownPay uses to "call back" and notify your server of events (e.g. a successful deposit). Open the webhook settings in the Portal, then:

Enter your server's destination URL (must be https://).
Select the events to receive from: deposit.success, deposit.expired, withdrawal.success, withdrawal.rejected, withdrawal.failed, withdrawal.refunded.
Save — the system issues a signing secret for verifying the payload signature.

The webhook signing secret is also show-once. Copy it immediately. If you lose it, reconfigure to issue a new one.

Who can do it: owner/admin only.
Test button: click "Test webhook" to have the system send a test event to your URL.
Delivery history: view the delivery log and replay failed events.

Diagram coming soon — Webhook config page (URL, event checkboxes, show-once secret, test button)

4. IP allowlist

The S2S gateway enforces an IP allowlist: only source IPs in your allowlist may call the S2S API on your behalf. An IP not in the allowlist is rejected with IP_NOT_ALLOWED (HTTP 403).

In the current phase, merchants cannot set the IP allowlist themselves — only the platform team can. You must send the IP/CIDR of the server(s) that will call S2S to the team.

What to prepare when notifying the team:

The source IP/CIDR (e.g. 203.0.113.10/32) of the server that will call S2S
A note for each IP (e.g. server name / environment)

Diagram coming soon — example IP-report form/email the merchant sends to the platform team

Pending confirmation — the official channel to send your IP (email/form/onboarding contact)

Before you start integrating

Once all 4 steps are done, you should have:

Portal access (with 2FA enabled if you want)
A stored API key + secret (live and/or test)
A configured and tested webhook URL + events + webhook secret
Your server IP sent to the team and confirmed added to the allowlist

Quickstart