Guides

Webhooks

Integration Guide

Suggest Edits

The webhook callback request informs the merchant back-end system of the payment transaction status. This is an asynchronous message in a separate HTTP transaction initiated from CellPoint Digital’s Velocity Payment Orchestration Platform. It is in addition to the synchronous response from the API when the user is redirected to the confirmation page.

Every time the transaction status changes, the status and additional transaction information are posted to the callback URL configured for the client. To see for which status code CellPoint Digital sends the callback, refer to Webhook Status Codes in Reference. For webhook parameters, see Webhook Parameters in Reference.

Prerequisite

Work with your CellPoint Digital sales representative or account manager to sign up, set up your test account, and access your testing credentials.

Workflow

When using CellPoint Digital Velocity webhooks, the workflow is as follows:

  1. Set up webhooks - The merchant uses one of two methods to request callbacks:
    1. During onboarding - The merchant provides a callback URL during CellPoint Digital's onboarding process to automatically receive a callback for every eligible transaction status change.
    2. In an Initialize API request - The merchant provides a callback URL in an Initialize API request to receive a callback for every eligible transaction status change for that transaction.
  2. Receive callback - Cellpoint Digital sends a callback request to the merchant's callback URL.
  3. Security check (optional) - The merchant uses the callback signature to perform an optional additional security check.

Integration

The steps below provide instructions for setting up and using webhooks with CellPoint Velocity.

1. Set up webhooks

You can set up webhooks by providing a callback URL during onboarding and/or when sending an Initialize request:

1a. During onboarding

At the time of merchant onboarding, CellPoint Digital asks you to provide a callback URL. This is optional. If you provide a callback URL at this stage, you will automatically receive a callback for every transaction at every applicable transaction status change, and you will not need to provide a callback URL at any other point in your workflow.

1b. In an Initialize request

You have the option to include a callback URL in an Initialize request. You may choose to do this if you did not provide a callback URL in onboarding or if you want to use a different callback URL than the one you gave in onboarding.

To do so, send an Initialize request with the URL as the text content of callback-url, as in the sample code snippet below:

<root>
	<initialize-payment account="[integer]" client-id="[integer]">
		<transaction order-no="testOrderId1" type-id="[integer]">
			<amount currency-id="[integer]">100</amount>
			<callback-url> [merchant callback url] </callback-url>...

For more information on Initialize requests, see API Quick Start and our Initialize API Reference.

Once you have sent this request and CellPoint Digital accepts the callback URL, you automatically receive a callback for this transaction at every applicable transaction status change.

🚧

NOTE: The callback URL in an Initialize request supersedes a callback URL that was provided during onboarding.

2. Receive callback

CellPoint Digital sends a POST request to the callback URL (provided in step 1) for every transaction status change listed in Webhook Status Codes in this site's Reference section.

Below is a sample payload of the JSON callback request sent to the merchant:

{
  "account_id": 100000,
  "callback_url": "URL",
  "client_id": 10600,
  "sale_amount": {
    "alpha3code": "NOK",
    "currency_id": 578,
    "decimals": 2,
    "value": 1210532
  },
  "session_id": 877777,
  "session_type": "1",
  "status": {
    "code": 4030,
    "message": "Session Complete",
    "sub_code": 2000101
  },
  "transactions": [
    {
      "accept_url": "URL",
      "additional_data": [
        {
          "name": "rule_id",
          "text": "7902"
        }
      ],
      "amount": {
        "alpha3code": "NOK",
        "conversion_rate": 1,
        "currency_id": 578,
        "decimals": 2,
        "value": 1210532
      },
      "approval_code": "111150",
      "cancel_url": "URL",
      "card": {
        "expiry": "12/27",
        "id": 7,
        "masked_card_number": "544444******4445",
        "name": "Master Card"
      },
      "customer_info": {
        "email": "[email protected]",
        "language": "en",
        "mobile": 2142142147,
        "operator": 10200
      },
      "date_time": "2027-01-02T13:27:23+00:00",
      "fee": 0,
      "hmac": "65425aaeb514648565f8a8a0665425aaeb514648565f8a8a0665425aaeb514648565f8a8a06dce5e3888fbd17c046a83ed45690565425aaeb514648565f8a8a06",
      "id": 5694589,
      "installment": 0,
      "ip_address": "49.248.250.130",
      "order_data": [],
      "order_id": "24DGFT",
      "payment_method": "CD",
      "payment_type": "1",
      "pos": 102,
      "product_type": 100,
      "psp": {
        "external_id": "811000000000243879",
        "id": 82,
        "name": "Name"
      },
      "route_config_id": 1235,
      "sale_amount": {
        "alpha3code": "NOK",
        "currency_id": 578,
        "decimals": 2,
        "value": 1210532
      },
      "status": {
        "code": 2000,
        "message": "Payment authorized by PSP",
        "sub_code": 2000101
      },
      "txn_type_id": 1
    }
  ],
  "signature": "175f37bb6094bbb2208e98f0faeda470920e6c079143c1573bef87174dbad43b756a9ee496ef6ef83a5d981467bc5ae6d7157d978a64e06f11d06cf8eb2b3cd8",
  "endpoint_url" : "URL",
  "content_type" : "3",
  "max_retry" : "3",
  "event_type" : "PAYMENT_EVENT",
  "event_subtype" : "PAYMENT_TRANSACTION_EVENT"
}

