MassPay menu

Webhooks

Use webhooks to get notified about payment events.

What is a webhook

Webhooks are a very important part of our payment process. We use webhooks to share information about an event that happened. These events could range from transactions updates to fraud rule triggers.

For security reasons the event details we send to you contain only a very small portion of information about that particular event.

Type of webhooks

  • Transaction updates
  • Refund updates
  • Chargeback updates
  • Tag rule trigger
  • Anti fraud rule trigger
  • Subscription updates

Sample webhook

This is a sample webhook for a transaction update: 

{
    "type": "transaction",
    "id": "c3c5ee57-25bd-4e98-b328-809417924f1d",
    "status": "SETTLEMENT_REQUESTED"
}

Webhook parameters

Field Optional Description
type no Type of item this webhook is connected to
Options: transaction, refund, chargeback, cardlink, validationruleset, report_generated, subscription
id no Item ID of the item this webhook is connected to
status yes The status change this webhook communicates
Options are based on type;
transaction: INITIATED, IN_PROGRESS, PENDING, AUTHORIZED, SETTLEMENT_REQUESTED, SETTLEMENT_COMPLETED, DECLINED, FAILED, UNKNOWN, ABANDONED, CANCELLED, AUTHORIZATION_VOIDED
refund: PENDING, PROCESSED, CANCELLED, FAILED, HOLD, UNKNOWN
chargeback: OPEN, IN_DISPUTE, WON, LOST, CANCELLED
cardlink: CREATED, INITIATED, DONE, CANCELLED, EXPIRED subscription: CREATED, ACTIVE, PAST_DUE, EXPIRED, CANCELLED, COMPLETED
status_reason yes Status reason details. Example; the reason why a transaction has been declined
amount yes The item amount in cents
Only available when type in: transaction, refund, chargeback
merchant_reference yes Reference specified by the merchant to identify the transaction
Only available when type is transaction
paymentlink_id yes ID of the paymentlink used to create this transaction
Only available when type is transaction
subscription_id yes ID of the subscription used to create this transaction
Only available when type is transaction

Integrating webhooks

You can configure transaction, refund and chargeback webhooks via the payment profile object.
See: API documentation.

Alternatively, it's possible to set the webhook url per transaction (Start transaction).
Transaction field: webhook_transaction_update.

Receiving a webhook

When the webhook is sent to the merchant's URL we expect the merchant's server to respond with a status code 200 - OK.

If the webhook is not successfully received we will make 11 attempts to resend the webhook in:
1m, 2m, 4m, 8m, ... 1024m(~17h).

Validating a webhook

To ensure that the Webhook originated from MassPay, all our Webhooks are digitally signed.

Read more about webhook signature verification