Sub-Account KYB Verification Webhook

Sub-Account Operation — This webhook fires on KYB review outcomes for your managed sub-accounts (business_managed). It does not apply to your own merchant-level KYB, or to owned/personal_managed sub-accounts (which never require KYB).

Information

Method	Path	Format	Authentication
POST	`https://your-webhook-url/callback`	json	HMAC SHA512 Signature

SingaPay sends a POST request to your configured kyb_notif_url whenever a managed sub-account’s KYB submission finishes review — either approved, or rejected at one of the review stages.

Events

This single webhook covers two events, distinguished by the event field:

`event`	Fired when	`data` contains
`kyb.approved`	The sub-account passes all review stages (Document → DTTOT → Blacklist) and becomes `active`.	`account`, `verified_at`
`kyb.rejected`	Any review stage (Document, DTTOT, or Blacklist) rejects the submission.	`account`, `stage`, `reason`, `rejected_at`

KYB review runs through three sequential stages: Document Check → DTTOT Check → Blacklist Check. kyb.rejected can fire at any of the three — you will receive a separate webhook call for each rejection, not just one at the end. kyb.approved fires only once, after the final stage passes.

Request Details

Headers

Field	Value	Type	Mandatory	Description
`Content-Type`	`application/json`	Alphabetic	Yes	Specifies JSON format for the request body
`User-Agent`	`SingaPaymentGateway/1.0`	Alphabetic	Yes	Identifies the source of the webhook
`Accept`	`application/json`	Alphabetic	Yes	Expected response format
`X-PARTNER-ID`	—	Alphanumeric	Yes	Your API Key from the merchant dashboard
`X-Signature`	—	Alphanumeric	Yes	HMAC SHA512 signature (128 chars) for request verification
`X-Timestamp`	—	Numeric	Yes	Unix timestamp in seconds when the request was sent
`Authorization`	`Bearer <random_token>`	Alphanumeric	Yes	System-generated random bearer token; used as a component in the signature

The Authorization token for KYB webhooks is a randomly generated string — not a user access token. KYB review outcomes are triggered by an internal reviewer action, not a merchant request. Extract the token as-is and use it in the string to sign. See Security and signature validation.

Body Parameters — common envelope

Every KYB webhook shares the same top-level envelope:

number

required

HTTP Status Code. Always 200.

boolean

required

Indicates a successful event. Always true.

string

required

Event type identifier. One of "kyb.approved", "kyb.rejected".

string

required

Event timestamp in format "d M Y H:i:s". Example: "28 Aug 2026 14:33:55"

object

required

Container for the account details (and, for rejections, the rejection details).

`data.account` (present on all events)

object

required

The sub-account the event relates to. Shape is identical to the Account object returned by GET /accounts/{id}.

Show account fields

string

required

Account ULID. Example: "01K946KF851RK7FX075GJHBVKF"

string

Account number. May be null.

string

required

Account name.

string

required

"active" or "inactive".

string

required

Always "business_managed" in the context of this webhook.

string

One of "kyb_waiting_document", "kyb_in_review", "kyb_rejected", "kyb_verified".

string

The currently outstanding rejection reason. null unless kyb_status is "kyb_rejected".

string

"individual" or "company". null until the sub-merchant makes this choice during onboarding.

string

Legal company name (business_type = "company") or the primary owner’s full name (business_type = "individual"). null until kyb_status = "kyb_verified".

string

Business/brand name. null until kyb_status = "kyb_verified".

string

The sub-merchant’s self-onboarding link. Stays active (and identical) across reject → resubmit cycles; becomes null once kyb_status = "kyb_verified" (the link is revoked).

string[]

Email addresses of your dashboard members who have access to this sub-account.

`data.verified_at` (`kyb.approved` only)

string

required

Timestamp the final review stage was approved. Format "d M Y H:i:s".

`data.stage`, `data.reason`, `data.rejected_at` (`kyb.rejected` only)

string

required

Which review stage rejected the submission. One of "document", "dttot", "blacklist".

string

required

Free-text reason written by the reviewer. Not a structured error code — read it directly to determine what needs correcting.

string

required

Timestamp the rejection was recorded. Format "d M Y H:i:s".

Payload Examples

kyb.approved

