Create a 3D Secure session linked to a merchant

curl --request POST \
  --url https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": 10000,
  "currency": "BRL",
  "card": {
    "card_id": "123e4567-e89b-12d3-a456-426614174000",
    "number": "ev:encrypted:..."
  },
  "merchant": {
    "website": "https://support.mystore.com"
  },
  "payer_email": "[email protected]",
  "payer_name": "João da Silva",
  "payer_document": "123.456.789-00"
}
'

import requests

url = "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions"

payload = {
    "amount": 10000,
    "currency": "BRL",
    "card": {
        "card_id": "123e4567-e89b-12d3-a456-426614174000",
        "number": "ev:encrypted:..."
    },
    "merchant": { "website": "https://support.mystore.com" },
    "payer_email": "[email protected]",
    "payer_name": "João da Silva",
    "payer_document": "123.456.789-00"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 10000,
    currency: 'BRL',
    card: {card_id: '123e4567-e89b-12d3-a456-426614174000', number: 'ev:encrypted:...'},
    merchant: {website: 'https://support.mystore.com'},
    payer_email: '[email protected]',
    payer_name: 'João da Silva',
    payer_document: '123.456.789-00'
  })
};

fetch('https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 10000,
    'currency' => 'BRL',
    'card' => [
        'card_id' => '123e4567-e89b-12d3-a456-426614174000',
        'number' => 'ev:encrypted:...'
    ],
    'merchant' => [
        'website' => 'https://support.mystore.com'
    ],
    'payer_email' => '[email protected]',
    'payer_name' => 'João da Silva',
    'payer_document' => '123.456.789-00'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions"

	payload := strings.NewReader("{\n  \"amount\": 10000,\n  \"currency\": \"BRL\",\n  \"card\": {\n    \"card_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"number\": \"ev:encrypted:...\"\n  },\n  \"merchant\": {\n    \"website\": \"https://support.mystore.com\"\n  },\n  \"payer_email\": \"[email protected]\",\n  \"payer_name\": \"João da Silva\",\n  \"payer_document\": \"123.456.789-00\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 10000,\n  \"currency\": \"BRL\",\n  \"card\": {\n    \"card_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"number\": \"ev:encrypted:...\"\n  },\n  \"merchant\": {\n    \"website\": \"https://support.mystore.com\"\n  },\n  \"payer_email\": \"[email protected]\",\n  \"payer_name\": \"João da Silva\",\n  \"payer_document\": \"123.456.789-00\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 10000,\n  \"currency\": \"BRL\",\n  \"card\": {\n    \"card_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"number\": \"ev:encrypted:...\"\n  },\n  \"merchant\": {\n    \"website\": \"https://support.mystore.com\"\n  },\n  \"payer_email\": \"[email protected]\",\n  \"payer_name\": \"João da Silva\",\n  \"payer_document\": \"123.456.789-00\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tds_session_id": "tds_visa_e7c2yfa3867c",
  "card_id": "123e4567-e89b-12d3-a456-426614174000",
  "auth_status": "AUTHENTICATED",
  "consumption_status": "NOT_CONSUMED",
  "amount": 10000,
  "currency": "BRL",
  "failure_reason": null,
  "liability_shift": true,
  "authentication_flow": "frictionless",
  "expires_at": "2026-02-06T20:35:00.000Z",
  "created_at": "2026-02-06T19:35:00.000Z",
  "updated_at": "2026-02-06T19:35:00.000Z"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "status": 400,
    "details": {
      "issues": [
        {
          "field": "email",
          "type": "REQUIRED",
          "message": "Field 'email' is required",
          "value": "invalid_value",
          "constraints": {
            "min": 18,
            "max": 120
          }
        }
      ]
    },
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Authentication required to access this resource",
    "status": 401,
    "details": {
      "reason": "Invalid API key"
    },
    "path": "/companies/me",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "You need 'admin' permissions to access this resource",
    "status": 403,
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Company with ID '123' not found",
    "status": 404,
    "path": "/companies/me",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "INTEGRATION_ERROR",
    "message": "Integration error with provider CELCOIN",
    "status": 502,
    "path": "/merchants/{merchantId}/balance",
    "timestamp": "2023-11-07T05:31:56Z",
    "requestId": "<string>",
    "details": {}
  }
}

Transactions

Create a 3D Secure session linked to a merchant

Creates a standalone 3D Secure (3DS) authentication session for a card payment. Requires the merchant.3ds.create permission.

