openapi: 3.1.0
info:
  title: ConnectPSP API
  description: >
    **ConnectPSP** is a PIX payment gateway designed for high-throughput
    platforms such as digital wallets, betting companies, and fintechs.


    This API allows you to:

    - 💸 **Receive payments** via PIX (Cash-In) — standard QR Code or
    OpenFinance

    - 🏦 **Send payments** via PIX key or bank account data (Cash-Out)

    - 📊 **Manage your wallet** — check consolidated balances and rebalance
    between transactional and proprietary accounts

    - 🪝 **Receive real-time events** via Webhooks as transactions progress


    ## Authentication


    All endpoints (except `POST /auth/token`) require two headers:


    | Header | Description |

    |---|---|

    | `Authorization` | `Bearer <jwt_token>` — obtained from `POST /auth/token`
    |

    | `ApplicationToken` | Fixed GUID token that identifies your integration |


    For **financial operations** (Cash-Out, Rebalance), an additional header is
    required:


    | Header | Description |

    |---|---|

    | `DigitalSignature` | HMAC-SHA256 hash of your JWT + CryptoToken. See
    [Authentication Guide](../guides/authentication.md) |


    ## Idempotency


    For `POST /cash-in` and `POST /cash-out`, we strongly recommend sending the
    `X-Idempotency-Key` header (UUID v4).

    This guarantees that network retries do not result in duplicate
    transactions.


    ## Recommended integration order


    | Phase | What to confirm first |

    |---|---|

    | **Setup** | Credentials, environment, headers, and webhook readiness in
    [Initial Setup](../tutorials/initial-setup.md) |

    | **Authentication** | JWT generation and `DigitalSignature` rules in the
    [Authentication Guide](../guides/authentication.md) |

    | **Transactions** | Your first Cash-In or Cash-Out flow with idempotency
    and webhook validation |
  version: 2.0.0
  contact:
    name: ConnectPSP Support
    email: suporte@connectpsp.com
  x-logo:
    url: ../images/logo.svg
    altText: ConnectPSP
servers:
  - url: https://api.homologacao.connectpsp.com
    description: Staging Environment (Testing)
tags:
  - name: Authentication
    description: Obtain JWT tokens to authenticate all other requests.
  - name: Cash-In
    description: >
      Generate and manage inbound PIX payments. Supports standard QR Code and
      OpenFinance flows.
  - name: Cash-Out
    description: |
      Request and track outbound PIX payments to any Brazilian bank account.
  - name: Account
    description: >
      View consolidated wallet balances across all banking partners (Delbank,
      Celcoin, StarkBank) and manage rebalancing between transactional and
      proprietary accounts.
x-tagGroups:
  - name: Getting started
    tags:
      - Authentication
  - name: Money movement
    tags:
      - Cash-In
      - Cash-Out
  - name: Operations
    tags:
      - Account
security:
  - bearerAuth: []
