> ## 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. # Cancel a merchant's affiliation that is waiting for documents > Requires the merchant.affiliation.edit permission. Cancels an affiliation while its `status` is `WAITING_DOCUMENTS`, so the company can start over with a new `POST /v1/merchants/{merchantId}/affiliations` for the same provider: a cancelled attempt no longer counts as the company's ongoing affiliation. The affiliation moves to `CANCELLED` with `cancellation_reason` `REQUESTED`, `onboarding_url` is no longer returned, and an `affiliation.status-changed` event is sent. `CANCELLED` is terminal: nothing moves the affiliation out of it, and a later provider update for the cancelled attempt is ignored. A link handed out for this attempt is abandoned: whatever is completed through it afterwards is not applied to the cancelled affiliation. Any other status is refused with `409 CONFLICT_ERROR`, whose `message` names the status found: an attempt the provider is already analysing, or one that is already `ACTIVE`, `REJECTED`, `FAILED`, `CLOSED` or `CANCELLED`, cannot be cancelled. The status check and the write are one statement, so a status change racing the cancel also answers `409`; when the affiliation is back in `WAITING_DOCUMENTS` by then, the message asks for a retry. ## OpenAPI ````yaml /api-spec.yaml post /v1/merchants/{merchantId}/affiliations/{id}/cancel 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}/affiliations/{id}/cancel: post: tags: - Affiliations summary: Cancel a merchant's affiliation that is waiting for documents description: > Requires the merchant.affiliation.edit permission. Cancels an affiliation while its `status` is `WAITING_DOCUMENTS`, so the company can start over with a new `POST /v1/merchants/{merchantId}/affiliations` for the same provider: a cancelled attempt no longer counts as the company's ongoing affiliation. The affiliation moves to `CANCELLED` with `cancellation_reason` `REQUESTED`, `onboarding_url` is no longer returned, and an `affiliation.status-changed` event is sent. `CANCELLED` is terminal: nothing moves the affiliation out of it, and a later provider update for the cancelled attempt is ignored. A link handed out for this attempt is abandoned: whatever is completed through it afterwards is not applied to the cancelled affiliation. Any other status is refused with `409 CONFLICT_ERROR`, whose `message` names the status found: an attempt the provider is already analysing, or one that is already `ACTIVE`, `REJECTED`, `FAILED`, `CLOSED` or `CANCELLED`, cannot be cancelled. The status check and the write are one statement, so a status change racing the cancel also answers `409`; when the affiliation is back in `WAITING_DOCUMENTS` by then, the message asks for a retry. parameters: - in: path name: merchantId required: true schema: type: string description: The merchant company ID example: b4ece1d3-0a8a-5097-9dbb-58880c4f3894 - in: path name: id required: true schema: type: string description: The affiliation ID example: a3dbd0c2-9f79-4f86-8caa-47779b3f2794 responses: '200': description: The affiliation, now `CANCELLED` content: application/json: schema: $ref: '#/components/schemas/AffiliationResponse' '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/AuthenticationErrorResponse' '403': description: > Insufficient permissions, the caller is not an organization account, or cancellation is not available to the caller yet (`message`: "Affiliation cancellation is not available yet") content: application/json: schema: $ref: '#/components/schemas/AuthorizationErrorResponse' '404': description: >- Merchant not found in the organization, or affiliation not found for that merchant content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '409': description: The affiliation is not waiting for documents content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponse' example: error: code: CONFLICT_ERROR message: >- Affiliation is PROCESSING_DOCUMENTS, not waiting for documents status: 409 '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' security: - ApiKeyAuth: [] components: schemas: AffiliationResponse: type: object description: Transformed affiliation data returned by the API properties: id: type: string example: 123e4567-e89b-12d3-a456-426614174002 provider: type: string enum: - CELCOIN - RINNE - CAPPTA description: Payment provider name example: CELCOIN provider_id: type: - string - 'null' description: ID in provider system example: prov_123456 soft_descriptor: type: - string - 'null' description: Soft descriptor for transactions example: MYSTORE merchant_id: type: string description: Merchant ID in provider example: '12345678' mcc: type: string description: Merchant Category Code example: '5411' cost_policy_id: type: - string - 'null' description: Associated cost policy ID example: 123e4567-e89b-12d3-a456-426614174003 status: type: string enum: - PENDING - ACTIVE - PROCESSING - BLOCKED - PENDING_APPROVAL - WAITING_DOCUMENTS - PROCESSING_DOCUMENTS - REJECTED - FAILED - INVALID_SETTLEMENT_BANK_ACCOUNT - CLOSED - CANCELLED description: > Current affiliation status. `WAITING_DOCUMENTS` means the company has something to complete before the provider can decide; `CANCELLED` means the attempt was cancelled while waiting (`cancellation_reason` says why) and is over, so a new affiliation can be created. example: ACTIVE provider_status_code: type: - string - 'null' description: Provider-specific status code example: '200' provider_status_message: type: - string - 'null' description: > Provider-specific status message. An onboarding status change that carries no reason keeps the previous text, so it may predate `status`, except a move into `ACTIVE`, which clears it; a block, closure or reactivation of the account behind the affiliation replaces it, with an empty string when it carries none. example: Merchant activated successfully provider_metadata: type: - object - 'null' nullable: true description: Provider-specific metadata example: {} enabled: type: boolean description: Whether the affiliation is enabled example: true company_id: type: string description: Associated company ID example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793 onboarding_url: type: - string - 'null' description: > Link where the company completes what the provider asked for. Returned only while `status` is `WAITING_DOCUMENTS`; null in every other status, including after a cancellation. For a provider whose onboarding Rinne runs, it is the Rinne onboarding link, which `POST /v1/affiliations/{id}/onboarding-link` replaces. example: https://provider.com/onboard/12345 onboarding_url_expires_at: type: - string - 'null' format: date-time description: > When `onboarding_url` stops working. Null while no expiry applies to the link, and in every status other than `WAITING_DOCUMENTS`. Always null in production until the onboarding flow is released. example: '2026-11-06T12:00:00.000Z' cancellation_reason: type: - string - 'null' enum: - REQUESTED - EXPIRED - null description: > Why the affiliation is `CANCELLED`, null in every other status. `REQUESTED` when the company cancelled it; `EXPIRED` when the deadline to complete the requirements passed. example: null rejection_reviewed_at: type: - string - 'null' format: date-time description: > When the provider's rejection of this attempt was reviewed and translated into the actions the company has to take. Null until then, and on an attempt that was never rejected. Set with an empty `rejection_reasons` when Rinne's review found nothing for the company to do. example: null rejection_reasons: type: array description: > What Rinne's review of the provider's rejection found, in the order the reviewer wrote them: what was wrong, what the company does about it, and the document or requirement each reason concerns. Empty until the rejection is reviewed (`rejection_reviewed_at`), when the review found nothing for the company to do, and on an attempt that was never rejected. `affiliation.requirements-changed` announces it. items: $ref: '#/components/schemas/AffiliationRejectionReason' bank_account: anyOf: - allOf: - $ref: '#/components/schemas/AffiliationBankAccount' - type: 'null' description: Associated bank account information (created by provider) settlement_bank_accounts: type: array items: $ref: '#/components/schemas/SettlementBankAccountResponse' description: Settlement bank accounts for this affiliation. allowed_capture_methods: type: array items: type: string enum: - EMV - MAGSTRIPE - ECOMMERCE - CONTACTLESS_ICC description: Allowed capture methods example: - ECOMMERCE allowed_payment_methods: type: array items: type: string enum: - CREDIT_CARD - DEBIT_CARD - PIX - BOLEPIX description: Allowed payment methods example: - PIX organization_id: type: string description: Associated organization ID example: a3dbd0c2-9f79-4f86-8caa-47779b3f2793 anticipation_type: type: string enum: - AUTOMATIC - SPOT description: Anticipation type for the affiliation example: AUTOMATIC anticipation_days: type: integer minimum: 1 description: Number of days for anticipation example: 1 gateway_mode: type: boolean description: >- Whether this is a gateway-mode affiliation (Rinne acts as a pure capture gateway; no settlement, splits, or ledger entries) example: false onboarding_documents: type: array description: List of onboarding documents associated with this affiliation items: $ref: '#/components/schemas/AffiliationOnboardingDocumentResponse' company_snapshot: type: - object - 'null' description: >- Snapshot of the company data (with contact) sent to the provider: taken at affiliation creation and refreshed when the affiliation is submitted, so an affiliation that waited for documents carries the company as it was at submission. Only included when include_company_snapshot=true query parameter is set. created_at: type: string format: date-time description: Creation timestamp in ISO 8601 format example: '2023-01-01T12:00:00.000Z' updated_at: type: string format: date-time description: Last update timestamp in ISO 8601 format example: '2023-01-01T12:00:00.000Z' required: - id - provider - merchant_id - status - enabled - company_id - allowed_capture_methods - allowed_payment_methods - organization_id - gateway_mode - onboarding_documents - onboarding_url - onboarding_url_expires_at - cancellation_reason - rejection_reviewed_at - rejection_reasons - created_at - updated_at 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 AffiliationRejectionReason: type: object description: > One reason of the provider's rejection, as Rinne staff translated it (ADR-0040 § 8): what was wrong (`code`), in words for the company (`message`), and what the company does about it (`action`), pointing at the document or requirement it concerns. properties: code: type: string enum: - DOCUMENT_UNREADABLE - DOCUMENT_DATA_MISMATCH - DOCUMENT_EXPIRED - DOCUMENT_MISSING - FACEMATCH_FAILED - COMPANY_DATA_MISMATCH - COMPLIANCE_REFUSAL - OTHER description: What was wrong, in Rinne's vocabulary example: DOCUMENT_UNREADABLE message: type: string description: The reason in words, written by the reviewer for the company example: >- The back of the CNH is cut off; send a photo showing the whole document. action: type: string enum: - RESUBMIT_DOCUMENT - NEW_REQUIREMENT - FIX_COMPANY_DATA - NONE description: > What the company does: `RESUBMIT_DOCUMENT` sends the evidence again (the refused evidence no longer counts at this provider, so its requirement reads `REJECTED` until new evidence meets it, or stays `SATISFIED` when other evidence still does); `NEW_REQUIREMENT` meets the requirement in `requirement_id`, added by the review; `FIX_COMPANY_DATA` corrects the company's data and creates a new attempt; `NONE` nothing, the reason is informational. example: RESUBMIT_DOCUMENT requirement_id: type: - string - 'null' format: uuid description: >- The requirement the reason concerns (the one refused, or the one added); null when it names a document or nothing example: null onboarding_document_id: type: - string - 'null' format: uuid description: >- The id of the document refused (`GET /v1/onboarding-documents/{id}`, once the onboarding routes are released); null when the reason names a requirement or nothing example: 4f6c1e8a-9b2d-4e7f-8a3c-1d5e6f7a8b9c required: - code - message - action - requirement_id - onboarding_document_id AffiliationBankAccount: type: object description: Bank account information for affiliation required: - id - bank_code - branch_number - account_number - account_holder_name - account_holder_document_number - ispb - operational_status - operational_status_occurred_at - created_at - updated_at properties: id: type: string format: uuid description: Bank account ID example: a2da4238-bdc2-47f9-b866-246cc87212d5 bank_code: type: string description: Bank code example: '001' branch_number: type: string description: Branch number example: '1234' account_number: type: string description: Account number example: '567890' account_holder_name: type: string description: Account holder name example: John Doe account_holder_document_number: type: string description: CPF (11 digits) or CNPJ (14 characters; alphanumeric CNPJ supported) example: '81146431023' ispb: type: string description: ISPB code example: '00000000' operational_status: type: string enum: - REGULAR - JUDICIAL_BLOCK description: > Operational status of the account. `JUDICIAL_BLOCK` means the balance is restricted by a court order; `REGULAR` means it operates normally. example: REGULAR operational_status_occurred_at: type: - string - 'null' format: date-time description: > Provider event time of the last operational status change, or null if the status has never changed. example: '2025-06-26T17:07:31.495Z' created_at: type: string format: date-time description: When the bank account was created example: '2025-06-26T17:07:31.495Z' updated_at: type: string format: date-time description: When the bank account was last updated example: '2025-06-26T17:07:31.495Z' SettlementBankAccountResponse: type: object description: Settlement bank account information in affiliation response required: - id - branch_number - account_number - account_type - account_holder_name - account_holder_document_number - ispb - status - created_at - updated_at properties: id: type: string description: Settlement bank account ID example: b3eb5349-cec3-48fa-c977-357dd98323e6 branch_number: type: string description: Branch number example: '1234' account_number: type: string description: Account number example: '567890' account_type: type: string enum: - CHECKING - SAVINGS - SALARY - PAYMENT description: Type of bank account example: CHECKING account_holder_name: type: string description: Account holder name example: John Doe account_holder_document_number: type: string description: CPF (11 digits) or CNPJ (14 characters; alphanumeric CNPJ supported) example: '81146431023' ispb: type: string description: ISPB code example: '00000000' status: type: string enum: - ACTIVE - PENDING_VALIDATION - VALIDATION_FAILED - FAILED - DISABLED description: > Settlement bank account validation status. ACTIVE: currently in use for settlements. PENDING_VALIDATION: sent to provider, awaiting async validation. VALIDATION_FAILED: provider rejected the bank account during async validation. FAILED: unrecoverable error (provider 4xx or timeout). DISABLED: superseded by a newly validated account. example: ACTIVE created_at: type: string format: date-time example: '2023-01-01T00:00:00Z' updated_at: type: string format: date-time example: '2023-01-01T00:00:00Z' AffiliationOnboardingDocumentResponse: type: object description: >- A document an affiliation sent to its provider (metadata, without download URL) properties: id: type: string description: Document unique identifier example: c5fdf2e4-1b9b-6108-aece-69991d5h4905 file_type: type: string description: Type of document (e.g., CNH_FRONT, SELFIE, CONTRATO_SOCIAL) example: CNH_FRONT file_name: type: string description: >- Generated filename in storage; empty for another organization's file shared with this one, which exposes nothing of it example: CNH_FRONT_a1b2c3d4.pdf content_type: type: - string - 'null' description: >- MIME type of the document; null for another organization's shared file example: application/pdf file_size_bytes: type: - integer - 'null' description: File size in bytes; null for another organization's shared file example: 125430 created_at: type: string format: date-time description: When the document was stored example: '2023-06-15T14:30:00.000Z' required: - id - file_type - file_name - created_at 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.