Webhooks - EasyOnRamp Business API

EasyOnRamp delivers events to HTTPS endpoints you configure. Each delivery is signed with HMAC-SHA256 so you can verify authenticity. Subscribe to specific events or use wildcards. Omit events (or pass ["*"]) to receive every event type.

POST /webhooks

{
  "url": "https://your-platform.com/easyonramp/webhooks"
}

Or narrow the subscription:

{
  "url": "https://your-platform.com/easyonramp/webhooks",
  "events": [
    "deposit.*",
    "business.application.*",
    "card.enrollment.*",
    "user.kyc.*"
  ]
}

Response includes id and secret. Store the secret immediately; it is only shown on create and rotate.

Delivery envelope

Every POST to your endpoint uses this shape. Use id for idempotent processing.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "deposit.approved",
  "data": { }
}

Headers:

Header	Purpose
`Content-Type`	`application/json`
`X-EasyOnRamp-Signature`	HMAC-SHA256 hex digest of the raw JSON body
`X-EasyOnRamp-Event-Id`	Same as body `id` (delivery id)
`X-EasyOnRamp-Event-Type`	Same as body `type`

All monetary amounts in data are integer cents unless noted.

Verify signatures (TypeScript)

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyEasyOnRampWebhook(
  secret: string,
  signatureHeader: string,
  rawBody: string,
): boolean {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');

  try {
    return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
  } catch {
    return false;
  }
}

// Express example
app.post('/easyonramp/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  const signature = req.header('x-easyonramp-signature') ?? '';

  if (!verifyEasyOnRampWebhook(process.env.WEBHOOK_SECRET!, signature, rawBody)) {
    return res.status(401).send('invalid signature');
  }

  const event = JSON.parse(rawBody) as { id: string; type: string; data: Record<string, unknown> };

  // Idempotent handler: skip if event.id already processed
  console.log(event.type, event.data);
  return res.sendStatus(200);
});

Compare signatures with a constant-time function. Use the raw request body bytes exactly as received (do not re-serialize parsed JSON).

Webhook delivery logs

Inspect outbound delivery attempts (pending, delivered, or failed) for your business.

GET /webhooks/deliveries?status=failed&sort=-createdAt&page=1&limit=50

Query	Purpose
`status`	`pending`, `delivered`, or `failed`
`q`	Search event type (for example deposit.approved)
`sort`	`eventType`, `status`, `createdAt`, `deliveredAt` (prefix `-` for descending)
`fields`	Comma-separated response fields
`page`, `limit`	Pagination

Response item

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "subscriptionId": "507f1f77bcf86cd799439011",
  "webhookUrl": "https://your-platform.com/easyonramp/webhooks",
  "eventType": "deposit.approved",
  "status": "failed",
  "attemptCount": 10,
  "lastError": "HTTP 500",
  "deliveredAt": null,
  "createdAt": "2026-07-07T07:30:00.000Z",
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "reference": "DEP-8F2K9Q",
    "amount": 100000,
    "status": "approved"
  }
}

Use delivery id to correlate with the id sent in the webhook body. Fix your endpoint, then rely on automatic retries for in-flight deliveries or investigate failed rows after the final attempt.

Retries

Failed deliveries (non-2xx or network error) retry with exponential backoff up to ten attempts. Design your handler to be idempotent using the delivery id in the payload.

Events

Subscribe using exact event names or wildcards (see Wildcards). Each delivery sets type to the event name and data to the payload below. Amounts are integer cents unless noted. Across user-scoped events, userId is the same Mongo ObjectId returned by POST /users and GET /users/{userId}. Card events include user: { id, name } instead of top-level userId / userCode.

Deposits

deposit.created

Treasury deposit created.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "deposit.created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "reference": "DEP-8F2K9Q",
    "amount": 100000,
    "currency": "ZAR",
    "status": "waiting_pop"
  }
}

deposit.proof_submitted

Proof of payment uploaded.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "deposit.proof_submitted",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "reference": "DEP-8F2K9Q",
    "amount": 100000,
    "currency": "ZAR",
    "status": "pending",
    "proofUrl": "https://cdn.example.com/proofs/abc123.pdf",
    "bankName": "First National Bank",
    "accountNumber": "****4521"
  }
}

