Webhooks

Listen for transaction events on your Primer account so you can automatically trigger reactions in your integration.

Receiving webhooks

Transaction webhook notifications allow you to be notified of:

Opened disputes or chargebacks by a configured payment processor. This enables you to take action with the processing gateway and resolve the dispute.
Requests processed asynchronously. Some payment processors complete a payment asynchronously and will notify Primer of the change. We process this callback and trigger a notification, updating you on the transaction state change.

Setting up an endpoint

You can set up a webhook endpoint through your Dashboard:

1
Log in and head over to the Developers area on your Dashboard.
2
In the Webhooks section, click on the Add button.
3
Fill in the following fields:
- Name: A descriptive string for the webhook configuration.
- Endpoint URL: The endpoint we should send notifications to. Make sure that this is a public URL.
- Trigger on: A checklist of events that will trigger notifications.
4
Click Create.

add a webhook

Testing an endpoint

You can test a webhook endpoint from the Developers area on your Dashboard. In the Webhooks section, select one of your newly configured webhooks and click on the Test connection button.

testing a webhook

This will send a POST request to the configured destination with the example payload shown below. Any response outside the 2XX range, including 3XX HTTP redirection codes, means the test has failed. Failed notification attempts are retried up to five times with a five-second timeout between each retry.

1
2
3
{
  "message": "Testing your webhook connection"
}

json

Webhook structure and event types

Notifications will either hold information about transaction updates or a dispute against the transaction.

Transactions

Transaction notifications contain the following fields:

Fields	Description
eventType	The type of event that triggered the notification. Refer to the table of events below for more information on supported events.
primerAccountId	The unique identifier of your Primer account.
transactionId	The unique identifier of the original Primer transaction.
transactionStatus	The transaction lifecycle status. Possible values can be found here.
eventStatus	The generated event outcome. Possible values are `SUCCESS`, `FAILED` or `PROCESSING`.
orderId	Your reference for the transaction.

Example transaction event payload:

1
2
3
4
5
6
7
8
{
    "eventType": "TRANSACTION.AUTHORIZATION",
    "primerAccountId": "7fcd50f1-99f2-416e-8013-6ecd1c1285c3",
    "transactionId": "c3f662ad-d197-492e-b78b-63eefa64a31d",
    "transactionStatus": "SETTLING",
    "eventStatus": "SUCCESS",
    "orderId": "order-123"
}

json

Below are the possible values for the eventType field:

Event Type	Description
`TRANSACTION.AUTHORIZATION`	A payment has been successfully approved or declined by the gateway or financial institution. If unsuccessful, the transaction fails. The request can sometimes be completed asynchronously during which you will receive multiple notifications about the transaction moving from Pending to Authorized or Failed status.
`TRANSACTION.SETTLEMENT`	A payment is successfully transferring funds or has been declined by the gateway or financial institution. This is a transitory state. The notifications are generated even if the transaction was authorized and submitted for capture at the same time. The transaction can likely fail here due to expired authorization, insufficient funds or gateway rules.
`TRANSACTION.SETTLED`	Final confirmation of funds being transferred by the financial institution.
`TRANSACTION.REFUND`	A refund has either been successfully issued or has failed. A payment can only be refunded after it has reached Settled status.
`TRANSACTION.CANCEL`	A payment has either been successfully cancelled or has failed. A payment can only be cancelled before it has reached Settled status.

Disputes

Dispute notifications contain the following fields:

Fields	Description
eventType	This will have the value `DISPUTE.OPENED`. This indicates that a dispute notification or chargeback was issued through a configured connection. The easiest actions you can take are to proactively communicate with your customer and issue refunds where appropriate, especially when requested.
primerAccountId	A unique identifier of your Primer merchant account.
transactionId	A unique identifier of the original Primer payment.
orderId	Your reference for the sale transaction that the dispute relates to.
processorId	The name of the processor that generated the dispute.
processorDisputeId	A unique identifier of the corresponding connection dispute.

Example dispute event payload:

1
2
3
4
5
6
7
8
{
    "eventType": "DISPUTE.OPENED",
    "primerAccountId": "7fcd50f1-99f2-416e-8013-6ecd1c1285c3",
    "transactionId": "c3f662ad-d197-492e-b78b-63eefa64a31d",
    "orderId": "order-123",
    "processorId": "Adyen",
    "processorDisputeId": "adyen_ref_123"
}

json

← 06. Workflows