Settings

⚙️
Webhook URL settings
The target URL to which HTTP POST requests will be sent needs to be provided to your integration manager, and confirmation should be received that it has been added to the partner settings on Paybis end.

Available webhooks

1. Verification Status Update

This webhook is called for each case when the user initiates/completes SumSub KYC verification in PnP wallets application, when crypto transaction is initiated.

Webhook messages are sent on the following status update events:

started - user initiated the KYC verification process but the final application status hasn't been yet received from SumSub OR RETRY result is returned (the user is supposed to resubmit the requested documents).
approved - KYC application was approved (GREEN result is received from SumSub).
failed - KYC application was rejected (RED final reject is received from SumSub).

Event parameters:

Parameter	Description
`partnerUserId`	The customer's unique ID in the partner's system used in the POST Request endpoint.
`status`	KYC verification status of the customer with corresponding `partnerUserId`. Possible values: Started, Approved, Failed.
`timestamp`	The time when the KYC verification status was updated in Unix 10-digit epoch time format.
`residenceCountry`	Two-letter ISO code of the country where user was verified.

Example webhook payload with verification-started status:

{
  "event": "VERIFICATION_STATUS_UPDATED",
  "data": {
    "partnerUserId":"e18fb964-fd9a-4de7-96c4-u1dq8a1ddd1",
    "status":"started"
  },
  "timestamp":1653593988
}

Example webhook payload with basic-verification-failed status:

If the verification has been failed, the residenceCountry parameter is set to null.

{
  "event": "VERIFICATION_STATUS_UPDATED",
  "data": {
    "partnerUserId":"e18fb964-fd9a-4de7-96c4-u1dq8a1ddd1",
    "status":"failed",
    "residenceCountry": null
  },
  "timestamp":1653593988
}

Example webhook payload with basic-verification-approved status:

Additional parameter residenceCountry is set to the country of the verification.

{
  "event": "VERIFICATION_STATUS_UPDATED",
  "data": {
    "partnerUserId":"e18fb964-fd9a-4de7-96c4-u1dq8a1ddd1",
    "status":"approved",
    "residenceCountry": "LV"
  },
  "timestamp":1653593988
}

📘
Shared access token
If you are using the Shared KYC solution, you can call the v1/sumsub/shared-token endpoint to retrieve the Shared Access Token for approved applicants. Shared token can be used to import applicant´s KYC data from SumSub.

2. Crypto Transaction Status

This webhook provides real-time updates on the status of cryptocurrency checkout transactions within the Plug'n'Play Wallets flow. The webhook is executed using HTTP POST method and contains JSON data with a CRYPTO_CHECKOUT_TRANSACTION_CHANGED event inside.

Webhook messages are sent on the following status update events:

confirming - transaction is being confirmed on the blockchain, and the required number of confirmations is not yet reached.
completed - transaction has been successfully completed, and the funds have been transferred to the designated wallet.
canceled - transaction has been canceled by the user or the system.
failed - transaction has failed due to an error, such as insufficient funds or network issues.

Webhook Structure

The webhook is sent via HTTP POST and contains a JSON payload with the following structure:

{
    "event": "CRYPTO_CHECKOUT_TRANSACTION_CHANGED",
    "data": {
        "cryptoCheckoutId": "9f6e6fb2-e1c7-4aa6-828c-f7c48df2a457",
        "transaction": {
            "hash": "047489836f7cbc7a5e41120bbe9a8007cac6179ab3108d673da7ff15b20aefee",
            "status": "completed",
            "fromAddress": {
                "address": "TKzB2CW95MLpP8yHXvKoQsAJjiyGDX4jDw"
            },
            "toAddress": {
                "address": "TCd9qHyjqiUkfTxe3gotbuTMpju8LEbpkN"
            },
            "explorerLink": "https://blockchain.list",
            "assetId": "USDT-TRC20",
            "amount": {
                "amount": "200.00",
                "currency": "USDT"
            },
            "networkFee": {
                "amount": "4.00",
                "currency": "USD"
            },
            "createdAt": "2024-05-29T14:52:42+00:00"
        }
    },
    "timestamp": 1718620483
}

Event parameters:

Parameter	Description
`cryptoCheckoutId`	The unique identifier of the checkout session.
`transaction.hash`	Unique identifier of the transaction on the blockchain (available only for completed and confirming statuses).
`transaction.status`	Current status of the transaction (`confirming`, `completed`, `canceled`, or `failed`).
`transaction.fromAddress.address`	The address from which the cryptocurrency was sent.
`transaction.toAddress.address`	The address to which the cryptocurrency was sent.
`transaction.explorerLink`	A link to the block explorer where the transaction details can be viewed.
`transaction.assetId`	The identifier of the crypto asset used in the transaction (e.g., USDT-TRC20).
`transaction.amount.amount`	The amount of cryptocurrency involved in the transaction.
`transaction.amount.currency`	The cryptocurrency used in the transaction (e.g., USDT).
`transaction.networkFee.amount`	The amount of network fee charged for the transaction.
`transaction.networkFee.currency`	The currency in which the network fee was charged (e.g., USD).
`transaction.createdAt`	The date and time when the transaction was created in ISO 8601 format.
`timestamp`	The time when the webhook message was sent in Unix 10-digit epoch time format.