deposit.approved

Deposit approved and treasury credited.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "deposit.approved",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "reference": "DEP-8F2K9Q",
    "amount": 100000,
    "currency": "ZAR",
    "status": "approved"
  }
}

deposit.declined

Deposit rejected by ops.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "deposit.declined",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "reference": "DEP-8F2K9Q",
    "amount": 100000,
    "currency": "ZAR",
    "status": "declined"
  }
}

deposit.expired

Deposit expired without matching transfer.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "deposit.expired",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "reference": "DEP-8F2K9Q",
    "amount": 100000,
    "currency": "ZAR",
    "status": "expired"
  }
}

Trading

payAmount, receiveAmount, and convertedAmount are integer cents. pay is the asset you pay; receive / convertedCurrency is the asset you receive.

trade.approved

Trade completed and treasury balances were updated. Same shape as the buy/sell API response (no status field).

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "trade.approved",
  "data": {
    "id": "662f1a2b3c4d5e6f7a8b9c0d",
    "pay": "ZAR",
    "receive": "USDC",
    "payAmount": 100000,
    "receiveAmount": 5432,
    "convertedAmount": 5432,
    "convertedCurrency": "USDC",
    "price": 0.05432
  }
}

Card transactions

amount is integer cents. transactionDateAt is the ISO-8601 time for this event. Lifecycle: the first event is usually card.transaction.pending (authorization held). Later you may receive completed, declined, or reversed.

card.transaction.pending

Authorization or hold recorded. Usual first event for a new spend.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "card.transaction.pending",
  "data": {
    "card": {
      "id": "660e8400-e29b-41d4-a716-446655440010",
      "name": "Jane Doe Card"
    },
    "transactionId": "770e8400-e29b-41d4-a716-446655440011",
    "status": "pending",
    "user": {
      "id": "507f1f77bcf86cd799439013",
      "name": "Jane Doe"
    },
    "amount": 4599,
    "currency": "USD",
    "merchantName": "Coffee Shop",
    "transactionDateAt": "2026-10-05T13:14:21.188Z"
  }
}

card.transaction.completed

Transaction settled.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "card.transaction.completed",
  "data": {
    "card": {
      "id": "660e8400-e29b-41d4-a716-446655440010",
      "name": "Jane Doe Card"
    },
    "transactionId": "770e8400-e29b-41d4-a716-446655440011",
    "status": "completed",
    "user": {
      "id": "507f1f77bcf86cd799439013",
      "name": "Jane Doe"
    },
    "amount": 4599,
    "currency": "USD",
    "merchantName": "Coffee Shop",
    "transactionDateAt": "2026-10-05T15:00:00.000Z"
  }
}

card.transaction.declined

Authorization declined.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "card.transaction.declined",
  "data": {
    "card": {
      "id": "660e8400-e29b-41d4-a716-446655440010",
      "name": "Jane Doe Card"
    },
    "transactionId": "770e8400-e29b-41d4-a716-446655440012",
    "status": "declined",
    "user": {
      "id": "507f1f77bcf86cd799439013",
      "name": "Jane Doe"
    },
    "amount": 4599,
    "currency": "USD",
    "merchantName": "Coffee Shop",
    "transactionDateAt": "2026-10-05T13:14:21.188Z"
  }
}

card.transaction.reversed

Reversal or refund.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "card.transaction.reversed",
  "data": {
    "card": {
      "id": "660e8400-e29b-41d4-a716-446655440010",
      "name": "Jane Doe Card"
    },
    "transactionId": "770e8400-e29b-41d4-a716-446655440011",
    "status": "reversed",
    "user": {
      "id": "507f1f77bcf86cd799439013",
      "name": "Jane Doe"
    },
    "amount": 4599,
    "currency": "USD",
    "merchantName": "Coffee Shop",
    "transactionDateAt": "2026-10-05T13:14:21.188Z"
  }
}

Card disputes

card.dispute.created fires when a dispute is filed. card.dispute.updated fires when the status or textEvidence changes. data.id is the dispute id. data.transactionId is the same id used on card transaction events. See Transaction disputes. Status values: pending, inReview, accepted, rejected, canceled, resolvedByMerchant. When the card network accepts a dispute, the credit arrives separately as card.transaction.completed with a negative amount.

