> ## 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 transaction for a specific merchant > Requires the merchant.transaction.create permission. Creates a new transaction for a merchant that belongs to the authenticated organization ## OpenAPI ````yaml /api-spec.yaml post /v1/merchants/{merchantId}/transactions 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: 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 - name: Admin description: Admin management endpoints x-scalar-ignore: true paths: /v1/merchants/{merchantId}/transactions: post: tags: - Transactions summary: Create a new transaction for a specific merchant description: > Requires the merchant.transaction.create permission. Creates a new transaction for a merchant that belongs to the authenticated organization parameters: - in: path name: merchantId required: true schema: type: string description: The merchant ID example: 123e4567-e89b-12d3-a456-426614174000 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TransactionCreateRequest' responses: '201': description: Transaction created successfully content: application/json: schema: $ref: '#/components/schemas/TransactionResponse' '400': description: Validation error 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: Merchant not found or does not belong to authenticated organization content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' 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: TransactionCreateRequest: type: object description: | Schema for creating a new transaction. required: - provider - request_id - amount - capture_method - payment_method properties: provider: type: string description: Payment provider identifier enum: - CELCOIN example: CELCOIN request_id: type: string description: Unique request ID for this transaction (used for idempotency) minLength: 1 example: request-123 amount: type: integer minimum: 1 maximum: 1500000000 description: Transaction amount in cents (e.g., 10050 = R$ 100,50) example: 10050 currency: type: string enum: - BRL default: BRL description: Transaction currency (defaults to BRL) example: BRL capture_method: type: string enum: - EMV - MAGSTRIPE - ECOMMERCE - CONTACTLESS_ICC description: | Transaction capture method: - EMV: Chip card - MAGSTRIPE: Magnetic stripe - ECOMMERCE: Online transaction - CONTACTLESS_ICC: Contactless payment example: ECOMMERCE installments: type: integer minimum: 1 maximum: 18 default: 1 description: | Number of installments (1-18). Defaults to 1 if not sent. Must be 1 when payment_method is PIX or BOLEPIX. example: 1 payment_method: type: string enum: - CREDIT_CARD - DEBIT_CARD - PIX - BOLEPIX description: | Payment method: - CREDIT_CARD: Credit card payment - DEBIT_CARD: Debit card payment - PIX: Instant payment - BOLEPIX: Hybrid Boleto + PIX payment example: PIX pix_data: allOf: - $ref: '#/components/schemas/PixDataInput' description: > PIX-specific data. Required when payment_method is PIX. When `due_date` is provided: `consumer` is required (full_name, document_number, document_type) and use `expiration_in_days_after_due_date` (do not send `expiration_in_seconds`). When `due_date` is NOT provided: use `expiration_in_seconds` (do not send `expiration_in_days_after_due_date`). bolepix_data: allOf: - $ref: '#/components/schemas/BolepixDataInput' description: > BOLEPIX-specific data. Required when payment_method is BOLEPIX. When payment_method is BOLEPIX, `consumer` is required with full_name, document_type, document_number, and full address including `address.street_number`. card_data: allOf: - $ref: '#/components/schemas/CardDataInput' description: > Card payment data. Required for CREDIT_CARD and DEBIT_CARD payment methods. three_d_secure_session_id: type: string format: uuid description: > ID of an authenticated 3DS session to use for this transaction (session-first flow). When provided, the cryptogram and ECI from the session are injected into the card data. The session must be authenticated (auth_status=AUTHENTICATED), not expired, not already consumed, and match the transaction's company, amount, and currency. example: 550e8400-e29b-41d4-a716-446655440000 require_3ds: type: boolean description: | Card transactions only. When `true`, the transaction is created directly in `AWAITING_3DS` and is not sent to the provider until `/authenticate` is called with an authenticated 3DS session. example: true refuse_on_challenge: type: boolean description: | Card transactions only. When `true`, challenge-triggered paths are refused (`REFUSED`) instead of transitioning to `AWAITING_3DS`. Cannot be `true` together with `require_3ds`. example: false consumer: allOf: - $ref: '#/components/schemas/ConsumerInput' description: > Optional consumer/customer information. Required with full_name, document_number, and document_type when `pix_data.due_date` is provided. When payment_method is BOLEPIX, consumer is required and must include full_name, document_type, document_number, and full address including `address.street_number`. metadata: type: object description: Optional additional metadata (key-value pairs) additionalProperties: true example: order_id: order-123 customer_id: cust-456 split_rules: type: array description: | Optional split rules for transaction revenue sharing. **Important rules:** - Cannot mix amount and percentage in same transaction - If using amounts: sum must equal transaction amount - If using percentages: sum must equal 100% items: $ref: '#/components/schemas/SplitRuleInput' example: - company_id: company-1 amount: 5000 charge_processing_cost: true - company_id: company-2 amount: 5050 charge_processing_cost: false soft_descriptor: type: string description: Optional text shown on cardholder statement (max 13 chars) maxLength: 13 example: MYSTORE serial_number: type: string description: Optional terminal serial number example: '12345678' nsu: type: string description: Optional Network Sequential Number example: '000123' fee_policy_id: type: string description: > Optional fee policy ID to use for this transaction. If provided, this takes priority over the company's default fee policy. The fee policy must belong to the same organization as the company. example: 123e4567-e89b-12d3-a456-426614174000 TransactionResponse: type: object description: Transaction data returned by the API properties: id: type: string description: Transaction unique identifier example: tx_123456789 provider: type: string enum: - CELCOIN - RINNE - CAPPTA description: Payment provider example: CELCOIN affiliation_id: type: string description: Affiliation ID for this transaction example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793 request_id: type: string description: Unique request ID for this transaction used for idempotency example: request-123 mcc: type: string description: Merchant Category Code example: '5411' amount: type: integer description: Transaction amount in cents example: 10050 currency: type: string enum: - BRL description: Transaction currency example: BRL pricing: $ref: '#/components/schemas/TransactionPricing' description: Transaction pricing information fee_policy_id: type: - string - 'null' description: Fee policy ID applied to this transaction example: fee_policy_123 cost_policy_id: type: - string - 'null' description: Cost policy ID applied to this transaction example: cost_policy_123 approved_amount: type: - integer - 'null' description: Approved amount in cents example: 10050 refunded_amount: type: - integer - 'null' description: Total amount refunded in cents (sum of completed refunds) example: 0 three_d_secure_session_id: type: - string - 'null' format: uuid description: | ID of the 3DS session linked to this transaction, if any. Set when the transaction was created with a 3DS session (session-first flow) or authenticated via the /authenticate endpoint (transaction-first flow). example: 550e8400-e29b-41d4-a716-446655440000 status: type: string enum: - PROCESSING - AUTHORIZED - APPROVED - REFUNDED - PARTIALLY_REFUNDED - PENDING_REFUND - CHARGEDBACK - WAITING_PAYMENT - AWAITING_3DS - REFUSED - FAILED - EXPIRED - PENDING_CANCELLATION - CANCELLED description: Transaction status example: APPROVED acquirer_response_code: type: - string - 'null' description: Acquirer response code example: '00' capture_method: type: string enum: - EMV - MAGSTRIPE - ECOMMERCE - CONTACTLESS_ICC description: Transaction capture method example: EMV installments: type: - integer - 'null' description: Number of installments example: 1 payment_method: type: string enum: - CREDIT_CARD - DEBIT_CARD - PIX - BOLEPIX description: Payment method example: PIX pix_data: anyOf: - $ref: '#/components/schemas/PixDataResponse' - type: 'null' description: PIX-specific data (present if payment_method is PIX) bolepix_data: anyOf: - $ref: '#/components/schemas/BolepixDataResponse' - type: 'null' description: Bolepix-specific data (present if payment_method is BOLEPIX) card_data: anyOf: - $ref: '#/components/schemas/CardDataResponse' - type: 'null' description: >- Card-specific data (present if payment_method is CREDIT_CARD or DEBIT_CARD) soft_descriptor: type: - string - 'null' description: Soft descriptor shown on cardholder statement example: MYSTORE serial_number: type: - string - 'null' description: Terminal serial number example: '12345678' nsu: type: - string - 'null' description: Network Sequential Number example: '000123' metadata: type: - object - 'null' nullable: true description: Additional metadata additionalProperties: true latest_refund_at: type: - string - 'null' format: date-time description: Latest refund timestamp (for the most recent completed refund) example: '2023-12-01T10:00:00.000Z' status_reason: type: - string - 'null' enum: - PROVIDER - ACQUIRER - ANTIFRAUD - INTERNAL_ERROR - NO_ACQUIRER - ACQUIRER_TIMEOUT - CHALLENGE_NOT_ALLOWED - REVERSED description: >- Status reason details. REVERSED indicates a failed card transaction whose charge was later found at the acquirer and reversed by reconciliation. example: PROVIDER approved_at: type: - string - 'null' description: Transaction approval timestamp example: '2023-12-01T10:00:00.000Z' automatic_anticipation: type: boolean description: > 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: type: string description: Company ID that owns this transaction example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793 company_full_name: type: string description: Company full name example: Test Company company_name: type: - string - 'null' description: Company name example: Test Company organization_id: type: - string - 'null' description: Organization transaction ID (for refunds/chargebacks) example: tx_organization_123456 consumer: anyOf: - $ref: '#/components/schemas/ConsumerResponse' - type: 'null' description: Consumer information created_at: type: string format: date-time description: Transaction creation timestamp example: '2023-12-01T10:00:00.000Z' updated_at: type: - string - 'null' format: date-time description: Transaction last update timestamp example: '2023-12-01T10:00:00.000Z' required: - id - provider - affiliation_id - request_id - mcc - amount - currency - pricing - status - capture_method - installments - payment_method - automatic_anticipation - company_id - created_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 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 PixDataInput: type: object description: > PIX-specific data for creating PIX transactions. - Interest, fine, discount, and abatement can only be applied when `due_date` is provided. - When `due_date` is provided: `expiration_in_seconds` must not be provided. Use `expiration_in_days_after_due_date` instead - When `due_date` is NOT provided: `expiration_in_days_after_due_date` must not be provided. Use `expiration_in_seconds` instead - When using discount with `FIXED_AMOUNT_UNTIL_DATE` or `PERCENTAGE_UNTIL_DATE` modality: all `discount_dates_config` dates must be before or equal to `due_date` properties: pix_key_id: type: string description: | Optional PIX key ID to use for this transaction. If not provided, the company's primary PIX key will be used. example: pix_key_123 description: type: string description: Optional description for the PIX payment (shown to payer) example: 'Payment for order #123' expiration_in_seconds: type: integer minimum: 1 maximum: 86400 default: 86400 description: > PIX QR code expiration time in seconds (1-86400, default: 86400 = 24h). Required when `due_date` is NOT provided. Must not be provided otherwise. example: 3600 due_date: type: string format: date description: > Optional due date for the PIX payment in YYYY-MM-DD format. Required when using interest, fine, discount, or abatement. **Important:** For validation purposes, dates are always interpreted in Brazil timezone by default (America/Sao_Paulo, UTC-3). example: '2025-12-31' expiration_in_days_after_due_date: type: integer minimum: 1 maximum: 365 description: > Number of days after the due date before the PIX payment expires. Required when `due_date` is provided. Must not be provided otherwise. example: 30 default: 30 interest: allOf: - $ref: '#/components/schemas/InterestConfig' description: | Optional interest configuration. Requires due_date. Interest is applied when payment is made after the due date. fine: allOf: - $ref: '#/components/schemas/FineConfig' description: | Optional fine configuration. Requires due_date. Fine is applied when payment is made after the due date. discount: allOf: - $ref: '#/components/schemas/DiscountConfig' description: > Optional discount configuration. Requires due_date. Discount is applied when payment is made before or on specific dates. abatement: allOf: - $ref: '#/components/schemas/AbatementConfig' description: | Optional abatement configuration. Requires due_date. Abatement reduces the total amount to be paid. example: pix_key_id: pix_key_123 description: 'Payment for order #123' expiration_in_seconds: 3600 due_date: '2025-12-31' expiration_in_days_after_due_date: 30 interest: percentage: 1 modality: PERCENTAGE_PER_MONTH fine: percentage: 2 modality: PERCENTAGE discount: modality: PERCENTAGE_UNTIL_DATE discount_dates_config: - until_date: '2025-12-15' percentage: 10 - until_date: '2025-12-20' percentage: 5 BolepixDataInput: type: object description: > Bolepix-specific data for creating BOLEPIX transactions. BOLEPIX is a hybrid payment method that generates both a Boleto and a PIX QR code. **Minimum amount after discount is applied:** 500 cents (R$5.00) **Required consumer fields for BOLEPIX:** - full_name - document_number - address (with street_number) **Financial configurations:** - Discount: Applied if payment is made before the `until_date` - Fine: Applied if payment is made after the `due_date` - Interest: Value is divided by 30 and applied per day after the `due_date` required: - due_date properties: pix_key_id: type: string description: | Optional PIX key ID to use for this transaction. If not provided, the company's primary PIX key will be used. example: pix_key_123 due_date: type: string format: date description: > Due date for the Bolepix payment in YYYY-MM-DD format. Must be today or later. **Important:** For validation purposes, dates are always interpreted in Brazil timezone by default (America/Sao_Paulo, UTC-3). example: '2025-12-31' expiration_in_days_after_due_date: type: integer minimum: 0 maximum: 59 default: 0 description: > Number of days after the due date before the Bolepix payment expires. Range: 0-59 days. example: 30 discount: type: object description: > Optional discount configuration. Discount is applied when payment is made before or on the `until_date`. required: - modality - until_date properties: amount: type: integer minimum: 1 description: | Discount amount in cents (positive integer). Required for FIXED modality. Must not be provided for PERCENTAGE modality. example: 5000 percentage: type: number minimum: 0.01 maximum: 100 multipleOf: 0.01 description: | Discount percentage (0.01-100, up to 2 decimal places). Required for PERCENTAGE modality. Must not be provided for FIXED modality. example: 10 modality: type: string enum: - FIXED - PERCENTAGE default: FIXED description: | Discount modality: - FIXED: Fixed amount discount - PERCENTAGE: Percentage-based discount example: FIXED until_date: type: string format: date description: | Date until which the discount applies in YYYY-MM-DD format. Must be today or later and before or equal to `due_date`. example: '2025-12-25' fine_percentage: type: number minimum: 0.01 maximum: 100 multipleOf: 0.01 description: | Fine percentage applied when payment is made after the due date. Range: 0.01-100%, up to 2 decimal places. example: 2 monthly_interest_percentage: type: number minimum: 0.01 maximum: 100 multipleOf: 0.01 description: > Monthly interest percentage (divided by 30 and applied per day after due date) Range: 0.01-100%, up to 2 decimal places. example: 1 example: due_date: '2025-12-31' expiration_in_days_after_due_date: 30 discount: amount: 5000 modality: FIXED until_date: '2025-12-25' fine_percentage: 2 monthly_interest_percentage: 1 CardDataInput: oneOf: - $ref: '#/components/schemas/CardDataInputWithNumber' - $ref: '#/components/schemas/CardDataInputWithNetworkToken' description: | Card-specific data for creating credit or debit card transactions. **Provide exactly one of:** - `number` — for raw card entry (see Option 1) - `network_token` — for tokenized/wallet payments (see Option 2) example: network_token: ev:encrypted:... cryptogram: ev:encrypted:... expiry_month: '12' expiry_year: '2025' authentication_type: 3DS wallet_type: APPLE_PAY display_name: Visa •••• 1111 ConsumerInput: type: object description: > Optional consumer/customer information for the transaction. **Required field:** document_type **Note:** This information is useful for compliance and customer tracking. properties: full_name: type: string description: Consumer's full name example: João Silva email: type: string format: email description: Consumer's email address example: joao@email.com pix_key: type: string description: Consumer's PIX key (email, phone, CPF/CNPJ, or random key) example: joao@email.com document_type: type: string enum: - CPF - CNPJ description: | **REQUIRED** - Consumer's document type: - CPF: Individual taxpayer (11 digits) - CNPJ: Corporate taxpayer (14 digits) example: CPF document_number: type: string description: 'Consumer''s document number (CPF: 11 digits, CNPJ: 14 digits)' example: '81146431023' phone: type: string pattern: ^\\+?[0-9]{10,15}$ description: Consumer's phone number (with country code) example: '+5511999999999' birth_date: type: string pattern: ^[0-9]{2}-[0-9]{2}-[0-9]{4}$ description: Consumer's birth date in DD-MM-YYYY format example: 15-08-1990 address: allOf: - $ref: '#/components/schemas/AddressInput' description: Consumer's address information required: - document_type example: full_name: João Silva email: joao@email.com pix_key: joao@email.com document_type: CPF document_number: '81146431023' phone: '+5511999999999' birth_date: 15-08-1990 SplitRuleInput: type: object description: > Split rule for revenue sharing in transactions. **Required field:** company_id **Important validation rules:** - Use either `amount` OR `percentage` (never both in same transaction) - If using amounts: sum of all amounts must equal transaction amount - If using percentages: sum of all percentages must equal 100% **Example scenarios:** - Amount-based: [{"amount": 5000, "company_id": "A"}, {"amount": 5050, "company_id": "B"}] for R$ 100,50 transaction - Percentage-based: [{"percentage": 60, "company_id": "A"}, {"percentage": 40, "company_id": "B"}] properties: amount: type: integer minimum: 1 description: | Split amount in cents (mutually exclusive with percentage). Use this when you want to specify exact amounts. example: 5000 percentage: type: number minimum: 0 maximum: 100 description: | Split percentage (mutually exclusive with amount). Use this when you want proportional splits. example: 50 charge_processing_cost: type: boolean default: true description: Whether this recipient should be charged for processing costs example: true liable: type: boolean description: Whether this recipient is liable for chargebacks and disputes example: true company_id: type: string description: '**REQUIRED** - Company ID that will receive this split' example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793 affiliation_id: type: string description: Optional affiliation ID for this split example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793 processed: type: boolean default: false description: Internal field - whether split has been processed example: false required: - company_id example: amount: 5000 charge_processing_cost: true liable: true company_id: a3dbd0c2-9f79-4f86-8caa-47779b3f2793 TransactionPricing: type: object description: Transaction pricing information with fee and cost structures properties: fee: $ref: '#/components/schemas/PricingValue' description: Fee pricing structure cost: $ref: '#/components/schemas/PricingValue' description: Cost pricing structure required: - fee - cost PixDataResponse: type: object description: PIX-specific data for transactions properties: pix_key_id: type: - string - 'null' description: PIX key ID example: pix_key_123 description: type: - string - 'null' description: PIX description example: 'Payment for order #123' qr_code: type: - string - 'null' description: PIX QR code example: >- 00020126580014br.gov.bcb.pix0136a3dbd0c2-9f79-4f86-8caa-47779b3f2793520400005303986540510.005802BR5913Test Company6008São Paulo62070503***6304E2CA expires_at: type: - string - 'null' format: date-time description: PIX expiration timestamp example: '2023-12-02T10:00:00.000Z' identification: type: - string - 'null' description: PIX identification example: order_123 expiration_in_seconds: type: - integer - 'null' minimum: 1 maximum: 86400 description: Expiration time in seconds (1-86400) example: 86400 end_to_end_id: type: - string - 'null' description: PIX end-to-end ID example: E12345678202312101234567890123456 due_date: type: - string - 'null' format: date description: > Due date for the PIX payment in YYYY-MM-DD format. Mandatory when using interest, fine, discount, and/or abatement. **Important:** For validation purposes, dates are always interpreted in Brazil timezone by default (America/Sao_Paulo, UTC-3). example: '2025-12-31' expiration_in_days_after_due_date: type: - integer - 'null' minimum: 1 maximum: 365 description: >- Number of days after the due date before the PIX payment expires. Required when `due_date` is provided. Must not be provided otherwise. example: 30 default: 30 interest: anyOf: - allOf: - $ref: '#/components/schemas/InterestConfig' - type: 'null' description: Interest configuration (if applicable) fine: anyOf: - allOf: - $ref: '#/components/schemas/FineConfig' - type: 'null' description: Fine configuration (if applicable) discount: anyOf: - allOf: - $ref: '#/components/schemas/DiscountDatesConfigItemResponse' - type: 'null' description: Discount configuration (if applicable) abatement: anyOf: - allOf: - $ref: '#/components/schemas/AbatementConfig' - type: 'null' description: Abatement configuration (if applicable) BolepixDataResponse: type: object description: Bolepix-specific data for transactions required: - pix_key_id - external_request_id - due_date properties: pix_key_id: type: string description: PIX key ID used for this transaction example: pix_key_123 external_request_id: type: string description: External request ID used with the provider example: ext-req-123 due_date: type: string format: date description: Due date in YYYY-MM-DD format example: '2025-12-31' expiration_in_days_after_due_date: type: - integer - 'null' description: Days after due date before expiration example: 30 boleto_transaction_id: type: - string - 'null' description: Provider's boleto transaction ID example: boleto-123 bank_issuer: type: - string - 'null' description: Issuing bank name example: Banco do Brasil bank_code: type: - string - 'null' description: Issuing bank code example: '001' bank_branch: type: - string - 'null' description: Bank branch number example: '1234' bank_account_number: type: - string - 'null' description: Bank account number example: 12345-6 bar_code: type: - string - 'null' description: Boleto bar code example: '00190000090299993600000000000000185830000010000' bank_line: type: - string - 'null' description: Boleto bank line (typed representation of bar code) example: 00190.00009 02999.936001 00000.000001 8 58300000010000 bank_assignor: type: - string - 'null' description: Assignor name example: Company Name pix_transaction_id: type: - string - 'null' description: Provider's PIX transaction ID example: pix-123 pix_identification: type: - string - 'null' description: PIX identification (txid) example: txid123456789 pix_emv: type: - string - 'null' description: PIX EMV QR code payload example: 00020126580014br.gov.bcb.pix... paid_via: type: - string - 'null' enum: - PIX - BOLETO description: How the payment was made (PIX or BOLETO) example: PIX paid_amount: type: - integer - 'null' description: Amount actually paid in cents example: 50000 paid_at: type: - string - 'null' format: date-time description: Payment timestamp example: '2025-12-20T10:00:00.000Z' discount: type: - object - 'null' description: Discount configuration properties: amount: type: - integer - 'null' description: Discount amount in cents example: 5000 percentage: type: - number - 'null' description: Discount percentage example: 10 modality: type: string enum: - FIXED - PERCENTAGE description: Discount modality example: FIXED until_date: type: - string - 'null' format: date description: Date until which discount applies example: '2025-12-25' fine_percentage: type: - number - 'null' description: Fine percentage applied after due date example: 2 monthly_interest_percentage: type: - number - 'null' description: >- Monthly interest percentage (divided by 30 and applied per day after due date) example: 1 CardDataResponse: type: object description: >- Card data included in transaction responses. Only non-sensitive fields are returned. required: - expiry_month - expiry_year - last_digits properties: expiry_month: type: string pattern: ^(0[1-9]|1[0-2])$ description: Card expiration month in MM format (01-12). example: '12' expiry_year: type: string pattern: ^\d{4}$ description: Card expiration year in YYYY format. example: '2028' brand: type: - string - 'null' description: Card brand (e.g., VISA, MASTERCARD, ELO, AMEX). example: VISA device_id: type: - string - 'null' description: Device identifier associated with the card token, if available. example: device-123 last_digits: type: string pattern: ^\d{4}$ description: Last 4 digits of the card number. example: '1111' cardholder_name: type: - string - 'null' description: Name of the cardholder as it appears on the card. example: John Doe country: type: - string - 'null' description: Issuing country of the card (ISO 3166-1 alpha-2). example: BR wallet_type: type: - string - 'null' enum: - APPLE_PAY - GOOGLE_PAY description: Digital wallet type used for the payment, if applicable. example: APPLE_PAY display_name: type: - string - 'null' description: Human-readable display name for the card. example: Visa •••• 1111 authentication_type: type: - string - 'null' enum: - 3DS description: Authentication type used for the card transaction, if any. example: 3DS ConsumerResponse: type: object description: Consumer information properties: full_name: type: - string - 'null' example: João Silva email: type: - string - 'null' format: email example: joao@email.com pix_key: type: - string - 'null' example: joao@email.com document_type: type: string enum: - CPF - CNPJ description: Consumer document type example: CPF document_number: type: - string - 'null' example: '81146431023' phone: type: - string - 'null' example: '+5511999999999' birth_date: type: - string - 'null' example: 15-08-1990 address: anyOf: - $ref: '#/components/schemas/AddressResponse' - type: 'null' description: Consumer address required: - document_type InterestConfig: type: object description: | Interest configuration for PIX payments with due date. Interest is applied when payment is made after the due date. Exactly one of amount or percentage must be provided. required: - modality properties: amount: type: integer minimum: 1 description: > Interest amount in cents (positive integer). Required for amount-based modalities (AMOUNT_PER_DAY, AMOUNT_PER_WORKING_DAY). Must not be provided for percentage-based modalities. example: 1000 percentage: type: number minimum: 0 maximum: 100 multipleOf: 0.01 description: > Interest percentage (0-100, up to 2 decimal places). Required for percentage-based modalities (PERCENTAGE_PER_DAY, PERCENTAGE_PER_MONTH, etc.). Must not be provided for amount-based modalities. example: 10.5 modality: type: string enum: - AMOUNT_PER_DAY - PERCENTAGE_PER_DAY - PERCENTAGE_PER_MONTH - PERCENTAGE_PER_YEAR - AMOUNT_PER_WORKING_DAY - PERCENTAGE_PER_WORKING_DAY - PERCENTAGE_PER_WORKING_MONTH - PERCENTAGE_PER_WORKING_YEAR description: | Interest calculation modality: - AMOUNT_PER_DAY: Fixed amount per day - PERCENTAGE_PER_DAY: Percentage per day - PERCENTAGE_PER_MONTH: Percentage per month - PERCENTAGE_PER_YEAR: Percentage per year - AMOUNT_PER_WORKING_DAY: Fixed amount per working day - PERCENTAGE_PER_WORKING_DAY: Percentage per working day - PERCENTAGE_PER_WORKING_MONTH: Percentage per working month - PERCENTAGE_PER_WORKING_YEAR: Percentage per working year example: PERCENTAGE_PER_MONTH FineConfig: type: object description: | Fine configuration for PIX payments with due date. Fine is applied when payment is made after the due date. Exactly one of amount or percentage must be provided. required: - modality properties: amount: type: integer minimum: 1 description: | Fine amount in cents (positive integer). Required for FIXED modality. Must not be provided for PERCENTAGE modality. example: 2000 percentage: type: number minimum: 0 maximum: 100 multipleOf: 0.01 description: | Fine percentage (0-100, up to 2 decimal places). Required for PERCENTAGE modality. Must not be provided for FIXED modality. example: 2.5 modality: type: string enum: - FIXED - PERCENTAGE description: | Fine calculation modality: - FIXED: Fixed amount fine - PERCENTAGE: Percentage-based fine example: PERCENTAGE DiscountConfig: type: object description: | Discount configuration for PIX payments with due date. Discount is applied when payment is made up to specific dates. required: - modality properties: modality: type: string enum: - FIXED_AMOUNT_UNTIL_DATE - PERCENTAGE_UNTIL_DATE - AMOUNT_PER_DAY - AMOUNT_PER_WORKING_DAY - PERCENTAGE_PER_DAY - PERCENTAGE_PER_WORKING_DAY description: | Discount calculation modality: - FIXED_AMOUNT_UNTIL_DATE: Fixed discount amount until specific date - PERCENTAGE_UNTIL_DATE: Percentage discount until specific date - AMOUNT_PER_DAY: Amount discount per day - AMOUNT_PER_WORKING_DAY: Amount discount per working day - PERCENTAGE_PER_DAY: Percentage discount per day - PERCENTAGE_PER_WORKING_DAY: Percentage discount per working day example: PERCENTAGE_UNTIL_DATE amount: type: integer minimum: 1 description: > Discount amount in cents (positive integer). Required for AMOUNT_PER_DAY and AMOUNT_PER_WORKING_DAY modalities. Must not be provided for percentage-based modalities or when discount_dates_config is used. example: 5000 percentage: type: number minimum: 0 maximum: 100 multipleOf: 0.01 description: > Discount percentage (0-100, up to 2 decimal places). Required for PERCENTAGE_PER_DAY and PERCENTAGE_PER_WORKING_DAY modalities. Must not be provided for amount-based modalities or when discount_dates_config is used. example: 5 discount_dates_config: type: array minItems: 1 maxItems: 3 description: > Array of discount date configurations. Required for FIXED_AMOUNT_UNTIL_DATE and PERCENTAGE_UNTIL_DATE modalities. All dates must be before or equal to the transaction's due_date. items: type: object required: - until_date properties: until_date: type: string format: date description: > Date until which this discount applies (YYYY-MM-DD). **Important:** For validation purposes, dates are always interpreted in Brazil timezone by default (America/Sao_Paulo, UTC-3). example: '2025-12-15' amount: type: - integer - 'null' minimum: 1 description: | Discount amount in cents (positive integer). Required for FIXED_AMOUNT_UNTIL_DATE modality. Null for PERCENTAGE_UNTIL_DATE modality. example: 10000 percentage: type: - number - 'null' minimum: 0 maximum: 100 multipleOf: 0.01 description: | Discount percentage (0-100, up to 2 decimal places). Required for PERCENTAGE_UNTIL_DATE modality. Null for FIXED_AMOUNT_UNTIL_DATE modality. example: 10 example: - until_date: '2025-12-15' percentage: 10 - until_date: '2025-12-20' percentage: 5 AbatementConfig: type: object description: | Abatement configuration for PIX payments with due date. Abatement reduces the total amount to be paid. Exactly one of amount or percentage must be provided. required: - modality properties: amount: type: integer minimum: 1 description: | Abatement amount in cents (positive integer). Required for FIXED modality. Must not be provided for PERCENTAGE modality. example: 5000 percentage: type: number minimum: 0 maximum: 100 multipleOf: 0.01 description: | Abatement percentage (0-100, up to 2 decimal places). Required for PERCENTAGE modality. Must not be provided for FIXED modality. example: 5 modality: type: string enum: - FIXED - PERCENTAGE description: | Abatement calculation modality: - FIXED: Fixed amount abatement - PERCENTAGE: Percentage-based abatement example: FIXED CardDataInputWithNumber: allOf: - $ref: '#/components/schemas/CardDataInputBase' - type: object required: - number properties: number: type: string pattern: '^ev:' writeOnly: true description: > Card number (PAN - Primary Account Number). Use this for raw card entry. Do not send `network_token` when using this. Must be encrypted (`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:... CardDataInputWithNetworkToken: allOf: - $ref: '#/components/schemas/CardDataInputBase' - type: object required: - network_token properties: network_token: type: string pattern: '^ev:' writeOnly: true description: > Network tokenized card number. Use this for tokenized card payments (e.g., Apple Pay, Google Pay). Do not send `number` when using this. Must be encrypted (`ev:` prefix), as emitted by rinne-js wallet flows; plaintext values are rejected with `400 VALIDATION_ERROR`. example: ev:encrypted:... AddressInput: type: object description: Address information for input properties: street: type: string description: Street name example: Rua das Flores street_number: type: string description: Street number example: '123' complement: type: string description: Address complement example: Apt 101 neighborhood: type: string description: Neighborhood example: Centro zipcode: type: string description: ZIP code example: '12345678' country: type: string description: Country code example: '076' state: type: string description: State example: SP city: type: string description: City example: São Paulo required: - street - neighborhood - zipcode - country - state - city PricingValue: type: object description: >- Pricing structure with percentage, flat fee, and minimum price. At least one pricing component must be provided. anyOf: - required: - percentage - required: - flat - required: - minimum_price properties: percentage: type: - number - 'null' format: float minimum: 0 description: Percentage fee (e.g., 2.5 for 2.5%) example: 2.5 flat: type: - number - 'null' format: float minimum: 0 description: Flat fee in cents example: 50 minimum_price: type: - number - 'null' format: float minimum: 0 description: Minimum fee in cents example: 100 DiscountDatesConfigItemResponse: type: object description: | Discount configuration response for PIX payments with due date. This is the response format for discount configuration. required: - modality properties: modality: type: string enum: - FIXED_AMOUNT_UNTIL_DATE - PERCENTAGE_UNTIL_DATE - AMOUNT_PER_DAY - AMOUNT_PER_WORKING_DAY - PERCENTAGE_PER_DAY - PERCENTAGE_PER_WORKING_DAY description: | Discount calculation modality: - FIXED_AMOUNT_UNTIL_DATE: Fixed discount amount until specific date - PERCENTAGE_UNTIL_DATE: Percentage discount until specific date - AMOUNT_PER_DAY: Amount discount per day - AMOUNT_PER_WORKING_DAY: Amount discount per working day - PERCENTAGE_PER_DAY: Percentage discount per day - PERCENTAGE_PER_WORKING_DAY: Percentage discount per working day example: PERCENTAGE_UNTIL_DATE amount: type: - integer - 'null' minimum: 1 description: | Discount amount in cents (positive integer). Required for AMOUNT_PER_DAY and AMOUNT_PER_WORKING_DAY modalities. Null for other modalities or when discount_dates_config is used. percentage: type: - number - 'null' minimum: 0 maximum: 100 multipleOf: 0.01 description: > Discount percentage (0-100, up to 2 decimal places). Required for PERCENTAGE_PER_DAY and PERCENTAGE_PER_WORKING_DAY modalities. Null for other modalities or when discount_dates_config is used. example: 50 discount_dates_config: type: - array - 'null' description: > Array of discount date configurations. Required for FIXED_AMOUNT_UNTIL_DATE and PERCENTAGE_UNTIL_DATE modalities. items: type: object required: - until_date properties: until_date: type: string format: date description: > Date until which this discount applies (YYYY-MM-DD). **Important:** For validation purposes, dates are always interpreted in Brazil timezone by default (America/Sao_Paulo, UTC-3). example: '2025-12-15' amount: type: - integer - 'null' minimum: 1 description: | Discount amount in cents (positive integer). Required for FIXED_AMOUNT_UNTIL_DATE modality. Null for PERCENTAGE_UNTIL_DATE modality. example: 10000 percentage: type: - number - 'null' minimum: 0 maximum: 100 multipleOf: 0.01 description: | Discount percentage (0-100, up to 2 decimal places). Required for PERCENTAGE_UNTIL_DATE modality. Null for FIXED_AMOUNT_UNTIL_DATE modality. example: 10 example: - until_date: '2025-12-15' percentage: 10 - until_date: '2025-12-20' percentage: 5 AddressResponse: type: object description: Address information properties: street: type: string description: Street name example: Rua das Flores street_number: type: - string - 'null' description: Street number example: '123' complement: type: - string - 'null' description: Address complement example: Apt 101 neighborhood: type: string description: Neighborhood example: Centro zipcode: type: string description: ZIP code example: '12345678' country: type: string description: Country code example: '076' state: type: string description: State example: SP city: type: string description: City example: São Paulo required: - street - neighborhood - zipcode - country - state - city CardDataInputBase: type: object required: - expiry_month - expiry_year - last_digits properties: expiry_month: type: string pattern: ^(0[1-9]|1[0-2])$ description: | Card expiration month in MM format (01-12). Must be a two-digit string with leading zero if needed. example: '12' expiry_year: type: string pattern: ^\d{4}$ description: | Card expiration year in YYYY format. Must be a four-digit string. example: '2025' cvv: type: string pattern: '^ev:' writeOnly: true description: > Card Verification Value (CVV/CVC). Optional security code for card verification. Must be encrypted (`ev:` prefix); plaintext values are rejected with `400 VALIDATION_ERROR`. Raw values must be sent via the PCI API host, which encrypts them in transit (see *Raw Card Data*). example: ev:encrypted:... cryptogram: type: string pattern: '^ev:' writeOnly: true description: > Cryptographic value for 3DS authentication (CAVV). Optional — can be provided directly or injected from a linked 3DS session via `three_d_secure_session_id`. Must be encrypted (`ev:` prefix), as emitted by rinne-js wallet flows; plaintext values are rejected with `400 VALIDATION_ERROR`. example: ev:encrypted:... eci: type: - string - 'null' description: | Electronic Commerce Indicator (ECI). Indicates the security level of the transaction. Used in 3DS authentication flows. example: '05' token_provider: type: string description: | Token provider identifier. Indicates which tokenization service was used. example: Apple brand: type: string description: | Card brand (e.g., VISA, MASTERCARD, AMEX). Optional identifier for the card network. example: VISA device_id: type: string description: | Device identifier for the payment device. Used for device fingerprinting and fraud prevention. example: device-12345 authentication_type: type: string enum: - 3DS description: | Authentication method used for the transaction. Currently only '3DS' (3D Secure) is supported. Optional — automatically set to '3DS' when using a 3DS session. example: 3DS last_digits: type: string pattern: ^\d{4}$ description: | Last 4 digits of the card number. Required for transaction registration with acquirers. example: '1111' cardholder_name: type: string minLength: 1 description: | Name of the cardholder as it appears on the card. Optional — omitted for wallet and tokenized flows where the name is unavailable or discouraged by the acquirer. example: John Doe issuer: type: string description: | Card issuer name or identifier. Optional information about the card-issuing bank. example: BANCO DO BRASIL segment: type: string description: | Card segment classification. Optional categorization of the card type. example: CONSUMER country: type: string pattern: ^[A-Z]{2}$ description: | Card issuing country code. Optional ISO country code where the card was issued. example: BR wallet_type: type: string enum: - APPLE_PAY - GOOGLE_PAY description: | Digital wallet type used for the payment. Required for wallet-based transactions (Apple Pay, Google Pay). example: APPLE_PAY display_name: type: string description: | Display name for the card or wallet. Optional human-readable identifier shown to the user. example: Visa •••• 1111 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: Company API key for authentication ````