Authenticate a merchant's transaction with 3D Secure

Authenticates a transaction that is in AWAITING_3DS status using a 3D Secure session. Links the authenticated session to the transaction, updates card data with 3DS authentication details (cryptogram, ECI, authentication_type), and processes the payment with the provider. Requires the merchant.transaction.create permission.

This endpoint is used in the transaction-first 3DS flow:

1. Transaction is created and enters AWAITING_3DS status
2. Organization creates a 3DS session and completes authentication
3. Organization calls this endpoint to link the session and process the payment

The session must be authenticated, not consumed, not expired, and match the transaction’s merchant, amount, and currency.

POST /v1/merchants/{merchantId}/transactions/{transactionId}/authenticate

Authenticate a merchant's transaction with 3D Secure

cURL

curl --request POST \
  --url https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/transactions/{transactionId}/authenticate \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "three_d_secure_session_id": "550e8400-e29b-41d4-a716-446655440000"
}
'

200

{
  "id": "tx_123456789",
  "provider": "CELCOIN",
  "affiliation_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "request_id": "request-123",
  "mcc": "5411",
  "amount": 10050,
  "currency": "BRL",
  "pricing": {
    "fee": {
      "percentage": 2.5,
      "flat": 50,
      "minimum_price": 100
    },
    "cost": {
      "percentage": 2.5,
      "flat": 50,
      "minimum_price": 100
    }
  },
  "status": "APPROVED",
  "capture_method": "EMV",
  "installments": 1,
  "payment_method": "PIX",
  "automatic_anticipation": false,
  "company_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "created_at": "2023-12-01T10:00:00.000Z",
  "fee_policy_id": "fee_policy_123",
  "cost_policy_id": "cost_policy_123",
  "approved_amount": 10050,
  "refunded_amount": 0,
  "acquirer_response_code": "00",
  "pix_data": {
    "pix_key_id": "pix_key_123",
    "description": "Payment for order #123",
    "qr_code": "00020126580014br.gov.bcb.pix0136a3dbd0c2-9f79-4f86-8caa-47779b3f2793520400005303986540510.005802BR5913Test Company6008São Paulo62070503***6304E2CA",
    "expires_at": "2023-12-02T10:00:00.000Z",
    "identification": "order_123",
    "expiration_in_seconds": 86400,
    "end_to_end_id": "E12345678202312101234567890123456",
    "due_date": "2025-12-31",
    "expiration_in_days_after_due_date": 30,
    "interest": {
      "modality": "PERCENTAGE_PER_MONTH",
      "amount": 1000,
      "percentage": 10.5
    },
    "fine": {
      "modality": "PERCENTAGE",
      "amount": 2000,
      "percentage": 2.5
    },
    "discount": {
      "modality": "PERCENTAGE_UNTIL_DATE",
      "amount": 2,
      "percentage": 50,
      "discount_dates_config": [
        {
          "until_date": "2025-12-15",
          "percentage": 10
        },
        {
          "until_date": "2025-12-20",
          "percentage": 5
        }
      ]
    },
    "abatement": {
      "modality": "FIXED",
      "amount": 5000,
      "percentage": 5
    }
  },
  "bolepix_data": {
    "pix_key_id": "pix_key_123",
    "external_request_id": "ext-req-123",
    "due_date": "2025-12-31",
    "expiration_in_days_after_due_date": 30,
    "boleto_transaction_id": "boleto-123",
    "bank_issuer": "Banco do Brasil",
    "bank_code": "001",
    "bank_branch": "1234",
    "bank_account_number": "12345-6",
    "bar_code": "00190000090299993600000000000000185830000010000",
    "bank_line": "00190.00009 02999.936001 00000.000001 8 58300000010000",
    "bank_assignor": "Company Name",
    "pix_transaction_id": "pix-123",
    "pix_identification": "txid123456789",
    "pix_emv": "00020126580014br.gov.bcb.pix...",
    "paid_via": "PIX",
    "paid_amount": 50000,
    "paid_at": "2025-12-20T10:00:00.000Z",
    "discount": {
      "amount": 5000,
      "percentage": 10,
      "modality": "FIXED",
      "until_date": "2025-12-25"
    },
    "fine_percentage": 2,
    "monthly_interest_percentage": 1
  },
  "card_data": {
    "expiry_month": "12",
    "expiry_year": "2028",
    "last_digits": "1111",
    "brand": "VISA",
    "device_id": "device-123",
    "cardholder_name": "John Doe",
    "country": "BR",
    "wallet_type": "APPLE_PAY",
    "display_name": "Visa •••• 1111",
    "authentication_type": "3DS"
  },
  "soft_descriptor": "MYSTORE",
  "serial_number": "12345678",
  "nsu": "000123",
  "metadata": {},
  "latest_refund_at": "2023-12-01T10:00:00.000Z",
  "status_reason": "PROVIDER",
  "approved_at": "2023-12-01T10:00:00.000Z",
  "company_full_name": "Test Company",
  "company_name": "Test Company",
  "organization_id": "tx_organization_123456",
  "consumer": {
    "document_type": "CPF",
    "full_name": "João Silva",
    "email": "[e-mail]",
    "pix_key": "[e-mail]",
    "document_number": "81146431023",
    "phone": "[phone]",
    "birth_date": "15-08-1990",
    "address": {
      "street": "Rua das Flores",
      "neighborhood": "Centro",
      "zipcode": "12345678",
      "country": "076",
      "state": "SP",
      "city": "São Paulo",
      "street_number": "123",
      "complement": "Apt 101"
    }
  },
  "updated_at": "2023-12-01T10:00:00.000Z"
}

