Spend & Expense 3D Secure challenge notification payloads

🚧

Limited access to Spend & Expense webhooks

At this time, the Spend & Expense webhooks are available only in the production environment. We will provide more information when these webhooks are available in the sandbox environment.

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 Working 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": "{event_id}",
    "subscriptionId":"{subscription_id}",
    "spendCompanyUuid":"{S&E_company_uuid}",
    "eventType":"spend.three-ds-challenge.created",
    "version":"1"
  },
  "threeDsChallenge": {
    "merchantName":"Amazon",
    "merchantCategoryCode":"5942",
    "acsTransactionId":"{3d_secure_acs_id}",
    "userUuid":"{user_uuid}",
    "occurredTime":"2025-12-30T18:23:01.211+00:00",
    "amount":21.38,
    "cardUuid":"{card_uuid}",
    "companyUuid":"{company_uuid}",
    "currencyCode":"USD"
  }
}