Purpose: Onboard an individual already verified in Sumsub by importing a share token, waiting for Reap's verification-completed webhook and retrieving a tamper-evident signed identity payload for downstream card issuance while Reap performs its own independent review.

When to Use This

This guide is intended for clients already using the Sumsub system who want to avoid repeating the KYC process for applicants. Verified token sharing lets Reap reuse an applicant's existing Sumsub verification through a share token, so the applicant does not need to complete the KYC process again.

Use this guide when you need to:

• Reuse an applicant's completed Sumsub verification instead of collecting identity data again
• Ingest a single Sumsub share token synchronously and receive an immediate processing result
• Associate one or more card processor public tokens with the entity at ingestion time
• Wait for Reap's asynchronous verification-completed webhook before continuing
• Retrieve the cryptographically signed identity payload for an entity once verification is complete
• Operate under Reap's non-reliance model where Reap performs its own review and issues the final decision

Overview

Verified Token Sharing allows integrators to share an already-verified applicant with Reap using a Sumsub share token, avoiding the need to resubmit identity details and documents.

Reap imports the shared applicant information, performs its own review under a non-reliance model, and communicates the final outcome asynchronously. The integrator can retrieve a signed identity payload containing the verified identity information once the review is complete,.

The flow is designed to support clear request tracking, consistent error handling, and secure sharing of verified identity data between systems.

Prerequisites

1. Compliance approval from Reap to use Verified Token Sharing for the program
2. An applicant already verified in Sumsub with a share token generated for that applicant
3. Agreement that Reap retains the final approval authority under its non-reliance model
4. A valid Reap API key to authenticate every request via the x-reap-api-key header
5. Use the externalId value as the correlation reference for the entity.

Key Concepts

Share Token

• Short-lived token issued by Sumsub that represents an already-verified applicant
• Supplied as shareToken in the ingestion request and consumed on first successful use
• A consumed token cannot be reused and a fresh token is required for each new attempt

External ID

• Unique identifier for the applicant within the originating system.
• Supplied as externalId and echoed back in every ingestion response
• Correlates the Reap entity with the internal record

Entity ID

• Reap's UUID for the entity created or updated by the ingestion
• Used as the entityId path parameter when retrieving the signed identity payload

Request ID

• Returned in every response as requestId
• Links a single request to Reap’s server-side logs for support investigation

Signed Identity Payload

• Portable, tamper-evident representation of the verified identity for an entity
• Retrieved via GET /entity/entityId/signed-payload once verification is complete
• Carries the verified identity fields plus a cryptographic signature for integrity verification

Non-Reliance Model

• Reap performs its own independent review of the imported applicant
• Successful ingestion does not mean the applicant is verified as Reap provides the final outcome.
• The signed identity payload becomes available only after Reap completes that review

Flow Overview

1. Register a webhook endpoint via POST /notification to receive account_status_change events
2. Ingest the Sumsub share token via POST /entity/kyc/import/sync, supplying externalId, shareToken, and optionally cardProcessorPublicToken
3. Receive Reap’s verification-completed webhook after the independent review is complete
4. Retrieve the signed identity payload via GET /entity/entityId/signed-payload using the entity's Reap entityId
5. Create the card via POST /cards

API Summary

Verified Token Sharing (Non-Reliance)

Step 1: Set Up Webhooks

Register a webhook endpoint with Reap's Compliance API to receive asynchronous KYC decision updates. Clients must register a webhook before receiving webhook responses.

Call the Notification Endpoint

Use POST /notification to subscribe a webhook endpoint to receive account_status_change events.

Sample Request (cURL)

curl --request POST \
  --url https://sandbox-compliance.api.reap.global/notification \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-reap-api-key: ********' \
  --data '{
    "webhookUrl": "https://api.example.com",
    "notificationChannel": "WEBHOOK",
    "notificationTypes": ["account_status_change"]
  }'

Key Input

Sample Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "channel": "WEBHOOK",
  "types": [
    "account_status_change"
  ],
  "config": {
    "webhook": {
      "url": "https://api.example.com"
    }
  },
  "createdAt": "2024-03-20T10:00:00Z"
}

Key Output

Step 2: Ingest the Sumsub Share Token

Synchronously ingest a single Sumsub share token for an applicant that has already been verified. The record is processed immediately, and the response returns a completed status alongside a requestId for support correlation. The supplied externalId becomes the correlation reference for the entity and is returned back on every response.

Call the Sync Ingestion Endpoint

Use POST /entity/kyc/import/sync to synchronously ingest a single Sumsub share token against the entity identified by the externalId.

Sample Request (cURL)

curl --request POST \
  --url https://sandbox-compliance.api.reap.global/entity/kyc/import/sync \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-reap-api-key: ********' \
  --data '{
    "externalId": "ef88fd57-26cf-415d-a112-941732c55350",
    "shareToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "cardProcessorPublicToken": "tok_abc123|tok_def456"
  }'

Key Input

Sample Response

