PaymentIntent Webhooks

This page provides information on the context object of payment intent webhooks.
Find out how to set a webhook, basic structure of the callbacks, and more here.

❗️

Important

Never consume the payload before validating the signature.
Check the example Recipe for the code to validate the webhook signature header.

payment-intent.completed

Event name: payment-intent.completed

This event is sent once the PaymentIntent is completed. The "state": "completed" can have more than one reason behind it.

Here are the possible stateReason values for a completed event:

"stateReason"	Description
completed_exact_amount	When the transaction of the Payment Intent is received on time, gets confirmed and the amount sent by the payer is equal to the amount requested in the PaymentIntent.
completed_overpaid	When the transaction of the Payment Intent gets confirmed and the amount paid by the payer is more than the expected amount.

As mentioned in Webhooks guide, all events have the same basic structure with the context property being different for each event. In the following table, an explanation for this specific context property is provided:

Property	Type	Description
context	object	The context object as passed during the creation.
id	string (UUID v4)	The ID of the PaymentIntent.
state	string	The current state of a PaymentIntent.
stateReason	string	The description of a reason behind the state of a PaymentIntent. See state reasons.
orderId	string	Merchant's internal ID of the order for which the PaymentIntent was created.
customerId	string	The ID of the customer as it was provided by Merchant during the creation of the PaymentIntent.
amount	string	The amount of the PaymentIntent denominated in a fiat currency.
currency	string	The denomination currency of the amount above.
creditAmount	string	The amount credited to the merchant account denominated in the selected fiat currency of the merchant.
creditCurrency	string	The denomination fiat currency that the merchant has selected.
payments	object	Contains the following blockchain information about the successful payment/s: amount, currency, transactionId.
amount	string	The amount of cryptocurrency transferred from the customer's wallet for the particular Payment Intent.
currency	string	The short-code of the cryptocurrency that the customer paid with.
transactionId	string	ID/hash of the transaction as stored on the specific blockchain used by customer for completing the payment.
senderAddresses	array	The list of address/es from which the transaction/s for the PaymentIntent was received from. When the address is unknown then the array is empty.

Furthermore, the merchant account is credited the amount denominated in the currency specified in the context parameters creditAmount and creditCurrency. Here's a payload example of a payment-intent.completed event:

payment-intent.completed

{
  "id": "fe9ae19d-4a85-4809-8bd8-08d05fb4091c",
  "time": "2022-03-28T14:23:52.988Z",
  "event": "payment-intent.completed",
  "context": {
    "id": "b0fca427-4e60-4999-b886-2d5a14b648a2",
    "state": "completed",
    "stateReason": "completed_exact_amount",
    "orderId": "123456",
    "customerId": "6af42318-9e60-4390-8bf0-e042d7b96b21",
    "amount": "40",
    "currency": "EUR",
    "creditAmount": "48.41",
    "creditCurrency": "USD",
    "payments": [
      {
        "amount": "0.00628029",
        "currency": "BTC",
        "transactionId": "0807a955421bf5fd32106f476ce9361149059ad46b1ba6d3ab7600d65a72deca",
        "senderAddresses": []
      }
	] 
  }
}

payment-intent.failed

Event name: payment-intent.failed

This event is sent once the PaymentIntent has failed. The "state": "failed" can have more than one reason behind it.

You can find all the stateReason values and their description for a failed event here.

Merchant's account will not be credited with any amount when the "state" of a PaymentIntent is "failed".

In the following table, you can find the details for this specific context property:

Property	Type	Description
id	string (UUID v4)	The ID of the PaymentIntent.
state	string	The current state of a PaymentIntent.
stateReason	string	The description of a reason behind the state of a PaymentIntent. See state reasons.
orderId	string	Merchant's ID of the order for which the PaymentIntent was created.
customerId	string	The ID of the customer as it was provided during the creation of the PaymentIntent.
amount	string	The amount of the PaymentIntent denominated in a fiat currency.
currency	string	The denomination currency of the amount above.

Here's an example of a payment-intent.failed object:

JSON

{
  "id": "d38a342a-0b91-40eb-8a5c-39e8b10f6c9c",
  "time": "2022-04-05T08:11:00.248Z",
  "event": "payment-intent.failed",
  "context": {
    "id": "25c88bf2-edad-425a-b759-bac2df2f28d5",
    "state": "failed",
    "stateReason": "failed_expired",
    "orderId": "a2b32jjk2l",
    "customerId": "6af46318-9e60-4390-8bf0-e042d7b96b21",
    "amount": "40",
    "currency": "EUR"
  }
}

payment-intent.refund.completed

Event name: payment-intent.refund.completed

This event is sent once the refund for the PaymentIntent has been sent to the destination refund address.

The context property of the payment-intent.refund.completed notification has the following interface:

Property	Type	Description
id	string	The paymentIntent ID for which the refund was created.
refund.id	string	The refund ID.

For example:

JSON

{
    "id": "f7f8c810-e12f-445d-9b2f-c5b8055254f6",
    "time": "2021-12-03T07:46:32.323Z",
    "event": "payment-intent.refund.completed",
    "context": {
        "id": "3314faf7-f540-4f84-912a-d87fc90088da",
        "refund": {
            "id": "5ca1aca0-021c-4a82-9d64-c99893ce277d"
            }
    }
}