Authorizations

x-api-key · string · header · required

Company API key for authentication

Path Parameters

merchantId · string<uuid> · required

Merchant ID

transactionId · string<uuid> · required

Transaction ID (must be in AWAITING_3DS status)

Body

application/json

three_d_secure_session_id · string<uuid> · required

ID of an authenticated 3D Secure session to link to the transaction

Example:

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

Response

200

application/json

Transaction authenticated and processed successfully

Transaction data returned by the API

id · string · required

Transaction unique identifier

Example:

"tx_123456789"

provider · enum<string> · required

Payment provider

Available options: CELCOIN, RINNE, CAPPTA

Example:

"CELCOIN"

affiliation_id · string · required

Affiliation ID for this transaction

Example:

"a3dbd0c2-9f79-4f86-8caa-47779b3f2793"

request_id · string · required

Unique request ID for this transaction used for idempotency

Example:

"request-123"

mcc · string · required

Merchant Category Code

Example:

"5411"

amount · integer · required

Transaction amount in cents

Example:

10050

currency · enum<string> · required

Transaction currency

Available options: BRL

Example:

"BRL"

pricing · object · required

Transaction pricing information

Show child attributes

status · enum<string> · required

Transaction status

Available options: PROCESSING, AUTHORIZED, APPROVED, REFUNDED, PARTIALLY_REFUNDED, PENDING_REFUND, CHARGEDBACK, WAITING_PAYMENT, AWAITING_3DS, REFUSED, FAILED, EXPIRED, PENDING_CANCELLATION, CANCELLED

Example:

"APPROVED"

capture_method · enum<string> · required

Transaction capture method

Available options: EMV, MAGSTRIPE, ECOMMERCE, CONTACTLESS_ICC

Example:

"EMV"

installments · integer | null · required

Number of installments

Example:

1

payment_method · enum<string> · required

Payment method

Available options: CREDIT_CARD, DEBIT_CARD, PIX, BOLEPIX

Example:

"PIX"

automatic_anticipation · boolean · required

Whether this transaction was automatically anticipated at creation time. Set to true when the affiliation's anticipation_type is AUTOMATIC; false otherwise.

Example:

false

company_id · string · required

Company ID that owns this transaction

Example:

"a3dbd0c2-9f79-4f86-8caa-47779b3f2793"

created_at · string<date-time> · required

Transaction creation timestamp

Example:

"2023-12-01T10:00:00.000Z"

fee_policy_id · string | null

Fee policy ID applied to this transaction

Example:

"fee_policy_123"

cost_policy_id · string | null

Cost policy ID applied to this transaction

Example:

"cost_policy_123"

approved_amount · integer | null

Approved amount in cents

Example:

10050

refunded_amount · integer | null

Total amount refunded in cents (sum of completed refunds)

Example:

0

acquirer_response_code · string | null

Acquirer response code

Example:

"00"

pix_data · object

PIX-specific data (present if payment_method is PIX)

Show child attributes

bolepix_data · object

Bolepix-specific data (present if payment_method is BOLEPIX)

Show child attributes

card_data · object

Card-specific data (present if payment_method is CREDIT_CARD or DEBIT_CARD)

Show child attributes

soft_descriptor · string | null

Soft descriptor shown on cardholder statement

Example:

"MYSTORE"

serial_number · string | null

Terminal serial number

Example:

"12345678"

nsu · string | null

Network Sequential Number

Example:

"000123"

metadata · object

Additional metadata

latest_refund_at · string<date-time> | null

Latest refund timestamp (for the most recent completed refund)

Example:

"2023-12-01T10:00:00.000Z"

status_reason · enum<string> | null

Status reason details

Available options: PROVIDER, ACQUIRER, ANTIFRAUD, INTERNAL_ERROR, NO_ACQUIRER, ACQUIRER_TIMEOUT, CHALLENGE_NOT_ALLOWED

Example:

"PROVIDER"

approved_at · string | null

Transaction approval timestamp

Example:

"2023-12-01T10:00:00.000Z"

company_full_name · string

Company full name

Example:

"Test Company"

company_name · string | null

Company name

Example:

"Test Company"

organization_id · string | null

Organization transaction ID (for refunds/chargebacks)

Example:

"tx_organization_123456"

consumer · object

Consumer information

Show child attributes

updated_at · string<date-time> | null

Transaction last update timestamp

Example:

"2023-12-01T10:00:00.000Z"