Menu

Settings and Settlement Webhooks

This guide explains how to set up settings webhooks.


There are three types of settings webhooks and one bank settlement webhook:

  1. MERCHANT_STATUS_UPDATE
  2. MERCHANT_ACCOUNT_UPDATE
  3. APM_STATUS_UPDATE
  4. SETTLEMENT

For general information about settings webhooks please refer to theOrders Webhooksguide, which explains how to:

  • Set up a webhook
  • Implement the webhooks receiver
  • Configure webhooks on the Worldpay website
  • Test the webhooks receiver

1. Merchant status update

When you activate your account, notifications containing merchant registration state and their keys will be sent to your configured webhook.

Copied!
{
  "notificationEventType" : "MERCHANT_STATUS_UPDATE",
  "merchantId" : "b2163722-e6cd-4db3-be90-80a59d70572334",
  "adminCode" : "Admin Code",
  "merchantCode" : "DEMO1",
  "keys" : [ {
    "keyType" : "CLIENT",
    "environment" : "TEST",
    "enabled" : true,
    "key" : "TEST_CLIENT_key"
  } ,
 {
    "keyType" : "SERVICE",
    "environment" : "TEST",
    "enabled" : true,
    "key" : "TEST_SERVICE_key"
  } ],
  "enabled" : true,
  "registrationStatus" : "BASIC | FULL | SENT_FOR_ACTIVATION | REFERRED"
}

You can generate your own test activation webhook by using the following curl command:

Copied!
curl https://your-server-name/your-webhook-endpoint 
    -H "Content-type: application/json" 
    -X POST 
    -d 
    '{ 
        "notificationEventType" : "MERCHANT_STATUS_UPDATE", 
        "merchantId" : "b2163722-e6cd-4db3-be90-80a59d70572334", 
        "adminCode" : "Admin Code", 
        "merchantCode" : "DEMO1", 
        "keys" : 
            [ 
                { 
                    "keyType" : "CLIENT", 
                    "environment" : "TEST", 
                    "enabled" : true, 
                    "key" : "TEST_CLIENT_key" 
                } , 
                { 
                    "keyType" : “SERVICE", 
                    "environment" : "TEST", 
                    "enabled" : true, 
                    "key" : "TEST_SERVICE_key" 
                } 
            ], 
        "enabled" : true, 
        "registrationStatus" : "SENT_FOR_ACTIVATION"
    }'

The registration state will reflect the current status of the merchant activation request in Worldpay’s onboarding systems.

Typical registration states are as follows:

  • Basic - test account only
  • Full - live account
  • Sent for activation - application form has been completed but not yet approved - test account only
  • Referred - application form has been completed and additional checks are required - test account only
  • Merchant disabled - account disabled

2. Merchant account update and merchant key reset

When merchant accounts are successfully updated or merchant keys are reset, notifications are sent to your webhook on completion. These do not contain full merchant information; if you update merchant accounts using the API, you are expected to manage the data in your own systems.

Copied!
{
  "notificationEventType" : "MERCHANT_STATUS_UPDATE",
  "merchantId" : "full_valid_merchant",
  "adminCode" : "Admin Code",
  "merchantCode" : "DEMO1",
  "keys" : [ {
    "keyType" : "CLIENT",
    "environment" : "TEST",
    "enabled" : false,
    "key" : "TEST_CLIENT_key"
  } ],
  "enabled" : false,
  "registrationStatus" : "BASIC"
}

You can generate your own test account update webhook by using the following curl command:

Copied!
curl https://your-server-name/your-webhook-endpoint 
    -H "Content-type: application/json" 
    -X POST 
    -d 
    '{        "notificationEventType" : "MERCHANT_STATUS_UPDATE",        "merchantId" : "full_valid_merchant",        "adminCode" : "Admin Code",        "merchantCode" : "DEMO1",        "keys" : [ 
            {                "keyType" : "CLIENT",                "environment" : "TEST",                "enabled" : false,                "key" : "TEST_CLIENT_key"            } 
        ],        "enabled" : false,        "registrationStatus" : "BASIC"
    }'

Note: When using this webhook to update merchant keys, it is the partner system’s responsibility to revoke/update the existing keys stored in their system. As all key resets are final only the newly provided keys sent via this notification will be valid once keys have been reset.

Copied!
{   "notificationEventType":"MERCHANT_ACCOUNT_UPDATE",
   "merchantId":"full_valid_merchant",
   "adminCode":"Admin Code",
   "merchantCode":"DEMO1"
}

You can also generate a test account update webhook yourself by using the following curl command:

Copied!
curl https://your-server-name/your-webhook-endpoint 
    -H "Content-type: application/json" 
    -X POST 
    -d '{        "notificationEventType":"MERCHANT_ACCOUNT_UPDATE",        "merchantId":"full_valid_merchant",        "adminCode":"Admin Code",        "merchantCode":"DEMO1"
    }'

3. Merchant APM updates

When APM settings are successfully updated, notifications are sent to your webhook on completion. If you update APM settings using the API, you are expected to manage the data in your own systems.

Copied!
{ 
   "notificationEventType":"APM_STATUS_UPDATE",
   "merchantId":"full_valid_merchant",
   "adminCode":"Admin Code",
   "ApmStatuses":{ 
      "PAYPAL":"SETUP_IN_PROGRESS"
   }
}

You can generate your own test APM update webhook by using the following curl command:

Copied!
curl https://your-server-name/your-webhook-endpoint -H "Content-type: application/json" -X POST -d '{ 
   "notificationEventType":"APM_STATUS_UPDATE",
   "merchantId":"full_valid_merchant",
   "adminCode":"Admin Code",
   "ApmStatuses":{ 
      "PAYPAL":"SETUP_IN_PROGRESS"
   }
}'

4. Bank Settlements

When a bank settlement is actioned, a notification is sent to your configured webhook.

This confirms the amount settled, currency and other related information for the merchant.

Copied!
{
  "notificationEventType" : "SETTLEMENT",
  "merchantId" : "full_valid_merchant",
  "adminCode" : "Admin Code",
  "merchantCode" : "DEMO1",
  "batchId" : "batch_id_1",
  "transferId" : "transfer_id_1",
  "settlementCurrency" : "GBP",
  "settlementAmount" : "1200.00",
  "settlementDate" : "2014-05-01"
}

You can generate your own test account update webhook by using the following CURL command:

Copied!
curl https://your-server-name/your-webhook-endpoint 
    -H "Content-type: application/json" 
    -X POST 
    -d '{        "notificationEventType" : "SETTLEMENT",        "merchantId" : "full_valid_merchant",        "adminCode" : "Admin Code",        "merchantCode" : "DEMO1",        "batchId" : "batch_id_1",        "settlementCurrency" : "GBP",        "settlementAmount" : "1200.00",        "settlementDate" : "2014-05-01"
    }'