For more information, see Webhook Parameters in this site's Reference section.

Security check (optional)

You have the option to perform a security check on POST requests that CellPoint Digital sends to your callback URL by cross-checking the signature in the request payload.

To perform an optional security check, continue the workflow by following the steps below:

3. Remove extra attributes

Remove every extra attribute parameter and value from the callback request's payload (in step 2). That is, you should keep the following:

  • account_id
  • callback_url
  • client_id
  • sale_amount and its children
  • session_id
  • session_type
  • status and its children
  • transactions and its children.

Remove everything else. In the example above (in step 2), the extra attributes to remove are at the bottom of the payload: signature, endpoint_url, content_type, max_retry, event_type, and event_subtype.

Once you have removed the extra attributes, you will have a JSON code block that looks like the following:

{
  "account_id": 100000,
  "callback_url": "URL",
  "client_id": 10600,
  "sale_amount": {
    "alpha3code": "NOK",
    "currency_id": 578,
    "decimals": 2,
    "value": 1210532
  },
  "session_id": 877777,
  "session_type": "1",
  "status": {
    "code": 4030,
    "message": "Session Complete",
    "sub_code": 2000101
  },
  "transactions": [
    {
      "accept_url": "URL",
      "additional_data": [
        {
          "name": "rule_id",
          "text": "7902"
        }
      ],
      "amount": {
        "alpha3code": "NOK",
        "conversion_rate": 1,
        "currency_id": 578,
        "decimals": 2,
        "value": 1210532
      },
      "approval_code": "111150",
      "cancel_url": "URL",
      "card": {
        "expiry": "12/27",
        "id": 7,
        "masked_card_number": "544444******4445",
        "name": "Master Card"
      },
      "customer_info": {
        "email": "[email protected]",
        "language": "en",
        "mobile": 2142142147,
        "operator": 10200
      },
      "date_time": "2027-01-02T13:27:23+00:00",
      "fee": 0,
      "hmac": "65425aaeb514648565f8a8a0665425aaeb514648565f8a8a0665425aaeb514648565f8a8a06dce5e3888fbd17c046a83ed45690565425aaeb514648565f8a8a06",
      "id": 5694589,
      "installment": 0,
      "ip_address": "49.248.250.130",
      "order_data": [],
      "order_id": "24DGFT",
      "payment_method": "CD",
      "payment_type": "1",
      "pos": 102,
      "product_type": 100,
      "psp": {
        "external_id": "811000000000243879",
        "id": 82,
        "name": "Name"
      },
      "route_config_id": 1235,
      "sale_amount": {
        "alpha3code": "NOK",
        "currency_id": 578,
        "decimals": 2,
        "value": 1210532
      },
      "status": {
        "code": 2000,
        "message": "Payment authorized by PSP",
        "sub_code": 2000101
      },
      "txn_type_id": 1
    }
  ]
}

4. Create a canonical JSON string

After having removed the extra attributes, take the remaining JSON code block (from step 3) and create a canonical JSON string like the following:

