Webhooks

Get notified about payment updates

A Webhook is a notification sent from Primer to your server. Webhooks will notify you of:

payment status updates
This is especially useful for asynchronous processor Connections, which do not respond with an upfront authorization.
opened disputes/chargebacks
Be notified of disputes across all processors in a unified way.
completed refunds
Primer notifies you when a refund request has been fully processed by a payment processor and the refund has reached a final state.

webhooks

Setting up Webhooks

Set up a Webhook in the Developers area of the Dashboard. Webhooks are sent with a POST request to your designated endpoint.

add a webhook

Failed notification attempts are retried up to three times with a five-second interval.

Testing Webhooks

Click the Test webhook link to test your Webhook endpoint.

test a webhook

This will send a POST request to your destination with the example payload shown below. Any response outside the 2XX range, including 3XX HTTP redirection codes, will result in a failure.

123{    "message": "Testing your webhook connection"}

json

copy

Webhook types

Status updates

Payment status notifications are sent when a payment's status has been updated. The webhook body contains the full payment object.

Example payment status notification:

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465{   "eventType":"PAYMENT.STATUS",   "date":"2021-02-21T15:36:16.367687",   "notificationConfig":{      "id":"cc51f9f0-7e1c-492b-9d37-f83a818f6070",      "description":"Payment webhook"   },   "version":"2.1",   "payment":{      "id":"DdRZ6YY0",      "date":"2022-01-01T12:12:12.000000",      "amount":3000,      "currencyCode":"GBP",      "customerId":"cust-123",      "orderId":"order-123",      "status":"SETTLED",      "paymentMethod":{         "paymentMethodToken":"-lcWjvBAAs2DnIRXwxNjUzNTYzNjIy",         "analyticsId":"LUi5pETUaVsdSEamK25L",         "paymentMethodType":"PAYMENT_CARD",         "paymentMethodData":{            "last4Digits":"1111",            "expirationMonth":"03",            "expirationYear":"2030",            "cardholderName":"ADYEN",            "network":"Visa",            "isNetworkTokenized":false,            "binData":{               "network":"VISA",               "issuerCountryCode":"US",               "issuerName":"JPMORGAN CHASE BANK, N.A.",               "regionalRestriction":"UNKNOWN",               "accountNumberType":"UNKNOWN",               "accountFundingType":"UNKNOWN",               "prepaidReloadableIndicator":"NOT_APPLICABLE",               "productUsageType":"UNKNOWN",               "productCode":"UNKNOWN",               "productName":"UNKNOWN"            },            "cvvAvailable":true         },         "threeDSecureAuthentication":{            "responseCode":"NOT_PERFORMED"         }      },      "processor":{         "name":"STRIPE",         "processorMerchantId":"acct_1GORasdasqNWFwi8c",         "amountCaptured":3000,         "amountRefunded":0      },      "transactions":[         {            "date":"2022-05-26T11:14:11.946300",            "amount":3000,            "currencyCode":"GBP",            "transactionType":"SALE",            "processorTransactionId":"pi_3L3edsGZasdasdc1iget38p",            "processorName":"STRIPE",            "processorMerchantId":"acct_1GORasvasdNWFwi8c",            "processorStatus":"SETTLED"         }      ]   }}

json

copy

Refunds

Refund notifications are triggered when a refund reaches a final state.

Check the most recent REFUND transaction in the transactions.status object to view the outcome:

if SETTLED, the refund was successful and the funds have been returned to the customer.
if FAILED, the refund was unsuccessful.

Example refund notification:

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475{   "eventType":"PAYMENT.REFUND",   "date":"2021-02-21T15:36:16.367687",   "notificationConfig":{      "id":"cc51f9f0-7e1c-492b-9d37-f83a818f6070",      "description":"Refund webhook"   },   "version":"2.1",   "payment":{      "id":"DdRZ6YY0",      "date":"2022-01-01T12:12:12.000000",      "amount":3000,      "currencyCode":"GBP",      "customerId":"cust-123",      "orderId":"order-123",      "status":"SETTLED",      "paymentMethod":{         "paymentMethodToken":"-lcWjvBASh2EpYaHgVwxNjUzNTYzNjIy",         "analyticsId":"LUi5pETUV2EpYaHgV77SEamK25L",         "paymentMethodType":"PAYMENT_CARD",         "paymentMethodData":{            "last4Digits":"1111",            "expirationMonth":"03",            "expirationYear":"2030",            "cardholderName":"ADYEN",            "network":"Visa",            "isNetworkTokenized":false,            "binData":{               "network":"VISA",               "issuerCountryCode":"US",               "issuerName":"JPMORGAN CHASE BANK, N.A.",               "regionalRestriction":"UNKNOWN",               "accountNumberType":"UNKNOWN",               "accountFundingType":"UNKNOWN",               "prepaidReloadableIndicator":"NOT_APPLICABLE",               "productUsageType":"UNKNOWN",               "productCode":"UNKNOWN",               "productName":"UNKNOWN"            },            "cvvAvailable":true         },         "threeDSecureAuthentication":{            "responseCode":"NOT_PERFORMED"         }      },      "processor":{         "name":"STRIPE",         "processorMerchantId":"acct_1G2EpYaHgVZqNWFwi8c",         "amountCaptured":3000,         "amountRefunded":3000      },      "transactions":[         {            "date":"2022-05-26T11:14:11.946300",            "amount":3000,            "currencyCode":"GBP",            "transactionType":"SALE",            "processorTransactionId":"pi_3L3ed23NWFwiNWFwi8c1iget38p",            "processorName":"STRIPE",            "processorMerchantId":"acct_1GORcaGv23NWFwi8c",            "processorStatus":"SETTLED"         },         {            "date":"2022-05-26T11:14:11.946300",            "amount":3000,            "currencyCode":"GBP",            "transactionType":"REFUND",            "processorTransactionId":"pi_3L3ed23NWFwiNWFwi8c1iget38p",            "processorName":"STRIPE",            "processorMerchantId":"acct_1GORcaGv23NWFwi8c",            "processorStatus":"SETTLED"         }      ]   }}

json

copy

Disputes & chargebacks

Dispute notifications trigger on newly opened disputes or chargebacks.

Field	Description
eventType	The type of event that triggered the webhook. 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 for your Primer merchant account.
transactionId	A unique identifier for the Primer transaction corresponding to this dispute.
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 for the corresponding connection dispute.
paymentId	A unique identifier for the Primer payment corresponding to this dispute.

Example dispute notification:

12345678910111213141516{   "eventType":"DISPUTE.OPENED",   "version":"2.1",   "primerAccountId":"7fcd50f1-99f2-416e-8013-6ecd1c1285c3",   "transactionId":"c3f662ad-d197-492e-b78b-63eefa64a31d",   "orderId":"order-123",   "processorId":"Adyen",   "processorDisputeId":"adyen_ref_123",   "paymentId":"ecb8d3bc-805d-4d97-826e-ef8d4cc3d2a2",   "raw_processor_callback":{      "example":{         "raw_callback":"request",         "from":"Adyen"      }   }}

json

copy