3DS with Tokenization Form

Bamboo provides a Bamboo-managed 3DS flow through the Tokenization Form, where Bamboo executes the full 3DS2 process, including frictionless and challenge flows.

📘

This method requires no PCI scope. Card data is captured securely by Bamboo.

Flow Overview

The 3DS flow handled by Bamboo’s Tokenization Form consists of 17 steps, grouped into the following four stages:

• 3DS Initialization
• Tokenization
• 3DS Authentication
• Purchase Authorization

3DS Initialization

1. Merchant prepares payment info
2. 3DS session is initialized using amount and billing address.
3. Bamboo returns AuthenticationId to bind the session to the Tokenization Form.

Tokenization

4. Merchant loads the Tokenization Form
5. Form is displayed to the payer.
6. Payer enters card data
7. Bamboo tokenizes the card
8. Card token is generated

3DS Authentication

9. Bamboo initiates 3DS authentication
10. Issuer evaluates the transaction
11. Challenge shown if required
12. Payer completes the challenge
13. Authentication approved
14. Form returns Token + Auth3DSId to the merchant

Purchase Authorization

15. Merchant creates the purchase including TrxToken and Auth3DSId
16. Bamboo processes the authorization with the acquirer
17. Purchase result is returned

3DS Initialization

When using the Tokenization Form, Bamboo requires specific fields to initialize the 3DS session. These parameters are evaluated by the issuer during risk-based authentication and must always be provided.

Required Parameters

BillingAddress object (all fields required)

Request Example

Test this endpoint in the API Reference

{
    "Currency": "USD",
    "Amount": "160",
    "Customer": {
        "Email": "[email protected]",
        "FirstName": "Juan Felipe",
        "LastName": "García",
        "PhoneNumber": "+59899999999",
        "BillingAddress": {
            "Country": "UY",
            "PostalCode": "11100",
            "AddressDetail": "Sarmiento 1234",
            "AdministrativeArea": "Montevideo"
        }
    }
}

Response

Example Response

{
    "AuthenticationId": "503a4368-8f39-4b28-a17f-8a5dd2afb90d",
    "AuthenticationToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoZW50aWNhdGlvbklkIjoiNTAzYTQzNjgtOGYzOS00YjI4LWExN2YtOGE1ZGQyYWZiOTBkIiwic2VydmljZVR5cGUiOiJjeWJlcnNvdXJjZSIsImlhdCI6MTc2NDYwOTEyOH0.jwH-F-Vt6ukBFwEDPZ3V7nKf1cI1upnZQyHbnHNx3eA"
}

Loading the Tokenization Form with 3DS

After initializing 3DS, the AuthenticationToken returned by the 3DS Initialize endpoint must be passed to the Tokenization Form configuration.

The token is sent inside metadata.authenticationToken in the options object used to load the form.

Form Initialization with AuthenticationToken

const options = {
  metadata: {
    publicKey: publicKey,
    targetCountryISO: document.getElementById("countryId").value,
    customer: {
      uniqueId: document.getElementById("uniqueId").value,
      email: email,
      cardOwnerName: cardOwnerName
    },
    logoUrl: logoUrl,
    locale: document.getElementById("langId").value,
    authenticationToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoZW50aWNhdGlvbklkIjoiNTAzYTQzNjgtOGYzOS00YjI4LWExN2YtOGE1ZGQyYWZiOTBkIiwic2VydmljZVR5cGUiOiJjeWJlcnNvdXJjZSIsImlhdCI6MTc2NDYwOTEyOH0.jwH-F-Vt6ukBFwEDPZ3V7nKf1cI1upnZQyHbnHNx3eA"
  },
  hooks: hooks,
  containerId: getContainerId()
};

The authenticationToken value must match the AuthenticationToken returned by the 3DS Initialize response. This binds the Tokenization Form session to the previously created 3DS authentication context.

Note:
The Tokenization Form returns the same structure shown on this page (the card Token).
For the purchase request, the Token must be sent as TrxToken, and the AuthenticationToken must be sent inside the ThreeDS object as ThreeDSId.
These values must match the identifiers returned during the 3DS initialization and Tokenization Form steps, so the acquirer can validate the authentication associated with the transaction.

3DS Fields Required in the Purchase Request

When the 3DS flow is handled through the Tokenization Form, Bamboo returns two values:

• the card Token, and
• the AuthenticationToken returned from the 3DS initialization step.

📘

Both values must be included in the purchase request

Required Parameters

Example (Purchase Request)

{
  "TrxToken": "OT__6dHAgJo6qeg62qIroA7H7_f_NWZZ6IEx4jiYpVJ8SzQ_",
  "UniqueID": "paymentID3022",
  "Capture": true,
  "TargetCountryISO": "BR",
  "Currency": "BRL",
  "Amount": 25000,
  "Installments": 2,
  "Order": "CH2023-001",
  "Description": "Compra de teste",
  
  "Customer": {
    "FirstName": "João",
    "LastName": "Silva",
    "ReferenceCode": "JS-001",
    "PhoneNumber": "11987654321",
    "DocumentNumber": "12345678901",
    "DocumentType": "CPF.BR",
    "Email": "[email protected]",
    "Address": {
      "Country": "BR",
      "City": "São Paulo",
      "State": "SP",
      "PostalCode": "01310-200",
      "AddressDetail": "Avenida Paulista 1000"
    }
  },

  "CustomerIP": "190.10.224.231",
  "AntifraudData": {
    "AntifraudFingerprintId": "0046f17b-197a-4d63-8b6b-6082cdd557ff"
  },
  "ThreeDSAuthMethod": "INTERNAL",
  "ThreeDS": {
    "ThreeDSId": "962b91dd-59d9-427c-951d-245eb9561c1a"
  }
}

Next Steps