Purpose: Onboard an individual already verified in Sumsub by importing a share token, waiting for Reap's verification webhook and retrieving a tamper-evident signed identity payload for downstream card issuance. Reap enforces its own verification standard and issues the final decision.

When to Use This

TThis 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 — provided the verification was performed against a Reap-defined Sumsub Partner Level.

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

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, validates it against a Reap-defined Sumsub Partner Level, and communicates the final outcome asynchronously. The integrator can retrieve a signed identity payload containing the verified identity information once the outcome is APPROVED.

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

Prerequisites

1. Confirmation with Reap Account Manager on using Verified Token Sharing for the program
2. A signed Sumsub Reusable KYC Agreement authorising the donor company as the donor and Reap as the recipient
3. Reap added as an authorised recipient in the donor Sumsub account using the token provided by the Reap Account Manager
4. An applicant already verified in Sumsub, with a share token generated for that applicant specifying Reap as the recipient via forClientId = reap.global_116803
5. A registered webhook endpoint. Reap's decision is delivered by webhook and is not available from any other endpoint
6. A valid Reap API key to authenticate every request via the x-reap-api-key header
7. 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
• Must be generated with Reap as the recipient by setting forClientId = reap.global_116803
• Expires 1,200 seconds (20 minutes) after generation and must be shared with Reap before expiry
• 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
• Must remain the same for the same cardholder across every card lifecycle event

Entity ID

• Reap's UUID for the entity created or updated by the ingestion
• Returned as entityId in the ingestion response
• Used as the entityId path parameter when retrieving the signed identity payloadRequest ID

Signed Identity Payload

• Portable, tamper-evident representation of the verified identity for an entity
• Retrieved via GET /entity/entityId/signed-payload once Reap's decision is APPROVED
• Carries the verified identity fields, an expiresAt timestamp, and a cryptographic signature
• Required at card creation for standard card issuance programs where Reap sits in the card creation path. Not used by BIN sponsorship programs

Enforced Verification Level

• Reap enforces its shared Partner Level for every ingested applicant using an exact match on the level name
• The enforced levels are KYC via API and KYC via API (with POA)
• A share token generated against any other level fails ingestion with the SHARE_TOKEN_LEVEL_MISMATCH error
• An applicant that does not meet the enforced level is rejected on the verification webhook with the LEVEL_ENFORCED_MISMATCH label and a RETRY reject type

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 and shareToken, plus cardProcessorPublicToken, which is mandatory for BIN sponsorship clients
3. Receive Reap's verification webhook once the decision is made
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, passing the signed payload into the kyc object

API Summary

Verified Token Sharing

Step 1: Set Up Webhooks

Register a webhook endpoint with Reap's Compliance API to receive Reap's KYC decision. Registration is required before any share token is ingested — the decision is delivered by webhook and is not retrievable from another endpoint.

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": "123456789|987654321"
  }'

Key Input

Sample Response

{
  "externalId": "ef88fd57-26cf-415d-a112-941732c55350",
  "status": "completed",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  "entityId": "b3d7e2f1-4a5c-6d8e-9f0a-1b2c3d4e5f6a"

}

Key Output

Step 3: Receive the Verification Webhook

Reap validates the shared applicant against the enforced Partner Level and notifies the registered webhook endpoint with the decision. Continue to Step 4 only after receiving an APPROVED decision.

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: Retrieve the Signed Identity Payload

The signed identity payload is Reap's tamper-evident attestation that the entity passed Reap's checks. Retrieve it after the APPROVED webhook. It carries the verified identity fields, an expiry, and a cryptographic signature.

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: ********'

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

Pass the signed payload returned in Step 4 into the Create Card endpoint. The recommended pattern is to copy the full signed-payload response into the kyc object rather than re-entering fields manually, which surfaces data and eligibility problems at Step 4 instead of at card creation.

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 1: Standard Card Issuance Clients

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

Scenario 2: BIN Sponsorship Client

• Generate a share token in Sumsub for the applicant, verified against a Reap-defined Partner Level
• Ingest it via POST /entity/kyc/import/sync with the externalId, the shareToken, and the cardProcessorPublicToken
• Wait for Reap's webhook for KYC decision. Every card must remain linked to an approved Reap KYC record via cardProcessorPublicToken
• Steps 4 and 5 do not apply. Reap is not in the card creation path, so there is no signed payload and no Create Card call

Common Errors

TL;DR

• Verified Token Sharing reuses an existing Sumsub verification through a single share token, where the applicant must have been verified against a Reap-defined Sumsub Partner Level
• 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 cardProcessorPublicToken, which is mandatory for BIN sponsorship clients, noting that a completed status confirms ingestion rather than the final decision
• Reap validates the applicant against the enforced level and delivers APPROVED or REJECTED by webhook, with reviewRejectType distinguishing a correctable RETRY from a non-correctable FINAL
• Retrieve the signed identity payload with GET /entity/entityId/signed-payload after the APPROVED webhook, then pass it into POST /cards
• BIN sponsorship programs skip Steps 4 and 5. Instead, every card must stay linked to an approved KYC record via cardProcessorPublicToken