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.

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.

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.

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
  }
}

Installation

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

CDN

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

<script src="https://cdn.marlim.co/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 marlim-sdk-3ds

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

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.

await MarlimSDK_3DS.authenticate({
  amount: 1000, // Amount in cents
  card: {
    number: '1111111111111111',
    expirationDate: '0126', // Format MMYY
    cvv: '123',
    holderName: 'John Doe'
  },
  customer: {
    name: 'Jose Silva',
    documentNumber: '9999999999',
    email: 'joao.silva@example.com',
    phone: {
      number: '999999999',
      areaCode: '99',
      countryCode: '55'
    },
    address: {
      country: 'BR',
      state: 'SP',
      city: 'São Paulo',
      neighborhood: 'Centro',
      number: '123',
      street: 'Rua das Flores',
      zipcode: '01001000',
      complement: 'Apt 123'
    }
  }
});

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.
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.

Important

You cannot use open card data and card_hash simultaneously. You must choose only one of the two options.

Attribute	Type	Description
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.

Example with optional parameters

await MarlimSDK_3DS.authenticate({
  amount: 1000, // Amount in cents
  card_hash: "93237fb4c0948881dc99929899f6eda2...",
  challenge: true, // Forces 3DS challenge (Sandbox only)
  customer: {
    name: 'Jose Silva',
    documentNumber: '9999999999',
    email: 'joao.silva@example.com',
    phone: {
      number: '999999999',
      areaCode: '99',
      countryCode: '55'
    },
    address: {
      country: 'BR',
      state: 'SP',
      city: 'São Paulo',
      neighborhood: 'Centro',
      number: '123',
      street: 'Rua das Flores',
      zipcode: '01001000',
      complement: 'Apt 123'
    }
  }
});

Result

Property	Type	Description
card_id	string	ID of a saved and validated card that can be used in the transaction.
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.