> ## 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 new PIX key > Requires the pix.create permission. Creates a new PIX key for the authenticated company. The key will be registered with the specified provider. For EVP (random) keys, the provider will generate the key value automatically. All other key types require a valid key value matching the type's format. ## OpenAPI ````yaml /api-spec.yaml post /v1/pix/keys 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/pix/keys: post: tags: - Company Pix summary: Create a new PIX key description: > Requires the pix.create permission. Creates a new PIX key for the authenticated company. The key will be registered with the specified provider. For EVP (random) keys, the provider will generate the key value automatically. All other key types require a valid key value matching the type's format. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePixKey' responses: '201': description: Pix key created successfully content: application/json: schema: $ref: '#/components/schemas/PixKeyResponse' '400': description: Validation error '401': description: Unauthorized - Invalid or missing API key '403': description: Insufficient permissions to access this resource content: application/json: schema: $ref: '#/components/schemas/AuthorizationErrorResponse' '404': description: Company or Provider not found '500': description: Internal server error security: - ApiKeyAuth: [] components: schemas: CreatePixKey: type: object required: - provider - key_type properties: provider: type: string enum: - CELCOIN - RINNE - CAPPTA minLength: 1 description: >- The provider name (accepts lowercase and uppercase, returns uppercase) example: CELCOIN key_type: type: - string - 'null' description: > The Pix key type: - EVP: Random key generated by provider (key field should not be provided) enum: - EVP primary: type: boolean description: >- Whether the Pix key should be set as the primary pix key for the company default: false example: false PixKeyResponse: type: object required: - id - affiliation_id - company_id - key_type - key - primary - status properties: id: type: string description: Pix key unique identifier example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793 affiliation_id: type: string description: Affiliation ID associated with this PIX key example: a3dbd0c2-9f79-4f86-8caa-47779b3f2794 company_id: type: string description: Company ID that owns this PIX key example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793 key_type: type: string description: The Pix key type enum: - EVP example: EVP key: type: - string - 'null' description: The Pix key value (null for EVP keys before activation) primary: type: boolean description: Whether this is the primary PIX key for the company example: true status: type: string description: | The current status of the PIX key: - ACTIVE: Key is active and can be used - INACTIVE: Key is inactive - PENDING_DELETION: Key is marked for deletion - DELETED: Key has been deleted enum: - ACTIVE - INACTIVE - PENDING_DELETION - DELETED example: ACTIVE 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 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: Company API key for authentication ````