Verification (KYB)

Before You Start

Read the following guides before proceeding:

Overview

Verification (KYB) is performed by the corporation itself, inside the SumSub SDK. Wirex issues the SDK
token; your application hosts the SDK; SumSub collects company documents, ownership structure and
director identities. Wirex advances the corporation's verification status as the review progresses.

A corporation carries one status per level, not a single global status. SDD unlocks one set of
capabilities; XDDBridgeBase, XDDOpenPaydBase and EDD unlock others. A corporation can hold SDD
as Approved while EDD is still Applied.

There is no API-side data submission path. Everything the reviewer sees comes from the SDK session.

Verification Levels

Which levels a capability requires depends on the corporation's registration country. Read the
requirement from the capability itself rather than assuming — verification_requirements on each entry
of GET /api/v1/corporations lists the levels and the order they are expected in.

Verification Statuses

None → Pending → Applied → InReview → Approved
                                   ↓
                          Rejected / Canceled

Only Approved counts. A level in any other status is treated as not passed by capability evaluation.

Step 1: Request an SDK Token for a Level

POST /api/v1/corporations/level-token

Requires Su. This is a superuser-only endpoint and cannot be delegated to a custom role.

Request body:

{
  "verification_level": "SDD"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

An unrecognised verification_level silently produces an SDD token. Only the literal value
N/A is rejected, with 400 ErrorInvalidField and
Verification level cannot be 'None' for this request. Any other unknown string — including an empty
one, a lowercase sdd, or a typo such as XDDBridge — falls through to SDD, and the corporation
ends up in the wrong review. Send one of the four documented values exactly as written.

Code

const response = await fetch(`${baseUrl}/api/v1/corporations/level-token`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${corporationToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ verification_level: 'SDD' })
});
const { token: sdkToken } = await response.json();

response = requests.post(
    f"{base_url}/api/v1/corporations/level-token",
    headers={
        "Authorization": f"Bearer {corporation_token}",
        "Content-Type": "application/json",
    },
    json={"verification_level": "SDD"},
)
sdk_token = response.json()["token"]

body, _ := json.Marshal(map[string]string{"verification_level": "SDD"})

req, _ := http.NewRequest("POST", baseURL+"/api/v1/corporations/level-token", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+corporationToken)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var tokenResp struct {
    Token string `json:"token"`
}
json.NewDecoder(resp.Body).Decode(&tokenResp)

Step 2: Open the SDK Session

Initialise the SumSub Web or Mobile SDK with the token from Step 1. The session runs entirely in the
SDK; Wirex receives the outcome from the provider.

Tokens are short-lived. Request a fresh one when the SDK reports an expired token rather than caching
it across sessions.

Step 3: Track the Result

Verification progress arrives two ways.

Webhook — POST {your_webhook_base_url}/v2/webhooks/corporations on each corporation change,
carrying the new verification_status. See Webhooks.

Read — GET /api/v1/corporations returns the per-level detail the webhook does not carry:

{
  "verification_status": "InReview",
  "verification_levels": [
    { "level": "SDD", "status": "Approved" },
    { "level": "EDD", "status": "InReview" }
  ],
  "passed_levels": ["SDD"],
  "capabilities": [
    {
      "type": "SepaAccount",
      "status": "ActivationNotStarted",
      "status_reason": "Account should be activated in order to use this capability",
      "verification_requirements": [{ "type": "SDD", "order": 1 }],
      "prerequisites": []
    }
  ]
}

SDD Shorthand

POST /api/v1/corporations/verification-token

Requires Su. Takes an empty body and returns an SDK token for SDD — it is
POST /api/v1/corporations/level-token with verification_level hard-wired to SDD.

{}

Use level-token for new integrations; it covers every level, including SDD.

What Happens Next

1. The corporation completes the SDK session; its level status moves to Applied.
2. The provider reviews; the level status moves to InReview.
3. On approval, the level status becomes Approved and the on-chain verification status is advanced by
   the Wirex oracle.
4. Capabilities whose verification_requirements are now satisfied move off NotFulfilled. Most then
   read ActivationNotStarted — verification unlocks a capability, it does not activate it. Bank
   account capabilities still need POST /api/v1/bank/accounts; see
   Activating Bank Account Details.
5. A corporation whose profile status reaches Active can use its approved capabilities.

Limitations

• There is no endpoint to submit or amend KYB data through the API. Everything is collected in the SDK.
• There is no endpoint to cancel or restart a verification. A Rejected level requires Wirex
  intervention.
• Employee-level identity verification is not exposed by the Corporate API. Employee records carry
  personal data for card embossing and delivery, not a verification status you can drive.

Error Handling

{
  "error_reason": "ErrorInvalidField",
  "error_description": "Verification level cannot be 'None' for this request",
  "error_category": {
    "category": "CategoryValidationFailure",
    "http_status_code": 400
  },
  "error_details": [
    { "key": "field", "details": "verification_level" }
  ]
}

Validation Errors (400)

Permission Errors (403)

Server Errors (500)