Webhooks for Ramp Payments

Webhooks allow your system to receive real-time updates about ramp payments, enabling automated actions based on payment events. For example, if you're running a platform that facilitates crypto top-ups, such as an online casino or a trading app, you can use webhooks to instantly verify deposits and credit users accordingly.

To receive webhook events for ramp payments, you must:

1. Have a BoomFi organization with a webhook endpoint set up.
2. Pass the ext_partner_id and ext_ref query parameters when generating the ramp URL.

Webhook Payload

{
  "id": "pay_2sJ7yMxWlTnWOO24UQZb7ykq5kA",
  "parent_id": "",
  "org_id": "2dwSdnkr8AE20YqM58eaix44r5J",
  "amount": "100",
  "currency": "USD",
  "invoice_id": "",
  "source": "BoomFi",
  "payment_method": "Ramp",
  "customer_id": "2nbx3a4CBjpUzILkM4tCPE6EZQK",
  "status": "RequiresAction",
  "next_action": "compliance",
  "scheduled_time": 0,
  "created_at": "2025-01-29T14:47:56.382Z",
  "updated_at": "2025-01-29T14:49:42.874265Z",
  "amount_usd": "100",
  "crypto_transaction": {
    "chain_id": 1,
    "customer_settlement_address": "0x184e38Ceac61f424f45Cb1f3558c61882f1e6d7F"
  },
  "buy_currency": "USDC",
  "buy_currency_amount": "96.33",
  "buy_token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "buy_token_chain_id": 1,
  "rate": "0.9873",
  "fees": {
    "boomfi_fee": "1",
    "fee_currency": "USD",
    "network_fee": "1.43411496991842617987769634",
    "total_fee": "2.43411496991842617987769634"
  },
  "org": {
    "id": "org_2dwSdnkr8AE20YqM58eaix44r5J",
    "name": "BoomfiOnramp"
  },
  "customer": {
    "id": "cus_2nbx3a4CBjpUzILkM4tCPE6EZQK",
    "org_id": "2dwSdnkr8AE20YqM58eaix44r5J",
    "name": "",
    "email": "[email protected]",
    "phone": "",
    "wallet_address": "",
    "deleted_at": null,
    "reference": "user-test-e25f549b-db1e-46ba-991f-73105f4667b7",
    "metadata": {},
    "created_at": "2024-10-18T12:42:57.721Z",
    "updated_at": "2024-10-18T12:42:57.721Z"
  }
}

🚧

Webhook Security

Always verify the webhook signature from the X-BoomFi-Signature header to prevent unauthorized spoofing.

Key Fields in the Webhook Payload

Tracking Your Payments:

The ext_ref field (passed in the query parameters) appears in the metadata section of the webhook payload lets you map the payment to your internal records.

Fiat vs. Crypto Values:

Fiat amount spent: amount (e.g., "amount": "100", "currency": "USD")

Crypto amount received: buy_currency_amount (e.g., "buy_currency_amount": "96.33", "buy_currency": "USDC")

Recipient Information:

The user's settlement wallet address is stored in crypto_transaction.customer_settlement_address.

Fees Breakdown:

BoomFi fee: fees.boomfi_fee

Network fee: fees.network_fee

Total fees: fees.total_fee

Blockchain Details:

The blockchain network ID is provided in crypto_transaction.chain_id. You can find the full list of supported chain IDs here.

Payment Statuses