--- updatedAt: 2025-10-13T08:27:54.000Z agentTools: projectIndex: https://coinify.readme.io/llms.txt --- # Payment Intent 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](https://coinify.readme.io/docs/webhooks)**. > ❗️ Important > > Never consume the payload before validating the signature.\ > Check the [example Recipe](https://coinify.readme.io/recipes/validate-webhook-signature) 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. | | completed\_underpaid | When the transaction of the Payment Intent gets confirmed and the amount paid by the payer is **less** than the expected amount. | As mentioned in [Webhooks](https://coinify.readme.io/docs/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](https://coinify.readme.io/reference/payment-intent-resource#statereason). | | 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: ```json 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](https://coinify.readme.io/reference/payment-intent-resource#statereason). 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](https://coinify.readme.io/reference/payment-intent-resource#statereason). | | 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" } } } ```