> ## Documentation Index > Fetch the complete documentation index at: https://docs.rinne.com.br/llms.txt > Use this file to discover all available pages before exploring further. # 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:** 1. Create a 3DS session with encrypted card data 2. If `auth_status` is `ACTION_REQUIRED`, the cardholder must complete the 3DS challenge using the `tds_session_id` with the client-side SDK 3. If `auth_status` is `AUTHENTICATED`, the session is ready to be used in a transaction 4. Pass the session `id` as `three_d_secure_session_id` when creating a card transaction **Expiration:** Sessions expire 1 hour after creation. **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`. ## OpenAPI ````yaml /api-spec.yaml post /v1/3ds-sessions openapi: 3.1.0 info: title: Rinne API version: 1.0.0 description: > **Rinne API** is a robust payment platform that offers integration with multiple payment providers. ## Authentication The API uses API Key authentication via the `x-api-key` header. Each company has a unique key to access resources. ## Response Format All responses follow a consistent format: - **Success**: Returns the requested data directly - **Error**: Returns an `error` object with detailed information ## Pagination Endpoints that return lists support pagination through parameters: - `page`: Page number (default: 1) - `limit`: Items per page (default: 20, maximum: 100) ## Supported Providers The API supports multiple payment providers: - **Rinne**: Internal provider - **Celcoin**: PIX integration and other financial services ## Raw Card Data (PCI Endpoints) Card credential fields (`card_data.number`, `card_data.cvv`, `card_data.network_token`, `card_data.cryptogram`, and the 3DS `card.number`) must always be sent encrypted — values start with the `ev:` prefix. Plaintext values are rejected with `400 VALIDATION_ERROR` on every host. There are two ways to send encrypted values: - **rinne-js**: card forms and wallet buttons (Apple Pay / Google Pay) encrypt credentials client-side before they leave the browser. - **PCI API host**: server-to-server integrations that handle raw card data must call `https://pci.api.rinne.com.br/core` (sandbox: `https://pci.api-sandbox.rinne.com.br/core`) instead of the regular host. This endpoint encrypts `number` and `cvv` in transit before the request reaches the API; all other fields pass through unchanged. The PCI host serves only transaction creation and 3DS session creation (both the self and merchant variants); use the regular host for everything else. contact: name: Rinne API Support email: suporte@rinne.com.br servers: - url: https://api-sandbox.rinne.com.br/core description: Sandbox - url: https://api.rinne.com.br/core description: Production security: [] tags: - name: System description: System and API health endpoints - name: Authentication description: User authentication and authorization endpoints - name: Management description: >- Merchant management endpoints - create, list, get specific, overview, update - name: Transactions description: Transaction operations for merchants - create, list, overview, refunds - name: Affiliations description: Affiliation management for merchants - name: Banking description: Banking operations for merchants - balance, cashout, statements - name: Bank Accounts description: Bank account management for merchants - name: Pix Keys description: PIX key management for merchants - name: Company Transactions description: Direct transaction management and query endpoints for companies - name: Companies description: Company management - name: Company Affiliations description: Payment provider affiliation management - name: Company Banking description: Company banking endpoints (balance, etc.) - name: Company Pix description: Company PIX key management - name: Company Ledger description: Company ledger entry query endpoints - name: Ledger description: Ledger entry query endpoints (company and merchants) - name: Cards description: Stored card management (self and merchant) - name: Webhooks description: Endpoints for receiving webhooks from external providers - name: Pricing description: Fee and cost policy management for transaction pricing - name: Users description: User management endpoints - name: Roles description: Role management endpoints - name: Permissions description: Permission management endpoints paths: /v1/3ds-sessions: post: tags: - 3D Secure summary: Create a 3D Secure session description: > Creates a standalone 3D Secure (3DS) authentication session for a card payment in the authenticated company context. Requires the 3ds.create permission. **Flow:** 1. Create a 3DS session with encrypted card data 2. If `auth_status` is `ACTION_REQUIRED`, the cardholder must complete the 3DS challenge using the `tds_session_id` with the client-side SDK 3. If `auth_status` is `AUTHENTICATED`, the session is ready to be used in a transaction 4. Pass the session `id` as `three_d_secure_session_id` when creating a card transaction **Expiration:** Sessions expire 1 hour after creation. **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`. operationId: createSelf3DSSession requestBody: required: true content: application/json: schema: type: object required: - amount - currency - card properties: amount: type: integer minimum: 1 description: Transaction amount in minor units (cents) example: 10000 currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code example: BRL card: type: object required: - number - expiry properties: number: type: string pattern: '^ev:' description: | Encrypted card number (`ev:` prefix); plaintext values are rejected with `400 VALIDATION_ERROR`. Send raw card data via the PCI API host, which encrypts it in transit, or encrypt client-side with rinne-js (see *Raw Card Data*). example: ev:encrypted:... expiry: type: object required: - month - year properties: month: type: string pattern: ^(0[1-9]|1[0-2])$ description: Card expiry month (MM format, 01-12) example: '12' year: type: string pattern: ^\d{4}$ description: Card expiry year (YYYY format required) example: '2027' merchant: type: object description: > Optional merchant overrides. Only `website` can be overridden. All other merchant fields (name, category_code, country) are always derived from the Company entity. properties: website: type: string format: uri description: > 3DS Requestor URL / customer-care website that might be shown to cardholders during technical errors in the 3DS authentication flow. This is NOT the page initiating the session. If omitted, falls back to the authenticated company's `website_url`, then the parent organization's `website_url`. example: https://support.mystore.com payer_email: type: string format: email description: Cardholder email for richer 3DS authentication example: john@example.com payer_name: type: string description: Cardholder name example: John Doe payer_document: type: string description: Cardholder document (CPF, etc.) example: 123.456.789-00 billing_address: type: object required: - line - city - postal_code - country properties: line: type: string description: Street address line example: 123 Main St city: type: string example: Sao Paulo state: type: string example: SP postal_code: type: string example: 01001-000 country: type: string minLength: 2 maxLength: 2 example: BR responses: '201': description: 3DS session created successfully content: application/json: schema: $ref: '#/components/schemas/ThreeDSecureSessionResponse' '400': description: >- Validation error — invalid card data, missing/invalid fields, or an unsupported card network (only Visa, Mastercard, and American Express are supported for 3DS). content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/AuthenticationErrorResponse' '403': description: Insufficient permissions to access this resource content: application/json: schema: $ref: '#/components/schemas/AuthorizationErrorResponse' '404': description: Authenticated company not found content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '502': description: 3DS provider error (provider unreachable, unexpected response, etc.) content: application/json: schema: $ref: '#/components/schemas/IntegrationErrorResponse' security: - ApiKeyAuth: [] servers: - url: https://api-sandbox.rinne.com.br/core description: Sandbox - url: https://pci.api-sandbox.rinne.com.br/core description: Sandbox (PCI — encrypts raw card number/cvv in transit) - url: https://api.rinne.com.br/core description: Production - url: https://pci.api.rinne.com.br/core description: Production (PCI — encrypts raw card number/cvv in transit) components: schemas: ThreeDSecureSessionResponse: type: object properties: id: type: string format: uuid description: >- Internal 3DS session ID (use as three_d_secure_session_id when creating a transaction) example: 550e8400-e29b-41d4-a716-446655440000 tds_session_id: type: string description: >- Provider session ID (use with the client-side SDK for challenge flows) example: tds_visa_e7c2yfa3867c auth_status: type: string enum: - ACTION_REQUIRED - AUTHENTICATED - FAILED description: > Current authentication status: - `ACTION_REQUIRED`: Cardholder must complete 3DS challenge - `AUTHENTICATED`: Authentication successful (frictionless or completed challenge) - `FAILED`: Authentication failed example: AUTHENTICATED consumption_status: type: string enum: - NOT_CONSUMED - PROCESSING - CONSUMED description: | 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 example: NOT_CONSUMED amount: type: integer description: Amount in minor units (cents) example: 10000 currency: type: string description: ISO 4217 currency code example: BRL failure_reason: type: - string - 'null' description: >- Reason for authentication failure (only present when auth_status is FAILED) example: null liability_shift: type: - boolean - 'null' description: Whether liability has shifted to the issuer example: true authentication_flow: type: - string - 'null' description: 3DS authentication flow type (frictionless, challenge, attempt) example: frictionless expires_at: type: string format: date-time description: Session expiration time example: '2026-02-06T20:35:00.000Z' created_at: type: string format: date-time example: '2026-02-06T19:35:00.000Z' updated_at: type: string format: date-time example: '2026-02-06T19:35:00.000Z' ValidationErrorResponse: type: object properties: error: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: Validation error status: type: integer example: 400 details: type: object properties: issues: type: array items: type: object properties: field: type: string example: email type: type: string example: REQUIRED message: type: string example: Field 'email' is required value: anyOf: - type: string - type: number - type: boolean example: invalid_value constraints: type: object example: min: 18 max: 120 path: type: string example: /companies timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 AuthenticationErrorResponse: type: object properties: error: type: object properties: code: type: string example: AUTHENTICATION_ERROR message: type: string example: Authentication required to access this resource status: type: integer example: 401 details: type: object properties: reason: type: string example: Invalid API key path: type: string example: /companies/me timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 AuthorizationErrorResponse: type: object properties: error: type: object properties: code: type: string example: AUTHORIZATION_ERROR message: type: string example: You need 'admin' permissions to access this resource status: type: integer example: 403 path: type: string example: /companies timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 NotFoundErrorResponse: type: object properties: error: type: object properties: code: type: string example: RESOURCE_NOT_FOUND message: type: string example: Company with ID '123' not found status: type: integer example: 404 path: type: string example: /companies/me timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 IntegrationErrorResponse: type: object properties: error: type: object properties: code: type: string example: INTEGRATION_ERROR message: type: string example: Integration error with provider CELCOIN status: type: integer example: 502 path: type: string example: /merchants/{merchantId}/balance timestamp: type: string format: date-time requestId: type: string details: type: object additionalProperties: true securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: Company API key for authentication ````