paths:
  /auth/token:
    post:
      tags:
        - Authentication
      summary: Obtain JWT Token
      operationId: authToken
      description: >
        Authenticates your application and returns a short-lived JWT token.


        Provide the `clientId` and `clientSecret` credentials issued by
        ConnectPSP during onboarding.

        The returned `accessToken` must be sent in all subsequent requests as:

        ```

        Authorization: Bearer <accessToken>

        ```
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthTokenRequest'
            example:
              clientId: YOUR_CLIENT_ID
              clientSecret: YOUR_CLIENT_SECRET
      responses:
        '200':
          description: Token generated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
              example:
                accessToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                tokenType: Bearer
                expiresIn: 3600
                issuedAt: '2026-03-10T14:00:00Z'
        '401':
          description: Invalid credentials.
          content:
            application/json:
              example:
                message: The provided credentials are not valid.
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |
            curl -X POST https://api.homologacao.connectpsp.com/auth/token \
              -H "Content-Type: application/json" \
              -d '{
                "clientId": "YOUR_CLIENT_ID",
                "clientSecret": "YOUR_CLIENT_SECRET"
              }'
  /cash-in:
    post:
      tags:
        - Cash-In
      summary: Create Cash-In
      operationId: createCashIn
      description: >
        Generates a PIX payment intent.


        **Standard PIX flow:** Returns a Copia e Cola string and a QR Code image
        (Base64) that your user can scan to complete the payment.


        **OpenFinance flow:** Include the `openFinance` object to generate an
        OpenFinance payment link instead. The user is redirected to their bank's
        app to authorize the payment.


        Once payment is confirmed by the banking network, ConnectPSP will POST a
        `CASHIN_PAID` event to your `webhookUrl`.
      parameters:
        - $ref: '#/components/parameters/ApplicationToken'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashInRequest'
            examples:
              standard_pix:
                summary: Standard PIX (QR Code)
                value:
                  amount: 150.5
                  externalReference: order_abc123
                  expirationInMinutes: 60
                  webhookUrl: https://api.yourdomain.com/webhooks/connectpsp
                  payer:
                    name: João Silva
                    document: '12345678909'
              open_finance:
                summary: OpenFinance
                value:
                  amount: 150.5
                  externalReference: order_abc123
                  webhookUrl: https://api.yourdomain.com/webhooks/connectpsp
                  payer:
                    name: João Silva
                    document: '12345678909'
                  openFinance:
                    redirectUrl: https://yourdomain.com/payment/success
      responses:
        '201':
          description: Cash-In created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashInCreatedResponse'
              examples:
                standard_pix:
                  summary: Standard PIX response
                  value:
                    transactionId: kk6g232xel65a0daee4dd13kk2912714964
                    internalCode: US7B1JQ
                    externalReference: order_abc123
                    status: AWAITING_PAYMENT
                    amount: 150.5
                    payer:
                      name: João Silva
                      document: '12345678909'
                    pixData:
                      copyAndPaste: 00020101021226...
                      qrCodeImageBase64: iVBORw0KGgoAAAANSU...
                    requestedAt: '2026-03-10T11:20:00-03:00'
                open_finance:
                  summary: OpenFinance response
                  value:
                    transactionId: kk6g232xel65a0daee4dd13kk2912714964
                    internalCode: US7B1JQ
                    externalReference: order_abc123
                    status: AWAITING_PAYMENT
                    amount: 150.5
                    payer:
                      name: João Silva
                      document: '12345678909'
                    openFinanceData:
                      paymentUrl: >-
                        https://app.linaopenx.com.br/payments?paymentLinkId=b7116f6a...
                    requestedAt: '2026-03-10T11:20:00-03:00'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |
            curl -X POST https://api.homologacao.connectpsp.com/cash-in \
              -H "Authorization: Bearer <token>" \
              -H "ApplicationToken: <app-token>" \
              -H "X-Idempotency-Key: $(uuidgen)" \
              -H "Content-Type: application/json" \
              -d '{
                "amount": 150.50,
                "externalReference": "order_abc123",
                "expirationInMinutes": 60,
                "webhookUrl": "https://api.yourdomain.com/webhooks/connectpsp",
                "payer": {
                  "name": "João Silva",
                  "document": "12345678909"
                }
              }'
  /cash-in/{id}:
    get:
      tags:
        - Cash-In
      summary: Get Cash-In
      operationId: getCashIn
      description: |
        Returns the current status and details of a Cash-In transaction.
      parameters:
        - $ref: '#/components/parameters/ApplicationToken'
        - name: id
          in: path
          required: true
          description: Transaction identifier — TxId, InternalCode, or EndToEndId.
          schema:
            type: string
          example: US7B1JQ
      responses:
        '200':
          description: Cash-In details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashInDetailedResponse'
              examples:
                paid:
                  summary: PAID — payment confirmed
                  value:
                    transactionId: kk6g232xel65a0daee4dd13kk2912714964
                    internalCode: US7B1JQ
                    externalReference: order_abc123
                    endToEndId: E00416968202603101827cemeFscF6AG
                    status: PAID
                    amount: 150.5
                    payer:
                      name: João Silva
                      document: '12345678909'
                      bankData:
                        ispb: '00000000'
                        bank: Banco do Brasil S.A.
                        branch: '0001'
                        account: '123456'
                    requestedAt: '2026-03-10T11:20:00-03:00'
                    paidAt: '2026-03-10T11:22:15-03:00'
                refunded:
                  summary: REFUNDED — payment returned to payer
                  value:
                    transactionId: kk6g232xel65a0daee4dd13kk2912714964
                    internalCode: US7B1JQ
                    externalReference: order_abc123
                    endToEndId: D00416968202603101827cemeFscF6AG
                    originalEndToEndId: E00416968202603101827cemeFscF6AG
                    status: REFUNDED
                    amount: 150.5
                    payer:
                      name: João Silva
                      document: '12345678909'
                      bankData:
                        ispb: '00000000'
                        bank: Banco do Brasil S.A.
                        branch: '0001'
                        account: '123456'
                    requestedAt: '2026-03-10T11:20:00-03:00'
                    paidAt: '2026-03-10T11:22:15-03:00'
                    refundedAt: '2026-03-11T09:00:00-03:00'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |
            curl https://api.homologacao.connectpsp.com/cash-in/US7B1JQ \
              -H "Authorization: Bearer <token>" \
              -H "ApplicationToken: <app-token>"
  /cash-in/{id}/refund:
    post:
      tags:
        - Cash-In
      summary: Request Refund
      operationId: refundCashIn
      description: >
        Requests a **full refund** of a paid Cash-In transaction (PIX Devolution
        via BACEN/SPI).


        > ⚠️ **Important:** Only transactions with status `PAID` can be
        refunded. Partial refunds are not supported — the full original amount
        will be returned to the payer.


        The refund is sent to the banking network synchronously. The `202
        Accepted` response includes the new `endToEndId` generated for the
        devolution (prefixed with `D`).


        This endpoint requires the `DigitalSignature` header. See the
        [Authentication Guide](../guides/authentication.md) for details on how
        to compute it.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ApplicationToken'
        - $ref: '#/components/parameters/DigitalSignature'
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: id
          in: path
          required: true
          description: Transaction identifier — TxId, InternalCode, or EndToEndId.
          schema:
            type: string
          example: US7B1JQ
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashInRefundRequest'
            example:
              reason: CUSTOMER_REQUEST
              description: 'Customer requested refund via support ticket #1234.'
      responses:
        '202':
          description: Refund accepted and submitted to the banking network.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashInRefundResponse'
              example:
                transactionId: kk6g232xel65a0daee4dd13kk2912714964
                internalCode: US7B1JQ
                externalReference: order_abc123
                endToEndId: D00416968202603101827cemeFscF6AG
                status: PROCESSING
                amount: 150.5
                requestedAt: '2026-03-10T13:30:00-03:00'
                message: >-
                  The refund for cash-in US7B1JQ has been successfully
                  initiated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: >
            curl -X POST
            https://api.homologacao.connectpsp.com/cash-in/US7B1JQ/refund \
              -H "Authorization: Bearer <token>" \
              -H "ApplicationToken: <app-token>" \
              -H "DigitalSignature: <computed-signature>" \
              -H "X-Idempotency-Key: $(uuidgen)" \
              -H "Content-Type: application/json" \
              -d '{
                "reason": "CUSTOMER_REQUEST",
                "description": "Customer requested refund via support ticket #1234."
              }'
  /cash-out:
    post:
      tags:
        - Cash-Out
      summary: Create Cash-Out
      operationId: createCashOut
      description: >
        Submits a PIX payment to an external bank account or PIX key.


        The request is validated against available balance and fraud rules, then
        queued for settlement. The response is `202 Accepted` — the payment is
        **not yet settled** at this point.


        Two destination types are supported:

        - **`PIX`** — by PIX key (CPF, CNPJ, email, phone, or EVP random key)

        - **`BANK_ACCOUNT`** — by bank account details (ISPB + branch + account)


        This endpoint requires `DigitalSignature` and `X-Idempotency-Key`
        headers.


        Once the payment is settled (or fails), ConnectPSP will POST either a
        `CASHOUT_COMPLETED` or `CASHOUT_FAILED` event to your `webhookUrl`.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ApplicationToken'
        - $ref: '#/components/parameters/DigitalSignature'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashOutRequest'
            examples:
              pix_key:
                summary: Via PIX key (CPF)
                value:
                  amount: 500
                  externalReference: withdraw_xyz789
                  description: Player withdrawal
                  webhookUrl: https://api.yourdomain.com/webhooks/connectpsp
                  payee:
                    name: Maria Silva
                    document: '12345678909'
                    destination:
                      type: PIX
                      pixKeyType: CPF
                      pixKey: '12345678909'
              bank_account:
                summary: Via bank account data
                value:
                  amount: 500
                  externalReference: withdraw_xyz789
                  description: Player withdrawal
                  webhookUrl: https://api.yourdomain.com/webhooks/connectpsp
                  payee:
                    name: Maria Silva
                    document: '12345678909'
                    destination:
                      type: BANK_ACCOUNT
                      bankAccount:
                        ispb: '18236120'
                        branch: '0001'
                        account: '947710840'
                        accountType: PAYMENT
      responses:
        '202':
          description: >-
            Cash-Out accepted for settlement. Awaiting banking network
            confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashOutAcceptedResponse'
              example:
                transactionId: dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9
                internalCode: IVKPRMOCDY
                externalReference: withdraw_xyz789
                status: PROCESSING
                requestedAt: '2026-03-10T14:00:00-03:00'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Conflict — a Cash-Out with this `externalReference` already exists.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://connect-psp.redocly.app/errors/duplicated-reference
                title: Duplicated External Reference
                status: 409
                code: DUPLICATED_EXTERNAL_REFERENCE
                detail: >-
                  A Cash-Out with externalReference 'withdraw_xyz789' already
                  exists.
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-codeSamples:
        - lang: cURL
          label: cURL (PIX key)
          source: |
            curl -X POST https://api.homologacao.connectpsp.com/cash-out \
              -H "Authorization: Bearer <token>" \
              -H "ApplicationToken: <app-token>" \
              -H "DigitalSignature: <computed-signature>" \
              -H "X-Idempotency-Key: $(uuidgen)" \
              -H "Content-Type: application/json" \
              -d '{
                "amount": 500.00,
                "externalReference": "withdraw_xyz789",
                "description": "Player withdrawal",
                "webhookUrl": "https://api.yourdomain.com/webhooks/connectpsp",
                "payee": {
                  "name": "Maria Silva",
                  "document": "12345678909",
                  "destination": {
                    "type": "PIX",
                    "pixKeyType": "CPF",
                    "pixKey": "12345678909"
                  }
                }
              }'
  /cash-out/{id}:
    get:
      tags:
        - Cash-Out
      summary: Get Cash-Out
      operationId: getCashOut
      description: >
        Returns the current status and details of a Cash-Out transaction,
        including settlement proof from BACEN/SPI when available.


        The `{id}` parameter accepts:

        - `internalCode` (ConnectPSP's code, e.g. `IVKPRMOCDY`)

        - `transactionId` (UUID)

        - `endToEndId` (E2E ID from BACEN/SPI)
      parameters:
        - name: id
          in: path
          required: true
          description: Transaction identifier.
          schema:
            type: string
          example: IVKPRMOCDY
      responses:
        '200':
          description: Cash-Out details returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashOutDetailedResponse'
              examples:
                completed:
                  summary: COMPLETED — settled successfully
                  value:
                    transactionId: dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9
                    internalCode: IVKPRMOCDY
                    externalReference: withdraw_xyz789
                    endToEndId: E00416968202603101827cemeFscF6AG
                    status: COMPLETED
                    amount: 500
                    payee:
                      name: Maria Silva
                      document: '12345678909'
                      destination:
                        type: PIX
                        pixKeyType: CPF
                        pixKey: '12345678909'
                      bankData:
                        ispb: '00000000'
                        bank: Banco do Brasil S.A.
                        branch: '0001'
                        account: '123456'
                    requestedAt: '2026-03-10T14:00:00-03:00'
                    paidAt: '2026-03-10T14:02:30-03:00'
                failed:
                  summary: FAILED — PIX key not found
                  value:
                    transactionId: dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9
                    internalCode: IVKPRMOCDY
                    externalReference: withdraw_xyz789
                    status: FAILED
                    amount: 500
                    failure:
                      code: PIX_KEY_NOT_FOUND
                      message: The provided PIX key did not resolve to a valid account.
                    payee:
                      name: Maria Silva
                      document: '12345678909'
                      destination:
                        type: PIX
                        pixKeyType: CPF
                        pixKey: '12345678909'
                    requestedAt: '2026-03-10T14:00:00-03:00'
                    failedAt: '2026-03-10T14:00:15-03:00'
                refunded:
                  summary: REFUNDED — returned asynchronously by the bank
                  value:
                    transactionId: dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9
                    internalCode: IVKPRMOCDY
                    externalReference: withdraw_xyz789
                    endToEndId: D00416968202603101827cemeFscF6AG
                    originalEndToEndId: E00416968202603101827cemeFscF6AG
                    status: REFUNDED
                    amount: 500
                    payee:
                      name: Maria Silva
                      document: '12345678909'
                      destination:
                        type: PIX
                        pixKeyType: CPF
                        pixKey: '12345678909'
                      bankData:
                        ispb: '00000000'
                        bank: Banco do Brasil S.A.
                        branch: '0001'
                        account: '123456'
                    requestedAt: '2026-03-10T14:00:00-03:00'
                    paidAt: '2026-03-10T14:02:30-03:00'
                    refundedAt: '2026-03-11T09:30:15-03:00'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |
            curl https://api.homologacao.connectpsp.com/cash-out/IVKPRMOCDY \
              -H "Authorization: Bearer <token>" \
              -H "ApplicationToken: <app-token>"
  /account/balance:
    get:
      tags:
        - Account
      summary: Get Balance
      operationId: getBalance
      description: >
        Returns the consolidated and detailed wallet snapshot across all banking
        partners (Delbank, Celcoin, StarkBank).


        Two account types are tracked per bank:

        - **Transactional** — funds available to cover Cash-Out requests
        (mirrors your users' exposure)

        - **Proprietary** — reserve/buffer account (your operational capital)


        > ℹ️ **Note:** Historical balance lookup (`?date=`) is currently in
        development. Only the current balance is available.
      parameters:
        - $ref: '#/components/parameters/ApplicationToken'
        - name: date
          in: query
          required: false
          description: >-
            Date for historical balance snapshot (ISO 8601 — `YYYY-MM-DD`).
            Currently not available.
          schema:
            type: string
            format: date
          example: '2026-03-10'
      responses:
        '200':
          description: Consolidated balance returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBalanceResponse'
              example:
                currency: BRL
                referenceDate: '2026-03-10'
                consolidated:
                  totalBalance: 1500000
                  transactionalBalance: 500000
                  proprietaryBalance: 1000000
                banks:
                  - ispb: '13935893'
                    bank: CELCOIN IP S.A.
                    accounts:
                      transactional:
                        branch: '0001'
                        account: '123456'
                        balance: 200000
                      proprietary:
                        branch: '0001'
                        account: '654321'
                        balance: 500000
                  - ispb: '38224857'
                    bank: DELBANK S.A.
                    accounts:
                      transactional:
                        branch: '0001'
                        account: '567890'
                        balance: 150000
                      proprietary:
                        branch: '0001'
                        account: '098765'
                        balance: 300000
                  - ispb: '20018183'
                    bank: STARK BANK S.A.
                    accounts:
                      transactional:
                        branch: '0001'
                        account: '654987'
                        balance: 150000
                      proprietary:
                        branch: '0001'
                        account: '987321'
                        balance: 200000
                updatedAt: '2026-03-10T14:35:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |
            curl https://api.homologacao.connectpsp.com/account/balance \
              -H "Authorization: Bearer <token>" \
              -H "ApplicationToken: <app-token>"
  /account/rebalance:
    post:
      tags:
        - Account
      summary: Rebalance Wallet
      operationId: rebalanceAccount
      description: >
        Synchronizes your **Transactional account** to match the total exposure
        you report.


        **How it works:**

        - If `targetAmount` is **greater** than the current transactional
        balance → funds are pulled from the Proprietary account (Top-up)

        - If `targetAmount` is **less** than the current transactional balance →
        excess funds are swept back to the Proprietary account


        The `targetAmount` represents the total exposure of your platform (sum
        of all user wallet balances + in-flight bets).


        This endpoint requires the `DigitalSignature` header.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ApplicationToken'
        - $ref: '#/components/parameters/DigitalSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RebalanceRequest'
            example:
              targetAmount: 1000000
      responses:
        '200':
          description: Rebalancing completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RebalanceResponse'
              example:
                success: true
                message: Rebalancing completed successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: >
            curl -X POST
            https://api.homologacao.connectpsp.com/account/rebalance \
              -H "Authorization: Bearer <token>" \
              -H "ApplicationToken: <app-token>" \
              -H "DigitalSignature: <computed-signature>" \
              -H "Content-Type: application/json" \
              -d '{ "targetAmount": 1000000.00 }'
components:
  parameters:
    IdempotencyKey:
      name: X-Idempotency-Key
      in: header
      required: false
      description: >
        A client-generated UUID v4 to guarantee idempotency. If the same key is
        sent twice, the second request returns the original response without
        creating a duplicate transaction.

        **Strongly recommended** for all POST operations.
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-41d4-a716-446655440000
    DigitalSignature:
      name: DigitalSignature
      in: header
      required: true
      description: >
        HMAC-SHA256 hash of the JWT token + your CryptoToken. Required for
        sensitive operations.

        See the [Authentication Guide](../guides/authentication.md) for the
        exact computation steps.
      schema:
        type: string
      example: '{{DigitalSignature}}'
    ApplicationToken:
      name: ApplicationToken
      in: header
      required: true
      description: >
        Fixed GUID that uniquely identifies your integration. Provided during
        ConnectPSP onboarding.
      schema:
        type: string
      example: '{{ApplicationToken}}'
  responses:
    BadRequest:
      description: Invalid request payload or missing required fields.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://connect-psp.redocly.app/errors/validation
            title: Validation Error
            status: 400
            code: VALIDATION_ERROR
            detail: The 'amount' field is required and must be greater than zero.
    Unauthorized:
      description: Missing or invalid authentication credentials.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://connect-psp.redocly.app/errors/unauthorized
            title: Unauthorized
            status: 401
            code: INVALID_CREDENTIALS
            detail: The provided JWT token is invalid or has expired.
    NotFound:
      description: The requested resource was not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://connect-psp.redocly.app/errors/not-found
            title: Not Found
            status: 404
            code: NOT_FOUND
            detail: No transaction found with the provided identifier.
    UnprocessableEntity:
      description: Business rule violation.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://connect-psp.redocly.app/errors/insufficient-funds
            title: Insufficient Funds
            status: 422
            code: INSUFFICIENT_FUNDS
            detail: >-
              The requested amount of R$ 500.00 exceeds available balance of R$
              100.00.
  schemas:
    AuthTokenRequest:
      type: object
      required:
        - clientId
        - clientSecret
      properties:
        clientId:
          type: string
          description: Your numeric client ID provided by ConnectPSP during onboarding.
          example: YOUR_CLIENT_ID
        clientSecret:
          type: string
          format: uuid
          description: >-
            Your secret GUID credential provided by ConnectPSP during
            onboarding.
          example: YOUR_CLIENT_SECRET
    AuthTokenResponse:
      type: object
      properties:
        accessToken:
          type: string
          description: JWT token to use in all subsequent requests.
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        tokenType:
          type: string
          description: Always `Bearer`.
          example: Bearer
        expiresIn:
          type: integer
          description: Token lifetime in seconds.
          example: 3600
        issuedAt:
          type: string
          format: date-time
          description: Token issuance timestamp (ISO 8601).
          example: '2026-03-10T14:00:00Z'
    CashInRequest:
      type: object
      required:
        - amount
        - externalReference
        - payer
      properties:
        amount:
          type: number
          format: decimal
          description: >-
            Payment amount in BRL (Brazilian Reais). Decimal format (e.g.
            `150.50`).
          minimum: 0.01
          example: 150.5
        externalReference:
          type: string
          maxLength: 100
          description: >-
            Your internal order or transaction ID. Must be unique per
            application.
          example: order_abc123
        expirationInMinutes:
          type: integer
          description: QR Code validity in minutes. Defaults to 1440 (24h) if omitted.
          minimum: 1
          maximum: 43200
          example: 60
        webhookUrl:
          type: string
          format: uri
          description: >-
            URL to receive asynchronous payment events (`CASHIN_PAID`,
            `CASHIN_REFUNDED`).
          example: https://api.yourdomain.com/webhooks/connectpsp
        payer:
          $ref: '#/components/schemas/CashInPayer'
        openFinance:
          $ref: '#/components/schemas/CashInOpenFinance'
        includeQrCodeImage:
          type: boolean
          description: >-
            If `true`, the response includes QR Code as Base64. Defaults to
            `true`.
          default: true
    CashInPayer:
      type: object
      required:
        - name
        - document
      properties:
        name:
          type: string
          description: Full name of the payer.
          example: João Silva
        document:
          type: string
          description: CPF (11 digits) or CNPJ (14 digits) — numbers only.
          example: '12345678909'
    CashInOpenFinance:
      type: object
      required:
        - redirectUrl
      description: >
        When present, triggers the OpenFinance flow instead of a standard QR
        Code.

        The response will include a `paymentUrl` to redirect the user to their
        bank's authorization screen.
      properties:
        redirectUrl:
          type: string
          format: uri
          description: >-
            URL to redirect the user after completing payment in their banking
            app.
          example: https://yourdomain.com/payment/success
    CashInCreatedResponse:
      type: object
      properties:
        transactionId:
          type: string
          description: PIX network TxId (alphanumeric).
          example: kk6g232xel65a0daee4dd13kk2912714964
        internalCode:
          type: string
          description: ConnectPSP short code (7 characters). Use this to poll status.
          example: US7B1JQ
        externalReference:
          type: string
          description: Your original order reference echoed back.
          example: order_abc123
        status:
          type: string
          enum:
            - AWAITING_PAYMENT
          description: Always `AWAITING_PAYMENT` at creation.
          example: AWAITING_PAYMENT
        amount:
          type: number
          format: decimal
          example: 150.5
        payer:
          $ref: '#/components/schemas/CashInResponsePayer'
        pixData:
          $ref: '#/components/schemas/CashInPixData'
        openFinanceData:
          $ref: '#/components/schemas/CashInOpenFinanceData'
        requestedAt:
          type: string
          format: date-time
          description: Transaction creation timestamp (ISO 8601, UTC-3).
          example: '2026-03-10T11:20:00-03:00'
    CashInDetailedResponse:
      type: object
      properties:
        transactionId:
          type: string
          example: kk6g232xel65a0daee4dd13kk2912714964
        internalCode:
          type: string
          example: US7B1JQ
        externalReference:
          type: string
          example: order_abc123
        endToEndId:
          type: string
          description: |
            End-to-end ID issued by BACEN/SPI upon settlement.
            - For paid transactions: starts with `E` (e.g. `E00416968...`)
            - For refunded transactions: starts with `D` (Devolution)
          example: E00416968202603101827cemeFscF6AG
        originalEndToEndId:
          type: string
          description: The original E2E ID when `endToEndId` represents a refund.
          example: E00416968202603101827cemeFscF6AG
        status:
          type: string
          enum:
            - AWAITING_PAYMENT
            - PAID
            - EXPIRED
            - REFUNDED
            - CANCELLED
          example: PAID
        amount:
          type: number
          format: decimal
          example: 150.5
        payer:
          $ref: '#/components/schemas/CashInResponsePayer'
        requestedAt:
          type: string
          format: date-time
          example: '2026-03-10T11:20:00-03:00'
        paidAt:
          type: string
          format: date-time
          example: '2026-03-10T11:22:15-03:00'
        refundedAt:
          type: string
          format: date-time
          example: '2026-03-11T09:00:00-03:00'
        expiredAt:
          type: string
          format: date-time
    CashInResponsePayer:
      type: object
      properties:
        name:
          type: string
          example: João Silva
        document:
          type: string
          example: '12345678909'
        bankData:
          $ref: '#/components/schemas/BankData'
    CashInPixData:
      type: object
      properties:
        copyAndPaste:
          type: string
          description: Full PIX Copia e Cola string (EMV QR Code payload).
          example: 00020101021226...
        qrCodeImageBase64:
          type: string
          description: >-
            QR Code image encoded as Base64. Present only when
            `includeQrCodeImage` is `true`.
          example: iVBORw0KGgoAAAANSU...
    CashInOpenFinanceData:
      type: object
      properties:
        paymentUrl:
          type: string
          format: uri
          description: Redirect URL to the user's OpenFinance payment authorization screen.
          example: https://app.linaopenx.com.br/payments?paymentLinkId=b7116f6a...
    CashInRefundRequest:
      type: object
      required:
        - reason
      properties:
        reason:
          type: string
          enum:
            - FRAUD
            - DUPLICATED_PAYMENT
            - CUSTOMER_REQUEST
            - MERCHANT_ERROR
          description: Reason for the refund.
          example: CUSTOMER_REQUEST
        description:
          type: string
          description: Optional internal note for audit purposes (not sent to payer).
          example: 'Customer requested refund via support ticket #1234.'
    CashInRefundResponse:
      type: object
      properties:
        transactionId:
          type: string
          example: kk6g232xel65a0daee4dd13kk2912714964
        internalCode:
          type: string
          example: US7B1JQ
        externalReference:
          type: string
          example: order_abc123
        endToEndId:
          type: string
          description: New E2E ID for this devolution (starts with `D`).
          example: D00416968202603101827cemeFscF6AG
        status:
          type: string
          enum:
            - PROCESSING
          example: PROCESSING
        amount:
          type: number
          format: decimal
          example: 150.5
        requestedAt:
          type: string
          format: date-time
          example: '2026-03-10T13:30:00-03:00'
        message:
          type: string
          example: The refund for cash-in US7B1JQ has been successfully initiated.
    CashOutRequest:
      type: object
      required:
        - amount
        - externalReference
        - payee
      properties:
        amount:
          type: number
          format: decimal
          description: Amount in BRL (Reais). Decimal format.
          minimum: 0.01
          example: 500
        externalReference:
          type: string
          maxLength: 100
          description: >-
            Your unique transaction reference. Duplicate references return `409
            Conflict`.
          example: withdraw_xyz789
        description:
          type: string
          maxLength: 140
          description: Optional description that may appear on the payee's bank statement.
          example: Player withdrawal
        webhookUrl:
          type: string
          format: uri
          description: >-
            URL to receive settlement events (`CASHOUT_COMPLETED`,
            `CASHOUT_FAILED`, `CASHOUT_REFUNDED`).
          example: https://api.yourdomain.com/webhooks/connectpsp
        payee:
          $ref: '#/components/schemas/CashOutPayee'
    CashOutPayee:
      type: object
      required:
        - name
        - document
        - destination
      properties:
        name:
          type: string
          description: Full name of the payee.
          example: Maria Silva
        document:
          type: string
          description: CPF or CNPJ of the payee (numbers only).
          example: '12345678909'
        destination:
          $ref: '#/components/schemas/CashOutDestination'
    CashOutDestination:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - PIX
            - BANK_ACCOUNT
          description: >
            - `PIX` — payment via PIX key. Provide `pixKeyType` and `pixKey`.

            - `BANK_ACCOUNT` — payment via bank account data. Provide
            `bankAccount`.
          example: PIX
        pixKeyType:
          type: string
          enum:
            - CPF
            - CNPJ
            - EMAIL
            - PHONE
            - EVP
          description: Type of PIX key. Required when `type` is `PIX`.
          example: CPF
        pixKey:
          type: string
          description: The PIX key value. Required when `type` is `PIX`.
          example: '12345678909'
        bankAccount:
          $ref: '#/components/schemas/CashOutBankAccountInput'
    CashOutBankAccountInput:
      type: object
      required:
        - ispb
        - branch
        - account
      description: >-
        Bank account details. Required when `destination.type` is
        `BANK_ACCOUNT`.
      properties:
        ispb:
          type: string
          description: Bank ISPB code (8 digits).
          example: '18236120'
        branch:
          type: string
          description: Branch number (without check digit).
          example: '0001'
        account:
          type: string
          description: Account number with check digit.
          example: '947710840'
        accountType:
          type: string
          enum:
            - CACC
            - SVGS
            - PAYMENT
          description: Account type. Defaults to `CACC` (checking).
          default: CACC
          example: PAYMENT
    CashOutAcceptedResponse:
      type: object
      properties:
        transactionId:
          type: string
          description: Internal UUID for this transaction.
          example: dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9
        internalCode:
          type: string
          description: ConnectPSP alphanumeric code. Use for polling.
          example: IVKPRMOCDY
        externalReference:
          type: string
          example: withdraw_xyz789
        status:
          type: string
          enum:
            - PROCESSING
          example: PROCESSING
        requestedAt:
          type: string
          format: date-time
          example: '2026-03-10T14:00:00-03:00'
    CashOutDetailedResponse:
      type: object
      properties:
        transactionId:
          type: string
          example: dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9
        internalCode:
          type: string
          example: IVKPRMOCDY
        externalReference:
          type: string
          example: withdraw_xyz789
        endToEndId:
          type: string
          description: |
            BACEN/SPI settlement proof.
            - `COMPLETED`: starts with `E`
            - `REFUNDED`: starts with `D`
            - `FAILED`: `null` (never settled)
          example: E00416968202603101827cemeFscF6AG
        originalEndToEndId:
          type: string
          description: Original E2E ID when `endToEndId` represents an async refund.
        status:
          type: string
          enum:
            - PROCESSING
            - COMPLETED
            - FAILED
            - REFUNDED
            - CANCELLED
          example: COMPLETED
        amount:
          type: number
          format: decimal
          example: 500
        failure:
          $ref: '#/components/schemas/CashOutFailure'
        payee:
          $ref: '#/components/schemas/CashOutPayeeDetailed'
        requestedAt:
          type: string
          format: date-time
          example: '2026-03-10T14:00:00-03:00'
        paidAt:
          type: string
          format: date-time
          example: '2026-03-10T14:02:30-03:00'
        failedAt:
          type: string
          format: date-time
        refundedAt:
          type: string
          format: date-time
        canceledAt:
          type: string
          format: date-time
    CashOutPayeeDetailed:
      allOf:
        - $ref: '#/components/schemas/CashOutPayee'
        - type: object
          properties:
            bankData:
              $ref: '#/components/schemas/BankData'
    CashOutFailure:
      type: object
      description: Present only when `status` is `FAILED`.
      properties:
        code:
          type: string
          description: Machine-readable failure code.
          example: PIX_KEY_NOT_FOUND
        message:
          type: string
          description: Human-readable failure reason.
          example: The provided PIX key did not resolve to a valid account.
    AccountBalanceResponse:
      type: object
      properties:
        currency:
          type: string
          example: BRL
        referenceDate:
          type: string
          format: date
          example: '2026-03-10'
        consolidated:
          type: object
          properties:
            totalBalance:
              type: number
              format: decimal
              description: Sum of all transactional and proprietary balances.
              example: 1500000
            transactionalBalance:
              type: number
              format: decimal
              description: Total funds available for Cash-Out operations.
              example: 500000
            proprietaryBalance:
              type: number
              format: decimal
              description: Total reserve/buffer capital.
              example: 1000000
        banks:
          type: array
          items:
            $ref: '#/components/schemas/BankBalance'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the balance snapshot was extracted.
          example: '2026-03-10T14:35:00Z'
    BankBalance:
      type: object
      properties:
        ispb:
          type: string
          example: '13935893'
        bank:
          type: string
          example: CELCOIN IP S.A.
        accounts:
          type: object
          properties:
            transactional:
              $ref: '#/components/schemas/AccountDetail'
            proprietary:
              $ref: '#/components/schemas/AccountDetail'
    AccountDetail:
      type: object
      properties:
        branch:
          type: string
          example: '0001'
        account:
          type: string
          example: '123456'
        balance:
          type: number
          format: decimal
          example: 200000
    RebalanceRequest:
      type: object
      required:
        - targetAmount
      properties:
        targetAmount:
          type: number
          format: decimal
          minimum: 0.01
          description: >
            The **target transactional balance** (in BRL) representing your
            total current user exposure

            (sum of all user wallet balances + in-flight operations).

            ConnectPSP will automatically calculate the direction (Top-up or
            Sweep).
          example: 1000000
    RebalanceResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Rebalancing completed successfully.
    BankData:
      type: object
      description: >-
        Banking details returned after settlement. May be `null` before
        settlement.
      properties:
        ispb:
          type: string
          description: Bank ISPB code (8 digits).
          example: '00000000'
        bank:
          type: string
          description: Bank name.
          example: Banco do Brasil S.A.
        branch:
          type: string
          description: Branch number.
          example: '0001'
        account:
          type: string
          description: Account number.
          example: '123456'
    Problem:
      type: object
      description: RFC 7807 Problem Details object returned for all 4xx/5xx errors.
      properties:
        type:
          type: string
          format: uri
          description: URI identifying the error type.
          example: https://connect-psp.redocly.app/errors/insufficient-funds
        title:
          type: string
          description: Short, human-readable summary.
          example: Insufficient Funds
        status:
          type: integer
          description: HTTP status code.
          example: 422
        code:
          type: string
          description: Machine-readable error code for programmatic handling.
          example: INSUFFICIENT_FUNDS
        detail:
          type: string
          description: Human-readable explanation of this specific occurrence.
          example: >-
            The requested amount of R$ 500.00 exceeds available balance of R$
            100.00.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from `POST /auth/token`. Expires in 1 hour.
    applicationToken:
      type: apiKey
      in: header
      name: ApplicationToken
      description: >-
        Fixed GUID that uniquely identifies your integration. Provided during
        ConnectPSP onboarding.
