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 the merchant the transaction state change.

Setting up an endpoint

You can set up a webhook endpoint through Primer Dashboard:

1
Log in and head over to Primer Dashboard > Developer section.
2
In the Webhooks section, click on the Add button.
3
Fill in the following fields:
- Name: Descriptive string for the configuration.
- Endpoint URL: Make sure that this is a public URL.
- Trigger on: Checklist of all events that will trigger the notification.
4
Click Create.

add a webhook

Testing an endpoint

You can test a webhook endpoint from the Primer Dashboard. From within the Developer page in the Primer Dashboard, click on a connection and check using the Test connection button

testing a webhook

This will send a POST request to the configured destination with the example body shown below. Any response outside the 2XX range, including 3XX HTTP redirection codes, classify the test as a failure. 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:

eventType : The type of event that triggered the notification. Refer to the table of events below for more information around supported events and their meaning.
primerAccountId : A unique identifier of your Primer merchant account.
transactionId : A unique identifier for the original Primer payment.
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 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": "example_ref"
}

json

`eventType`	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 multiple notifications will notify of the transaction move 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 failed. A payment can be refunded only after it has reached "SETTLING" status.
`TRANSACTION.CANCEL`	A payment has either been successfully cancelled request or failed. A payment can be cancelled only before it has reached "SETTLING" status.

Disputes

Dispute notifications contain the following fields:

eventType : The type of event that triggered the notification. Refer to the table of events below for more information around supported events and their meaning.
primerAccountId : A unique identifier for your Primer merchant account.
transactionId : A unique identifier for the original Primer payment.
orderId : Your reference for the sale transaction the dispute relates to.
processorId: The type of connection that generated the dispute.
processorDisputeId : A unique identifier of the corresponding connection dispute.

Example 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": "example_ref",
    "processorId": "Adyen",
    "processorDisputeId": "adyen_ref_123"
}

json

`eventType`	Description
`DISPUTE.OPENED`	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.

← 06. Workflows