3DS Integration

Marlim uses 3D Secure (3DS) authentication to confirm the cardholder's identity during payment. When 3DS is triggered, the issuing bank may request an additional verification step. This reduces fraud and increases transaction approval rates.

Attention

The 3DS authentication flow only supports Visa, Mastercard and Elo cards. American Express (Amex) cards are not supported in this flow. Ask the customer to use one of the supported card brands.

SDK

The Marlim 3DS SDK was developed with speed of integration and complexity reduction in mind. Built to be simple and straightforward, you configure, authenticate, and you're ready to perform a transaction with 3DS authentication.

Installation

Before initializing 3DS, you need to import the SDK via CDN or NPM.

These examples use version 1.1.0, which adds card_id as an input to authenticate(). Pin the version to choose when your checkout receives an SDK update.

CDN

To import via CDN, add the script tag to your checkout page HTML:

<script src="https://cdn.marlim.co/3ds/1.1.0/marlim-3ds-sdk.min.js"></script>

NPM

If you prefer to manage the SDK as a dependency of your project, you can install it via NPM. Run the command below in your project's terminal:

npm install --save-exact marlim-sdk-3ds@1.1.0

For more information about the NPM package, check the official page on NPM.

SDK updates

Keep the exact version in the CDN URL or project dependency (1.1.0, without ^ or ~) and commit your lockfile. To upgrade, choose the new version, validate your checkout in Sandbox and update your integration reference. Publishing a new SDK version does not change a pinned reference.

The legacy URL https://cdn.marlim.co/marlim-3ds-sdk.min.js does not select a version. To control updates to your checkout, migrate to the versioned URL shown above.

Session Token

The first step to use the Marlim 3DS SDK is to generate a session token through our API. This token is required to initialize the SDK and perform 3DS authentication. The session token works as a temporary key that allows the SDK to communicate with our services securely during the authentication process. Without it, it's not possible to proceed with the integration.

Important

The session token must be generated by your backend to avoid exposing your api_key on the frontend. Never make direct calls to our token generation API from the client, as this would compromise the security of your integration.

Public Key for Encryption

In addition to the session token, our API also returns a public key required to encrypt card data before sending it for 3DS authentication.

With this public key, you can generate a secure card_hash to send card data during 3DS authentication. To understand how to create the card_hash, check our documentation on how to generate a card_hash.

Response Object

Response from GET /v3/3ds/sessions:

Property	Type	Description
session	object	Session data used by the 3DS SDK.
session.session_token	string	Token used to initialize the SDK and authenticate 3DS setup and authentication requests.
session.created_at	number	Session creation time as a Unix timestamp in milliseconds.
session.expires_at	number	Session expiration time as a Unix timestamp in milliseconds. The session is valid for 30 minutes.
card_hash	object	Public key data used to encrypt the card.
card_hash.public_key	string	Public key used to generate the card_hash.
card_hash.public_key_id	string	Public key identifier.
card_hash.created_at	number	Key creation time as a Unix timestamp in milliseconds.
card_hash.expires_at	number	Key expiration time as a Unix timestamp in milliseconds.

Example - Generating 3DS session

curl -X GET "https://api.marlim.co/v3/3ds/sessions" \
-H "api_key: your-api-key" \
-d '{}'

Response200

{
  "session": {
    "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "created_at": 1760984954000,
    "expires_at": 1760986754000
  },
  "card_hash": {
    "public_key": "-----BEGIN PUBLIC KEY-----\n...",
    "public_key_id": "061ab8ee28bfb5fa...",
    "created_at": 1760984954894,
    "expires_at": 1760986754894
  }
}

Initialization

Initialization is used to configure the SDK with the environment you are using and the session token required for authentication.

MarlimSDK_3DS.init({
  token: 'your-session-token-here',
  env: 'sandbox' // or 'production'
});

Important

This step is essential for 3DS authentication to occur. Without proper SDK initialization, it won't be possible to proceed with the authentication process.

Authentication

After SDK initialization, perform 3DS authentication using the authenticate() method. This process collects card and customer data, executes 3DS verification, and returns the card_id and threeds_authentication_id.

Provide exactly one card input: card, card_hash or card_id. With card_id, the SDK uses a saved card and still performs setup, device data collection and a new 3DS authentication. You do not need to send the card details again.

Properties

Attribute	Type	Description
amount	int32	Final amount to be charged from the paying customer. Must be passed in cents.
card	object	Card data object. Use only when neither card_hash nor card_id is provided.
card[number]	string	Card number.
card[expirationDate]	string	Card expiration date. Numbers only in MMYY format.
card[cvv]	string	Card verification code.
card[holderName]	string	Cardholder name.
customer	object	Customer Object.
customer[name]	string	Customer name.
customer[documentNumber]	string	Customer document number.
customer[email]	string	Customer email.
customer[phone]	object	Customer phone number object.
customer[phone][countryCode]	string	Customer phone country code (DDI), e.g.: 55.
customer[phone][areaCode]	string	Customer phone area code (DDD).
customer[phone][number]	string	Customer phone number.
customer[address]	object	Customer Address Object from card billing or customer residence.
customer[address][country]	string	Customer nationality, in country code format. Only ISO 3166-1 alpha-2 (two-letter) format will be accepted. E.g.: BR, US, UY... Maximum characters: 2
customer[address][state]	string	State from card billing or customer residence, in state code format. E.g.: SP, RJ, MG... Maximum characters: 2
customer[address][city]	string	City from card billing or customer residence. Maximum characters: 50
customer[address][neighborhood]	string	Neighborhood from card billing or customer residence. Maximum characters: 45
customer[address][street]	string	Street from card billing or customer residence. Maximum characters: 54
customer[address][number]	string	Number from card billing or customer residence. Maximum characters: 5
customer[address][complement]	string	Optional parameter for complement from card billing or customer residence. Maximum characters: 14
customer[address][zipcode]	string	ZIP code from card billing or customer residence. Maximum characters: 9