Retry policy

The HTTP 2xx responses indicate that our webhook call was successful. If your server returns any other response, we retry up to 80 times with the exponential backoff (backoff multiplier = 2). The first retry is made in 10 sec after unsuccessful response. The maximum delay between the retries is limited to 6 h: when this limit is reached, multiplier no longer applies.

Security

For your safety we sign each webhook message with the 4096 bit RSA key using the RSASSA_PSS_SHA_512 asymmetric signing algorithm. The signature is encoded to base64 and sent with the original request in the X-Request-Signature header.

Use our public key to verify incoming POST calls.

Production public key:

Sandbox environment public key:

Signature validation example: node.js

const crypto = require("crypto");

const publicKey = `-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEApR7LLr506sbJjzs5BuBf
Ubu5Efi+fFN3XlGx6wrKimZ5OSSImHOA8T5fRy/teRriD/92+V18pAh6jmMR7r9E
nnIskJ45IwlMbrp6HRQ5GGt2phHxwj31MvkB+JahqDZrJ6GCwWSd/i7gZjizLy03
pxzV1Sw02342pQMtHX8QgwV5j3/J8Btez5bANHZn5Zp9FS9N6pkedOiZWjiSWOFQ
YUk73VhyW5TjXN5MYQ6FlHmPdwm/Qe/x4DZYXLNAMlFL8Tsb3xNkekJiJPKyr0h2
vqmbEdc9WYtaJAilVS6Yt0QOJtymmQsowCbP7mUFW/i7q8ayjrRUyLnzmoR8H+yY
G+B8lcpu7Aqt0lxUTMRm5KwnTkUyZrimwReWE8LVc68Ae7t4Qxj1dN6nLegDWO7G
BynD7D8ESJ6bNp6GCbc5ntY1T5g+HIGrff7DclcYfzu6RNVgKFlnLxue9J6iJv8q
4wFtn3OM3hxDG/SDk+YUlXiVeUNjPjoA8Z4aEE7OkJBouykLVSiHn4nVrN0WZ1+y
ouYyGwFbL2Vw5G4QR+bi3CZP6rYk9X3A8/xzXjDSYoAqK1+0/7Qncmapbr1Id8qc
huUr+tJq91Ua+EjpdjfaxOrSVBts0iYujY0ahrVCFYBlqu89MSOW4tM4BEgkOeN/
IrZj8Jj85onbaoJr1svCpZUCAwEAAQ==
-----END PUBLIC KEY-----`;

const message = '{"event":"VERIFICATION_STATUS_UPDATED","data":{"partnerUserId":"e18fb964-fd9a-4de7-96c4-1lclszzd","status":"started"},"timestamp":1654073212}'
var signature = 'jcbM5ysMZuQnUplcBOTqOiPQ3jOsIgl+imMy+AJtbTlvYG3c62WKyYTtm9BvBSuplEvhxOKoe9RBHjYkYsvaOelZr+RcnHkhg1EzEVXfaISJDA6fUyi38uGkWihVnzBjkDvZf7mgpY/4a4q3A+7dN2m5yNQPwPlf/HdExeNQTnrLEANB0rHDa5X091ID5E6vZjccF4/52MkrKdW+9DVbcqT7QLfFwaTxO/E90Aal3tGt/HqE+Ybhw+RocNl14elXeWUm8TtEOn7sr23RxskrBJkuVf68k2zD9zdKiPU7bB94ughqQUbz+6zln8W2F5PugIDkRFbrcigesL1xuR0fRfZJPmqRkaRyy6bZ4mNAisQAo+lBwzQOmowuT+8c/UgS3xU6KT1UF7+W8fj1J4JQ//TjMwWKkYDSpx8fAMGs458jh4+FmrnzFwE9XwXeTDPf38OeREZ7e7AHptyEKfZojjkVbdYtHrQjdqHdkXT35JF23uuItxMEEIEh6jy4STdjHcgl5e1V2N9QNg6V/0Cqax5at60I6oek8iMLgBLnSVOh8DNBSj5Fdt8fQ+kLZj6Q/S+9E9PP2L96Abw9qvexNGpSX2ShgQdkDbe/RsbpN+ORHOfPnnvdzXKsYR4iiVD23GNrsh4QgBd5rbwI7KgloCovpdQhjiyV07g/qBAg+kM';

const verified = crypto.verify(
  'sha512',
  Buffer.from(message),
  {
	key: publicKey,
	padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
  },
  Buffer.from(signature, 'base64'),
)

