Merchant Notifications

Payment - Webhooks

Naspay servers may notify merchants automatically when transaction status is updated by making HTTP requests to merchants’ web server. This is called webhooks. A webhook listener is a server that listens for incoming HTTP POST notification messages that are triggered when events occur.

To create a webhook, merchant provide a webhook listener URL for corresponding merchant terminal in Merchant Portal.

It is required to use secure HTTP connection for webhooks. Please use https: schema in webhook URLs.

Webhooks are sent when transaction reaches one of the following states:

  • COMPLETED
  • ON_HOLD (when Payment Intent was SALE)
  • AUTHORIZED (when Payment Intent was AUTHORIZE)
  • DECLINED
  • CANCELLED
  • VOIDED
  • PARTIALLY_REFUNDED
  • REFUNDED
  • TIMEOUT
  • ERROR

For example, when the transaction state is changed from Merchant Portal, a TransactionChangedEvent is issued and webhook is triggered.

Webhooks will be sent whenever the state of the resource changes. Certain activity may lead to the same event being sent more than once.

Example webhook:

POST /webhook HTTP/1.1
Host: www.example.com
Content-Type: application/json
{
  "type": "TransactionChangedEvent",
  "operationType": "REFUND",
  "operationState": "COMPLETED",
  "created": "2017-05-19T08:27:49.402Z",
  "transaction": {
    "type": "REFUND",
    "id": "345e3802528841bea67dc76744b76ab8",
    "amount": 59.02,
    "currency": "USD",
    "created": "2017-05-19T08:27:49.199Z",
    "updated": "2017-05-19T08:27:49.402Z",
    "state": "COMPLETED",
    "description": "Refund request",
    "maskedPan": "400000...0002",
    "paymentTransactionId": "70eb665c254140558921dfd479a5f390",
    "merchantCustomerId": "cus-123456",
    "customerEmail": "andy@example.com",
    "customerAccountId": "paypal_user_123"
  }
}

Example webhook for declined operation (note the error property):

POST /webhook HTTP/1.1
Host: www.example.com
Content-Type: application/json
{
    "type": "TransactionChangedEvent",
    "created": "2017-01-19T11:45:55.251Z",
    "operationType": "REFUND",
    "operationState": "DECLINED",
    "error": {
        "code": "06.40.000",
        "description": "General Decline by Bank"
    },
    "transaction": {
        "id": "96a8c187f15f4bc3a9f553abc4e2d714",
        "type": "PURCHASE",
        "created": "2017-01-18T13:32:14.543Z",
        "updated": "2017-01-19T11:45:55.161Z",
        "state": "PARTIALLY_REFUNDED",
        "amount": 119.32,
        "currency": "USD",
        "refundedAmount": 42.32,
        "maskedPan": "400000...0002",
        "merchantTransactionId": "MTID383057",
        "description": "Just purchase",
        "chargebackState": "CHARGEBACK_REFUNDED"
    }
}

Payment - Responding to a webhook

To acknowledge that you received the webhook, your server should return a 200 or 201 HTTP status code. Any other information returned in the response headers or response body will be ignored.

Any response code other then 200 and 201, including 3xx codes, will indicate to Naspay that the webhook is not received. In this case Naspay can send another webhook after some time. Webhook will be repeated 9 times - after 1, 5, 15, 30, 60, 120, 180, 360 and 720 minutes. Repeated webhooks are optional, consult your integration manager.

Payment - Email Notifications

Naspay may send email notifications when transaction status is changed.

Notification email will be sent when transaction reaches one of the following states:

  • COMPLETED
  • ON_HOLD (when Payment Intent was SALE)
  • AUTHORIZED (when Payment Intent was AUTHORIZE)
  • DECLINED
  • CANCELLED
  • VOIDED
  • PARTIALLY_REFUNDED
  • REFUNDED
  • TIMEOUT

Merchant should provide email address for notifications during integration process.

Identification - Webhooks

Naspay servers may notify merchants automatically when identification transaction status is updated by making HTTP requests to merchants’ web server. This is called webhooks. A webhook listener is a server that listens for incoming HTTP POST notification messages that are triggered when events occur.

To create a webhook, merchant provide a webhook listener URL in the Identification Login & Registration requests.

It is required to use secure HTTP connection for webhooks. Please use https: schema in webhook URLs.

Webhooks are sent when transaction reaches one of the following states:

  • COMPLETED
  • DECLINED

An IdentWebhookResponse object is sent when the Identification Merchant webhook is called.

Example webhook:

POST /webhook HTTP/1.1
Host: www.example.com
Content-Type: application/json
{
      "merchantTransactionId": "mtid_ZjQzMjM2Y2NhZTk1"
      "id": "6d353a24d1d24b49bf69fc0cb4d25b8a",
      "identToken": "6556-ffrxzxxryzn0ovki08ca",
      "merchantCustomerId": "mtid_ZjQzMjM2Y2NhZTk1",
      "transactionState": "COMPLETED",
      "resultCode": "00.00.000",
      "personData": {
          "id": "1111111112",
          "name": "Johan Hedberg",
          "address": {
              "street": "Toringsgatan 41",
              "city": "Stockholm",
              "country": "SE",
              "postalCode": "10121"
          },
          "phone": "+46701231231",
          "phones": [
              {
                  "phone": "+46701231231",
                  "type": "MOBILE"
              },
              {
                  "phone": "+46701231232",
                  "type": "MOBILE"
              },
              {
                  "phone": "+4680111231233",
                  "type": "OTHER"
              }
          ],
          "firstName": "Johan",
          "firstNames": [
              "Johan",
              "Kim",
              "Kattla"
          ],
          "lastName": "Hedberg",
          "gender": "MALE"
      }
}

Example webhook for declined identification transactions:

POST /webhook HTTP/1.1
Host: www.example.com
Content-Type: application/json
{
    "id": "13e29f7ff1774d3e96298b9ddcb3ebd7",
    "merchantCustomerId": "mtid_ZDc4YTQ3YmJhZDFj",
    "transactionState": "DECLINED",
    "resultCode": "09.40.016",
    "merchantTransactionId": "mtid_ZDc4YTQ3YmJhZDFj"
}

Identification - Responding to a webhook

To acknowledge that you received the webhook, your server should return a 200 or 201 HTTP status code. Any other information returned in the response headers or response body will be ignored.

Any response code other then 200 and 201, including 3xx codes, will indicate to Naspay that the webhook is not received.