Webhooks

Get real-time notifications about payment status updates and newly opened disputes.

Receiving webhooks

Our 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 you on the payment status change.

Setting up an endpoint

You can set up a webhook endpoint through your Dashboard:

1
Log in and head over to the Developers area on your Dashboard.
2
In the Webhooks section, click on the Add button.
3
Fill in the following fields:
- Name: A descriptive string for the webhook configuration.
- Endpoint URL: The endpoint we should send notifications to. Make sure that this is a public URL.
- Trigger on: A checklist of events that will trigger notifications.
4
Click Create.

adding a webhook

Authenticating webhooks

If you'd like to implement webhook authentication, we recommend creating a new API key specifically for this purpose and passing it as a query parameter in the endpoint URL.

Testing an endpoint

You can test a webhook endpoint from the Developers area on your Dashboard. In the Webhooks section, select one of your newly configured webhooks and click on the Test connection button.

testing a webhook

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

Payment webhooks

Payment notifications provide you with up-to-date information about your payments. They are triggered by changes to the payment status.

Structure

Payment notifications contain the following fields:

Field	Description
eventType	The type of event that triggered the webhook. This will have the value `PAYMENT.STATUS`.
date	The date and time at which the webhook was triggered.
notificationConfig	An object containing details about the webhook configuration.
notificationConfig id	The unique identifier for the webhook. This is automatically generated by Primer.
notificationConfig description	The name of the webhook, as defined in the Dashboard.
payment	An object containing details about the payment.
payment id	The unique identifier for the payment.
payment date	The date and time at which the payment was created.
payment status	The latest status of the payment. Can be one of: `PENDING` `AUTHORIZED` `DECLINED` `FAILED` `SETTLING` `CANCELLED` `PARTIALLY_SETTLED` `SETTLED`
payment orderId	The unique identifier for the order associated with this payment.
payment processor	The name of the processor that processed the payment.
payment processorMerchantId	The merchant identifier registered at the payment processor used for this payment.
payment currencyCode	The three-digit currency code in ISO 4217 format.
payment amount	The total payment amount in minor units. For example, $7 will show as `700`.
payment amountAuthorized	The amount authorized when this webhook was generated.
payment amountCaptured	The amount captured when this webhook was generated.
payment amountRefunded	The amount refunded when this webhook was generated.
payment statementDescriptor	A description of the payment, as it would typically appear on a bank statement.
payment paymentInstrument	An object containing details about the payment instrument.
payment paymentInstrument token	The payment instrument token.
payment paymentInstrument analyticsId	The unique analytics identifier for this payment instrument.
payment paymentInstrument tokenType	The type of token. Can be either `SINGLE_USE` or `MULTI_USE`.
payment paymentInstrument paymentInstrumentType	The type of payment instrument. Can be one of: `PAYMENT_CARD` `PAYPAL_BILLING_AGREEMENT` `GOCARDLESS_MANDATE` `KLARNA_CUSTOMER_TOKEN`
payment paymentInstrument paymentInstrumentData	An object containing details about the payment instrument. The fields included in this object depend on the payment instrument type.
payment customer	An object containing details about the customer.
payment customer id	The unique identifier for the customer.
payment customer email	The customer's email address.
payment metadata	An object containing additional data to used throughout the payment lifecycle.
payment metadata productId	An optional product identifier.
payment metadata merchantId	An optional merchant identifier.
payment transactions	A list of the transactions that have occurred while processing the payment.
payment transactions id	The unique identifier for the transaction. This is automatically generated by Primer.
payment transactions type	The type of transaction. Can be either `SALE` or `REFUND`.
payment transactions status	The transaction status. Can be one of: `PENDING` `AUTHORIZED` `DECLINED` `FAILED` `SETTLING` `CANCELLED` `PARTIALLY_SETTLED` `SETTLED`
payment transactions processor	The name of the processor that processed the payment.
payment transactions processorMerchantId	The merchant identifier registered at the payment processor used for this payment.

Example

This is an example of a payment notification.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
    "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

Dispute webhooks

Dispute notifications alert you about newly-opened disputes or chargebacks. They are triggered when one of your configured connections informs Primer about a dispute or chargeback.

Structure

Dispute notifications contain the following fields:

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 original Primer payment.
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.

Example

This is an example of a dispute notification.

1
2
3
4
5
6
7
8
{
    "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

← 07. Workflows