Integration Guide
1. Setup
-
Register account https://paydefi.io/auth/register/ (opens in a new tab)
-
Set wallet address in settings section
-
Obtain API credentials.
-
Add webhook endpoint to receive notifications about payment status change
2. Making Requests
For more detailed information, visit the API Reference (Swagger) (opens in a new tab) directly.
Base URL
https://api.paydefi.io/
Authentication
To use the PayDeFi API, you must obtain an API key by signing up on the PayDeFi (opens in a new tab) website. Include this API key in the Authorization header of your requests.
Paydefi-Api-Key: YOUR_ACCESS_TOKEN
Webhook Payload Verification
Every payment status update request includes a Paydefi-Signature
header. This header contains the SHA256 HMAC signature of the raw request payload, computed using your webhook secret as the key.
Paydefi-Signature: COMPUTED_SIGNATURE
1. Verify HMAC Signature
To verify the signature you have to:
- Get your secret key by visiting Webhook settings page (opens in a new tab).
- Get signature from
Paydefi-Signature
header. - Get the payload. It should be the raw body of the HTTP request, formatted as a JSON string. Any change in the payload could invalidate the signature, so it must be captured exactly as it arrives.
2. Implementation Example
const crypto = require("node:crypto");
verifySignature(signature, payload, secret) {
// Create a new HMAC object using the secret key and the SHA256 hash algorithm
const hmac = crypto.createHmac("sha256", secret).update(payload);
// Generate the hexadecimal HMAC signature
const computedSignature = hmac.digest("hex");
// Compare the computed signature with the given signature
return computedSignature === signature;
}
// Example values
const signature = "received_signature" // Replace "received_signature" with the signature you get from Paydefi-Signature header.
const payload = '{"orderId":"123","status":"ACCEPTED","paymentId":"234"}' // Example payload. Ensure it is raw as received.
const secret = "your_webhook_secret" // Replace "your_webhook_secret" with secret you received from https://paydefi.io/settings/webhooks.
const isValid = verifySignature(signature, payload, secret);
console.log("Signature is valid: ", isValid);
⚠️ Important: Make sure to capture the payload as a raw string, without parsing or modifying it.
Webhook Event Reference
Webhooks are triggered automatically when the status of a payment changes. Below is a breakdown of the available event types and example payloads for each.
1. Webhook Event Types
Status | Description |
---|---|
ACCEPTED | Payment is received and is currently being processed. |
COMPLETED | Payment was successfully processed and finalized. |
EXPIRED | The payment link expired before payment was completed. |
CANCELLED | The payment attempt was rejected or superseded by a new one with the same orderId . |
2. Webhook Payloads
ACCEPTED
{
"orderId": "1",
"status": "ACCEPTED",
"metaData": null,
"paymentId": "IEpGEyrQR_yDaDS"
}
COMPLETED
{
"orderId": "1",
"status": "COMPLETED",
"metaData": null,
"paymentId": "IEpGEyrQR_yDaDS",
"transactions": [
{
"chainId": 1,
"protocolFeeAmount": 0.0003,
"protocolFeeRate": 0.003,
"acceptanceRate": 0.005,
"merchantAddress": "0x521E8E916EB48b7f7AAcb962b1cBb3C4Dc0921DE",
"payIn": {
"token": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
"symbol": "USDC",
"amount": 0.1
},
"payOut": {
"token": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
"symbol": "USDC",
"amount": 0.0997
}
}
]
}
EXPIRED
{
"orderId": "1",
"status": "EXPIRED",
"metaData": null,
"paymentId": "IEpGEyrQR_yDaDS"
}
CANCELLED
{
"orderId": "1",
"status": "CANCELLED",
"metaData": null,
"paymentId": "IEpGEyrQR_yDaDS"
}
Below is an example of the response body structure for a payment-related API response.
ℹ️ Note: The
transactions
field appears only when thestatus
is COMPLETED. This array provides full breakdown of the processed blockchain transaction.
Parameter | Type | Optional | Description |
---|---|---|---|
orderId | string | No | Unique identifier for the payment. |
status | string | No | Current status of the payment. |
metaData | string | null | Yes | Optional object allowing you to attach custom data to a payment. Returned in all webhook responses. |
paymentId | string | No | Unique identifier assigned to the payment by PayDeFi. |
transactions | array | Yes | Array of transaction details. |