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:

12345678910111213141516171819202122232425262728293031323334353637383940414243444546
{    "eventType": "PAYMENT.STATUS",    "date": "2021-02-21T15:36:16.367687",    "notificationConfig": {        "id": "cc51f9f0-7e1c-492b-9d37-f83a818f6070",        "description": "Payment webhook"    },    "payment": {        "id": "kHdEw9EG",        "date": "2021-02-21T15:36:16.367687",        "status": "PENDING",        "orderId": "order-123",        "processor": "STRIPE",        "processorMerchantId": "acct_stripe_1234",        "currencyCode": "EUR",        "amount": 42,        "amountAuthorized": 0,        "amountCaptured": 0,        "amountRefunded": 0,        "statementDescriptor": "Purchase: socks",        "paymentInstrument": {            "token": "heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4",            "analyticsId": "VtkMDAxZW5isH0HsbbNxZ3lo",            "tokenType": "SINGLE_USE",            "paymentInstrumentType": "PAYMENT_CARD",            "paymentInstrumentData": {}        },        "customer": {            "id": "customer-123",            "email": "customer123@gmail.com"        },        "metadata": {            "productId": 123,            "merchantId": "a13bsd62s"        },    "transactions": [        {            "id": "1bbb016c5a654c4eb5b3ef8a80437124",            "type": "SALE",            "status": "AUTHORIZED",            "processor": "STRIPE",            "processorMerchantId": "acct_stripe_1234"        }    ],    }}
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:

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172
{  "eventType": "PAYMENT.REFUND",  "date": "2021-07-26 09:00:45.531493",  "notificationConfig": {    "id": "1b174b5c-e247-45e5-b561-e4f21a14bd4c",    "description": "Test refund"  },  "payment": {    "id": "2K5A6cpb",    "date": "2021-07-15T12:18:48.531261",    "status": "SETTLED",    "orderId": "938f01e0-0aae-4484-8407-be9fa3ac9332",    "processor": "STRIPE",    "processorMerchantId": "acct_1GORcsGZqNWFwi8c",    "currencyCode": "EUR",    "amount": 2223,    "amountAuthorized": 2223,    "amountCaptured": 2223,    "amountRefunded": 2223,    "requiredAction": null,    "statementDescriptor": "Purchase: socks",    "paymentInstrument": {      "token": "jeB6ZUZ0RCKbz6rg1nne43wxNjI2MzUxNTI1",      "analyticsId": "3K1dz8TqXr2J1647k63MxkJs",      "tokenType": "SINGLE_USE",      "paymentInstrumentType": "PAYMENT_CARD",      "paymentInstrumentData": {}      },      "threeDSecureAuthentication": {        "responseCode": "NOT_PERFORMED",        "reasonCode": null,        "reasonText": null,        "protocolVersion": null,        "challengeIssued": null      }    },    "vaultedPaymentInstrument": null,    "customer": {      "id": null,      "email": "customer123@gmail.com",      "billingAddress": null,      "shippingAddress": null    },    "lastPaymentError": null,    "metadata": {      "productId": 123,      "merchantId": "a13bsd62s"    },    "workflowExecutionError": null,    "workflowLastExecutedStep": null,    "transactions": [      {        "id": "632fbcb3-f2ba-40ba-91f9-efcd28b2b54c",        "processorTransactionId": "pi_1JDTWfGZqNWFwi8cmmLKh43o",        "processor": "STRIPE",        "processorMerchantId": "acct_1GORcsGZqNWFwi8c",        "type": "SALE",        "status": "SETTLED",        "paymentError": null      },      {        "id": "ab0b804d-ce66-475d-82bd-ce5419628161",        "processorTransactionId": "re_1JHPg0GZqNWFwi8cgM21sR8x",        "processor": "STRIPE",        "processorMerchantId": "acct_1GORcsGZqNWFwi8c",        "type": "REFUND",        "status": "SETTLED",        "paymentError": null      }    ]  }}
json
copy

Disputes & chargebacks

Dispute notifications trigger on newly opened disputes or chargebacks.

FieldDescription
  1. 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.
  1. primerAccountId
A unique identifier for your Primer merchant account.
  1. transactionId
A unique identifier for the original Primer payment.
  1. orderId
Your reference for the sale transaction that the dispute relates to.
  1. processorId
The name of the processor that generated the dispute.
  1. processorDisputeId
A unique identifier for the corresponding connection dispute.

Example dispute notification:

12345678
{    "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
copy
© Primer 2021