# Onboard a compliance provider

Source: https://docs.settlemint.com/docs/developer-guides/compliance/onboarding-a-provider
Operator guide for adding Sumsub or Elliptic in the DALP dapp, configuring
provider webhooks, and reaching an active compliance-provider integration.




DALP administrators and compliance managers add provider integrations in the dapp, then configure provider webhook delivery and subject mapping.

For API subject mapping after the integration is active, see [Map compliance-provider subjects](/docs/developer-guides/compliance/compliance-provider-subjects). For endpoint and schema details, see [Compliance provider API reference](/docs/developer-guides/compliance/compliance-provider-api-reference).

## Prerequisites [#prerequisites]

* A DALP user with the `admin`, `systemManager`, or `complianceManager` role on the active organisation.
* A Sumsub account with an app token and secret key, or an Elliptic account with API key and API secret.
* Access to the provider dashboard where webhook destinations and signing secrets are configured.
* An operational trusted issuer registry for the DALP organisation.

## Add the integration in DALP [#add-the-integration-in-dalp]

<Steps>
  <Step>
    ### Open the provider section [#open-the-provider-section]

    In the dapp, go to **Platform Settings → Compliance providers → Add integration**.
  </Step>

  <Step>
    ### Select the provider [#select-the-provider]

    Choose one provider:

    * **Sumsub** for identity verdict topics such as `knowYourCustomer`, `antiMoneyLaundering`, `accreditedInvestor`, and `regulationS`. Sumsub applicant-on-hold events also appear as monitoring alerts for the integration.
    * **Elliptic** for wallet monitoring. The topic selector shows wallet-monitoring topics.

    Each integration declares exactly one claim topic. If one provider workflow covers multiple topics, create one integration per topic.
  </Step>

  <Step>
    ### Enter write-only credentials [#enter-write-only-credentials]

    Sumsub asks for **App token** and **Secret key**. Elliptic asks for **API key** and **API secret**. DALP also asks for the **webhook signing secret** that you configure in the provider dashboard.

    Credentials are encrypted and never displayed back. The dapp validates the credential shape before provisioning starts.
  </Step>

  <Step>
    ### Set the revocation threshold [#set-the-revocation-threshold]

    For monitoring alerts, select the severity tier that should revoke claims for this integration. The default threshold is `80`, shown in the dapp as the **High** tier.

    Sumsub applicant-review verdicts issue or revoke claims from the verdict state. Sumsub applicant-on-hold events and Elliptic wallet alerts use severity-based monitoring behaviour.
  </Step>

  <Step>
    ### Wait for provisioning [#wait-for-provisioning]

    After credential validation, DALP provisions the provider issuer EOA and registers it as a trusted issuer for the integration's claim topic.

    The integration status can be:

    * `pending`: provisioning or trusted-issuer registration is still in progress
    * `active`: webhook intake is ready
    * `paused`: intake is paused by an operator
    * `failed`: provisioning failed and can be retried
    * `revoked`: the integration has been revoked

    If provisioning fails, open the integration detail page and use **Retry provisioning**. The retry is idempotent.
  </Step>

  <Step>
    ### Copy the webhook URL [#copy-the-webhook-url]

    On completion, DALP opens the integration detail page. Copy the webhook URL:

    ```text
    https://your-platform.example.com/api/webhooks/compliance/<provider>/<integrationId>/<urlToken>
    ```

    The URL token is partially masked by default in the UI. Use the reveal toggle before copying the full URL.
  </Step>
</Steps>

## Configure the provider dashboard [#configure-the-provider-dashboard]

### Sumsub [#sumsub]

In the Sumsub dashboard, go to **Dev space → Webhooks → Webhook manager → Create webhook**. Sumsub documents the flow in its [Webhook manager guide](https://docs.sumsub.com/docs/webhook-manager).

* Use the DALP webhook URL as the HTTP address.
* Configure the same webhook signing secret you entered in DALP.
* Sumsub sends `x-payload-digest-alg` and `x-payload-digest`; DALP verifies the digest against the raw request body.

### Elliptic [#elliptic]

Configure alert webhook delivery to the DALP webhook URL in Elliptic. Elliptic documents alert webhooks in [Rescreening and Alerting](https://developers.elliptic.co/docs/rescreening-and-alerting) and API authentication in [Manual Integration](https://developers.elliptic.co/docs/authentication).

* Use the DALP webhook URL as the destination.
* Configure the same webhook signing secret you entered in DALP.
* Elliptic sends `x-elliptic-signature`; DALP verifies the HMAC-SHA256 digest against the raw request body.

## After activation [#after-activation]

An active integration can receive webhooks, but DALP still needs a subject mapping before a provider event can affect claims.

* For Sumsub, create an applicant mapping for the DALP identity.
* For Elliptic, register the wallet so DALP can resolve it to its on-chain identity.

Follow [Map compliance-provider subjects](/docs/developer-guides/compliance/compliance-provider-subjects) for the API calls.

## Troubleshooting [#troubleshooting]

* **Provisioning failed.** Use **Retry provisioning** on the integration detail page. The retry picks up existing provisioning work and only retries steps that did not land.
* **Webhook signature rejected.** Confirm the provider dashboard's signing secret matches the one entered in DALP. Confirm the provider sends the expected signature header.
* **Webhook accepted but no claim appeared.** Confirm the subject was mapped before the webhook was sent. If the subject was unmapped at delivery time, the event is retained for audit without an on-chain claim effect; map the subject before the next provider event.
* **Monitoring tab is empty.** Monitoring rows appear only after Sumsub applicant-on-hold events or Elliptic wallet alerts arrive. Use the Identity view for issued or revoked claims from Sumsub applicant-review verdicts.
* **Need to rotate the webhook signing secret.** Use **Rotate signing secret** on the integration detail page to stage the new secret. Update the provider dashboard to use the new secret. Promote the secret before the grace window expires. The existing active secret remains valid until promotion.

## See also [#see-also]

* [Choose a KYC issuance path](/docs/developer-guides/compliance/choose-kyc-issuance-path)
* [Map compliance-provider subjects](/docs/developer-guides/compliance/compliance-provider-subjects)
* [Compliance provider API reference](/docs/developer-guides/compliance/compliance-provider-api-reference)
* [How compliance provider intake works](/docs/architecture/integrations/compliance-providers)