Webhooks & IPN Events

Track payment intent status updates

Payment operators can listen for events to automatically trigger payment status updates. Setup webhooks status updates by specifying a webhook_url during payment intent initiation requests.

Payment Statuses

• RELEASED_TO_GATEWAY: The payment intent has been successfully submitted to the Paygrid Clearing Gateway Node

• REJECTED: The gateway rejected the payment intent request due to validation issues or insufficient authorizations.

• PROCESSING: The payment intent has been validated and submitted for processing.

• COMPLETED: The payment intent has been successfully completed. This indicates that the funds have been transferred.

• SCHEDULED: The payment intent is scheduled for processing at a specific time interval or recurring cycle.

• CANCELLED: The payment intent has been cancelled by the operator or either transaction parties

• FAILED: The payment transaction encountered an error or was reverted for some reason preventing the transaction from being completed.

Payment Status Update: IPN Webhooks

IPN is a specific type of webhook typically used in financial contexts to communicate changes in payment status. Payment status events during the payment intent lifecycle are recorded by a PAYMENT_STATUS_UPDATE event emitted by the protocol with the following details:

• Event ID

• Payment Intent ID

• Payment operator ID

• Operator address

• Payment execution date

• Payment status code

• Payment reference and metadata for reconciliation

• Description of the reason of failure or other edge cases

• Payer account address

• Recipient(s) account address(s)

• Payment token that was spent by the payer

• Amount of the payment token spent by the payer

Webhook signature & security

To make your webhooks secure, you can verify that they originated from Paygrid by generating a HMAC SHA-256 hash code using your unique webhook signing key provided on request by Paygrid.

Validate the signature received

Every outbound request contains a hashed authentication signature in the header. It's computed by concatenating your signing key and request body. Then generates a hash using the HMAC SHA256 hash algorithm.

To verify the signature sent by Paygrid, you generate the HMAC SHA256 hash and compare it with the signature received.