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. 1
    Log in and head over to the Developers area on your Dashboard.
  2. 2
    In the Webhooks section, click on the Add button.
  3. 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. 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:

FieldDescription
  1. eventType
The type of event that triggered the webhook. This will have the value PAYMENT.STATUS.
  1. date
The date and time at which the webhook was triggered.
  1. notificationConfig
An object containing details about the webhook configuration.
  1. notificationConfig
  2. id
The unique identifier for the webhook. This is automatically generated by Primer.
  1. notificationConfig
  2. description
The name of the webhook, as defined in the Dashboard.
  1. payment
An object containing details about the payment.
  1. payment
  2. id
The unique identifier for the payment.
  1. payment
  2. date
The date and time at which the payment was created.
  1. payment
  2. status
The latest status of the payment.

Can be one of:
  • PENDING
  • AUTHORIZED
  • DECLINED
  • FAILED
  • SETTLING
  • CANCELLED
  • PARTIALLY_SETTLED
  • SETTLED
  1. payment
  2. orderId
The unique identifier for the order associated with this payment.
  1. payment
  2. processor
The name of the processor that processed the payment.
  1. payment
  2. processorMerchantId
The merchant identifier registered at the payment processor used for this payment.
  1. payment
  2. currencyCode
The three-digit currency code in ISO 4217 format.
  1. payment
  2. amount
The total payment amount in minor units. For example, $7 will show as 700.
  1. payment
  2. amountAuthorized
The amount authorized when this webhook was generated.
  1. payment
  2. amountCaptured
The amount captured when this webhook was generated.
  1. payment
  2. amountRefunded
The amount refunded when this webhook was generated.
  1. payment
  2. statementDescriptor
A description of the payment, as it would typically appear on a bank statement.
  1. payment
  2. paymentInstrument
An object containing details about the payment instrument.
  1. payment
  2. paymentInstrument
  3. token
The payment instrument token.
  1. payment
  2. paymentInstrument
  3. analyticsId
The unique analytics identifier for this payment instrument.
  1. payment
  2. paymentInstrument
  3. tokenType
The type of token. Can be either SINGLE_USE or MULTI_USE.
  1. payment
  2. paymentInstrument
  3. paymentInstrumentType
The type of payment instrument.

Can be one of:
  • PAYMENT_CARD
  • PAYPAL_BILLING_AGREEMENT
  • GOCARDLESS_MANDATE
  • KLARNA_CUSTOMER_TOKEN
  1. payment
  2. paymentInstrument
  3. paymentInstrumentData
An object containing details about the payment instrument. The fields included in this object depend on the payment instrument type.
  1. payment
  2. customer
An object containing details about the customer.
  1. payment
  2. customer
  3. id
The unique identifier for the customer.
  1. payment
  2. customer
  3. email
The customer's email address.
  1. payment
  2. metadata
An object containing additional data to used throughout the payment lifecycle.
  1. payment
  2. metadata
  3. productId
An optional product identifier.
  1. payment
  2. metadata
  3. merchantId
An optional merchant identifier.
  1. payment
  2. transactions
A list of the transactions that have occurred while processing the payment.
  1. payment
  2. transactions
  3. id
The unique identifier for the transaction. This is automatically generated by Primer.
  1. payment
  2. transactions
  3. type
The type of transaction. Can be either SALE or REFUND.
  1. payment
  2. transactions
  3. status
The transaction status. Can be one of:
  • PENDING
  • AUTHORIZED
  • DECLINED
  • FAILED
  • SETTLING
  • CANCELLED
  • PARTIALLY_SETTLED
  • SETTLED
  1. payment
  2. transactions
  3. processor
The name of the processor that processed the payment.
  1. payment
  2. transactions
  3. 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:

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

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