card.dispute.created

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "card.dispute.created",
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440099",
    "transactionId": "770e8400-e29b-41d4-a716-446655440011",
    "status": "pending",
    "disputeType": "fraud",
    "disputeReasonCode": "otherFraudCardAbsent",
    "textEvidence": "Cardholder did not authorise this charge",
    "disputeAmount": 4599,
    "currency": "usd",
    "createdAt": "2026-10-20T10:00:00.000Z"
  }
}

card.dispute.updated

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "card.dispute.updated",
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440099",
    "transactionId": "770e8400-e29b-41d4-a716-446655440011",
    "status": "inReview",
    "reviewedBy": "network",
    "disputeType": "fraud",
    "disputeReasonCode": "otherFraudCardAbsent",
    "disputeAmount": 4599,
    "currency": "usd",
    "createdAt": "2026-10-20T10:00:00.000Z",
    "updatedAt": "2026-10-22T08:12:00.000Z"
  }
}

EasyCard application

business.application.pending

Company application submitted (POST /business/application).

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "business.application.pending",
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440020",
    "status": "pending",
    "verificationUrl": null
  }
}

business.application.needs_verification

Additional issuer verification required for the company application.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "business.application.needs_verification",
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440020",
    "status": "needs_verification",
    "verificationUrl": "https://issuer.example.com/verify/abc"
  }
}

business.application.approved

Company application approved - you may enroll end users.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "business.application.approved",
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440020",
    "status": "approved",
    "verificationUrl": null
  }
}

business.application.rejected

Company application declined.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "business.application.rejected",
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440020",
    "status": "rejected",
    "verificationUrl": null
  }
}

Card enrollment

card.enrollment.pending

End user enrolled on the EasyCard application; compliance in progress.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "card.enrollment.pending",
  "data": {
    "id": "507f1f77bcf86cd799439013",
    "user": {
      "id": "507f1f77bcf86cd799439013",
      "name": "Jane Doe"
    },
    "status": "pending",
    "rainCardholderId": "cardholder-uuid"
  }
}

card.enrollment.needs_verification

Issuer requires additional verification before enrollment can be approved.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "card.enrollment.needs_verification",
  "data": {
    "id": "507f1f77bcf86cd799439013",
    "user": {
      "id": "507f1f77bcf86cd799439013",
      "name": "Jane Doe"
    },
    "status": "needs_verification",
    "rainCardholderId": "cardholder-uuid"
  }
}

card.enrollment.approved

User compliance approved - you may issue cards.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "card.enrollment.approved",
  "data": {
    "id": "507f1f77bcf86cd799439013",
    "user": {
      "id": "507f1f77bcf86cd799439013",
      "name": "Jane Doe"
    },
    "status": "approved",
    "rainCardholderId": "cardholder-uuid"
  }
}

card.enrollment.rejected

User enrollment declined.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "card.enrollment.rejected",
  "data": {
    "id": "507f1f77bcf86cd799439013",
    "user": {
      "id": "507f1f77bcf86cd799439013",
      "name": "Jane Doe"
    },
    "status": "rejected",
    "rainCardholderId": "cardholder-uuid"
  }
}

Card status

card.status.changed

Card frozen, unfrozen, or terminated.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "card.status.changed",
  "data": {
    "card": {
      "id": "660e8400-e29b-41d4-a716-446655440010",
      "name": "Jane Doe Card"
    },
    "status": "frozen"
  }
}

Status is one of active, frozen, or terminated.

Card programme movements

card.fund.completed

Corporate EasyCard programme funding completed. spendingPower is the updated company programme balance.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "card.fund.completed",
  "data": {
    "id": "990e8400-e29b-41d4-a716-446655440030",
    "amount": 50000,
    "currency": "USDC",
    "status": "completed",
    "spendingPower": 150000,
    "spendingPowerWithWallet": 150000
  }
}

card / user may be omitted for programme-level funds.

card.withdraw.completed