{
  "externalId": "ef88fd57-26cf-415d-a112-941732c55350",
  "status": "completed",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Key Output

Step 3: Receive the Verification Webhook

Reap will perform an independent review under the non-reliance model after the share token is ingested and notify the registered webhook endpoint once verification is complete. Continue to Step 4 only after receiving this notification.

Sample Notification Webhook

The KYC decision is communicated via webhook notification.

{
  "eventName": "card_issuance_api_access_updated",
  "eventType": "account_status_change",
  "data": {
    "eventId": "938c65f7-2aad-494d-b488-5256c4cfc370",
    "message": "Card Issuance KYC API access updated",
    "entityId": "6ac28264-c21b-4757-b141-1efce00adce6",
    "timestamp": "2026-01-27T13:27:51.027Z",
    "status": "APPROVED"
  }
}

{
  "eventName": "card_issuance_api_access_updated",
  "eventType": "account_status_change",
  "data": {
    "eventId": "938c65f7-2aad-494d-b488-5256c4cfc370",
    "message": "Card Issuance KYC API access updated",
    "entityId": "6ac28264-c21b-4757-b141-1efce00adce6",
    "timestamp": "2026-01-27T13:27:51.027Z",
    "status": "REJECTED",
    "moderationComment": "Sumsub did not approve the applicant.",
    "rejectLabels": ["DOCUMENT_QUALITY"],
    "reviewRejectType": "FINAL"
  }
}

Webhook Outcomes

Rejection Reasons

The webhook payload includes the rejection reason through the moderationComment, rejectLabels, and reviewRejectType fields when the decision is REJECTED.

Step 4: Generate the Signed Identity Payload

The signed identity payload is a portable record of the entity’s verified identity that can be checked for tampering. Retrieve it after Reap sends the verification-completed webhook. It includes the verified identity fields and a cryptographic signature that allows its integrity to be verified.

Call the Signed Payload Endpoint

Use GET /entity/entityId/signed-payload to retrieve the signed identity payload for the entity.

Sample Request (cURL)

curl --request GET \
  --url https://sandbox-compliance.api.reap.global/entity/entityId/signed-payload \
  --header 'Accept: application/json' \
  --header 'x-reap-api-key: ********'

Key Input

Sample Response

{
  "firstName": "Jack",
  "lastName": "Sam Ong",
  "dob": "1994-06-18",
  "idDocumentType": "Passport",
  "idDocumentNumber": "K1234567",
  "residentialAddress": {
    "line1": "Flat 1208, 350, TIFF Bell Lightbox, King Street West",
    "line2": "Downtown",
    "city": "Toronto",
    "country": "CAN",
    "postalCode": "M5V 3L9"
  },
  "expiresAt": "2026-03-10T09:18:51.998Z",
  "signature": "bd6565bfb621f6321095e7dc574ea52b3829e29a732440170794fabfc8dec..."
}

Key Output

residentialAddress (object)

Step 5: Create Card

The signed payload returned in Step 4 must be passed into the Create Card endpoint when creating a card.

Call the Create Card Endpoint

Use POST /cards to create the card and include the signed payload in the request body.

Sample Request (cURL)

curl --request POST \
  --url https://sandbox-compliance.api.reap.global/cards \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Accept-Version: v2.0' \
  --header 'x-reap-api-key: ********' \
  --data '{
    "...": "...",
    "kyc": {
      "firstName": "Jack",
      "lastName": "Sam Ong",
      "dob": "1994-06-18",
      "idDocumentType": "Passport",
      "idDocumentNumber": "K1234567",
      "residentialAddress": {
        "line1": "Flat 1208, 350, TIFF Bell Lightbox, King Street West",
        "line2": "Downtown",
        "city": "Toronto",
        "country": "CAN",
        "postalCode": "M5V 3L9"
      },
      "expiresAt": "2026-03-10T09:18:51.998Z",
      "signature": "bd6565bfb621f6321095e7dc574ea52b3829e29a732440170794fabfc8dec..."
    },
    "...": "..."
  }'

Key Input

kyc (object)

Sample Response

{
  "id": "fa1bcdae-c101-4986-b385-8083fb43a7ab"
}

Key Output

Scenarios

Scenario: Standard Verified Token Reuse

• Generate a share token in Sumsub for the already-verified applicant
• Ingest it via POST /entity/kyc/import/sync with the externalId and the shareToken, receiving status: "completed"
• Wait for Reap's verification-completed webhook
• Retrieve the signed identity payload via GET entity/entityId/signed-payload
• Create the card via POST /cards

Scenario: BIN Sponsorship Client

• Generate a share token in Sumsub for the already-verified applicant
• Ingest it via POST /entity/kyc/import/sync with the externalId, the shareToken, and the cardProcessorPublicToken for the sponsored BIN
• Wait for Reap's verification-completed webhook
• Stop after receiving the verification webhook.
• BIN sponsorship clients do not need to generate signed payloads, so Step 4 and Step 5 do not apply

Common Errors

TL;DR

• Verified Token Sharing reuses an existing Sumsub verification through a single share token under Reap’s non-reliance model
• Register a webhook endpoint with POST /notification to receive account_status_change events before ingesting any share tokens
• Ingest synchronously with POST /entity/kyc/import/sync by supplying externalId and shareToken plus the optional cardProcessorPublicToken field where needed, noting that a completed status confirms ingestion rather than the final decision
• Reap reviews the applicant independently and sends a completion update by webhook once the contract is pending as described in Step 3
• Retrieve the signed identity payload with GET /entity/entityId/signed-payload which includes the verified identity fields and a cryptographic signature after receiving the webhook
• Create the card via POST /cardsby following Step 5 of the card creation process once the signed identity payload is retrieved