Bamboo 3DS Authentication

Bamboo runs the full 3DS2 process — device fingerprinting, enrollment check, and challenge — on a Bamboo-hosted page, then authorizes the transaction with the acquirer.

Who this is for

The same ThreeDSAuthMethod: "INTERNAL" + Redirection mechanism works no matter how your integration reaches Create Purchase:

How it's different from External Authentication

Flow Overview

1. You create the purchase with ThreeDSAuthMethod: "INTERNAL" and a Redirection object.
2. If 3DS applies, the purchase comes back with Result: "ACTION_REQUIRED" and Status: "PENDING", plus an Action.URL. The purchase stays in PENDING for the entire authentication step — it hasn't been authorized yet.
3. You redirect the payer to Action.URL.
4. Bamboo's hosted page runs the 3DS process through its 3DS Server: device fingerprinting, enrollment check, and challenge if the issuer requires it.
5. Bamboo authorizes the transaction with the acquirer using the 3DS result.
6. The purchase resolves to its final Status — APPROVED or REJECTED — based on both outcomes in sequence: first whether 3DS authentication succeeded, then (only if it did) whether the acquirer approved the authorization. A failed authentication rejects the purchase outright, without ever reaching the acquirer.
7. The payer is redirected back to the URL you provided in Redirection.
8. Bamboo also notifies you via webhook (the same Transaction Notification you already use) with the final purchase + 3DS result — use it as your source of truth, since the redirect alone doesn't guarantee delivery (e.g., the payer closes the browser mid-flow).

3DS Configuration

Independently of what you send in the request, 3DS behavior is governed by a setting on your merchant account — per card brand and acquirer — with three possible states: Disabled, Mandatory, or Merchant's choice.

Ask your Bamboo account manager which state applies to your account for each acquirer/country you operate in.

Step 1 — Create the Purchase

Use the regular Create Purchase endpoint with your CardData or TrxToken (whichever matches your integration), plus:

Customer and billing address fields required for 3DS

When ThreeDSAuthMethod: "INTERNAL" applies to a purchase (or your account has 3DS set to Mandatory), Bamboo's 3DS Server requires a stricter set of Customer fields than a standard, non-3DS purchase. These fields are listed as optional or recommended on the general Create Purchase reference and on some Country Requirements pages, but they are mandatory whenever 3DS authentication runs — the request is rejected before reaching the issuer if they're missing.

Request Example

{
  "CardData": {
    "CardHolderName": "João Silva",
    "Pan": "4507990000004905",
    "CVV": "123",
    "Expiration": "08/30",
    "Email": "[email protected]"
  },
  "Amount": 100000,
  "Capture": true,
  "Currency": "ARS",
  "Installments": 1,
  "Customer": {
    "Email": "[email protected]",
    "FirstName": "João",
    "LastName": "Silva",
    "PhoneNumber": "11987654321",
    "Address": {
      "Country": "AR",
      "City": "Buenos Aires",
      "State": "C",
      "PostalCode": "11223",
      "AddressDetail": "Avenida Paulista 1000"
    }
  },
  "Order": "CH2023-001",
  "TargetCountryISO": "AR",
  "ThreeDSAuthMethod": "INTERNAL",
  "Redirection": {
    "url_Response": "https://www.merchant-response-page.com"
  }
}

{
  "TrxToken": "OT__6dHAgJo6qeg62qIroA7H7_f_NWZZ6IEx4jiYpVJ8SzQ_",
  "Amount": 100000,
  "Capture": true,
  "Currency": "ARS",
  "Installments": 1,
  "Customer": {
    "Email": "[email protected]",
    "FirstName": "João",
    "LastName": "Silva",
    "PhoneNumber": "11987654321",
    "Address": {
      "Country": "AR",
      "City": "Buenos Aires",
      "State": "C",
      "PostalCode": "11223",
      "AddressDetail": "Avenida Paulista 1000"
    }
  },
  "Order": "CH2023-001",
  "TargetCountryISO": "AR",
  "ThreeDSAuthMethod": "INTERNAL",
  "Redirection": {
    "url_Response": "https://www.merchant-response-page.com"
  }
}

Response — 3DS Required

{
  "TransactionId": "79632697147789184",
  "Result": "ACTION_REQUIRED",
  "Status": "PENDING",
  "ErrorCode": null,
  "ErrorDescription": null,
  "Created": "2026-07-30T21:43:36.440",
  "AuthorizationDate": null,
  "AuthorizationCode": null,
  "Amount": 100000,
  "Currency": "ARS",
  "Installments": 1,
  "Url": "https://api.bamboopayment.com/v3/api/transaction/79632697147789184",
  "MetadataOut": null,
  "Action": {
    "SessionId": "CA_00000000-0000-0000-0000-000000000000",
    "URL": "https://auth-3ds.bamboopayment.com?data=<opaque_base64_payload>",
    "Reason": "AUTHENTICATION_REQUIRED"
  },
  "PaymentMethod": {
    "Brand": "VISA",
    "CardOwner": "João Silva",
    "Bin": "450799",
    "IssuerBank": "Santander",
    "Type": "CreditCard",
    "Expiration": "203008",
    "Last4": "4905"
  },
  "CardOnFile": null
}

Step 2 — Redirect the payer

Redirect the payer to Action.URL. This redirect always happens once 3DS applies — regardless of whether the issuer ends up showing a challenge — because it's how Bamboo's hosted page collects the device data needed to decide whether a challenge is required at all. From there, Bamboo's hosted page:

1. Loads and collects device fingerprint data.
2. Runs the enrollment check through Bamboo's 3DS Server.
3. Shows the issuer's challenge screen if required.
4. Completes the pending purchase and authorizes it with the acquirer.
5. Redirects the payer back to your url_Response.

There's no widget or SDK to embed on your side — this is the main difference vs. integrating your own 3DS Server.

Step 3 — Get the result

Once the purchase resolves, Bamboo sends the standard Transaction Notification webhook, and the same data is available via GET Transaction. Both now include a ThreeDS object with the authentication result:

Error Codes

3DS-specific errors follow the same TR family used across Bamboo:

Prerequisites

• PCI-DSS compliance: only required if you send card data directly through CardData. If you integrate with TrxToken (via the tokenization API or the hosted Tokenization Form), this doesn't apply to you. (Confirm the specific SAQ/level required for the CardData path with your Bamboo account manager.)
• 3DS enabled on your merchant account: ask your Bamboo account manager to enable 3DS for the acquirer(s)/country(ies) you operate in — otherwise transactions resolve without 3DS (TR043).
• Redirection.url_Response reachable and stable: it must be a URL the payer's browser can reach directly (not localhost, not behind auth walls).
• Webhook endpoint configured: to receive the final ThreeDS + purchase result — see Transaction Notification.

Next Steps