Flow:

Create a 3DS session with encrypted card data, or with card.card_id to authenticate a card stored via POST /v1/cards
If auth_status is ACTION_REQUIRED, the cardholder must complete the 3DS challenge using the tds_session_id with the client-side SDK
If auth_status is AUTHENTICATED, the session is ready to be used in a transaction
Pass the session id as three_d_secure_session_id when creating a card transaction

Expiration: Sessions expire 1 hour after creation.

Single use: A session authenticates one amount and currency and can be spent on one transaction. Recurring charges need a new session each time — a stored card does not change this.

Supported card networks: Visa, Mastercard, and American Express. Cards from other networks (e.g. Elo, Hipercard, Discover, Diners, JCB) cannot be authenticated and are rejected with 400 VALIDATION_ERROR.

POST

merchants

{merchantId}

3ds-sessions

Create a 3D Secure session linked to a merchant

curl --request POST \
  --url https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": 10000,
  "currency": "BRL",
  "card": {
    "card_id": "123e4567-e89b-12d3-a456-426614174000",
    "number": "ev:encrypted:..."
  },
  "merchant": {
    "website": "https://support.mystore.com"
  },
  "payer_email": "[email protected]",
  "payer_name": "João da Silva",
  "payer_document": "123.456.789-00"
}
'

import requests

url = "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions"

payload = {
    "amount": 10000,
    "currency": "BRL",
    "card": {
        "card_id": "123e4567-e89b-12d3-a456-426614174000",
        "number": "ev:encrypted:..."
    },
    "merchant": { "website": "https://support.mystore.com" },
    "payer_email": "[email protected]",
    "payer_name": "João da Silva",
    "payer_document": "123.456.789-00"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 10000,
    currency: 'BRL',
    card: {card_id: '123e4567-e89b-12d3-a456-426614174000', number: 'ev:encrypted:...'},
    merchant: {website: 'https://support.mystore.com'},
    payer_email: '[email protected]',
    payer_name: 'João da Silva',
    payer_document: '123.456.789-00'
  })
};

fetch('https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 10000,
    'currency' => 'BRL',
    'card' => [
        'card_id' => '123e4567-e89b-12d3-a456-426614174000',
        'number' => 'ev:encrypted:...'
    ],
    'merchant' => [
        'website' => 'https://support.mystore.com'
    ],
    'payer_email' => '[email protected]',
    'payer_name' => 'João da Silva',
    'payer_document' => '123.456.789-00'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions"

	payload := strings.NewReader("{\n  \"amount\": 10000,\n  \"currency\": \"BRL\",\n  \"card\": {\n    \"card_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"number\": \"ev:encrypted:...\"\n  },\n  \"merchant\": {\n    \"website\": \"https://support.mystore.com\"\n  },\n  \"payer_email\": \"[email protected]\",\n  \"payer_name\": \"João da Silva\",\n  \"payer_document\": \"123.456.789-00\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 10000,\n  \"currency\": \"BRL\",\n  \"card\": {\n    \"card_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"number\": \"ev:encrypted:...\"\n  },\n  \"merchant\": {\n    \"website\": \"https://support.mystore.com\"\n  },\n  \"payer_email\": \"[email protected]\",\n  \"payer_name\": \"João da Silva\",\n  \"payer_document\": \"123.456.789-00\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/3ds-sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 10000,\n  \"currency\": \"BRL\",\n  \"card\": {\n    \"card_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"number\": \"ev:encrypted:...\"\n  },\n  \"merchant\": {\n    \"website\": \"https://support.mystore.com\"\n  },\n  \"payer_email\": \"[email protected]\",\n  \"payer_name\": \"João da Silva\",\n  \"payer_document\": \"123.456.789-00\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tds_session_id": "tds_visa_e7c2yfa3867c",
  "card_id": "123e4567-e89b-12d3-a456-426614174000",
  "auth_status": "AUTHENTICATED",
  "consumption_status": "NOT_CONSUMED",
  "amount": 10000,
  "currency": "BRL",
  "failure_reason": null,
  "liability_shift": true,
  "authentication_flow": "frictionless",
  "expires_at": "2026-02-06T20:35:00.000Z",
  "created_at": "2026-02-06T19:35:00.000Z",
  "updated_at": "2026-02-06T19:35:00.000Z"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "status": 400,
    "details": {
      "issues": [
        {
          "field": "email",
          "type": "REQUIRED",
          "message": "Field 'email' is required",
          "value": "invalid_value",
          "constraints": {
            "min": 18,
            "max": 120
          }
        }
      ]
    },
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Authentication required to access this resource",
    "status": 401,
    "details": {
      "reason": "Invalid API key"
    },
    "path": "/companies/me",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "You need 'admin' permissions to access this resource",
    "status": 403,
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Company with ID '123' not found",
    "status": 404,
    "path": "/companies/me",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "INTEGRATION_ERROR",
    "message": "Integration error with provider CELCOIN",
    "status": 502,
    "path": "/merchants/{merchantId}/balance",
    "timestamp": "2023-11-07T05:31:56Z",
    "requestId": "<string>",
    "details": {}
  }
}

