Webhook Integration

Overview

PayRam provides webhook functionality to notify your backend server whenever a payment is received from your customers. This ensures real-time updates and automated processing of transactions.

Your backend server must create a webhook endpoint to receive these notifications. PayRam will send a GET request to this endpoint with payment details.

---

Webhook Endpoint

Merchants need to create an API endpoint in their backend to receive webhook notifications.

📌 Example Webhook URL:

<http://yourprojectwebsite.com/webhook>

Ensure that this endpoint is publicly accessible and capable of handling incoming GET requests.

---

Payment Data Structure

When a customer makes a payment to the PayRam server, PayRam sends the payment details in a JSON payload to your webhook.

Sample Webhook Request:

Header

*API-Key:* ad9db0a5e2e720eaa07a573b4142b51b

Body

{
    "amount": "35",
    "blockchain_symbol": "ETH",
    "cancel_url": "abc",
    "created_at": "2024-05-24T10:44:08.469147221Z",
    "currency_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "currency_decimals": 6,
    "currency_desc": null,
    "currency_name": "Ethereum",
    "currency_symbol": "USDC",
    "customer_id": "104755546182221158537",
    "deposit_address": "0x8e25fE332188B027aD2119906eD1e3954195ED1a",
    "filled_amount": "",
    "filled_amount_in_usd": "",
    "invoice_id": "1716559699",
    "merchant_name": "Merchant Name",
    "payment_state": "OPEN",
    "reference_id": "2618e325-b533-447c-b203-98cb9c6a8665",
    "success_url": "<http://yourwebsite/success>"
}

---

Project API-Key validation

The API-Key will be passed in the header of the webhook API call. This API key corresponds to the project API key, which must be validated on your end before processing any customer credits or performing any operations on the received data.

---

Payment Statuses

The payment_state field in the webhook payload represents the current status of the payment:

Status	Description
OPEN	Payment has not been completed.
CANCELED	The payment link has expired.
FILLED	The full requested amount has been paid.
PARTIALLY_FILLED	A partial payment has been made.
OVER_FILLED	An excess payment was received.

📌 For FILLED, PARTIALLY_FILLED, and OVER_FILLED statuses, the following fields will be populated:

• filled_amount (Supports decimals)

• filled_amount_in_usd (USD equivalent of the paid amount)

Example for a FILLED payment:

{
    "payment_state": "FILLED",
    "filled_amount": "35.000000",
    "filled_amount_in_usd": "120.50"
}

---

Handling Webhook Requests

Your backend should:

✅ Accept incoming GET requests from PayRam.

✅ Parse the JSON payload.

✅ Validate the received payment data.

✅ Store or process the payment details as needed.

✅ Respond with HTTP 200 OK to acknowledge receipt.

Example Implementation in Node.js (Express)

const express = require('express');
const app = express();

const PROJECT_API_KEY = "ad9db0a5e2e720eaa07a573b4142b51b"; // Replace with your actual project API key

app.get('/webhook', (req, res) => {
    // Extract API key from request headers
    const apiKey = req.headers['api-key'];

    // Validate API key
    if (!apiKey || apiKey !== PROJECT_API_KEY) {
        return res.status(401).json({ error: "Unauthorized: Invalid API key" });
    }

    // Extract payment details from query params
    const paymentData = req.query;
    console.log('Received Webhook:', paymentData);

    // Process the payment details here

    res.status(200).send('Webhook received successfully');
});

app.listen(3000, () => {
    console.log('Server is running on port 3000');
});

---

Best Practices

🔹 Secure your webhook endpoint: Use API keys, IP whitelisting, or signature validation to prevent unauthorized access.

🔹 Log all webhook events: Store webhook requests in your logs for debugging and tracking purposes.

🔹 Retry handling: If your server is down, implement a retry mechanism to reprocess failed webhook events.

🔹 Confirm webhook receipt: Always respond with an HTTP 200 status code after successful processing.

---

Next Steps

• Implement the webhook in your backend.

• Test webhook handling using PayRam’s sandbox/test environment.

• Monitor webhook events and logs to ensure smooth payment tracking.

For any issues, reach out to [email protected]. 🚀