Webhooks

Get real-time notifications about payments 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.
  • Completed refund requests. 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 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.

add 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.

test 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

The payment webhooks notify you when a payment status is updated or a refund request is completed.

Status

Payment status notifications are triggered when a payment's status is updated. For example, when a payment goes from Pending to Authorized.

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.

Here's 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

Refunds

Refund notifications are triggered when a refund reaches its final state: SETTLED or FAILED.

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.

Multiple partial refunds
When you perform multiple partial refunds on the same payment, you'll receive a refund notification for each of them.

Refund notifications contain the following fields:

FieldDescription
  1. eventType
The type of event that triggered the webhook. This will have the value PAYMENT.REFUND.
  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. This will have the value 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. requiredAction
The action required to continue with the payment, if any. This will have the value null.
  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. paymentInstrument
  3. threeDSecureAuthentication
Details about the 3D Secure check, if it was performed.
  1. payment
  2. vaultedPaymentInstrument
An object containing details about the vaulted payment method token, if any.
  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. customer
  3. billingAddress
The customer's billing address.
  1. payment
  2. customer
  3. shippingAddress
The customer's shipping address.
  1. payment
  2. lastPaymentError
An object containing details about the payment error. This will have the value null.
  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. workflowExecutionError
An object containing details about the workflow execution error, if any. This will have the value null.
  1. payment
  2. workflowLastExecutedStep
An object containing details about the last step executed as part of a payment workflow. This will have the value null.
  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.

Here's an example of a SETTLED refund:

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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
{
"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

Dispute webhooks

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

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.

Here's 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