Registering webhooks

You can register simplified webhooks for a merchant ID or payout account ID.

To configure simplified webhooks for a merchant ID or payout account ID, follow the steps below:

  1. Determine whether you want to add a webhook for transactions (through the merchant ID) or for payouts (through the payout account ID).

  2. If needed, check your access rights for the merchant ID or payout account ID.

    In order to configure webhooks for a merchant, you must have administrator access to that merchant account.
    If you know that your user has sufficient rights, skip to step 3.

    To check your account's access rights, send a request to the Who am I endpoint in the User Management Service.

    In the example below, the user has authorization to configure webhooks for merchant ID 100039 and payout account ID 3927.

    Example Access Rights
    {
      "payoutAccessRights": {
        "3927": "A" // Admin access
      },
      "accessRights": {
        "merchantIds": {
          "100039": "A", // Admin access
          "100040": "W", // Write access
          "100068": "R" // Read-only access
        },
        "role": "A"
      }
    }
    

📘

Try it out . . .

  1. Go to the Who am I endpoint.

  2. Type your username and password in the Authentication section.

  3. Click the Try it! button.

    The response should include lots of parameters, including the objects and parameters in the example above.

    If you get anything other than a 200 Response, check that you provided a valid username and password. If that does not help, contact us for more assistance.

  1. If needed, get a list of existing simplified webhooks by sending a GET request to the View webhook URLs by ID and type endpoint.

    The following examples request the webhooks for a specified merchant ID (100039) and a specified payout account ID (3927).

    curl --request GET \
      --url https://api.nexiopaysandbox.com/webhook/v3/webhookUrls/100039/MERCHANT \
      --header 'Authorization: Basic [Base64_encoded_login]' \
      --header 'Content-Type: application/json'
    
    curl --request GET \
      --url https://api.nexiopaysandbox.com/webhook/v3/webhookUrls/3927/PAYOUT_ACCOUNT \
      --header 'Authorization: Basic [Base64_encoded_login]' \
      --header 'Content-Type: application/json'
    


    The response lists any configured webhook URLs in a webhookUrls array.

    {
      "dateCreated": "2022-01-14T16:46:56.393Z",
      "dateLastModified": "2022-03-24T21:55:02.998Z",
      "webhookUrls": [
        "https://your-ecommerce-website.example.com?webhook12345",
        "https://webhook.site/ca1002e9-1f52-4733-a1a4-db05e93f7064"
      ],
      "merchantId": "100039"
    }
    
    {
      "dateCreated": "2022-03-24T21:36:03.375Z",
      "dateLastModified": "2022-03-24T21:36:03.375Z",
      "webhookUrls": [
        "https://webhook.site/1d255420-876e-43ba-b2d6-640101c505ad"
      ],
      "payoutAccountId": "3927"
    }
    

    📘

    Try it out . . .

    1. Go to the View webhook URLs by ID and type endpoint.

    2. Type a value for the id that is either a merchant ID or a payout account ID.

    3. Type a value for the webhook_type that is either MERCHANT or PAYOUT_ACCOUNT, depending on the ID you use.

    4. Type your username and password in the Authentication section.

    5. Click the Try it! button.

      The response should include lots of parameters, including the objects and parameters in the example above.

      If you get anything other than a 200 Response, check that you provided a valid username and password. If that does not help, contact us for more assistance.

    If the webhookUrls array contains any values, copy any that you want to keep and use them in the next step.


  2. Send a POST request to the Register webhook URLs endpoint.
    Include either a merchant ID or payout account ID and the webhook URLs you want to register. If you are adding to existing URLs, you also need the existing registered ones (see step 3).

    The example below configures a second webhook for merchant ID 100039 to be sent to https://your-ecommerce-website.example.com/123abc when a transaction status changes.

    Example Request
    curl -X POST https://api.nexiopaysandbox.com/webhook/v3/webhookUrls \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Basic [Base64_encoded_login]'
      -d '{
      "merchantId": "100039",
      "webhookUrls": [
        "https://your-ecommerce-website.example.com/123abc",
        "https://webhook.site/ca1002e9-1f52-4733-a1a4-db05e93f7064"
      ]
    }'
    

    This returns a response similar to the following:

    Example Request
    {
      "dateLastModified": "2022-03-25T21:42:41.528Z",
      "dateCreated": "2022-01-14T16:46:56.393Z",
      "webhookUrls": [
        "https://your-ecommerce-website.example.com/123abc",
        "https://webhook.site/ca1002e9-1f52-4733-a1a4-db05e93f7064"
      ],
      "merchantId": "100039"
    }
    

    📘

    Try it out . . .

    1. Go to the Register webhook URLs endpoint.

    2. Type your username and password in the Authentication section.

    3. Type a value for the merchantId or the payoutAccountId.

    4. Type one or more webhook URLs (click ADD STRING to add a second and subsequent URLs). Make sure to include any existing URLs that are registered, unless you want to delete them.

    5. Click the Try it! button.

      The response should include lots of parameters, including the objects and parameters in the example above.

      If you get anything other than a 200 Response, check that you provided a valid username and password. If that does not help, contact us for more assistance.