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

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:
- 1Log in and head over to Primer Dashboard > Developer section.
- 2In the Webhooks section, click on the Add button.
- 3Fill 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.
- 4Click Create.
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
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.
123
{"message": "Testing your webhook connection"}
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 areSUCCESS
FAILED
orPROCESSING
.orderId
: Your reference for the transaction.
Example event payload
12345678
{"eventType": "TRANSACTION.AUTHORIZATION","primerAccountId": "7fcd50f1-99f2-416e-8013-6ecd1c1285c3","transactionId": "c3f662ad-d197-492e-b78b-63eefa64a31d","transactionStatus": "SETTLING","eventStatus": "SUCCESS","orderId": "example_ref"}
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
12345678
{"eventType": "DISPUTE.OPENED","primerAccountId": "7fcd50f1-99f2-416e-8013-6ecd1c1285c3","transactionId": "c3f662ad-d197-492e-b78b-63eefa64a31d","orderId": "example_ref","processorId": "Adyen","processorDisputeId": "adyen_ref_123"}
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. |