> ## 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. # Get a 3D Secure session > Returns a 3D Secure session with its current `auth_status`. Use it server-side to confirm the outcome of a challenge the cardholder completed in the client-side SDK, for example after saving a card with no charge. Requires the 3ds.view permission. **When to call:** once, after the SDK's `onSuccess`, `onFailure` or `onError` callback fires — not in a loop. While the session is `ACTION_REQUIRED`, the status is re-read from the 3DS provider before responding, so a challenge completed since creation is reflected here. `AUTHENTICATED` and `FAILED` are final and returned as stored. **Verifying a saved card:** create the session with `card.card_id`, then check that the `card_id` returned here is the card you saved. A session created with inline card data returns `card_id: null`. **`AUTHENTICATED` is not always an authenticated cardholder:** with `authentication_flow: attempt`, the cardholder was not authenticated and only proof of the authentication attempt exists. ## OpenAPI ````yaml /api-spec.yaml get /v1/3ds-sessions/{id} 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: Tap-on-Phone description: Access-token minting for the Tap-on-Phone SDK (called from your backend) - 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: Biometric Verifications description: Biometric verifications of your merchants' contacts - name: Onboarding Requirements description: What your merchants must prove to a provider, and how far along they are - name: Onboarding Documents description: Documents uploaded for your merchants - name: KYC description: KYC check history of your 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 Biometric Verifications description: Biometric verifications of the company contact - name: Company Onboarding Requirements description: What the company must prove to a provider, and how far along it is - name: Company Onboarding Documents description: Documents the company uploads for its onboarding - 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: Company Disputes description: Company dispute query endpoints - name: Ledger description: Ledger entry query endpoints (company and merchants) - name: Disputes description: Dispute query endpoints for an organization's merchants - name: Cards description: Stored card management (self and merchant) - name: API Keys description: API key management - create, list, revoke (hashed, show-once) - 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/{id}: get: tags: - 3D Secure summary: Get a 3D Secure session description: > Returns a 3D Secure session with its current `auth_status`. Use it server-side to confirm the outcome of a challenge the cardholder completed in the client-side SDK, for example after saving a card with no charge. Requires the 3ds.view permission. **When to call:** once, after the SDK's `onSuccess`, `onFailure` or `onError` callback fires — not in a loop. While the session is `ACTION_REQUIRED`, the status is re-read from the 3DS provider before responding, so a challenge completed since creation is reflected here. `AUTHENTICATED` and `FAILED` are final and returned as stored. **Verifying a saved card:** create the session with `card.card_id`, then check that the `card_id` returned here is the card you saved. A session created with inline card data returns `card_id: null`. **`AUTHENTICATED` is not always an authenticated cardholder:** with `authentication_flow: attempt`, the cardholder was not authenticated and only proof of the authentication attempt exists. operationId: getSelf3DSSession parameters: - name: id in: path required: true description: 3DS session ID (`id` from the create response) schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 responses: '200': description: The 3DS session content: application/json: schema: $ref: '#/components/schemas/ThreeDSecureSessionResponse' '401': description: Unauthorized - Invalid or missing authentication 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: Session not found for the authenticated company content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '502': description: 3DS provider error while refreshing a pending session content: application/json: schema: $ref: '#/components/schemas/IntegrationErrorResponse' security: - ApiKeyAuth: [] - BearerAuth: [] 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 card_id: type: string format: uuid nullable: true description: > 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: 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), or only attempted: with `authentication_flow: attempt` the cardholder was not authenticated and only proof of the attempt exists - `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). `attempt` comes with `auth_status: AUTHENTICATED`, but the cardholder was not authenticated: only proof of the authentication attempt exists. 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' 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 BearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token for user authentication ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.