Spend & Expense 3D Secure challenge notification payload

🚧

Limited access to Spend & Expense webhooks

At this time, the Spend & Expense webhooks are available only in the production environment. You can test with Spend & Expense 3D Secure challenge notifications in the sandbox environment only with GET /v3/subscriptions/{subscriptionId}/test.

This does not affect access to any other webhook in the sandbox environment.

When you subscribe to a BILL event and the event triggers, BILL sends a notification to your provided notificationUrl. See /v3/spend/transactions in the API reference for more information about the response fields.

When a transaction is initiated, a 3D Secure challenge may be created to verify the identity of the cardholder. When you subscribe to the spend.three-ds-challenge.created event, you get a notification when a 3D Secure challenge is triggered for a Spend & Expense transaction.

Prerequisites

• API token: When you create a subscription (POST v3/subscriptions) for a Spend & Expense event, the apiToken header value is required for authentication. See Authentication with Spend & Expense API token for information about authentication for the Spend & Expense API endpoints.
• Sample request: See Work with BILL webhooks for information about setting up a subscription for a Spend & Expense API event.

Sample spend.three-ds-challenge.created payload

In this sample unescaped JSON payload, the details of a Spend & Expense 3DS challenge are available. The notification provides a set of fields.

{
  "metadata": {
    "eventId": "625947c4-8e6b-48f0-ae72-ea9c9375ec27",
    "subscriptionId": "f6d06930-e3e2-4509-be37-4dbda29efc6i",
    "spendCompanyUuid": "9ddf9db2-210c-45cc-a5b8-c25f3f741721",
    "eventType":"spend.three-ds-challenge.created",
    "version":"1"
  },
  "threeDsChallenge": {
    "merchantName":"Amazon",
    "merchantCategoryCode":"5942",
    "acsTransactionId":"8267ce06-53ec-4e2d-80a6-afba0fb27yz1",
    "userUuid":"usr_8fe5a27i617a3557lirjoag5ks",
    "occurredTime":"2026-12-30T18:23:01.211+00:00",
    "amount":21.38,
    "cardUuid":"crd_p6ck386qk12cbbjkk8l687h901",
    "companyUuid":"cmp_jnfprch11h2sp9doo9fjut2wqa",
    "currencyCode":"USD"
  }
}