Authorizations

x-api-key

string

header

required

Company API key for authentication

Path Parameters

merchantId

string<uuid>

required

Merchant/Company ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

Body

application/json

amount

integer

required

Transaction amount in minor units (cents)

Required range: x >= 1

Example:

10000

currency

string

required

ISO 4217 currency code

Required string length: 3

Example:

"BRL"

card

object

required

Card to authenticate. Provide either card_id (a card stored via POST /v1/cards) or the inline pair number + expiry — never both.

Option 1
Option 2

Show child attributes

merchant

object

Optional merchant overrides. Only website can be overridden. All other merchant fields (name, category_code, country) are always derived from the Company entity. The merchant name shown to the cardholder during a challenge is the company's legal name (full_name), shortened to the 40 characters the 3DS specification allows.

Show child attributes

payer_email

string<email>

Cardholder email for richer 3DS authentication

Example:

"[email protected]"

payer_name

string

Cardholder name. Accented and non-Latin characters are accepted; accents are folded for authentication (e.g. "João" is authenticated as "Joao"), while the name is stored exactly as sent. Names that cannot be folded to unaccented Latin letters may be rejected by the authentication provider. Names containing invalid characters are rejected. Not allowed together with card.card_id: a stored card supplies its own cardholder_name, so set it when storing the card. The other payer fields (payer_email, payer_document, billing_address) are still accepted with a stored card.

Example:

"João da Silva"

payer_document

string

Cardholder document (CPF, etc.)

Example:

"123.456.789-00"

billing_address

object

Show child attributes

Response

3DS session created successfully

string<uuid>

Internal 3DS session ID (use as three_d_secure_session_id when creating a transaction)

Example:

"550e8400-e29b-41d4-a716-446655440000"

tds_session_id

string

Provider session ID (use with the client-side SDK for challenge flows)

Example:

"tds_visa_e7c2yfa3867c"

card_id

string<uuid> | null

The stored card this session authenticated, or null when the card was sent inline. When both this and the transaction's card_data.card_id are set, they must match or the transaction is rejected.

Example:

"123e4567-e89b-12d3-a456-426614174000"

auth_status

enum<string>

Current authentication status:

ACTION_REQUIRED: Cardholder must complete 3DS challenge
AUTHENTICATED: Authentication successful (frictionless or completed challenge)
FAILED: Authentication failed

Available options:

ACTION_REQUIRED,

AUTHENTICATED,

FAILED

Example:

"AUTHENTICATED"

consumption_status

enum<string>

Whether this session has been used for a transaction:

NOT_CONSUMED: Available for use
PROCESSING: Currently being used (atomic claim)
CONSUMED: Already used for a transaction

Available options:

NOT_CONSUMED,

PROCESSING,

CONSUMED

Example:

"NOT_CONSUMED"

amount

integer

Amount in minor units (cents)

Example:

10000

currency

string

ISO 4217 currency code

Example:

"BRL"

failure_reason

string | null

Reason for authentication failure (only present when auth_status is FAILED)

Example:

null

liability_shift

boolean | null

Whether liability has shifted to the issuer

Example:

true

authentication_flow

string | null

3DS authentication flow type (frictionless, challenge, attempt)

Example:

"frictionless"

expires_at

string<date-time>

Session expiration time

Example:

"2026-02-06T20:35:00.000Z"

created_at

string<date-time>

Example:

"2026-02-06T19:35:00.000Z"

updated_at

string<date-time>

Example:

"2026-02-06T19:35:00.000Z"

Introduction

Merchants

Pricing

Webhooks

Organization Management

User Management

System

Create a 3D Secure session linked to a merchant

Authorizations

Path Parameters

Body

Response