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.
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.
Testing Webhooks
Click the Test webhook link to test your Webhook endpoint.
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"}
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" } ] }}
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" } ] }}
Disputes & chargebacks
Dispute notifications trigger on newly opened disputes or chargebacks.
Field | Description |
---|---|
| 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. |
| A unique identifier for your Primer merchant account. |
| A unique identifier for the Primer transaction corresponding to this dispute. |
| Your reference for the sale transaction that the dispute relates to. |
| The name of the processor that generated the dispute. |
| A unique identifier for the corresponding connection dispute. |
| 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" } }}