> ## 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. # Start a biometric verification > Requires the merchant.biometric-verification.create permission. Starts a liveness capture of the merchant's contact at the provider and returns the provider's own capture URL (`verification_url`), to be handed to the person as is; `verification_url_expires_at` is Rinne's clock plus the lifetime the provider granted. The result arrives through the `biometric-verification.status-changed` webhook event: `APPROVED` stores the selfie as a `SELFIE` onboarding document and the provider's evidence package; `REPROVED` carries the provider's `rejection_reason` and stores the evidence package only. `provider` must offer biometric verifications (today `CELCOIN`); any other answers `400` on `provider`. `subject_document_number` must be the merchant's contact's document number; anyone else answers `400` on `subject_document_number`. One verification per person and provider is pending at a time: a second request answers `409` with `details.pending_verification_id`. ## OpenAPI ````yaml /api-spec.yaml post /v1/merchants/{merchantId}/biometric-verifications 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: Company Receivables description: Contract effects on the company's own receivables - 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/merchants/{merchantId}/biometric-verifications: post: tags: - Biometric Verifications summary: Start a biometric verification description: > Requires the merchant.biometric-verification.create permission. Starts a liveness capture of the merchant's contact at the provider and returns the provider's own capture URL (`verification_url`), to be handed to the person as is; `verification_url_expires_at` is Rinne's clock plus the lifetime the provider granted. The result arrives through the `biometric-verification.status-changed` webhook event: `APPROVED` stores the selfie as a `SELFIE` onboarding document and the provider's evidence package; `REPROVED` carries the provider's `rejection_reason` and stores the evidence package only. `provider` must offer biometric verifications (today `CELCOIN`); any other answers `400` on `provider`. `subject_document_number` must be the merchant's contact's document number; anyone else answers `400` on `subject_document_number`. One verification per person and provider is pending at a time: a second request answers `409` with `details.pending_verification_id`. parameters: - in: path name: merchantId required: true schema: type: string description: The merchant ID example: c0a8012e-4d3b-4a6e-8f1b-1a2b3c4d5e6f requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBiometricVerificationRequest' responses: '201': description: The verification, `PENDING`, with the provider's capture URL content: application/json: schema: $ref: '#/components/schemas/BiometricVerificationResponse' '400': description: >- Validation error, a provider without biometric verifications, or a subject who is not the contact 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, or biometric verifications are not available to the caller yet (`message`: "Biometric verifications is not available yet") content: application/json: schema: $ref: '#/components/schemas/AuthorizationErrorResponse' '404': description: >- Merchant not found or does not belong to the authenticated organization content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: > A verification of this person at this provider is pending and its `verification_url` has not expired, or expired less than ten minutes ago. Every company that person is the contact of, within the organization, can read it by `details.pending_verification_id`; the `biometric-verification.status-changed` event stays with the company that created it. A pending verification whose `verification_url` expired more than ten minutes ago is resolved first (the provider's result is applied when it has one, otherwise the row is closed as `EXPIRED`) and the new one is created. content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' example: error: code: CONFLICT_ERROR message: >- A BiometricVerification with this subject_document_number already exists status: 409 details: pending_verification_id: 2b6f0a5e-7c1d-4f1a-9a3e-2d0c1b7e8f90 '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' security: - ApiKeyAuth: [] components: schemas: CreateBiometricVerificationRequest: type: object properties: provider: type: string enum: - CELCOIN description: >- The provider that runs the capture; it must offer biometric verifications example: CELCOIN subject_document_number: type: string description: >- The document number (CPF) of the company's contact; punctuation is ignored example: 811.464.310-23 redirect_url: type: string format: uri description: Where the provider sends the person after the capture example: https://app.example.com/onboarding/done required: - provider - subject_document_number BiometricVerificationResponse: description: A biometric verification of a company contact at a provider allOf: - $ref: '#/components/schemas/BiometricVerificationEntitySnapshot' - type: object required: - approved_at 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 ConflictErrorResponse: type: object properties: error: type: object properties: code: type: string example: CONFLICT_ERROR message: type: string example: >- A Resource with this origin_bank_account_id + request_id already exists status: type: integer example: 409 details: type: object properties: field: description: >- The field(s) involved in the conflict. May also name a state check rather than a constraint column. type: string example: origin_bank_account_id + request_id value: type: string example: '12345678' path: type: string example: /companies/bank-accounts timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 InternalServerErrorResponse: type: object properties: error: type: object properties: code: type: string example: INTERNAL_SERVER_ERROR message: type: string example: An unexpected error occurred status: type: integer example: 500 path: type: string example: /companies timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 BiometricVerificationEntitySnapshot: type: object description: > A biometric verification as the `entity` of `biometric-verification.status-changed` carries it. Same shape as `BiometricVerificationResponse`, except that `approved_at` may be absent: it was added after the event existed, and a snapshot is taken when the event is written. properties: id: type: string format: uuid example: 2b6f0a5e-7c1d-4f1a-9a3e-2d0c1b7e8f90 company_id: type: string description: >- The company the verification was created for (the organization itself or one of its merchants) example: c0a8012e-4d3b-4a6e-8f1b-1a2b3c4d5e6f provider: type: string enum: - CELCOIN example: CELCOIN subject_document_number: type: string description: The verified person's document number (CPF), digits only example: '81146431023' status: type: string enum: - PENDING - APPROVED - REPROVED - EXPIRED description: > `PENDING` until the provider reports the capture; `APPROVED` or `REPROVED` from its result; `EXPIRED` when the capture URL expired with no result. example: PENDING verification_url: type: string format: uri description: The provider's capture URL, to be handed to the person as is example: https://biometric.provider.example/session/abc verification_url_expires_at: type: string format: date-time description: When the capture URL stops working example: '2026-10-09T12:00:00.000Z' redirect_url: type: string format: uri nullable: true description: >- Where the provider sends the person after the capture, when given at creation example: https://app.example.com/onboarding/done selfie_onboarding_document_id: type: string format: uuid nullable: true description: >- The `SELFIE` onboarding document an `APPROVED` result produced; `null` otherwise example: null approved_at: type: string format: date-time nullable: true description: When the verification became `APPROVED`; `null` on any other status example: null rejection_reason: nullable: true allOf: - $ref: '#/components/schemas/BiometricVerificationRejectionReason' description: The provider's reason for a `REPROVED` result; `null` otherwise created_at: type: string format: date-time example: '2026-10-08T12:00:00.000Z' updated_at: type: string format: date-time example: '2026-10-08T12:00:00.000Z' required: - id - company_id - provider - subject_document_number - status - verification_url - verification_url_expires_at - redirect_url - selfie_onboarding_document_id - rejection_reason - created_at - updated_at BiometricVerificationRejectionReason: type: object description: The provider's reason for a `REPROVED` result properties: code: type: string description: The provider's reason code example: RRU008 message: type: string description: The provider's reason, as it stated it example: Identity could not be confirmed during the biometric validation test required: - code - message securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: Company API key for authentication ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.