Create a 3D Secure session

curl --request POST \
  --url https://api-sandbox.rinne.com.br/core/v1/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/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/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/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/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/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/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",
  "acs_transaction_id": "b0bb6068-8d68-40a1-9606-20fa01ba74de",
  "ds_transaction_id": "cfb8d11b-8129-414e-983a-3e95f0f4f6c6",
  "server_transaction_id": "dc46fbb1-a898-4760-b8a2-56dae36cb0e2",
  "protocol_version": "2.2.0",
  "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": {}
  }
}

Company Transactions

Create a 3D Secure session

Creates a standalone 3D Secure (3DS) authentication session for a card payment in the authenticated company context. Requires the 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

3ds-sessions

Create a 3D Secure session

curl --request POST \
  --url https://api-sandbox.rinne.com.br/core/v1/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/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/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/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/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/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/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",
  "acs_transaction_id": "b0bb6068-8d68-40a1-9606-20fa01ba74de",
  "ds_transaction_id": "cfb8d11b-8129-414e-983a-3e95f0f4f6c6",
  "server_transaction_id": "dc46fbb1-a898-4760-b8a2-56dae36cb0e2",
  "protocol_version": "2.2.0",
  "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

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>

required

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

required

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

Example:

"tds_visa_e7c2yfa3867c"

card_id

string<uuid> | null

required

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>

required

Current authentication status:

ACTION_REQUIRED: Cardholder must complete 3DS challenge
AUTHENTICATED: Authentication successful (frictionless or completed challenge), or only attempted: with authentication_flow: attempt the cardholder was not authenticated and only proof of the attempt exists
FAILED: Authentication failed

Available options:

ACTION_REQUIRED,

AUTHENTICATED,

FAILED

Example:

"AUTHENTICATED"

consumption_status

enum<string>

required

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

required

Amount in minor units (cents)

Example:

10000

currency

string

required

ISO 4217 currency code

Example:

"BRL"

failure_reason

string | null

required

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

Example:

null

liability_shift

boolean | null

required

Whether liability has shifted to the issuer

Example:

true

authentication_flow

string | null

required

3DS authentication flow type (frictionless, challenge, attempt). attempt comes with auth_status: AUTHENTICATED, but the cardholder was not authenticated: only proof of the authentication attempt exists.

Example:

"frictionless"

acs_transaction_id

string | null

required

Transaction ID the issuer's Access Control Server (ACS) assigned to the authentication. Recorded with the outcome: null while auth_status is ACTION_REQUIRED, and when it was not reported.

Example:

"b0bb6068-8d68-40a1-9606-20fa01ba74de"

ds_transaction_id

string | null

required

Transaction ID the card network's Directory Server (DS) assigned to the authentication, which the network uses to find it, for example in a chargeback dispute. Recorded with the outcome: null while auth_status is ACTION_REQUIRED, and when it was not reported.

Example:

"cfb8d11b-8129-414e-983a-3e95f0f4f6c6"

server_transaction_id

string | null

required

Transaction ID the 3DS Server assigned to the authentication. Recorded with the outcome: null while auth_status is ACTION_REQUIRED, and when it was not reported.

Example:

"dc46fbb1-a898-4760-b8a2-56dae36cb0e2"

protocol_version

string | null

required

EMV 3-D Secure protocol version of the authentication. Recorded with the outcome: null while auth_status is ACTION_REQUIRED, and when it was not reported.

Example:

"2.2.0"

expires_at

string<date-time>

required

Session expiration time

Example:

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

created_at

string<date-time>

required

Example:

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

updated_at

string<date-time>

required

Example:

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

Introduction

Merchants

Pricing

Tap-on-Phone

Webhooks

Organization Management

User Management

System

Create a 3D Secure session

Authorizations

Body

Response