Skip to main content

API & Webhook Integration

You can enhance your Wallet Pay experience by integrating with our API and enabling webhooks to receive real-time payment notifications.

📤 Passing Custom Metadata​

When generating the hash (either via the dashboard or API), you can include additional metadata:

Optional Parameters​

  • custom_id: Your internal reference ID (e.g., order ID)
  • email: Customer’s email address

This metadata will be returned in webhook responses so you can track and reconcile transactions easily.

To create a unique Wallet Pay payment hash using the API, make a POST request to the following endpoint:

POST /api/business/smart_contract/generate_wallet_pay_hash HTTP/1.1
Host: https://api.1buy.io
api-key: API_KEY
Content-Type: application/json

Example Request Body​

{
  "urlData": "?api_key=API_KEY&custom_id=CUSTOM_ID&email=EMAIL&amount=AMOUNT"
}

This will return a response containing a hash, which can then be embedded or shared as a payment URL.

🔔 Connect Webhook​

Webhooks allow your application to receive real-time updates for specific events occurring on the 1buy.io platform. By configuring a webhook, you can automate tasks such as order processing, transaction tracking, and customer notifications.

📝 Step 1: Register the Webhook URL​

Navigate to the appropriate environment:

Once there:

  1. Go to the Webhook Settings section https://app.1buy.io/widget-webhook
  2. Enter the URL where you want to receive webhook payloads (e.g., https://yourdomain.com/webhook-endpoint)
  3. Click Save to register

⚠️ Ensure your webhook URL is publicly accessible and supports HTTPS

⚙️ Step 2: Catching the Webhook Response​

To handle webhook events, create a server endpoint that listens for POST requests.

Example in Node.js:​

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

app.use(express.json()); // Middleware to parse JSON payloads

app.post("/my-webhook-endpoint", (req, res) => {
  const webhookPayload = req.body;
  console.log("Received webhook:", webhookPayload);

  // Process the webhook data
  res.status(200).send("Received!");
});

app.listen(3000, () => {
  console.log("Webhook server is running on port 3000");
});

📬 Webhook Response Structure​

When a webhook triggers, it sends a JSON response with the following structure:

{
  "token_symbol": "string", // e.g., "ETH"
  "wallet": "string", // e.g., "0x1a300Ea76131e683f89446FcDab674F109E606FF"
  "email": "string", // e.g., "user@example.com"
  "stage": "string", // e.g., "public" or "private"
  "hash": "string", // e.g., transaction hash
  "amount": "number", // e.g., 21
  "event": "string", // e.g., "purchase"
  "releaseEscrow": "boolean", // true or false
  "customId": "string", // custom identifier
  "is_token_webhook": "boolean", // true or false
  "api_key": "string", // e.g., "ENCRYPTED::your_api_key"
  "order_id": "string", // order reference
  "data": {
    "cryptoAmount": "string", // e.g., "0.00731274"
    "cryptoCurrency": "string", // e.g., "ETH"
    "customOrderId": "string", // optional, can be empty
    "destinationWallet": "string", // wallet address
    "failReason": "string", // optional, can be empty
    "fiatAmount": "string", // e.g., "21"
    "fiatCurrency": "string", // e.g., "USD"
    "networkId": "string", // e.g., "1"
    "paymentMethod": "string", // e.g., "BANKCARD"
    "status": "string", // e.g., "succeeded"
    "tapOnFeeAmount": "string", // e.g., "0"
    "tapOnFeeCurrency": "string", // e.g., "USD"
    "transactionHashes": ["string"], // array of hashes
    "transactionId": "string" // e.g., UUID
  }
}

You can verify this payload to update order statuses, send confirmation emails, or trigger other business logic.

The webhook triggers for the following stage:

Stage TypeDescription
wallet_connectTriggered when the user's wallet connection process is initiated.
buying_tokenTriggered when the user accesses the token purchase page.
bought_successTriggered when the user successfully confirms the purchase details.
final_transaction_startedTriggered when the final payment transaction process has started.
final_approval_completedTriggered when the payment transaction is successfully approved and completed.
final_transaction_rejectedTriggered when the payment transaction is rejected or unsuccessful.
final_transaction_failedTriggered when the transfer of funds to the user's wallet has failed.
final_transaction_completedTriggered when the final payment transaction is successfully executed and settled.

✅ Tips for Integration​

  • Ensure your webhook URL is publicly accessible via HTTPS
  • Handle duplicate webhooks idempotently
  • Log incoming payloads for debugging and validation

🧭 Next: FAQ & Support​

Need help or have questions? 👉 FAQ & Support