Corporate EasyCard programme withdrawal completed. spendingPower is the updated company programme balance.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "card.withdraw.completed",
  "data": {
    "id": "991e8400-e29b-41d4-a716-446655440031",
    "amount": 25000,
    "currency": "USDC",
    "status": "completed",
    "spendingPower": 125000,
    "spendingPowerWithWallet": 125000
  }
}

card / user may be omitted for programme-level withdrawals.

Users

user.created

End user provisioned.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "user.created",
  "data": {
    "userId": "507f1f77bcf86cd799439013",
    "kycStatus": "pending",
    "subAccount": {
      "id": "507f1f77bcf86cd799439012",
      "name": "Default"
    },
    "email": "jane@enduser.example.com"
  }
}

user.deleted

End user removed.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "user.deleted",
  "data": {
    "userId": "507f1f77bcf86cd799439013"
  }
}

user.updated

End user profile updated via PATCH /users/{userId} or retail/ops changes. Includes only fields that changed (name, firstName, lastName, email, phone, subAccount, twoFactorEnabled, emailVerified, and/or phoneVerified).

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "user.updated",
  "data": {
    "userId": "507f1f77bcf86cd799439013",
    "name": "Jane Doe",
    "firstName": "Jane",
    "lastName": "Doe",
    "subAccount": {
      "id": "507f1f77bcf86cd799439012",
      "name": "Default"
    },
    "twoFactorEnabled": true
  }
}

User KYC

user.kyc.pending

KYC started. Emitted with user.created when a Persona inquiry is created.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "user.kyc.pending",
  "data": {
    "userId": "507f1f77bcf86cd799439013",
    "kycStatus": "pending"
  }
}

user.kyc.approved

KYC approved.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "user.kyc.approved",
  "data": {
    "userId": "507f1f77bcf86cd799439013",
    "kycStatus": "approved"
  }
}

user.kyc.declined

KYC declined.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "user.kyc.declined",
  "data": {
    "userId": "507f1f77bcf86cd799439013",
    "kycStatus": "declined"
  }
}

Business KYB

business.kyb.pending

Business KYB started.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "business.kyb.pending",
  "data": {
    "kybStatus": "pending"
  }
}

business.kyb.approved

Business KYB approved.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "business.kyb.approved",
  "data": {
    "kybStatus": "approved"
  }
}

business.kyb.declined

Business KYB declined.

{
  "id": "wh_01HZYXK8VQ2M3N4P5R6S7T8U9",
  "type": "business.kyb.declined",
  "data": {
    "kybStatus": "declined"
  }
}

Wildcards

Use these patterns in the events array when creating or updating a subscription.

Pattern	Matches
*	Every event type (default when `events` is omitted)
deposit.*	All deposit events
card.transaction.*	All card transaction events
card.dispute.*	card.dispute.created, card.dispute.updated
card.enrollment.*	All card enrollment events
business.application.*	All EasyCard application events
card.status.*	card.status.changed
card.fund.*	card.fund.completed
card.withdraw.*	card.withdraw.completed
user.*	user.created, user.updated, user.deleted, and all user.kyc.* events
user.kyc.*	All user KYC events
business.kyb.*	All business KYB events

​Subscribe

​Delivery envelope

​Verify signatures (TypeScript)

​Webhook delivery logs

​Retries

​Events

​Deposits

​deposit.created

​deposit.proof_submitted

​deposit.approved

​deposit.declined

​deposit.expired

​Trading

​trade.approved

​Card transactions

​card.transaction.pending

​card.transaction.completed

​card.transaction.declined

​card.transaction.reversed

​Card disputes

​card.dispute.created

​card.dispute.updated

​EasyCard application

​business.application.pending

​business.application.needs_verification

​business.application.approved

​business.application.rejected

​Card enrollment

​card.enrollment.pending

​card.enrollment.needs_verification

​card.enrollment.approved

​card.enrollment.rejected

​Card status

​card.status.changed

​Card programme movements

​card.fund.completed

​card.withdraw.completed

​Users

​user.created

​user.deleted

​user.updated

​User KYC

​user.kyc.pending

​user.kyc.approved

​user.kyc.declined

​Business KYB

​business.kyb.pending

​business.kyb.approved

​business.kyb.declined

​Wildcards

​Related

Subscribe