Paygrid
WebsiteDiscord
  • Getting started
    • Introduction
    • Reach out
  • How it works
    • Demo
    • Core features
      • Chain abstracted payments
      • Payment Clearing and MEV
    • Supported Networks & Tokens
  • Use cases
    • Payment workflows
    • Recurring workflows
    • Invoice workflows
    • Agentic workflows
    • DeFi - High Frequency Trading workflows
  • Technical Docs
    • What is a Payment Intent?
    • What is a Corridor?
    • Payment Lifecycle
    • Paygrid API
      • Authentication
      • Payment Intent API
      • Corridor Pricing API
      • Webhooks & IPN Events
      • Payment Recovery & Fallback Guarantees
    • Paygrid SDK
      • Quickstart
    • Security Considerations
  • Resources
    • Discord
    • Brand assets
Powered by GitBook
On this page
  • Payment Statuses
  • Payment Status Update: IPN Webhooks
  • Webhook signature & security
  • Validate the signature received
  1. Technical Docs
  2. Paygrid API

Webhooks & IPN Events

Track payment intent status updates

PreviousCorridor Pricing APINextPayment Recovery & Fallback Guarantees

Last updated 2 months ago

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

IPN Webhooks