console.log("Verified:", verified);

Signature validation example: PHP

<?php

use phpseclib\Crypt\RSA;

$publicKey = <<<PUBKEY
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEApR7LLr506sbJjzs5BuBf
Ubu5Efi+fFN3XlGx6wrKimZ5OSSImHOA8T5fRy/teRriD/92+V18pAh6jmMR7r9E
nnIskJ45IwlMbrp6HRQ5GGt2phHxwj31MvkB+JahqDZrJ6GCwWSd/i7gZjizLy03
pxzV1Sw02342pQMtHX8QgwV5j3/J8Btez5bANHZn5Zp9FS9N6pkedOiZWjiSWOFQ
YUk73VhyW5TjXN5MYQ6FlHmPdwm/Qe/x4DZYXLNAMlFL8Tsb3xNkekJiJPKyr0h2
vqmbEdc9WYtaJAilVS6Yt0QOJtymmQsowCbP7mUFW/i7q8ayjrRUyLnzmoR8H+yY
G+B8lcpu7Aqt0lxUTMRm5KwnTkUyZrimwReWE8LVc68Ae7t4Qxj1dN6nLegDWO7G
BynD7D8ESJ6bNp6GCbc5ntY1T5g+HIGrff7DclcYfzu6RNVgKFlnLxue9J6iJv8q
4wFtn3OM3hxDG/SDk+YUlXiVeUNjPjoA8Z4aEE7OkJBouykLVSiHn4nVrN0WZ1+y
ouYyGwFbL2Vw5G4QR+bi3CZP6rYk9X3A8/xzXjDSYoAqK1+0/7Qncmapbr1Id8qc
huUr+tJq91Ua+EjpdjfaxOrSVBts0iYujY0ahrVCFYBlqu89MSOW4tM4BEgkOeN/
IrZj8Jj85onbaoJr1svCpZUCAwEAAQ==
-----END PUBLIC KEY-----
PUBKEY;
$message = '{"event":"VERIFICATION_STATUS_UPDATED","data":{"partnerUserId":"e18fb964-fd9a-4de7-96c4-1lclszzd","status":"started"},"timestamp":1654073212}';
$signature = 'jcbM5ysMZuQnUplcBOTqOiPQ3jOsIgl+imMy+AJtbTlvYG3c62WKyYTtm9BvBSuplEvhxOKoe9RBHjYkYsvaOelZr+RcnHkhg1EzEVXfaISJDA6fUyi38uGkWihVnzBjkDvZf7mgpY/4a4q3A+7dN2m5yNQPwPlf/HdExeNQTnrLEANB0rHDa5X091ID5E6vZjccF4/52MkrKdW+9DVbcqT7QLfFwaTxO/E90Aal3tGt/HqE+Ybhw+RocNl14elXeWUm8TtEOn7sr23RxskrBJkuVf68k2zD9zdKiPU7bB94ughqQUbz+6zln8W2F5PugIDkRFbrcigesL1xuR0fRfZJPmqRkaRyy6bZ4mNAisQAo+lBwzQOmowuT+8c/UgS3xU6KT1UF7+W8fj1J4JQ//TjMwWKkYDSpx8fAMGs458jh4+FmrnzFwE9XwXeTDPf38OeREZ7e7AHptyEKfZojjkVbdYtHrQjdqHdkXT35JF23uuItxMEEIEh6jy4STdjHcgl5e1V2N9QNg6V/0Cqax5at60I6oek8iMLgBLnSVOh8DNBSj5Fdt8fQ+kLZj6Q/S+9E9PP2L96Abw9qvexNGpSX2ShgQdkDbe/RsbpN+ORHOfPnnvdzXKsYR4iiVD23GNrsh4QgBd5rbwI7KgloCovpdQhjiyV07g/qBAg+kM';

$verifier = new \phpseclib\Crypt\RSA();
$verifier->setSignatureMode(RSA::SIGNATURE_PSS);
$verifier->setHash('sha512');
$verifier->setMGFHash('sha512');
$verifier->loadKey($publicKey);

$valid = $verifier->verify(addcslashes($message, '/'), base64_decode($signature));

🚧
Note that you should use version 2.0 of the phpseclib/phpseclib library: phpseclib/phpseclib:^2.

Webhooks for Plug'n'Play Wallets

Settings

⚙️
Webhook URL settings

Available webhooks

1. Verification Status Update

📘
Shared access token

2. Crypto Transaction Status

Retry policy

Security

Signature validation example: node.js

Signature validation example: PHP

🚧

Settings

⚙️Webhook URL settings

Available webhooks

1. Verification Status Update

📘Shared access token

2. Crypto Transaction Status

Retry policy

Security

Signature validation example: node.js

Signature validation example: PHP

🚧

⚙️
Webhook URL settings

📘
Shared access token