{"account_id":106000,"callback_url":"https://jsonplaceholder.typicode.com/posts","client_id":10600,"sale_amount":{"alpha3code":"NOK","currency_id":578,"decimals":2,"value":1210532},"session_id":873797,"session_type":"1","status":{"code":4030,"message":"Session Complete","sub_code":2000101},"transactions":[{"accept_url":"https://hpp2.sit-01.cellpoint.dev/views/redirect_response.php","additional_data":[{"name":"rule_id","text":"7902"},{"name":"card-holder-name","text":"CL BRWA"},{"name":"invoiceid","text":"24DGFT"},{"name":"merchant","text":"7816526757210932602"},{"name":"TransactionID","text":"811000000000243879"}],"amount":{"alpha3code":"NOK","conversion_rate":1,"currency_id":578,"decimals":2,"value":1210532},"approval_code":"111150","cancel_url":"https://hpp2.sit-01.cellpoint.dev/views/redirect_response.php","card":{"expiry":"12/27","id":7,"masked_card_number":"533330******4276","name":"Master Card"},"customer_info":{"email":"[email protected]","language":"en","mobile":2147483647,"operator":10200},"date_time":"2022-12-02T13:27:23+00:00","fee":0,"hmac":"65425aaeb514648565f8a8a06d9d05d62619aa1fe89221c24e52df59967bfaf48398eae0dce5e3888fbd17c046a83ed45690516b0c98aced468fa8bfc82773ce","id":5694589,"installment":0,"ip_address":"49.248.250.130","order_data":[],"order_id":"24DGFT","payment_method":"CD","payment_type":"1","pos":102,"product_type":100,"psp":{"external_id":"811000000000243879","id":82,"name":"Nuvei"},"route_config_id":1235,"sale_amount":{"alpha3code":"NOK","currency_id":578,"decimals":2,"value":1210532},"status":{"code":2000,"message":"Payment authorized by PSP","sub_code":2000101},"txn_type_id":1}]}

For more information, see RFC 8785: JSON Canonicalization Scheme (JCS).

5. Append salt

Append your salt value to the end of the canonical JSON string (from step 4). See the example below, where the salt value is az1sx2dc3fv:

{"account_id":106000,"callback_url":"https://jsonplaceholder.typicode.com/posts","client_id":10600,"sale_amount":{"alpha3code":"NOK","currency_id":578,"decimals":2,"value":1210532},"session_id":873797,"session_type":"1","status":{"code":4030,"message":"Session Complete","sub_code":2000101},"transactions":[{"accept_url":"https://hpp2.sit-01.cellpoint.dev/views/redirect_response.php","additional_data":[{"name":"rule_id","text":"7902"},{"name":"card-holder-name","text":"CL BRWA"},{"name":"invoiceid","text":"24DGFT"},{"name":"merchant","text":"7816526757210932602"},{"name":"TransactionID","text":"811000000000243879"}],"amount":{"alpha3code":"NOK","conversion_rate":1,"currency_id":578,"decimals":2,"value":1210532},"approval_code":"111150","cancel_url":"https://hpp2.sit-01.cellpoint.dev/views/redirect_response.php","card":{"expiry":"12/27","id":7,"masked_card_number":"533330******4276","name":"Master Card"},"customer_info":{"email":"[email protected]","language":"en","mobile":2147483647,"operator":10200},"date_time":"2022-12-02T13:27:23+00:00","fee":0,"hmac":"65425aaeb514648565f8a8a06d9d05d62619aa1fe89221c24e52df59967bfaf48398eae0dce5e3888fbd17c046a83ed45690516b0c98aced468fa8bfc82773ce","id":5694589,"installment":0,"ip_address":"49.248.250.130","order_data":[],"order_id":"24DGFT","payment_method":"CD","payment_type":"1","pos":102,"product_type":100,"psp":{"external_id":"811000000000243879","id":82,"name":"Nuvei"},"route_config_id":1235,"sale_amount":{"alpha3code":"NOK","currency_id":578,"decimals":2,"value":1210532},"status":{"code":2000,"message":"Payment authorized by PSP","sub_code":2000101},"txn_type_id":1}]}az1sx2dc3fv

📘

Salt

The "salt" is the merchant's shared secret string. CellPoint Digital provides the salt value to merchants.

6. Generate the SHA-512 hash value

After appending your salt, take the resulting string (from step 5) and use it to generate a SHA-512 hash value, as in the example below:

175f37bb6094bbb2208e98f0faeda470920e6c079143c1573bef87174dbad43b756a9ee496ef6ef83a5d981467bc5ae6d7157d978a64e06f11d06cf8eb2b3cd8

The security check succeeds if this value is identical to the value of signature in the original payload (step 2).

Updated 4 days ago