Overview

Getting started with our webhooks

TradPay Webhooks allow developers to monitor TradPay payment events and verify transactions in real-time through backend services.

Create Webhook

To create a webhook on TradPay:

1. Go to Dashboard → Developers → Webhooks

2. Choose from two types:

   • PayLink Webhook – applies to all or individual Paylinks&Checkout links

   • PayCard Webhook – applies to all or individual Paycard links

In the dashboard, you can:

• View and edit all created webhooks

• See all triggered events

• Access key details like status and delivery time

Payload Structure

PayLink & Checkout

{
  "eventType": "PAY_IN",
  "checkoutCode": "4cADM2G7UJfXXjJlXsC9t9NL",
  "name": "Checkout Intros",
  "pricing": "56",        // Pricing Amount
  "pricingSymbol": "USDT",// Pricing Currency
  "from": "0x923967a6D7017051a8090F7e5aa1C6236aA73f6d",// Actual payment wallet
  "to": [
    {
      "address": "0x5FbE74A283f7954f10AA04C2eDf55578811aeb03",// recipient address
      "amount": "55.8651" // Actual amount received
    }
  ],
  "chainName": "ethereum", // payment chain, (Equivalent to ETH, case-insensitive)
  "paySymbol": "USDT",// payment currency
  "hash": "0xcd6893915b37a3da9693df9a95038a4b51eecff3bbf213048a92699c7a571d5c",
  "hashLink": "https://etherscan.io/tx/0xcd6893915b37a3da9693df9a95038a4b51eecff3bbf213048a92699c7a571d5c",
  "amount": "56.0151", // Actual payment amount
  "amountUsd": "56.01",// USD price at the time of payment
  "updatedAt": 1748182332000,// unit: ms
  "status": "Completed",// Values: Pending, Completed, Failed
  "fee": "0.15"// merchant fees
}

Paycard

Important Information

1. Webhook Event Types:

   • PayLink & Checkout: Pending, Completed, Failed

   • Paycard: Created, Pending, Paid, Completed, Canceled, Declined, or Failed

2. Signature Verification: Each webhook request includes a signature in the x-tx-signature header to verify it's from TradPay.

3. Delivery Order: Webhooks are delivered in sequence when possible, but order is not guaranteed due to network delays. Handle events based on their type.

4. Idempotency: Implement idempotent handling to manage duplicate deliveries from retries or network issues.

// request header
POST /your-app.com/webhook HTTP/1.1 
content-type: application/json;
x-tx-signature: HMAC SHA-256 content hash

Retry Policy

TradPay uses the HTTP status code in your response to determine if a retry is needed. For more on status codes, see: HTTP Response Status Codes.

Retries are triggered in these cases:

• HTTP response status code is not 200

• HTTP response/connection times out (15s timeout)

Retry intervals:

1. 15s

2. 1m

3. 5m

4. 15m

5. 30m

6. 60m

After a total of 6 attempts, there will be no resends.

TradPay does not parse response content. Retries are triggered solely based on HTTP status codes.