Optional

In addition to required parameters, the authenticate() method offers optional parameters. The card_hash is a secure alternative to open card data, allowing card identification without exposing sensitive information through a hash generated by our public key API. Check our documentation on how to generate a card_hash. The challenge forces the display of the 3DS challenge during development, allowing you to test different authentication scenarios. The softDescriptorChallenge allows you to define the name displayed to the cardholder during the 3DS challenge. When not provided, the seller's default configured name is used. This parameter changes only the name sent to 3DS (merchantName) and does not replace the soft_descriptor used in the transaction endpoint.

Important

Provide exactly one of the three options: card, card_hash or card_id. Do not combine these inputs in the same call.

Attribute	Type	Description
card_id	string	ID of a card already saved in Marlim. Alternative to card and card_hash, available in Sandbox and Production.
card_hash	string	Encrypted card hash. Allows secure card identification without storing sensitive data.
challenge	boolean	Forces 3DS challenge during authentication. Available only in Sandbox environment to simulate different authentication flows.
softDescriptorChallenge	string	Name displayed in the 3DS challenge. Optional parameter. Maximum of 30 characters, accepting letters, numbers, and spaces. When not provided, the seller's default name is used.

Authentication examples

Each example contains a complete authenticate() call. Customer data and the other parameters are the same; only the card input changes. The values are illustrative and must be replaced with data from your integration.

🕹  Authentication example with card (card details)

Provide the card details in the card object.

await MarlimSDK_3DS.authenticate({
  amount: 1000, // Amount in cents
  softDescriptorChallenge: 'LOJA EXEMPLO', // Optional
  // challenge: true, // Optional: force a challenge in Sandbox only
  card: {
    number: '4111111111111111',
    expirationDate: '1230', // MMYY format
    cvv: '123',
    holderName: 'Jose Silva'
  },
  customer: {
    name: 'Jose Silva',
    documentNumber: '12345678909',
    email: 'jose.silva@example.com',
    phone: {
      number: '999999999',
      areaCode: '11',
      countryCode: '55'
    },
    address: {
      country: 'BR',
      state: 'SP',
      city: 'São Paulo',
      neighborhood: 'Centro',
      number: '123',
      street: 'Rua das Flores',
      zipcode: '01001000',
      complement: 'Apt 123'
    }
  }
});

🕹  Authentication example with card_hash (encrypted card)

Replace YOUR_CARD_HASH with the hash generated for this attempt. See how to generate a card_hash.

await MarlimSDK_3DS.authenticate({
  amount: 1000, // Amount in cents
  softDescriptorChallenge: 'LOJA EXEMPLO', // Optional
  // challenge: true, // Optional: force a challenge in Sandbox only
  card_hash: 'YOUR_CARD_HASH',
  customer: {
    name: 'Jose Silva',
    documentNumber: '12345678909',
    email: 'jose.silva@example.com',
    phone: {
      number: '999999999',
      areaCode: '11',
      countryCode: '55'
    },
    address: {
      country: 'BR',
      state: 'SP',
      city: 'São Paulo',
      neighborhood: 'Centro',
      number: '123',
      street: 'Rua das Flores',
      zipcode: '01001000',
      complement: 'Apt 123'
    }
  }
});

🕹  Authentication example with card_id (saved card)

Replace card_id with the ID of a card already saved in the environment you are using (Sandbox or Production). You do not need to resend the card details or generate a card_hash.

await MarlimSDK_3DS.authenticate({
  amount: 1000, // Amount in cents
  softDescriptorChallenge: 'LOJA EXEMPLO', // Optional
  // challenge: true, // Optional: force a challenge in Sandbox only
  card_id: 'card_097v98z0djvnbwaaaai54mxqew',
  customer: {
    name: 'Jose Silva',
    documentNumber: '12345678909',
    email: 'jose.silva@example.com',
    phone: {
      number: '999999999',
      areaCode: '11',
      countryCode: '55'
    },
    address: {
      country: 'BR',
      state: 'SP',
      city: 'São Paulo',
      neighborhood: 'Centro',
      number: '123',
      street: 'Rua das Flores',
      zipcode: '01001000',
      complement: 'Apt 123'
    }
  }
});

Setup reuses the supplied card_id. With card or card_hash, it creates a new ID. In all cases, use the IDs returned for this attempt and submit the same amount in the transaction. Reusing a card does not allow reusing a previous authentication.

Response Object

Property	Type	Description
card_id	string	Card ID returned by setup. Matches the input when card_id is provided.
threeds_authentication_id	string	3DS authentication ID. Required to be sent in the transaction endpoint for the transaction to occur with 3DS authentication.

Response Example

{
  "card_id": "card_097v98z0djvnbwaaaai54mxqew",
  "threeds_authentication_id": "32WcjjJ8U445AUaaaafv01"
}

After successful 3DS authentication, use the card_id and threeds_authentication_id in the transaction endpoint. The card_id represents a saved and validated card that can be used in future transactions without needing to provide card data again. The threeds_authentication_id is required to apply 3DS authentication to the transaction and is specific to each transaction.

To create the transaction, check our documentation on how to create a card transaction.