{
  "status": 200,
  "success": true,
  "event": "kyb.approved",
  "timestamp": "28 Aug 2026 14:33:55",
  "data": {
    "account": {
      "id": "01K946KF851RK7FX075GJHBVKF",
      "account_number": "000000000123",
      "name": "SingaPay Demo Store",
      "status": "active",
      "account_type": "business_managed",
      "kyb_status": "kyb_verified",
      "kyb_rejection_reason": null,
      "business_type": "company",
      "legal_name": "PT SingaPay Demo Indonesia",
      "brand_name": "SingaPay Demo Store",
      "kyb_onboarding_url": null,
      "invite_members": ["owner@merchant.com"]
    },
    "verified_at": "28 Aug 2026 14:33:55"
  }
}

kyb.rejected

{
  "status": 200,
  "success": true,
  "event": "kyb.rejected",
  "timestamp": "28 Aug 2026 14:35:12",
  "data": {
    "account": {
      "id": "01K946KF851RK7FX075GJHBVKF",
      "account_number": "000000000123",
      "name": "SingaPay Demo Store",
      "status": "inactive",
      "account_type": "business_managed",
      "kyb_status": "kyb_rejected",
      "kyb_rejection_reason": "KTP tidak terbaca / dokumen buram",
      "business_type": "company",
      "legal_name": null,
      "brand_name": null,
      "kyb_onboarding_url": "https://sandbox-payment-b2b.singapay.id/kyb/0b0e5ad5957a7c2de066c2cde97e91089b605aae9afeba3398ff871cd1e99d54",
      "invite_members": ["owner@merchant.com"]
    },
    "stage": "document",
    "reason": "KTP tidak terbaca / dokumen buram",
    "rejected_at": "28 Aug 2026 14:35:12"
  }
}

Security and responses

Return HTTP 200 promptly after validating the request. For retry behavior, see Webhook retry mechanism. Verify every webhook using Security and signature validation. Use your configured kyb_notif_url path when building StringToSign. Handle duplicate deliveries idempotently using data.account.id combined with the event (and, for rejections, data.stage) as a stable identifier.

Sub-Account KYB Specific Notes

Dedicated callback URL

kyb_notif_url is a dedicated field — it does not share a callback URL with any other webhook type. Configure it separately in your dashboard under Settings → Credentials → Webhook & Notification URLs.

Multiple rejections per sub-account

Review runs through three sequential stages. If a sub-merchant is rejected, corrects the issue, and resubmits, and is rejected again at a later stage, you will receive a new kyb.rejected webhook for that stage — each rejection in the account’s history triggers its own call.

The onboarding link survives rejection

kyb_onboarding_url stays the same across reject → resubmit cycles — no new link is generated on rejection. The sub-merchant reopens the same URL to fix and resubmit their data. The link is only revoked (becomes null) once kyb_status reaches kyb_verified.

kyb_status alone doesn't tell you why

kyb_status = "kyb_rejected" tells you a rejection is outstanding, but the specific reason lives in kyb_rejection_reason — a free-text string written by a human reviewer, not a structured per-field error code. If you need to know exactly which document or field was flagged, parse the reason text or direct your sub-merchant to read it carefully before resubmitting.

legal_name and brand_name are null until verified

Both fields only populate once kyb_status = "kyb_verified" — they are null throughout kyb_waiting_document, kyb_in_review, and kyb_rejected, including in the kyb.rejected payload itself.

Timestamp format & timezone

All timestamps (timestamp, verified_at, rejected_at) use the format "d M Y H:i:s" (e.g. "28 Aug 2026 14:33:55") in Asia/Jakarta (WIB) timezone — not UTC.

Getting Started

Security

Accept Money

Send Money

Transaction Records

Money Accounts

Webhook

Information

Events

Request Details

Headers

Body Parameters — common envelope

`data.account` (present on all events)

`data.verified_at` (`kyb.approved` only)

`data.stage`, `data.reason`, `data.rejected_at` (`kyb.rejected` only)

Payload Examples

Security and responses

Sub-Account KYB Specific Notes

​Information

​Events

​Request Details

​Headers

​Body Parameters — common envelope

​data.account (present on all events)

​data.verified_at (kyb.approved only)

​data.stage, data.reason, data.rejected_at (kyb.rejected only)

​Payload Examples

​Security and responses

​Sub-Account KYB Specific Notes

Information

Events

Request Details

Headers

Body Parameters — common envelope

`data.account` (present on all events)

`data.verified_at` (`kyb.approved` only)

`data.stage`, `data.reason`, `data.rejected_at` (`kyb.rejected` only)

Payload Examples

Security and responses

Sub-Account KYB Specific Notes