components:
    schemas:
        Account:
            properties:
                balance:
                    $ref: '#/components/schemas/AccountBalance'
                currency:
                    description: ISO 4217 currency code for the account.
                    type: string
                id:
                    description: Unique identifier for the account.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                status:
                    description: Status of the account (e.g., active, suspended).
                    type: string
            required:
                - id
                - currency
                - balance
                - status
            type: object
        AccountBalance:
            properties:
                available:
                    description: Amount available for withdrawal or use.
                    type: string
                pending:
                    description: Amount pending settlement.
                    type: string
                spentThisMonth:
                    description: Amount moved into the spend balance over the current calendar month.
                    type: string
            required:
                - available
                - pending
            type: object
        AccountCardTopUpRequest:
            additionalProperties: false
            description: Top up an account using an external payment card.
            properties:
                amount:
                    description: Amount to credit to the account (in account currency).
                    format: decimal
                    type: string
                    x-go-type: decimal.Decimal
                clientTransactionId:
                    description: Optional client-side transaction identifier.
                    type: string
                customerIp:
                    $ref: '#/components/schemas/IPAddress'
                idempotencyKey:
                    description: Optional idempotency key to deduplicate requests.
                    type: string
                metadata:
                    additionalProperties: true
                    description: Optional free-form metadata that will be stored with the transaction.
                    type: object
                payer:
                    $ref: '#/components/schemas/PersonKyc'
                paymentMethod:
                    $ref: '#/components/schemas/PaymentCardPlain'
                returnUrl:
                    description: Optional URL to return the end-user to after any required authentication steps.
                    format: uri
                    type: string
            required:
                - amount
                - paymentMethod
                - payer
            type: object
        AccountCardTopUpResponse:
            allOf:
                - $ref: '#/components/schemas/AccountPaymentTxResponse'
                - description: Top-up initiation response.
                  properties:
                    type:
                        enum:
                            - account_topup_card
                        type: string
                  type: object
        AccountCardWithdrawRequest:
            additionalProperties: false
            description: Withdraw funds from an account to an external payment card.
            properties:
                amount:
                    description: Amount to withdraw from the account.
                    format: decimal
                    type: string
                    x-go-type: decimal.Decimal
                clientTransactionId:
                    description: Optional client-side transaction identifier.
                    type: string
                customerIp:
                    $ref: '#/components/schemas/IPAddress'
                destination:
                    $ref: '#/components/schemas/CardPayoutDestination'
                idempotencyKey:
                    description: Optional idempotency key to deduplicate requests.
                    type: string
                metadata:
                    additionalProperties: true
                    type: object
                note:
                    maxLength: 150
                    type: string
                purpose:
                    maxLength: 100
                    type: string
                sender:
                    $ref: '#/components/schemas/PersonKyc'
            required:
                - amount
                - sender
                - destination
            type: object
        AccountCardWithdrawResponse:
            allOf:
                - $ref: '#/components/schemas/AccountPaymentTxResponse'
                - description: Withdrawal initiation response.
                  properties:
                    type:
                        enum:
                            - account_withdraw_card
                        type: string
                  type: object
        AccountPaymentTxResponse:
            additionalProperties: false
            description: Response for an initiated account funding/payout operation.
            properties:
                accountId:
                    description: Payca account identifier.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                clientTransactionId:
                    type: string
                createdAt:
                    format: date-time
                    type: string
                externalReferenceId:
                    type: string
                metadata:
                    additionalProperties: true
                    type: object
                nextAction:
                    $ref: '#/components/schemas/PaymentNextAction'
                status:
                    $ref: '#/components/schemas/PaymentStatus'
                txId:
                    description: Payca transaction identifier.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                updatedAt:
                    format: date-time
                    type: string
            required:
                - txId
                - accountId
                - status
                - createdAt
                - updatedAt
            type: object
        AccountTransaction:
            properties:
                AccountBalance:
                    type: object
                accountId:
                    description: Identifier of the associated account.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                amount:
                    description: Transaction amount.
                    type: string
                    x-go-type: decimal.Decimal
                cardId:
                    description: Linked card identifier.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                currency:
                    description: ISO 4217 currency code of the transaction.
                    type: string
                id:
                    description: Unique identifier of the transaction.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                referenceId:
                    description: Linked transaction identifier.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                subtype:
                    description: Subtype of the transaction.
                    enum:
                        - card_withdraw
                        - card_closed_adjustment
                        - card_closed_refund
                        - card_closed_cancel
                        - card_deposit
                        - card_issue
                        - card_monthly_fee
                        - legacy
                        - settle_fee
                        - decline_fee
                        - authorization_fee
                        - issue_fee
                        - deposit_sepa
                        - deposit_crypto
                        - deposit_wire
                        - deposit_user
                        - withdraw_user
                        - account_topup_card
                        - account_withdraw_card
                        - user_fee_debt
                        - user_fee_repay
                        - lock_user_funds
                        - unlock_user_funds
                        - spend_user_funds
                        - refund_user_funds
                    type: string
                timestamp:
                    description: The timestamp when the transaction occurred.
                    format: date-time
                    type: string
                type:
                    description: Type of the transaction.
                    enum:
                        - deposit
                        - withdraw
                        - transfer
                        - fee
                        - pending
                        - lock_user_funds
                        - unlock_user_funds
                        - spend_user_funds
                        - refund_user_funds
                    type: string
            required:
                - id
                - accountId
                - referenceId
                - type
                - currency
                - amount
                - timestamp
                - subtype
            type: object
        AccountTransactionsResponse:
            properties:
                data:
                    items:
                        $ref: '#/components/schemas/AccountTransaction'
                    type: array
                page:
                    description: Current page of results.
                    type: integer
                total:
                    description: Total number of transactions available.
                    type: integer
            required:
                - data
                - page
                - total
            type: object
        AccountWithBins:
            allOf:
                - $ref: '#/components/schemas/Account'
                - properties:
                    bins:
                        items:
                            $ref: '#/components/schemas/Bin'
                        type: array
                  type: object
        AccountsResponse:
            properties:
                accounts:
                    items:
                        $ref: '#/components/schemas/Account'
                    type: array
            type: object
        AccountsWithBinsResponse:
            properties:
                accounts:
                    items:
                        $ref: '#/components/schemas/AccountWithBins'
                    type: array
            type: object
        AllocationInfo:
            properties:
                currency:
                    type: string
                depositAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                depositConfirmed:
                    type: boolean
                expectedAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                expiresAt:
                    format: date-time
                    type: string
            type: object
        Bin:
            properties:
                applePay:
                    description: Indicates if cards issued under this BIN can be provisioned into Apple Pay.
                    type: boolean
                bin:
                    description: Bank Identification Number (BIN) code.
                    type: string
                currencyCode:
                    description: Currency code associated with the BIN.
                    type: string
                fees:
                    $ref: '#/components/schemas/BinFees'
                googlePay:
                    description: Indicates if cards issued under this BIN can be provisioned into Google Pay.
                    type: boolean
                isTokenizable:
                    description: Indicates if cards issued under this BIN can be tokenized (provisioned into any digital wallet). Equals applePay OR googlePay.
                    type: boolean
                name:
                    description: Human-readable name of the BIN.
                    type: string
                provider:
                    description: Card provider associated with the BIN code.
                    enum:
                        - visa
                        - mastercard
                    type: string
                settings:
                    properties:
                        minCardBalance:
                            description: Minimal issuing balance required.
                            format: float
                            type: string
                        providerCardHolderModel:
                            description: Cardholder model the upstream provider expects for cards on this BIN. Empty when the BIN is not tied to a provider with per-cardholder KYC.
                            enum:
                                - B2B
                                - B2C
                            type: string
                    required:
                        - minCardBalance
                    type: object
            required:
                - currencyCode
                - bin
                - provider
                - settings
                - isTokenizable
            type: object
        BinAuthFee:
            properties:
                range:
                    description: Authorization amount range.
                    type: string
                value:
                    description: Fee value for the authorization range.
                    format: float
                    type: string
            required:
                - range
                - value
            type: object
        BinCapacityResponse:
            description: Per-cardholder issuance capacity for a BIN.
            properties:
                bin:
                    description: BIN code.
                    type: string
                cardholderId:
                    description: Cardholder UUID the capacity is reported for.
                    format: uuid
                    type: string
                hasLimit:
                    description: |
                        True when this BIN limits how many cards one cardholder may
                        hold. False means no limit applies — counts are zero and the
                        cardholder should be treated as effectively unlimited.
                    type: boolean
                max:
                    description: Cards one cardholder may hold at a time on this BIN.
                    format: int64
                    type: integer
                remaining:
                    description: |
                        Cards this cardholder can still be issued now (max - used,
                        clamped at 0). At 0, issue on another cardholder.
                    format: int64
                    type: integer
                used:
                    description: |
                        Cards this cardholder currently HOLDS, not cards ever issued:
                        closing a card gives its slot back, so this number can go
                        down. Do not compare it against a running total of your own
                        issuances.
                    format: int64
                    type: integer
            required:
                - bin
                - cardholderId
                - hasLimit
                - used
                - max
                - remaining
            type: object
        BinCatalogEntry:
            properties:
                bin:
                    description: Bank Identification Number (BIN) code.
                    type: string
                currencyCode:
                    description: Currency code associated with the BIN.
                    type: string
                isArchived:
                    description: Whether the BIN is archived (hidden from assignment).
                    type: boolean
                isEnabled:
                    description: Whether the BIN is currently enabled (issuable).
                    type: boolean
                providerCardHolderModel:
                    description: |
                        Cardholder model the upstream provider expects for cards on this
                        BIN. Absent when the BIN is not tied to a provider with
                        per-cardholder KYC.
                    enum:
                        - B2B
                        - B2C
                    type: string
            required:
                - bin
                - currencyCode
                - isEnabled
                - isArchived
            type: object
        BinCatalogResponse:
            properties:
                bins:
                    items:
                        $ref: '#/components/schemas/BinCatalogEntry'
                    type: array
            required:
                - bins
            type: object
        BinDeclineFee:
            properties:
                range:
                    description: Decline rate percentage range.
                    type: string
                value:
                    description: Fee value for the decline rate range.
                    format: float
                    type: string
            required:
                - range
                - value
            type: object
        BinFees:
            properties:
                authorization:
                    items:
                        $ref: '#/components/schemas/BinAuthFee'
                    type: array
                decline:
                    items:
                        $ref: '#/components/schemas/BinDeclineFee'
                    type: array
                deliveryFee:
                    description: |
                        What it costs to post a physical card, charged on top of the issue fee. Absent on every virtual BIN — only a program that ships plastic sets it. Kept apart from issueFee so a cabinet downstream can show a customer what they are paying for.
                    format: float
                    type: string
                issueFee:
                    description: Fee for issuing a card.
                    format: float
                    type: string
                minCardBalance:
                    description: Minimal issuing balance required.
                    format: float
                    type: string
                monthlyFee:
                    description: Monthly maintenance fee for the card.
                    format: float
                    type: string
            required:
                - issueFee
                - monthlyFee
                - authorization
                - decline
                - minCardBalance
            type: object
        BinsResponse:
            properties:
                bins:
                    items:
                        $ref: '#/components/schemas/Bin'
                    type: array
            required:
                - bins
            type: object
        BlockchainChain:
            description: Supported blockchain networks.
            enum:
                - ETH
                - BASE
                - SOL
            type: string
        Card:
            properties:
                accountId:
                    description: Account linked to the card.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                balance:
                    $ref: '#/components/schemas/CardBalance'
                bin:
                    description: Card BIN code.
                    type: string
                currency:
                    description: ISO 4217 currency code for the card.
                    type: string
                externalUserId:
                    description: Reference identifier for the issued card.
                    type: string
                id:
                    description: Unique identifier for the card.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                maskedPan:
                    description: Masked PAN (Primary Account Number).
                    type: string
                productCode:
                    description: Card product code (e.g., TCC for Tokenized, VCC for Virtual).
                    type: string
                status:
                    description: Current status of the card.
                    enum:
                        - active
                        - closed
                        - frozen
                        - pending
                        - blocked
                    type: string
                tokenizationExpiresAt:
                    description: The timestamp (UTC) when the tokenization process will expire.
                    format: date-time
                    type: string
                tokenizationStatus:
                    description: Status of the card tokenization process.
                    enum:
                        - tokenization_pending
                        - tokenization_expired
                        - tokenization_done
                        - tokenization_disabled
                    type: string
            required:
                - id
                - currency
                - balance
                - accountId
                - status
                - tokenizationStatus
                - productCode
                - maskedPan
                - bin
            type: object
        CardBalance:
            properties:
                available:
                    description: Amount available for withdrawal or use.
                    type: string
                pending:
                    description: Amount pending settlement.
                    type: string
                spent:
                    description: Amount already spent.
                    type: string
            required:
                - available
                - pending
                - spent
            type: object
        CardIssueRequest:
            properties:
                accountId:
                    description: Account ID that will be debited for issuing the card.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                balance:
                    description: Initial balance for the issued card.
                    type: string
                    x-go-type: decimal.Decimal
                bin:
                    description: Target BIN code for the new card.
                    type: string
                cardholderId:
                    description: Cardholder UUID for B2B cards. Create a cardholder first (see Cardholders endpoints), wait for pass_audit status, then pass the ID here.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                externalUserId:
                    description: Reference identifier for the issued card.
                    type: string
                idempotencyKey:
                    description: Idempotency key, must be unique for each request.
                    type: string
            required:
                - bin
                - balance
                - accountId
            type: object
        CardPayoutCardholder:
            additionalProperties: false
            description: Cardholder identity details.
            properties:
                birthDate:
                    format: date
                    type: string
                countryOfResidence:
                    $ref: '#/components/schemas/CountryCodeAlpha2'
                email:
                    format: email
                    type: string
                firstName:
                    type: string
                lastName:
                    type: string
            required:
                - firstName
                - lastName
                - countryOfResidence
            type: object
        CardPayoutDestination:
            additionalProperties: false
            description: Destination card details for payouts.
            properties:
                cardNumber:
                    description: Recipient card number (PAN).
                    pattern: ^[0-9]{12,19}$
                    type: string
                cardholder:
                    $ref: '#/components/schemas/CardPayoutCardholder'
                currency:
                    $ref: '#/components/schemas/CurrencyCode'
            required:
                - cardNumber
                - cardholder
            type: object
        CardSensitive:
            properties:
                cvc2:
                    description: Card security code.
                    type: string
                expiration:
                    description: Card expiration date (MM/YY).
                    type: string
                number:
                    description: Full card number.
                    type: string
            required:
                - number
                - cvc2
                - expiration
            type: object
        CardTokenizationStarted:
            properties:
                expiresAt:
                    description: UTC timestamp when this tokenization session expires.
                    format: date-time
                    type: string
                phone:
                    description: The BIP phone number the cardholder should use as OTP destination.
                    example: "+37254276463"
                    type: string
            required:
                - phone
                - expiresAt
            type: object
        CardTopUpRequest:
            properties:
                accountID:
                    description: Unique identifier of the account that will be debited.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                amount:
                    description: Amount to add to the card balance.
                    format: decimal
                    type: string
                    x-go-type: decimal.Decimal
                idempotencyKey:
                    description: Idempotency key, must be unique for each request.
                    type: string
            required:
                - amount
                - accountID
            type: object
        CardTransaction:
            properties:
                billingAmount:
                    description: Billed amount.
                    type: string
                    x-go-type: decimal.Decimal
                billingCurrency:
                    description: Currency in which the transaction was billed.
                    type: string
                cardId:
                    description: Identifier of the associated card.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                exchangeRate:
                    description: Exchange rate used for conversion.
                    type: string
                    x-go-type: decimal.Decimal
                id:
                    description: Unique identifier of the transaction.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                merchantCode:
                    description: Merchant MCC code.
                    type: string
                merchantName:
                    description: Merchant name.
                    type: string
                meta:
                    type: object
                    x-go-type: json.RawMessage
                referenceId:
                    description: Linked transaction identifier.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                timestamp:
                    description: The timestamp when the transaction occurred.
                    format: date-time
                    type: string
                transactionAmount:
                    description: Amount in the transaction currency.
                    type: string
                    x-go-type: decimal.Decimal
                transactionCurrency:
                    description: Currency used in the transaction.
                    type: string
                type:
                    description: Type of the transaction.
                    enum:
                        - issue
                        - topup
                        - withdraw
                        - authorization
                        - decline
                        - cancel
                        - settle
                        - refund
                    type: string
            required:
                - id
                - type
                - cardId
                - billingCurrency
                - billingAmount
                - timestamp
                - referenceId
                - transactionCurrency
                - transactionAmount
                - merchantName
                - merchantCode
                - exchangeRate
                - meta
            type: object
        CardTransactionsResponse:
            properties:
                data:
                    items:
                        $ref: '#/components/schemas/CardTransaction'
                    type: array
                page:
                    description: Current page of results.
                    type: integer
                total:
                    description: Total number of transactions available.
                    type: integer
            required:
                - data
                - page
                - total
            type: object
        CardTxResponse:
            properties:
                cardId:
                    description: Unique identifier for the card.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                txId:
                    description: Card transaction ID.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - txId
                - cardId
            type: object
        CardWithdrawRequest:
            properties:
                accountID:
                    description: Unique identifier of the account that will be credited.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                amount:
                    description: Amount to withdraw from the card balance.
                    format: decimal
                    type: string
                    x-go-type: decimal.Decimal
                idempotencyKey:
                    description: Idempotency key, must be unique for each request.
                    type: string
            required:
                - amount
                - accountID
            type: object
        CardholderCity:
            properties:
                code:
                    description: City code to use in cardholder creation (town field).
                    type: string
                country:
                    description: Country code this city belongs to.
                    type: string
                name:
                    description: Human-readable city name.
                    type: string
            required:
                - code
                - name
                - country
            type: object
        CardholderFileUploadResponse:
            properties:
                fileId:
                    description: File ID to use in cardholder creation (idFrontId, idBackId, idHoldId fields).
                    type: string
            required:
                - fileId
            type: object
        CardholderOccupation:
            properties:
                code:
                    description: Occupation code to use in B2C cardholder creation.
                    type: string
                description:
                    description: Human-readable occupation description.
                    type: string
            required:
                - code
                - description
            type: object
        CardholderRegion:
            properties:
                code:
                    description: ISO 3166-1 alpha-2 country code.
                    type: string
                name:
                    description: Country/region name.
                    type: string
                standardCode:
                    description: ISO 3166-1 alpha-3 code.
                    type: string
            required:
                - code
                - name
            type: object
        CardholderResponse:
            properties:
                createdAt:
                    format: date-time
                    type: string
                description:
                    description: Rejection reason (if rejected).
                    type: string
                email:
                    type: string
                firstName:
                    type: string
                holderId:
                    description: |
                        Upstream holder assigned to this cardholder. `0` until one is
                        assigned — and always `0` on a B2B BIN, where the holder is picked
                        per card at issue time rather than per cardholder. Not an error.
                    format: int64
                    type: integer
                id:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                lastName:
                    type: string
                status:
                    description: 'Status: pending_review, rejected_by_admin, wait_audit, under_review, pass_audit, reject'
                    type: string
                statusFlowLocation:
                    type: string
                updatedAt:
                    format: date-time
                    type: string
            required:
                - id
                - holderId
                - status
                - firstName
                - lastName
                - email
                - createdAt
                - updatedAt
            type: object
        CardholderUpdateRequest:
            description: |
                Partial update of a cardholder's personal data. All fields are optional;
                omitted fields keep their current value. Field rules match
                `POST /v1/users/{id}/cardholder` (see the user `meta` table there).
            properties:
                accountPurpose:
                    type: string
                address:
                    description: |
                        Letters, digits, hyphens and spaces only (no commas or other
                        punctuation); max 40 chars; ASCII.
                    type: string
                annualSalary:
                    type: string
                birthday:
                    description: YYYY-MM-DD.
                    type: string
                country:
                    description: Country code, see /v1/cardholders/regions.
                    type: string
                email:
                    description: Max 50 chars.
                    type: string
                expectedMonthlyVolume:
                    type: string
                firstName:
                    description: |
                        Latin letters, space, hyphen, apostrophe and period only; max 40 chars.
                        TEST/MOCK/SANDBOX are rejected.
                    type: string
                gender:
                    description: M or F (B2C).
                    type: string
                idExpiryDate:
                    description: YYYY-MM-DD. Must not be earlier than idIssueDate.
                    type: string
                idIssueDate:
                    description: YYYY-MM-DD. Required for B2C.
                    type: string
                idNo:
                    type: string
                idType:
                    description: PASSPORT, DLN, HK_HKID or GOVERNMENT_ISSUED_ID_CARD.
                    type: string
                lastName:
                    description: Same rules as firstName.
                    type: string
                nationality:
                    description: Country code, see /v1/cardholders/regions.
                    type: string
                occupation:
                    description: Occupation code, see /v1/cardholders/occupations.
                    type: string
                phone:
                    description: Digits only, 7-15 digits, no country code; must be a mobile number.
                    type: string
                phoneCode:
                    description: '"+" and 1-4 digits, e.g. "+372".'
                    type: string
                postCode:
                    description: Letters and digits only, max 15 chars; spaces are stripped.
                    type: string
                town:
                    description: City code, see /v1/cardholders/cities.
                    type: string
            type: object
        CardsResponse:
            properties:
                data:
                    items:
                        $ref: '#/components/schemas/Card'
                    type: array
                page:
                    description: Current page of results.
                    type: integer
                total:
                    description: Total number of cards available.
                    type: integer
            required:
                - page
                - total
                - data
            type: object
        CheckBalanceIncreaseRequest:
            properties:
                currency:
                    description: Settlement currency (e.g. USD, EUR). Defaults to USD.
                    type: string
                expectedIncrease:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                previousBalance:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - previousBalance
                - expectedIncrease
            type: object
        CheckBalanceIncreaseResponse:
            properties:
                actualIncrease:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                confirmed:
                    type: boolean
                currentBalance:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                thresholdUsed:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - confirmed
                - currentBalance
            type: object
        ConfirmGasTopupRequest:
            properties:
                actualAmount:
                    description: Actual amount sent (if different from planned).
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                txHash:
                    description: Transaction hash of the gas topup.
                    type: string
            required:
                - txHash
            type: object
        ConfirmSweepRequest:
            properties:
                gasUsed:
                    description: Gas used for the transaction.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                txHash:
                    description: Blockchain transaction hash.
                    type: string
            required:
                - txHash
            type: object
        CountryCodeAlpha2:
            description: ISO 3166-1 alpha-2 country code.
            maxLength: 2
            minLength: 2
            type: string
        CreateCardholderRequest:
            description: Request to create a cardholder for a user. Personal data is read from user meta.
            properties:
                accountId:
                    description: Account ID that determines the provider.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                bin:
                    description: BIN code to determine the card type.
                    type: string
            required:
                - accountId
                - bin
            type: object
        CreateDepositRequest:
            properties:
                amount:
                    description: |
                        Amount to deposit, in the account's own currency. A deposit is never
                        converted on the way in.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                cancelRedirectUrl:
                    description: |
                        Where the payer returns after cancelling. Must match a prefix
                        allow-listed for the calling client.
                    type: string
                completeRedirectUrl:
                    description: |
                        Where the payer returns after a completed checkout. Must match a prefix
                        allow-listed for the calling client.
                    type: string
                country:
                    description: ISO 3166-1 alpha-2 billing country of the payer.
                    maxLength: 2
                    minLength: 2
                    type: string
                expectedChargedAmount:
                    description: Total previously shown by the quote endpoint. Create returns 409 if it changed.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                expectedCreditedAmount:
                    description: Credited amount previously shown by the quote endpoint.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                expectedDeclineFee:
                    description: Decline fee previously shown by the quote endpoint.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                expectedPaycaFee:
                    description: Processing fee previously shown by the quote endpoint.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                expectedProviderFee:
                    description: Acquiring fee previously shown by the quote endpoint.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                expectedRefundFee:
                    description: Refund fee previously shown by the quote endpoint.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                method:
                    $ref: '#/components/schemas/FundingMethod'
                payer:
                    $ref: '#/components/schemas/DepositPayer'
                userId:
                    description: |
                        User the deposit is for. Required when the account is not itself bound to
                        a user, and it must belong to the same account.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - method
                - amount
                - country
                - completeRedirectUrl
                - cancelRedirectUrl
            type: object
        CreateGasTopupRequest:
            properties:
                amount:
                    description: Optional override for the topup amount.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                walletId:
                    format: uuid
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - walletId
                - chain
            type: object
        CreatePayoutRequest:
            properties:
                amount:
                    description: |
                        The amount you are sending. In `deducted` mode this is what leaves the
                        account; in `add_on` mode it is what the recipient receives.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                country:
                    description: ISO 3166-1 alpha-2 country of the recipient.
                    maxLength: 2
                    minLength: 2
                    type: string
                destination:
                    $ref: '#/components/schemas/PayoutDestination'
                expectedTotalFee:
                    description: |
                        Exact totalFee returned by the latest quote. Creation is rejected if the
                        live provider tariff changed before this request.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                feeMode:
                    $ref: '#/components/schemas/PayoutFeeMode'
                method:
                    $ref: '#/components/schemas/PayoutMethod'
                userId:
                    description: |
                        User the payout belongs to. Required when the account is not bound to one;
                        must match the account's user when it is.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - method
                - amount
                - feeMode
                - country
                - destination
                - expectedTotalFee
            type: object
        CreateSweepOperationRequest:
            properties:
                amount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                autoTopup:
                    default: false
                    description: If true, automatically create a gas topup operation if wallet has insufficient gas.
                    type: boolean
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                treasuryAddress:
                    description: Override default treasury address.
                    type: string
                walletId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - walletId
                - chain
                - amount
            type: object
        CreateSweepOperationResponse:
            properties:
                sweepOperation:
                    $ref: '#/components/schemas/GasStationOperation'
                topupOperation:
                    $ref: '#/components/schemas/GasStationOperation'
                    description: If auto-topup was triggered, this contains the topup operation.
            required:
                - sweepOperation
            type: object
        CurrencyCode:
            description: ISO 4217 currency code.
            maxLength: 4
            minLength: 3
            type: string
        Deposit:
            properties:
                accountId:
                    description: Account the deposit credits.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                amount:
                    description: Requested deposit amount.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                chargedAmount:
                    description: |
                        Total charged to the payer. Provider fee is always added on top; Payca fee follows the configured deducted/add-on mode.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                checkoutUrl:
                    description: Hosted checkout URL, for methods that use one.
                    type: string
                completedAt:
                    format: date-time
                    type: string
                createdAt:
                    format: date-time
                    type: string
                creditedAmount:
                    description: Amount credited to the account. Present once credited.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                currency:
                    description: Deposit currency; always matches the target account currency.
                    type: string
                declineFee:
                    description: Total provider and Payca fee charged separately if this deposit is declined.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                expiresAt:
                    format: date-time
                    type: string
                id:
                    description: Payca deposit identifier.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                method:
                    $ref: '#/components/schemas/FundingMethod'
                paycaFee:
                    description: |
                        Payca fee, priced when the deposit is created and fixed for its lifetime. Absent means the deposit was never priced — absent is not zero.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                providerFee:
                    description: |
                        Acquiring fee quoted and fixed when the deposit is created. Absent on legacy orders that were created before provider pricing was available.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                refundFee:
                    description: Total provider and Payca fee charged separately if this deposit is refunded.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                refundedAt:
                    format: date-time
                    type: string
                status:
                    $ref: '#/components/schemas/DepositStatus'
            required:
                - id
                - status
                - method
                - accountId
                - amount
                - currency
                - createdAt
            type: object
        DepositAmountMode:
            description: Which side of the deposit quote the caller supplied.
            enum:
                - credited
                - charged
            type: string
        DepositFeeMode:
            description: |
                Which side of the deposit carries the fee.
                `deducted` — the payer is charged the requested amount and the account is
                credited less the fee.
                `add_on` — the account is credited the requested amount and the payer is
                charged that plus the fee.
            enum:
                - deducted
                - add_on
            type: string
        DepositFeeTerms:
            description: |
                What a deposit on this option costs, so the price can be shown before an order is opened. The fee is `fixed` plus `rate` percent of the requested amount, clamped to `minFee` and `maxFee`. Absent from an option means no fee is charged on it.
            properties:
                declineFixed:
                    description: Fixed fee charged separately after a decline.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                declineRate:
                    description: Percentage fee charged separately after a decline.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                fixed:
                    description: Flat component, in the deposit currency.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                maxFee:
                    description: Cap on the computed fee. Absent means no cap.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                minFee:
                    description: Floor on the computed fee. Absent means no floor.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                mode:
                    $ref: '#/components/schemas/DepositFeeMode'
                rate:
                    description: Percentage component, in percent — "2.5" means 2.5%.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                refundFixed:
                    description: Fixed fee charged separately after a refund.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                refundRate:
                    description: Percentage fee charged separately after a refund.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - mode
                - rate
                - fixed
            type: object
        DepositListResponse:
            properties:
                deposits:
                    items:
                        $ref: '#/components/schemas/Deposit'
                    type: array
                total:
                    description: Total deposits matching the filter, ignoring pagination.
                    format: int64
                    type: integer
            required:
                - deposits
                - total
            type: object
        DepositPayer:
            description: |
                Who is paying. Required the first time a given user deposits; afterwards the
                payer identity established with the provider is reused and this may be
                omitted.

                Send every identity attribute you hold (taxId, dateOfBirth, city, postalCode,
                address). A complete set allows screening through the API. For payment methods
                with a simplified profile flow, the platform may complete missing attributes
                server-side when the provider permits it. If the provider requires full
                verification, the hosted checkout collects the additional information from the
                payer before payment.
            properties:
                address:
                    type: string
                city:
                    type: string
                dateOfBirth:
                    description: Date of birth, YYYY-MM-DD.
                    type: string
                email:
                    format: email
                    type: string
                firstName:
                    type: string
                lastName:
                    type: string
                postalCode:
                    type: string
                taxId:
                    description: |
                        Tax identification number.
                    type: string
            required:
                - email
                - firstName
            type: object
        DepositQuote:
            properties:
                amountMode:
                    $ref: '#/components/schemas/DepositAmountMode'
                chargedAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                creditedAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                currency:
                    type: string
                declineFee:
                    description: Total provider and Payca fee charged if the payment is declined.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                processingFee:
                    description: Payca markup configured for this deposit route.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                providerFee:
                    description: Acquiring fee included in chargedAmount.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                refundFee:
                    description: Total provider and Payca fee charged if the payment is refunded.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                requestedAmount:
                    description: Amount to pass to CreateAccountDeposit.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - requestedAmount
                - amountMode
                - currency
                - processingFee
                - providerFee
                - declineFee
                - refundFee
                - creditedAmount
                - chargedAmount
            type: object
        DepositQuoteError:
            properties:
                code:
                    type: string
                    x-go-type: ErrorCode
                details:
                    type: string
                minimumInputAmount:
                    description: Minimum valid amount for the input side selected by amountMode.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                quote:
                    $ref: '#/components/schemas/DepositQuote'
            required:
                - code
                - details
            type: object
        DepositQuoteRequest:
            properties:
                amount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                amountMode:
                    $ref: '#/components/schemas/DepositAmountMode'
                country:
                    maxLength: 2
                    minLength: 2
                    type: string
                method:
                    $ref: '#/components/schemas/FundingMethod'
            required:
                - method
                - amount
                - amountMode
                - country
            type: object
        DepositStatus:
            description: |
                Normalised deposit status. Independent of any provider's own vocabulary.
                `completed` means settlement was confirmed AND the balance credit was
                recorded; `processing` covers payment confirmed but not yet settled or
                credited, so funds are not available yet.
            enum:
                - created
                - awaiting_payment
                - processing
                - completed
                - failed
                - cancelled
                - expired
                - refunded
                - chargeback
                - manual_review
            type: string
        Error:
            description: Error response payload containing details about the issue encountered.
            properties:
                code:
                    enum:
                        - ErrAccessDenied
                        - ErrAlreadyExists
                        - ErrAlreadyVerified
                        - ErrAuthCodeInvalid
                        - ErrInsufficientFunds
                        - ErrInternal
                        - ErrInvalidArg
                        - ErrInvalidCredentials
                        - ErrNotFound
                        - idempotency_conflict
                    type: string
                details:
                    description: human readable error details
                    type: string
            required:
                - code
                - details
            type: object
        ExchangeOrderRequest:
            properties:
                pair:
                    description: Trading pair (e.g. USDCUSD, USDCEUR).
                    type: string
                volume:
                    description: Volume in base currency.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - pair
                - volume
            type: object
        ExchangeOrderResponse:
            properties:
                cost:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                executedPrice:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                fee:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                feeCurrency:
                    type: string
                mockMode:
                    type: boolean
                orderId:
                    type: string
                pair:
                    type: string
                side:
                    type: string
                status:
                    type: string
                volume:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - orderId
                - status
                - mockMode
            type: object
        ExchangeRateInfo:
            properties:
                ask:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                bid:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                high:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                last:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                low:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                pair:
                    type: string
                timestamp:
                    format: date-time
                    type: string
                volume:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - pair
                - ask
                - bid
                - last
            type: object
        ExchangeRatesResponse:
            properties:
                cacheExpiresAt:
                    format: date-time
                    type: string
                cached:
                    type: boolean
                rates:
                    items:
                        $ref: '#/components/schemas/ExchangeRateInfo'
                    type: array
            required:
                - rates
                - cached
            type: object
        ExchangeWithdrawalDestination:
            properties:
                address:
                    description: Account identifier as the exchange reports it, for display only.
                    type: string
                asset:
                    type: string
                isDefault:
                    type: boolean
                key:
                    description: Nickname of the destination in the exchange account; this is what a withdrawal names.
                    type: string
                method:
                    description: Withdrawal method the destination is registered under (e.g. a SWIFT bank).
                    type: string
                verified:
                    type: boolean
            required:
                - key
                - isDefault
                - verified
            type: object
        ExchangeWithdrawalDestinationsResponse:
            properties:
                defaultKey:
                    type: string
                destinations:
                    items:
                        $ref: '#/components/schemas/ExchangeWithdrawalDestination'
                    type: array
                mockMode:
                    type: boolean
            required:
                - destinations
                - defaultKey
                - mockMode
            type: object
        ExchangeWithdrawalRequest:
            properties:
                amount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                currency:
                    type: string
                destination:
                    description: |
                        Withdrawal key registered in the exchange account, as listed by
                        GET /v1/exchange/withdrawal-destinations. Omit to use the configured
                        default destination. A key outside the allowlist is rejected.
                    type: string
            required:
                - amount
                - currency
            type: object
        ExchangeWithdrawalResponse:
            properties:
                amount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                currency:
                    type: string
                destination:
                    description: Withdrawal key the funds were sent to.
                    type: string
                fee:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                mockMode:
                    type: boolean
                status:
                    type: string
                withdrawalId:
                    type: string
            required:
                - withdrawalId
                - amount
                - currency
                - status
                - mockMode
            type: object
        ExchangeWithdrawalStatusResponse:
            properties:
                amount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                currency:
                    type: string
                fee:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                method:
                    type: string
                mockMode:
                    type: boolean
                status:
                    type: string
                txId:
                    type: string
                withdrawalId:
                    type: string
            required:
                - withdrawalId
                - status
                - mockMode
            type: object
        FailSweepRequest:
            properties:
                error:
                    description: Error message.
                    type: string
            required:
                - error
            type: object
        FundingMethod:
            description: How the external funds arrive.
            enum:
                - card
                - bank_transfer
                - crypto
            type: string
        FundingOption:
            properties:
                currency:
                    type: string
                fee:
                    $ref: '#/components/schemas/DepositFeeTerms'
                maxAmount:
                    description: Largest accepted deposit. Absent means no upper bound.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                method:
                    $ref: '#/components/schemas/FundingMethod'
                minAmount:
                    description: Smallest accepted deposit. Absent means no lower bound.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - method
                - currency
            type: object
        FundingOptionsResponse:
            properties:
                options:
                    items:
                        $ref: '#/components/schemas/FundingOption'
                    type: array
            required:
                - options
            type: object
        GasStationOperation:
            properties:
                amount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                confirmedAt:
                    format: date-time
                    type: string
                createdAt:
                    format: date-time
                    type: string
                error:
                    type: string
                fromAddress:
                    type: string
                gasUsed:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                id:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                status:
                    enum:
                        - pending
                        - submitted
                        - confirmed
                        - failed
                    type: string
                toAddress:
                    type: string
                token:
                    type: string
                txHash:
                    type: string
                type:
                    enum:
                        - sweep
                        - gas_topup
                    type: string
                walletId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - id
                - walletId
                - type
                - chain
                - fromAddress
                - toAddress
                - amount
                - token
                - status
                - createdAt
            type: object
        GasStationOperationsHistoryResponse:
            properties:
                operations:
                    items:
                        $ref: '#/components/schemas/GasStationOperation'
                    type: array
                total:
                    description: Total number of operations matching the filter.
                    type: integer
            required:
                - operations
                - total
            type: object
        GasStationOperationsResponse:
            properties:
                operations:
                    items:
                        $ref: '#/components/schemas/GasStationOperation'
                    type: array
            required:
                - operations
            type: object
        GasStationStatus:
            properties:
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                configured:
                    description: Whether gas station wallet is configured.
                    type: boolean
                gasMinThreshold:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                gasStationAddress:
                    description: Address of gas station wallet (if configured).
                    type: string
                gasStationBalance:
                    description: Current on-chain balance of gas station wallet (in native token).
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                gasTargetAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                pendingTopupOps:
                    description: Number of pending gas topup operations.
                    type: integer
                totalTopupRequired:
                    description: Total gas needed to top up all wallets.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                walletsNeedingGas:
                    description: Number of wallets that need gas topup.
                    type: integer
                walletsWithGas:
                    description: Number of available wallets with gas > 0.
                    type: integer
                walletsWithoutGas:
                    description: Number of available wallets with no gas.
                    type: integer
            required:
                - chain
                - configured
                - gasMinThreshold
                - gasTargetAmount
                - walletsNeedingGas
                - totalTopupRequired
                - pendingTopupOps
                - walletsWithGas
                - walletsWithoutGas
            type: object
        GasTopupCandidate:
            properties:
                address:
                    type: string
                allocationId:
                    format: uuid
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                currentGas:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                depositAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                targetGas:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                topupAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                walletId:
                    format: uuid
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - walletId
                - allocationId
                - address
                - chain
                - currentGas
                - targetGas
                - topupAmount
                - depositAmount
            type: object
        GasTopupCandidatesResponse:
            properties:
                candidates:
                    items:
                        $ref: '#/components/schemas/GasTopupCandidate'
                    type: array
            required:
                - candidates
            type: object
        GasTopupExportData:
            properties:
                amount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                fromAddress:
                    type: string
                gasStationPrivateKey:
                    description: Decrypted private key for the gas station wallet.
                    type: string
                operationId:
                    format: uuid
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                toAddress:
                    type: string
                token:
                    type: string
            required:
                - operationId
                - chain
                - fromAddress
                - toAddress
                - amount
                - token
                - gasStationPrivateKey
            type: object
        GenerateGasStationWalletRequest:
            properties:
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
            required:
                - chain
            type: object
        GenerateGasStationWalletResponse:
            properties:
                address:
                    description: Public address of the generated gas station wallet.
                    type: string
            required:
                - address
            type: object
        GenerateWalletsRequest:
            properties:
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                count:
                    description: Number of wallets to generate.
                    maximum: 100
                    minimum: 1
                    type: integer
            required:
                - chain
                - count
            type: object
        GenerateWalletsResponse:
            properties:
                generated:
                    description: Number of wallets generated.
                    type: integer
            required:
                - generated
            type: object
        HealthResponse:
            properties:
                status:
                    description: Health status of the service.
                    example: ok
                    type: string
            required:
                - status
            type: object
        IPAddress:
            description: IP address of the end user.
            type: string
        KYCDocumentResponse:
            properties:
                documentType:
                    $ref: '#/components/schemas/KYCDocumentType'
                fileName:
                    type: string
                fileSize:
                    format: int64
                    type: integer
                id:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                mimeType:
                    type: string
                rejectionReason:
                    type: string
                reviewedAt:
                    format: date-time
                    type: string
                reviewedBy:
                    type: string
                status:
                    $ref: '#/components/schemas/KYCDocumentStatus'
                uploadedAt:
                    format: date-time
                    type: string
                userId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - id
                - userId
                - documentType
                - fileName
                - fileSize
                - mimeType
                - status
                - uploadedAt
            type: object
        KYCDocumentStatus:
            enum:
                - pending
                - approved
                - rejected
            type: string
        KYCDocumentStatusUpdateRequest:
            properties:
                rejectionReason:
                    description: Required when rejecting a document.
                    type: string
                reviewedBy:
                    description: Admin who reviewed the document.
                    type: string
                status:
                    $ref: '#/components/schemas/KYCDocumentStatus'
            required:
                - status
            type: object
        KYCDocumentType:
            enum:
                - driving_licence
                - passport
                - residence_permit
                - id_card
                - proof_of_address
                - selfie_with_document
            type: string
        KYCDocumentUploadRequest:
            properties:
                documentType:
                    $ref: '#/components/schemas/KYCDocumentType'
                fileContent:
                    description: |
                        Base64-encoded file content. Max 20MB decoded. Images above the
                        provider's 2MB cap are recompressed automatically; PDFs are not.
                    format: byte
                    type: string
                fileName:
                    description: |
                        Original file name. For the reverse side of a two-sided document
                        include "back" (or "rear"/"reverse") as a word, e.g. "id-card-back.jpg".
                    type: string
                mimeType:
                    description: MIME type of the file.
                    enum:
                        - image/jpeg
                        - image/jpg
                        - image/png
                        - application/pdf
                    type: string
            required:
                - documentType
                - fileName
                - fileContent
                - mimeType
            type: object
        KYCDocumentsResponse:
            properties:
                documents:
                    items:
                        $ref: '#/components/schemas/KYCDocumentResponse'
                    type: array
            required:
                - documents
            type: object
        KYCNotesUpdateRequest:
            properties:
                notes:
                    description: Internal admin notes.
                    type: string
            required:
                - notes
            type: object
        KYCStatus:
            enum:
                - not_started
                - started
                - pending
                - completed
                - rejected
                - request_more_info
            type: string
        KYCStatusResponse:
            properties:
                documentsSummary:
                    properties:
                        approved:
                            type: integer
                        pending:
                            type: integer
                        rejected:
                            type: integer
                        total:
                            type: integer
                    type: object
                notes:
                    description: Internal admin notes.
                    type: string
                rejectLabels:
                    description: Comma-separated rejection labels.
                    type: string
                status:
                    $ref: '#/components/schemas/KYCStatus'
                userId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - userId
                - status
            type: object
        KYCStatusUpdateRequest:
            properties:
                rejectLabels:
                    description: Comma-separated rejection labels (for rejected status).
                    type: string
                reviewedBy:
                    description: Admin who performed the review.
                    type: string
                status:
                    $ref: '#/components/schemas/KYCStatus'
            required:
                - status
            type: object
        KYCWebhookPayload:
            properties:
                kycStatus:
                    $ref: '#/components/schemas/KYCStatus'
                previousStatus:
                    $ref: '#/components/schemas/KYCStatus'
                rejectLabels:
                    type: string
                reviewedBy:
                    type: string
                timestamp:
                    format: date-time
                    type: string
                userId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - userId
                - kycStatus
                - previousStatus
                - timestamp
            type: object
        ListStationTopupsResponse:
            properties:
                topups:
                    items:
                        $ref: '#/components/schemas/StationTopup'
                    type: array
                total:
                    type: integer
            required:
                - topups
                - total
            type: object
        ListWalletsResponse:
            properties:
                total:
                    description: Total number of wallets matching the filter
                    format: int64
                    type: integer
                wallets:
                    items:
                        $ref: '#/components/schemas/WalletWithAllocation'
                    type: array
            required:
                - wallets
                - total
            type: object
        NetworkInfo:
            properties:
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                chainId:
                    description: EVM chain ID (null for non-EVM chains like Solana)
                    format: int64
                    type: integer
                explorerUrl:
                    description: Block explorer URL
                    type: string
                isTestnet:
                    description: Whether this is a testnet
                    type: boolean
                networkName:
                    description: Network name (e.g., "sepolia", "base-sepolia", "devnet")
                    type: string
                rpcUrl:
                    description: RPC endpoint URL
                    type: string
                usdcContractAddress:
                    description: USDC token contract address
                    type: string
            required:
                - chain
                - networkName
                - rpcUrl
                - explorerUrl
                - usdcContractAddress
                - isTestnet
            type: object
        NetworksResponse:
            properties:
                networks:
                    items:
                        $ref: '#/components/schemas/NetworkInfo'
                    type: array
            required:
                - networks
            type: object
        OfframpDepositRequest:
            properties:
                accountId:
                    description: Target account ID (user or primary).
                    format: uuid
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                amount:
                    description: Gross settlement amount.
                    format: decimal
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                feePercent:
                    description: Fee fraction in [0, 1). Fee stays on master account.
                    format: decimal
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - accountId
                - amount
                - feePercent
            type: object
        OfframpDepositResponse:
            properties:
                status:
                    description: Result status (ok).
                    type: string
            required:
                - status
            type: object
        PaymentCardPlain:
            additionalProperties: false
            description: Plain card details.
            properties:
                cardNumber:
                    description: Card number (PAN).
                    pattern: ^[0-9]{12,19}$
                    type: string
                cvc:
                    description: Card verification code (CVC/CVV).
                    pattern: ^[0-9]{3,4}$
                    type: string
                expiry:
                    description: Card expiry in MM/YY format.
                    type: string
            required:
                - cardNumber
                - expiry
                - cvc
            type: object
        PaymentNextAction:
            additionalProperties: false
            description: Next action required to continue the flow (e.g., redirect or 3DS).
            properties:
                method:
                    type: string
                params:
                    additionalProperties: true
                    type: object
                type:
                    enum:
                        - redirect
                        - 3ds_method
                        - 3ds_sdk
                    type: string
                url:
                    format: uri
                    type: string
            type: object
        PaymentStatus:
            description: Lifecycle status of the card-based operation.
            enum:
                - pending
                - requires_action
                - completed
                - failed
            type: string
        Payout:
            properties:
                accountId:
                    description: Account the payout debits.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                completedAt:
                    format: date-time
                    type: string
                createdAt:
                    format: date-time
                    type: string
                currency:
                    description: Payout currency; always matches the account currency.
                    type: string
                debitedAmount:
                    description: |
                        Amount actually debited. Absent until the payout completes — absent is not
                        zero.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                destinationDisplay:
                    description: Masked form of the destination, when the provider supplied one.
                    type: string
                feeMode:
                    $ref: '#/components/schemas/PayoutFeeMode'
                id:
                    description: Payca payout identifier.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                method:
                    $ref: '#/components/schemas/PayoutMethod'
                paycaFee:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                providerFee:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                recipientAmount:
                    description: What the recipient receives.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                requestedAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                status:
                    $ref: '#/components/schemas/PayoutStatus'
                totalDebitAmount:
                    description: What leaves the account, and what is reserved until the outcome.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                totalFee:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - id
                - status
                - method
                - accountId
                - currency
                - requestedAmount
                - feeMode
                - paycaFee
                - providerFee
                - totalFee
                - recipientAmount
                - totalDebitAmount
                - createdAt
            type: object
        PayoutCardRequisites:
            additionalProperties: false
            description: Recipient card details used for a payout-only card rail.
            properties:
                cardNumber:
                    description: Recipient card number (PAN).
                    pattern: ^[0-9]{12,19}$
                    type: string
                customerName:
                    description: Customer name required by the payout provider; Latin letters, at least two space-separated words and at least three letters per word.
                    maxLength: 20
                    minLength: 7
                    pattern: '^[A-Za-z]{3,}(?: [A-Za-z]{3,})+$'
                    type: string
                expiryMonth:
                    description: Two-digit expiry month.
                    pattern: ^(0[1-9]|1[0-2])$
                    type: string
                expiryYear:
                    description: Four-digit expiry year.
                    pattern: ^[0-9]{4}$
                    type: string
            required:
                - cardNumber
                - expiryMonth
                - expiryYear
                - customerName
            type: object
        PayoutDestination:
            description: |
                Where the money goes.

                `card_token` uses an opaque token or hosted reference issued for the
                recipient's card. `card` carries the card requisites required by payout-only
                providers. Card requisites are encrypted before the payout order is stored
                and are never returned by the API.
            properties:
                card:
                    $ref: '#/components/schemas/PayoutCardRequisites'
                display:
                    description: |
                        Optional masked form for a token destination, e.g. `**** 4242`. For a
                        `card` destination the server derives this value from the PAN and ignores
                        a caller-supplied display. This is the only destination detail a response
                        returns.
                    type: string
                reference:
                    description: |
                        For `card_token`, the opaque provider reference. For `card`, a stable
                        client-generated reference for this recipient card. Never echoed back in
                        a response.
                    maxLength: 128
                    minLength: 1
                    type: string
                type:
                    description: Opaque provider token or encrypted card requisites.
                    enum:
                        - card_token
                        - card
                    type: string
            required:
                - type
                - reference
            type: object
        PayoutFeeMode:
            description: |
                Who absorbs the fees.

                `deducted` — the amount you send is what leaves the account, and the recipient
                receives it minus the fees.
                `add_on` — the amount you send is what the recipient receives, and the fees are
                debited on top.

                Fixed once the payout is created: it decides both what the recipient gets and
                what is reserved.
            enum:
                - deducted
                - add_on
            type: string
        PayoutFeeTariff:
            description: |
                What a payout on this route costs: a fixed part plus a percentage of the amount
                entered. The percentage applies to the amount you send, in both fee modes.

                Published so a caller can show an estimate; the authoritative figures come from
                the quote endpoint, which applies the rounding the created payout will use.
            properties:
                paycaFeeFixed:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                paycaFeeRate:
                    description: Percent, e.g. "1.5" for 1.5%.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                providerFeeFixed:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                providerFeeRate:
                    description: Percent, e.g. "1.5" for 1.5%.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            type: object
        PayoutListResponse:
            properties:
                payouts:
                    items:
                        $ref: '#/components/schemas/Payout'
                    type: array
                total:
                    description: Total payouts matching the filter, ignoring pagination.
                    format: int64
                    type: integer
            required:
                - payouts
                - total
            type: object
        PayoutMethod:
            description: How the money reaches the recipient.
            enum:
                - bank_card
            type: string
        PayoutOption:
            properties:
                currency:
                    type: string
                fees:
                    $ref: '#/components/schemas/PayoutFeeTariff'
                maxAmount:
                    description: Largest accepted payout. Absent means no upper bound.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                method:
                    $ref: '#/components/schemas/PayoutMethod'
                minAmount:
                    description: Smallest accepted payout. Absent means no lower bound.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - method
                - currency
            type: object
        PayoutOptionsResponse:
            properties:
                options:
                    items:
                        $ref: '#/components/schemas/PayoutOption'
                    type: array
            required:
                - options
            type: object
        PayoutQuote:
            description: |
                The complete price of a payout. Every figure here is what the created payout
                will carry, and `totalDebitAmount` is exactly what gets reserved.
            properties:
                currency:
                    type: string
                feeMode:
                    $ref: '#/components/schemas/PayoutFeeMode'
                paycaFee:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                providerFee:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                recipientAmount:
                    description: What the recipient receives.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                requestedAmount:
                    description: The amount you sent. Its meaning depends on feeMode.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                totalDebitAmount:
                    description: What leaves the account, and what is reserved.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                totalFee:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - requestedAmount
                - feeMode
                - currency
                - paycaFee
                - providerFee
                - totalFee
                - recipientAmount
                - totalDebitAmount
            type: object
        PayoutStatus:
            description: |
                Normalised payout status. Independent of any provider's own vocabulary.
                `completed` means the provider confirmed the payout AND the ledger debit was
                recorded. `submitted` and `processing` mean the money is held and in flight;
                `failed` and `cancelled` mean it was not sent and the hold is returned;
                `manual_review` means the payout needs a human before it goes further.
            enum:
                - created
                - submitted
                - processing
                - completed
                - failed
                - cancelled
                - reversed
                - manual_review
            type: string
        PersonAddress:
            additionalProperties: false
            description: Postal address used for compliance and fraud checks.
            properties:
                city:
                    type: string
                country:
                    $ref: '#/components/schemas/CountryCodeAlpha2'
                flatNumber:
                    type: string
                houseNumber:
                    type: string
                postalCode:
                    type: string
                province:
                    description: State/province code (required for some countries).
                    maxLength: 64
                    minLength: 2
                    type: string
                street:
                    type: string
            required:
                - street
                - city
                - postalCode
                - country
            type: object
        PersonKyc:
            additionalProperties: false
            description: End-user identity information required by payment processors.
            properties:
                address:
                    $ref: '#/components/schemas/PersonAddress'
                birthDate:
                    format: date
                    type: string
                countryOfResidence:
                    $ref: '#/components/schemas/CountryCodeAlpha2'
                email:
                    format: email
                    type: string
                firstName:
                    type: string
                lastName:
                    type: string
                personalId:
                    type: string
                phoneNumber:
                    pattern: ^[0-9]+$
                    type: string
            required:
                - firstName
                - lastName
                - countryOfResidence
                - address
            type: object
        QuotePayoutRequest:
            properties:
                amount:
                    description: |
                        The amount you are sending. In `deducted` mode this is what leaves the
                        account; in `add_on` mode it is what the recipient receives.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                country:
                    description: ISO 3166-1 alpha-2 country of the recipient.
                    maxLength: 2
                    minLength: 2
                    type: string
                feeMode:
                    $ref: '#/components/schemas/PayoutFeeMode'
                method:
                    $ref: '#/components/schemas/PayoutMethod'
            required:
                - method
                - amount
                - feeMode
                - country
            type: object
        SandboxTransactionCreateRequest:
            properties:
                amount:
                    type: string
                    x-go-type: decimal.Decimal
                cardId:
                    format: uuid
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                currency:
                    description: ISO 4217 currency code.
                    type: string
                linkedId:
                    type: string
                type:
                    $ref: '#/components/schemas/SandboxTransactionType'
            required:
                - cardId
                - currency
                - type
                - amount
            type: object
        SandboxTransactionResponse:
            properties:
                amount:
                    type: string
                    x-go-type: decimal.Decimal
                cardId:
                    format: uuid
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                createdAt:
                    format: date-time
                    type: string
                currency:
                    description: ISO 4217 currency code.
                    type: string
                id:
                    format: uuid
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                linkedId:
                    type: string
                transitions:
                    description: Follow-up sandbox requests that keep the transaction flow aligned with production.
                    items:
                        $ref: '#/components/schemas/SandboxTransition'
                    type: array
                type:
                    $ref: '#/components/schemas/SandboxTransactionType'
            required:
                - cardId
                - currency
                - type
                - amount
            type: object
        SandboxTransactionType:
            description: Internal card transaction type accepted by the sandbox.
            enum:
                - authorization
                - settle
                - cancel
                - refund
                - decline
            type: string
            x-enum-varnames:
                - SandboxTransactionTypeAuthorization
                - SandboxTransactionTypeSettle
                - SandboxTransactionTypeAdjustment
                - SandboxTransactionTypeCancel
                - SandboxTransactionTypeRefund
                - SandboxTransactionTypeDecline
        SandboxTransition:
            properties:
                amount:
                    type: string
                    x-go-type: decimal.Decimal
                cardId:
                    format: uuid
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                currency:
                    type: string
                linkedId:
                    type: string
                type:
                    $ref: '#/components/schemas/SandboxTransactionType'
            required:
                - cardId
                - currency
                - type
                - amount
            type: object
        ScanStationTopupsRequest:
            properties:
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
            required:
                - chain
            type: object
        ScanStationTopupsResponse:
            properties:
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                currentBalance:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                detected:
                    type: boolean
                detectedAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                message:
                    type: string
                outflows:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                previousBalance:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                topup:
                    $ref: '#/components/schemas/StationTopup'
            required:
                - chain
                - currentBalance
                - previousBalance
                - outflows
                - detected
            type: object
        SetGasStationWalletRequest:
            properties:
                address:
                    description: Public address of the gas station wallet.
                    type: string
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                privateKey:
                    description: Private key of the gas station wallet (will be encrypted).
                    type: string
            required:
                - chain
                - address
                - privateKey
            type: object
        SettlementBalanceResponse:
            properties:
                availableToAuthorize:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                availableToIssue:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                cashBalance:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                lastUpdated:
                    format: date-time
                    type: string
                pendingSettlement:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - cashBalance
            type: object
        StationTopup:
            properties:
                amount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                createdAt:
                    format: date-time
                    type: string
                fromAddress:
                    type: string
                id:
                    format: uuid
                    type: string
                notes:
                    type: string
                toAddress:
                    type: string
                token:
                    type: string
                txHash:
                    type: string
            required:
                - id
                - chain
                - fromAddress
                - toAddress
                - amount
                - token
                - createdAt
            type: object
        SweepCandidate:
            properties:
                address:
                    type: string
                allocationId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                amount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                walletId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - walletId
                - allocationId
                - address
                - chain
                - amount
            type: object
        SweepCandidatesResponse:
            properties:
                candidates:
                    items:
                        $ref: '#/components/schemas/SweepCandidate'
                    type: array
            required:
                - candidates
            type: object
        SweepExportData:
            properties:
                amount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                fromAddress:
                    type: string
                operationId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                privateKey:
                    description: Decrypted private key for signing.
                    type: string
                toAddress:
                    type: string
                token:
                    type: string
                usdcContract:
                    description: USDC contract address for the chain.
                    type: string
            required:
                - operationId
                - chain
                - fromAddress
                - toAddress
                - amount
                - token
                - privateKey
                - usdcContract
            type: object
        SweepPreflightResult:
            properties:
                canSweep:
                    description: Whether the wallet can be swept immediately.
                    type: boolean
                currentGas:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                gasStationReady:
                    description: Whether gas station is configured and ready.
                    type: boolean
                message:
                    description: Human-readable status message.
                    type: string
                needsGasTopup:
                    description: Whether gas topup is needed before sweep.
                    type: boolean
                requiredGas:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                topupAmount:
                    description: Amount of gas needed (if topup required).
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - canSweep
                - needsGasTopup
                - currentGas
                - requiredGas
                - gasStationReady
            type: object
        UpdateGasBalanceRequest:
            properties:
                balance:
                    description: New gas balance for the wallet.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
            required:
                - balance
            type: object
        UpdateNetworkConfigRequest:
            properties:
                chainId:
                    description: EVM chain ID
                    format: int64
                    type: integer
                explorerUrl:
                    description: Block explorer URL
                    type: string
                networkName:
                    description: Network name (e.g., "mainnet", "sepolia")
                    type: string
                rpcUrl:
                    description: RPC endpoint URL
                    type: string
            type: object
        User:
            properties:
                account:
                    $ref: '#/components/schemas/UserAccountWithBins'
                id:
                    description: User ID.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                meta:
                    description: Arbitrary JSON metadata.
                    type: object
                    x-go-type: json.RawMessage
                status:
                    description: User status.
                    enum:
                        - active
                        - pending
                        - frozen
                        - blocked
                    type: string
            required:
                - id
                - account
                - status
                - meta
            type: object
        UserAccount:
            properties:
                balance:
                    $ref: '#/components/schemas/UserAccountBalance'
                currency:
                    description: ISO 4217 currency code for the user account.
                    type: string
                id:
                    description: Unique identifier for the user account.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                status:
                    description: Status of the user account (e.g., active, suspended).
                    type: string
            required:
                - id
                - currency
                - balance
                - status
            type: object
        UserAccountBalance:
            properties:
                available:
                    description: Amount available for withdrawal or use.
                    type: string
                pending:
                    description: Amount pending settlement.
                    type: string
                spentThisMonth:
                    description: Amount moved into the spend balance over the current calendar month.
                    type: string
            required:
                - available
                - pending
            type: object
        UserAccountWithBins:
            allOf:
                - $ref: '#/components/schemas/UserAccount'
                - properties:
                    bins:
                        items:
                            $ref: '#/components/schemas/Bin'
                        type: array
                  type: object
        UserBinUpsertRequest:
            properties:
                bin:
                    description: BIN code to attach or update on the user's account.
                    type: string
                fees:
                    $ref: '#/components/schemas/BinFees'
            required:
                - bin
            type: object
        UserCreateRequest:
            properties:
                bins:
                    description: Enabled BINs and fees to charge this user.
                    items:
                        $ref: '#/components/schemas/Bin'
                    type: array
                meta:
                    description: |
                        User metadata (JSON). For B2C cardholders this must contain personal data fields
                        (firstName, lastName, email, birthday, gender, idType, idNo, nationality, etc.).
                        See `CreateUserCardholder` endpoint for the full list of required fields.

                        `meta` is stored as given and is **not** validated here — the field
                        rules (charsets, length limits, mobile-only phone, reference codes)
                        are enforced when the cardholder is created, so apply them in your
                        own form validation to avoid a late rejection.
                    type: object
                    x-go-type: json.RawMessage
                status:
                    default: pending
                    description: Initial user status. Defaults to `pending`.
                    enum:
                        - active
                        - pending
                        - frozen
                        - blocked
                    type: string
                userId:
                    description: Optional user ID. If omitted, a new UUID will be generated.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - bins
            type: object
        UserCreateResponse:
            properties:
                userAccountId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                userId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - userId
                - userAccountId
            type: object
        UserStatusUpdateRequest:
            properties:
                status:
                    description: Desired user status.
                    enum:
                        - active
                        - pending
                        - frozen
                        - blocked
                    type: string
            required:
                - status
            type: object
        UserTopUpRequest:
            properties:
                amount:
                    description: Amount to transfer from client account to user account.
                    format: decimal
                    type: string
                    x-go-type: decimal.Decimal
                idempotencyKey:
                    description: Idempotency key, must be unique for each request.
                    type: string
                userAccountId:
                    description: The user's internal account ID.
                    format: uuid
                    type: string
            required:
                - amount
            type: object
        UserTransferRequest:
            properties:
                amount:
                    description: Amount to transfer.
                    format: decimal
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                fromAccountId:
                    description: Source Payca account ID.
                    format: uuid
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                idempotencyKey:
                    description: Optional idempotency key to deduplicate requests.
                    type: string
                toAccountId:
                    description: Destination Payca account ID.
                    format: uuid
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - fromAccountId
                - toAccountId
                - amount
            type: object
        UserTransferResponse:
            properties:
                fromAccountId:
                    description: Source Payca account ID.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                toAccountId:
                    description: Destination Payca account ID.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                txId:
                    description: Ledger transaction ID for the transfer.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - txId
                - fromAccountId
                - toAccountId
            type: object
        UserWithdrawRequest:
            properties:
                amount:
                    description: Amount to transfer from user account to client account.
                    format: decimal
                    type: string
                    x-go-type: decimal.Decimal
                idempotencyKey:
                    description: Idempotency key, must be unique for each request.
                    type: string
                userAccountId:
                    description: The user's internal account ID.
                    format: uuid
                    type: string
            required:
                - amount
            type: object
        UsersResponse:
            properties:
                data:
                    items:
                        $ref: '#/components/schemas/User'
                    type: array
                page:
                    type: integer
                total:
                    type: integer
            required:
                - page
                - total
                - data
            type: object
        WalletAllocateRequest:
            properties:
                accountId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                clientId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                currency:
                    default: USDC
                    type: string
                expectedAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                orderId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                ttlMinutes:
                    default: 30
                    description: Time-to-live in minutes (default 30).
                    type: integer
            required:
                - chain
            type: object
        WalletAllocateResponse:
            properties:
                address:
                    description: Wallet address for deposits.
                    type: string
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                currency:
                    type: string
                expectedAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                expiresAt:
                    description: When the allocation expires.
                    format: date-time
                    type: string
            required:
                - address
                - chain
                - expiresAt
            type: object
        WalletAllocationDetails:
            properties:
                accountId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                allocatedAt:
                    format: date-time
                    type: string
                allocationId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                clientId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                currency:
                    type: string
                depositAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                depositConfirmed:
                    type: boolean
                depositTxHash:
                    type: string
                expectedAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                expiresAt:
                    format: date-time
                    type: string
                orderId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - allocationId
                - expectedAmount
                - currency
                - expiresAt
                - allocatedAt
                - depositAmount
                - depositConfirmed
            type: object
        WalletBalanceResponse:
            properties:
                address:
                    type: string
                allocation:
                    $ref: '#/components/schemas/AllocationInfo'
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                status:
                    $ref: '#/components/schemas/WalletStatus'
            required:
                - address
                - chain
                - status
            type: object
        WalletDepositConfirmRequest:
            properties:
                address:
                    description: Wallet address where deposit was received.
                    type: string
                amount:
                    description: Deposited amount.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                txHash:
                    description: Blockchain transaction hash.
                    type: string
            required:
                - address
                - txHash
                - amount
            type: object
        WalletPoolConfig:
            properties:
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                enabled:
                    type: boolean
                gasMinThreshold:
                    description: Minimum gas balance before refill is needed.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                gasReserve:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                gasStationAddress:
                    description: Address of the gas station wallet for this chain.
                    type: string
                gasTargetAmount:
                    description: Target gas balance to fill up to.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                minPoolSize:
                    type: integer
                minSweepAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                treasuryAddress:
                    type: string
                updatedAt:
                    format: date-time
                    type: string
                usdcContractAddress:
                    type: string
            required:
                - chain
                - minPoolSize
                - treasuryAddress
                - usdcContractAddress
                - minSweepAmount
                - gasReserve
                - enabled
            type: object
        WalletPoolConfigUpdate:
            properties:
                enabled:
                    type: boolean
                gasMinThreshold:
                    description: Minimum gas balance before refill is needed.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                gasReserve:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                gasTargetAmount:
                    description: Target gas balance to fill up to.
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                minPoolSize:
                    type: integer
                minSweepAmount:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                treasuryAddress:
                    type: string
                usdcContractAddress:
                    type: string
            type: object
        WalletPoolStats:
            properties:
                allocated:
                    format: int64
                    type: integer
                available:
                    format: int64
                    type: integer
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                disabled:
                    format: int64
                    type: integer
                needMoreWallets:
                    type: boolean
                sweeping:
                    format: int64
                    type: integer
                totalWallets:
                    format: int64
                    type: integer
            required:
                - chain
                - totalWallets
                - available
                - allocated
                - sweeping
                - disabled
            type: object
        WalletPoolStatsResponse:
            properties:
                stats:
                    items:
                        $ref: '#/components/schemas/WalletPoolStats'
                    type: array
            required:
                - stats
            type: object
        WalletReleaseRequest:
            properties:
                address:
                    description: Wallet address to release.
                    type: string
            required:
                - address
            type: object
        WalletStatus:
            description: Status of a wallet in the pool.
            enum:
                - available
                - allocated
                - sweeping
                - disabled
            type: string
        WalletWithAllocation:
            properties:
                address:
                    type: string
                allocation:
                    $ref: '#/components/schemas/WalletAllocationDetails'
                chain:
                    $ref: '#/components/schemas/BlockchainChain'
                createdAt:
                    format: date-time
                    type: string
                gasBalance:
                    type: string
                    x-go-type: decimal.Decimal
                    x-go-type-import:
                        path: github.com/shopspring/decimal
                status:
                    $ref: '#/components/schemas/WalletStatus'
                updatedAt:
                    format: date-time
                    type: string
                walletId:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            required:
                - walletId
                - chain
                - address
                - status
                - gasBalance
                - createdAt
                - updatedAt
            type: object
        WebhookPayload:
            properties:
                data:
                    description: The details of the event. Structure varies based on the event type.
                    type: object
                event:
                    description: The type of event triggering the webhook.
                    enum:
                        - card_transaction
                        - account_transaction
                        - user_account_transaction
                        - funding_deposit
                        - cardholder_status
                    type: string
            required:
                - event
                - data
            type: object
        WebhookRequest:
            properties:
                type:
                    enum:
                        - account
                        - card
                        - user
                        - kyc
                        - funding
                        - cardholder
                        - deposit
                    type: string
                url:
                    description: The URL to receive webhook events.
                    format: uri
                    type: string
            required:
                - url
                - type
            type: object
        WebhookResendResponse:
            properties:
                account:
                    description: Number of account webhook deliveries queued.
                    format: int32
                    type: integer
                card:
                    description: Number of card webhook deliveries queued.
                    format: int32
                    type: integer
                cardholder:
                    description: Number of cardholder webhook deliveries queued.
                    format: int32
                    type: integer
                deposit:
                    description: |
                        Number of deposit webhook deliveries queued. A deposit resend reflects
                        the order's current status rather than replaying a historical event, so
                        deliveries whose event no longer matches the order are skipped.
                    format: int32
                    type: integer
                kyc:
                    description: Number of KYC webhook deliveries queued.
                    format: int32
                    type: integer
                payout:
                    description: |
                        Number of payout webhook deliveries queued. Same rule as deposits: the
                        resend reflects the payout's current status rather than replaying a
                        historical event, so deliveries whose event no longer matches are skipped.
                    format: int32
                    type: integer
                total:
                    description: Total number of webhook deliveries queued for resend.
                    format: int32
                    type: integer
                user:
                    description: Number of user webhook deliveries queued.
                    format: int32
                    type: integer
            required:
                - total
            type: object
        WebhookResponse:
            properties:
                id:
                    description: Unique identifier for the webhook.
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                type:
                    enum:
                        - account
                        - card
                        - user
                        - kyc
                        - funding
                        - cardholder
                        - deposit
                    type: string
                url:
                    description: The URL to receive webhook events.
                    format: uri
                    type: string
            required:
                - url
                - id
                - type
            type: object
    securitySchemes:
        clientId:
            in: header
            name: x-client-id
            type: apiKey
        clientSecret:
            in: header
            name: x-client-secret
            type: apiKey
info:
    description: |
        Payca beta API provides features for managing accounts, cards, and transactions for enterprise users.
    title: Payca beta API
    version: 1.0.0
openapi: 3.0.3
paths:
    /health:
        get:
            description: |
                Public, unauthenticated liveness probe. Returns 200 with a small JSON
                body while the API process is up. Used by deploy workflows and uptime
                monitors.
            operationId: GetHealth
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                ok:
                                    summary: Healthy
                                    value:
                                        status: ok
                            schema:
                                $ref: '#/components/schemas/HealthResponse'
                    description: Service is healthy.
            security: []
            summary: Health check
            tags:
                - Health
    /sandbox/transactions:
        post:
            description: Create a transaction in the sandbox using an internal card ID and currency.
            operationId: SandboxTransaction
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/SandboxTransactionCreateRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SandboxTransactionResponse'
                    description: Transaction created
            summary: Create sandbox transaction
            tags:
                - Sandbox
    /v1/accounts:
        get:
            description: |
                Fetch a list of primary accounts linked to the authenticated user. Only accounts with kind "primary" are returned;
                fee/debt accounts stay hidden. Includes account balances, statuses, and associated currency codes.
            operationId: GetAccounts
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                sampleAccounts:
                                    summary: A sample accounts response
                                    value:
                                        accounts:
                                            - balance:
                                                available: "1500.00"
                                                pending: "100.00"
                                              currency: USD
                                              id: d290f1ee-6c54-4b01-90e6-d701748f0851
                                              status: active
                            schema:
                                $ref: '#/components/schemas/AccountsResponse'
                    description: Successfully retrieved accounts.
            summary: Retrieve Accounts
            tags:
                - Accounts
    /v1/accounts/{id}/transactions:
        get:
            description: |
                Fetch transaction details for a specific account. Results can be paginated using limit and offset parameters.
            operationId: GetAccountTransactions
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Maximum number of transactions to return. Default is 10.
                  in: query
                  name: limit
                  required: false
                  schema:
                    type: integer
                - description: Offset from where to start returning transactions. Default is 0.
                  in: query
                  name: offset
                  required: false
                  schema:
                    type: integer
                - description: ISO-8601 timestamp. Only transactions created at or after this date are returned.
                  in: query
                  name: from
                  required: false
                  schema:
                    format: date-time
                    type: string
                - description: ISO-8601 timestamp. Only transactions created strictly before this date are returned.
                  in: query
                  name: to
                  required: false
                  schema:
                    format: date-time
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                sampleAccountTransactions:
                                    summary: Sample account transactions
                                    value:
                                        data:
                                            - accountId: d290f1ee-6c54-4b01-90e6-d701748f0851
                                              amount: "500.00"
                                              cardId: a1b2c3d4-5678-90ab-cdef-1234567890ac
                                              currency: USD
                                              id: a1b2c3d4-5678-90ab-cdef-1234567890ab
                                              referenceId: f1234567-89ab-4cde-f012-3456789abcd0
                                              subtype: card_deposit
                                              timestamp: "2025-01-01T12:00:00Z"
                                              type: deposit
                                        page: 1
                                        total: 2
                            schema:
                                $ref: '#/components/schemas/AccountTransactionsResponse'
                    description: Successfully retrieved account transactions.
                "400":
                    content:
                        application/json:
                            examples:
                                invalidAccountId:
                                    summary: Invalid account id error
                                    value:
                                        code: ErrInvalidArg
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Retrieve Account Transactions
            tags:
                - Accounts
    /v1/accounts/offramp-deposit:
        post:
            description: |
                Credits the master/primary account with the gross settlement amount and transfers
                the net amount (after fee) to the target account. Restricted to authorized clients.
            operationId: OfframpDeposit
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/OfframpDepositRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/OfframpDepositResponse'
                    description: Deposit initiated.
            summary: Offramp deposit (master credit + transfer)
            tags:
                - Accounts
    /v1/bins:
        get:
            description: |
                Returns every BIN attached to this client — including the disabled
                and archived ones — with its upstream cardholder model
                (`providerCardHolderModel`) and current `isEnabled` / `isArchived`
                flags.

                Unlike the account/user bin listings (which only surface bins that
                are attached AND enabled), this catalog also carries bins that are
                attached but no longer issuable, so an integrating service can keep
                its own BIN→model map in sync and retire bins decommissioned
                upstream. Bins never assigned to this client are not listed.
            operationId: ListBinCatalog
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BinCatalogResponse'
                    description: The client's BIN catalog.
            summary: List the BIN catalog
            tags:
                - Bins
    /v1/bins/{bin}/capacity:
        get:
            description: |
                Returns how many more cards the given cardholder can be issued
                on the given BIN. A cardholder may hold a fixed number of live
                cards at a time (3 unless the BIN says otherwise), so the caller
                must pin a specific `cardholderId`. Closing a card frees its
                slot, so `remaining` goes back up.

                Issuance is rejected once the cardholder is at its limit —
                register another cardholder to issue more.

                `hasLimit` is `false` when the BIN carries no per-cardholder
                limit; counts are zero and the cardholder should be treated as
                effectively unlimited.
            operationId: GetBinCapacity
            parameters:
                - description: BIN code (e.g. `5449`, `4938`).
                  in: path
                  name: bin
                  required: true
                  schema:
                    type: string
                - description: |
                    Cardholder UUID, as returned when the cardholder was created.
                    It must be registered for this BIN — otherwise the request is
                    rejected.
                  in: query
                  name: cardholderId
                  required: true
                  schema:
                    format: uuid
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BinCapacityResponse'
                    description: Capacity retrieved.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Cardholder belongs to a different BIN's cardTypeId.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: BIN or cardholder not found.
            summary: Get per-cardholder issuance capacity on a BIN
            tags:
                - Bins
    /v1/cardholders:
        get:
            description: |
                List all cardholders belonging to the authenticated client.
            operationId: ListCardholders
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                items:
                                    $ref: '#/components/schemas/CardholderResponse'
                                type: array
                    description: List of cardholders.
            summary: List Client Cardholders
            tags:
                - Cardholders
    /v1/cardholders/{id}:
        get:
            description: |
                Get a specific cardholder by ID.
            operationId: GetCardholder
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CardholderResponse'
                    description: Cardholder details.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Cardholder not found.
            summary: Get Cardholder
            tags:
                - Cardholders
        patch:
            description: |
                Correct the personal data of a cardholder that has not been approved yet
                and — when it is in `submission_failed` — resubmit it in one call.

                Use this when the provider rejected the submission because of the data
                itself (a mistyped ID number, a phone already used by another
                cardholder, a non-ASCII address). The `description` field of the
                cardholder carries the reason.

                Only the fields present in the body are changed; everything else is
                kept. The values are written to the linked user's `meta` — the source
                of truth the submission rebuilds from — so a later
                `POST /v1/users/{id}/cardholder` sees the same corrected data.

                Allowed while the cardholder is in `submission_failed`, `reject`,
                `rejected_by_admin` or `pending_review`. An approved cardholder
                (`pass_audit`) or one under review at the provider cannot be edited.

                For `submission_failed` the submission workflow is started again right
                away (same as `POST /v1/cardholders/{id}/retry`) and the response comes
                back with status `wait_audit`; the provider's decision arrives through
                the usual cardholder webhook. In the other statuses the data is stored
                and the cardholder keeps its status — submit it with
                `POST /v1/cardholders/{id}/submit` once it is reviewed.

                KYC documents are not part of this call: re-upload them with
                `POST /v1/users/{id}/kyc/documents` (the newest non-rejected document
                per slot is used) before resubmitting.
            operationId: UpdateCardholder
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CardholderUpdateRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CardholderResponse'
                    description: Cardholder updated (and resubmitted when it was `submission_failed`).
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid or empty body, or the resulting data fails validation.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Cardholder not found.
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Cardholder is in a status that cannot be edited, or has no linked user.
            summary: Update Cardholder Data
            tags:
                - Cardholders
    /v1/cardholders/{id}/photos:
        post:
            description: |
                Upload passport photo and/or selfie with passport for admin review.
                Photos are stored locally and are not sent to the card provider.
                JPEG or PNG, max 5MB each. At least one photo must be provided.
            operationId: UploadCardholderPhotos
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            properties:
                                passportPhoto:
                                    description: Passport photo (JPEG/PNG, max 5MB).
                                    format: binary
                                    type: string
                                selfiePhoto:
                                    description: Selfie with passport (JPEG/PNG, max 5MB).
                                    format: binary
                                    type: string
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    ok:
                                        type: boolean
                                type: object
                    description: Photos uploaded successfully.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid input (wrong format, too large, no photos provided).
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Cardholder not found.
            summary: Upload Cardholder Photos
            tags:
                - Cardholders
    /v1/cardholders/{id}/retry:
        post:
            description: |
                Retry submitting a cardholder that ended up in `submission_failed`.
                Mirrors the PayCA-admin "retry" action, but callable from the
                client integration once the underlying issue (typically missing
                KYC docs at the time of the original submit) has been fixed.

                Asynchronous: kicks off the submission workflow and returns 202
                immediately. The provider's decision flows back through the
                existing cardholder webhook.
            operationId: RetryCardholder
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "202":
                    content:
                        application/json:
                            schema:
                                properties:
                                    ok:
                                        type: boolean
                                type: object
                    description: Retry workflow started.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Cardholder not found.
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Cardholder is not in a retryable state (must be `submission_failed`).
            summary: Retry Submission of a Failed Cardholder
            tags:
                - Cardholders
    /v1/cardholders/{id}/submit:
        post:
            description: |
                Submit a `pending_review` cardholder to the upstream card
                provider. Equivalent to the PayCA-admin "approve" action, but
                callable from a client integration once the client's own admin
                has signed off on the cardholder review.

                Asynchronous: kicks off the submission workflow and returns 202
                immediately. The provider's decision flows back through the
                existing cardholder webhook (`pass_audit` / `reject` /
                `submission_failed`).
            operationId: SubmitCardholder
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "202":
                    content:
                        application/json:
                            schema:
                                properties:
                                    ok:
                                        type: boolean
                                type: object
                    description: Submission workflow started.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Cardholder not found.
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Cardholder is not in a submittable state (must be `pending_review`).
            summary: Submit Cardholder to Provider
            tags:
                - Cardholders
    /v1/cardholders/cities:
        get:
            description: |
                Get available city codes for cardholder registration (B2C only).
                Use the returned `code` as the `town` field in user meta.
                Pass `region` query param to filter cities by country.
            operationId: ListCardholderCities
            parameters:
                - description: ISO 3166-1 alpha-2 country code to filter cities.
                  in: query
                  name: region
                  required: false
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                items:
                                    $ref: '#/components/schemas/CardholderCity'
                                type: array
                    description: List of city codes.
            summary: List Cardholder Cities
            tags:
                - Cardholders
    /v1/cardholders/files:
        post:
            description: |
                Upload a file directly to the card provider for use in cardholder registration.
                Supported formats: JPG, PNG, PDF. Max size: 2MB.

                **Not needed for B2C cardholders** — KYC documents are automatically uploaded
                from the KYC system when creating a B2C cardholder via `CreateUserCardholder`.
            operationId: UploadCardholderFile
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            properties:
                                file:
                                    description: The file to upload (JPG, PNG, or PDF, max 2MB).
                                    format: binary
                                    type: string
                            required:
                                - file
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CardholderFileUploadResponse'
                    description: File uploaded.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid file.
            summary: Upload Cardholder File
            tags:
                - Cardholders
    /v1/cardholders/occupations:
        get:
            description: |
                Get available occupation codes for B2C cardholder registration.
                Use the returned `code` as the `occupation` field in user meta.
            operationId: ListCardholderOccupations
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                items:
                                    $ref: '#/components/schemas/CardholderOccupation'
                                type: array
                    description: List of occupation codes.
            summary: List Cardholder Occupations
            tags:
                - Cardholders
    /v1/cardholders/regions:
        get:
            description: |
                Get available country/region codes for B2C cardholder registration.
                Use the returned `code` as the `country` and `nationality` fields in user meta.
            operationId: ListCardholderRegions
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                items:
                                    $ref: '#/components/schemas/CardholderRegion'
                                type: array
                    description: List of regions.
            summary: List Cardholder Regions
            tags:
                - Cardholders
    /v1/cards:
        get:
            description: |
                Retrieve a list of all cards associated with the authenticated user, including details such as balance, status, and currency.
            operationId: ListCards
            parameters:
                - description: Maximum number of cards to return. Default is 10.
                  in: query
                  name: limit
                  required: false
                  schema:
                    type: integer
                - description: Offset from where to start returning cards. Default is 0.
                  in: query
                  name: offset
                  required: false
                  schema:
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                listCards:
                                    summary: List of user cards
                                    value:
                                        data:
                                            - accountId: d290f1ee-6c54-4b01-90e6-d701748f0851
                                              balance:
                                                available: "1000.00"
                                                pending: "0.00"
                                                spent: "0.00"
                                              bin: "411111"
                                              currency: USD
                                              externalUserId: user123
                                              id: b1234567-89ab-4cde-f012-3456789abcde
                                              maskedPan: 4111********1111
                                              productCode: TCC
                                              status: active
                                              tokenizationStatus: tokenization_done
                                        page: 1
                                        total: 2
                            schema:
                                $ref: '#/components/schemas/CardsResponse'
                    description: Successfully retrieved the list of cards.
                "400":
                    content:
                        application/json:
                            examples:
                                invalidListCards:
                                    summary: Invalid request error
                                    value:
                                        code: ErrInvalidArg
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: List Cards
            tags:
                - Cards
        post:
            description: |
                Create and issue a new card. Funds are debited from the `accountId` you provide (client or user). For user-funded issuances, fees are charged to the user first and then to the parent client account.
            operationId: IssueCard
            requestBody:
                content:
                    application/json:
                        examples:
                            sampleCardIssue:
                                summary: New card issue request example
                                value:
                                    accountId: d290f1ee-6c54-4b01-90e6-d701748f0851
                                    balance: "1000.00"
                                    bin: "411111"
                                    externalUserId: user123
                        schema:
                            $ref: '#/components/schemas/CardIssueRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                replayedIssuedCard:
                                    summary: Previously issued card returned from idempotency replay
                                    value:
                                        accountId: d290f1ee-6c54-4b01-90e6-d701748f0851
                                        balance:
                                            available: "1000.00"
                                            pending: "0.00"
                                            spent: "0.00"
                                        bin: "411111"
                                        currency: USD
                                        externalUserId: user123
                                        id: b1234567-89ab-4cde-f012-3456789abcde
                                        maskedPan: 4111********1111
                                        productCode: TCC
                                        status: active
                                        tokenizationStatus: tokenization_pending
                            schema:
                                $ref: '#/components/schemas/Card'
                    description: Existing successful card issue result returned for an idempotent replay of the same request.
                    headers:
                        Idempotent-Replayed:
                            description: Present and set to `true` when the response replays the first successful result for the same `idempotencyKey`.
                            schema:
                                enum:
                                    - "true"
                                type: string
                "201":
                    content:
                        application/json:
                            examples:
                                issuedCard:
                                    summary: Newly issued card example
                                    value:
                                        accountId: d290f1ee-6c54-4b01-90e6-d701748f0851
                                        balance:
                                            available: "1000.00"
                                            pending: "0.00"
                                            spent: "0.00"
                                        bin: "411111"
                                        currency: USD
                                        externalUserId: user123
                                        id: b1234567-89ab-4cde-f012-3456789abcde
                                        maskedPan: 4111********1111
                                        productCode: TCC
                                        status: active
                                        tokenizationStatus: tokenization_pending
                            schema:
                                $ref: '#/components/schemas/Card'
                    description: Successfully issued a new card.
                "409":
                    content:
                        application/json:
                            examples:
                                idempotencyConflict:
                                    summary: Idempotency key conflict
                                    value:
                                        code: idempotency_conflict
                                        details: 'ErrFailedPrecondition: idempotency key reused with a different request'
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: The provided `idempotencyKey` conflicts with an in-flight request or was reused with a different payload.
            summary: Issue a New Card
            tags:
                - Cards
    /v1/cards/{id}:
        delete:
            description: |
                Permanently close a card using its unique identifier. Only cards with no active transactions can be closed.
            operationId: CloseCard
            parameters:
                - description: Unique identifier of the card to close.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                closeCardResponse:
                                    summary: Close card transaction response
                                    value:
                                        cardId: b1234567-89ab-4cde-f012-3456789abcde
                                        txId: e1234567-89ab-4cde-f012-3456789abcd3
                            schema:
                                $ref: '#/components/schemas/CardTxResponse'
                    description: Successfully closed the card. Close transaction returned.
                "400":
                    content:
                        application/json:
                            examples:
                                closeCardError:
                                    summary: Error closing card
                                    value:
                                        code: ErrInvalidArg
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Close Card
            tags:
                - Cards
        get:
            description: |
                Retrieve detailed information about a specific card using its unique identifier.
            operationId: GetCardByID
            parameters:
                - description: Unique identifier of the card.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                cardDetail:
                                    summary: Card detail example
                                    value:
                                        accountId: d290f1ee-6c54-4b01-90e6-d701748f0851
                                        balance:
                                            available: "1000.00"
                                            pending: "0.00"
                                            spent: "0.00"
                                        bin: "411111"
                                        currency: USD
                                        externalUserId: user123
                                        id: b1234567-89ab-4cde-f012-3456789abcde
                                        maskedPan: 4111********1111
                                        productCode: TCC
                                        status: active
                                        tokenizationStatus: tokenization_done
                            schema:
                                $ref: '#/components/schemas/Card'
                    description: Successfully retrieved card details.
            summary: Retrieve Card by ID
            tags:
                - Cards
    /v1/cards/{id}/freeze:
        post:
            description: |
                Temporarily freeze a card to prevent any transactions. The card can be unfrozen later.
            operationId: FreezeCard
            parameters:
                - description: Unique identifier of the card to freeze.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                freezeCard:
                                    summary: Frozen card example
                                    value:
                                        accountId: d290f1ee-6c54-4b01-90e6-d701748f0851
                                        balance:
                                            available: "1000.00"
                                            pending: "0.00"
                                            spent: "0.00"
                                        bin: "411111"
                                        currency: USD
                                        externalUserId: user123
                                        id: b1234567-89ab-4cde-f012-3456789abcde
                                        maskedPan: 4111********1111
                                        productCode: TCC
                                        status: frozen
                                        tokenizationStatus: tokenization_done
                            schema:
                                $ref: '#/components/schemas/Card'
                    description: Card successfully frozen.
                "400":
                    content:
                        application/json:
                            examples:
                                freezeError:
                                    summary: Error freezing card
                                    value:
                                        code: ErrInvalidArg
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Freeze Card
            tags:
                - Cards
    /v1/cards/{id}/sensitive:
        get:
            description: |
                Retrieve sensitive card information such as card number, CVC2 and expiration.
            operationId: GetCardSensitive
            parameters:
                - description: Unique identifier of the card.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                cardSensitiveInfo:
                                    summary: Card sensitive details example
                                    value:
                                        cvc2: "123"
                                        expiration: 12/27
                                        number: "4111111111111111"
                            schema:
                                $ref: '#/components/schemas/CardSensitive'
                    description: Successfully retrieved card sensitive information.
                "400":
                    content:
                        application/json:
                            examples:
                                sensitiveError:
                                    summary: Error retrieving sensitive info
                                    value:
                                        code: ErrInvalidArg
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Get card sensitive info
            tags:
                - Cards
    /v1/cards/{id}/tokenize:
        post:
            description: |
                Initiates the tokenization process for a card (e.g., for adding to Google Pay or Apple Pay).
                Returns the BIP phone number the cardholder should use as their OTP destination during
                the wallet provisioning flow. When the OTP SMS arrives on that number, the platform
                automatically delivers a `tokenization_code` webhook to the client.
            operationId: StartCardTokenization
            parameters:
                - description: Unique identifier of the card to tokenize.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CardTokenizationStarted'
                    description: Tokenization started. Contains the OTP phone the cardholder should use.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request or card not eligible for tokenization.
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: No OTP phone channels available. Try again later.
            summary: Start Card Tokenization
            tags:
                - Cards
    /v1/cards/{id}/topup:
        post:
            description: |
                Add funds to a specific card by its unique identifier.
            operationId: TopUpCard
            parameters:
                - description: Unique identifier of the card.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        examples:
                            topupRequest:
                                summary: Top up card request example
                                value:
                                    accountID: d290f1ee-6c54-4b01-90e6-d701748f0851
                                    amount: "250.00"
                                    idempotencyKey: unique-key-123
                        schema:
                            $ref: '#/components/schemas/CardTopUpRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                topupResponse:
                                    summary: Top up transaction response
                                    value:
                                        cardId: b1234567-89ab-4cde-f012-3456789abcde
                                        txId: c1234567-89ab-4cde-f012-3456789abcd1
                            schema:
                                $ref: '#/components/schemas/CardTxResponse'
                    description: Successfully topped up the card.
                "400":
                    content:
                        application/json:
                            examples:
                                topupError:
                                    summary: Top up error response
                                    value:
                                        code: ErrInvalidArg
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Top Up Card
            tags:
                - Cards
    /v1/cards/{id}/transactions:
        get:
            description: |
                Fetch transaction details for a specific card. Results can be paginated using limit and offset parameters.
            operationId: GetCardTransactions
            parameters:
                - description: Unique identifier of the card.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Maximum number of transactions to return. Default is 10.
                  in: query
                  name: limit
                  required: false
                  schema:
                    type: integer
                - description: Offset from where to start returning transactions. Default is 0.
                  in: query
                  name: offset
                  required: false
                  schema:
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                listCardTransactions:
                                    summary: List of card transactions
                                    value:
                                        data:
                                            - billingAmount: "250.00"
                                              billingCurrency: USD
                                              cardId: b1234567-89ab-4cde-f012-3456789abcde
                                              exchangeRate: "1.00"
                                              id: f1234567-89ab-4cde-f012-3456789abcd4
                                              merchantCode: "1234"
                                              merchantName: Acme Store
                                              meta: {}
                                              referenceId: g1234567-89ab-4cde-f012-3456789abcd5
                                              timestamp: "2025-01-02T12:00:00Z"
                                              transactionAmount: "250.00"
                                              transactionCurrency: USD
                                              type: topup
                                        page: 1
                                        total: 1
                            schema:
                                $ref: '#/components/schemas/CardTransactionsResponse'
                    description: Successfully retrieved card transactions.
            summary: Retrieve Card Transactions
            tags:
                - Cards
    /v1/cards/{id}/unfreeze:
        post:
            description: |
                Reactivate a previously frozen card to allow transactions again.
            operationId: UnfreezeCard
            parameters:
                - description: Unique identifier of the card to unfreeze.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                unfreezeCard:
                                    summary: Unfrozen card example
                                    value:
                                        accountId: d290f1ee-6c54-4b01-90e6-d701748f0851
                                        balance:
                                            available: "1000.00"
                                            pending: "0.00"
                                            spent: "0.00"
                                        bin: "411111"
                                        currency: USD
                                        externalUserId: user123
                                        id: b1234567-89ab-4cde-f012-3456789abcde
                                        maskedPan: 4111********1111
                                        productCode: TCC
                                        status: active
                                        tokenizationStatus: tokenization_done
                            schema:
                                $ref: '#/components/schemas/Card'
                    description: Card successfully unfrozen.
                "400":
                    content:
                        application/json:
                            examples:
                                unfreezeError:
                                    summary: Error unfreezing card
                                    value:
                                        code: ErrInvalidArg
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Unfreeze Card
            tags:
                - Cards
    /v1/cards/{id}/withdraw:
        post:
            description: |
                Withdraw funds from a specific card by its unique identifier.
            operationId: WithdrawFromCard
            parameters:
                - description: Unique identifier of the card.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        examples:
                            withdrawRequest:
                                summary: Withdraw from card request example
                                value:
                                    accountID: d290f1ee-6c54-4b01-90e6-d701748f0851
                                    amount: "100.00"
                                    idempotencyKey: unique-withdraw-123
                        schema:
                            $ref: '#/components/schemas/CardWithdrawRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                withdrawResponse:
                                    summary: Withdrawal transaction response
                                    value:
                                        cardId: b1234567-89ab-4cde-f012-3456789abcde
                                        txId: d1234567-89ab-4cde-f012-3456789abcd2
                            schema:
                                $ref: '#/components/schemas/CardTxResponse'
                    description: Successfully withdrew funds from the card.
                "400":
                    content:
                        application/json:
                            examples:
                                withdrawError:
                                    summary: Withdrawal error response
                                    value:
                                        code: ErrInvalidArg
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Withdraw from Card
            tags:
                - Cards
    /v1/cards/transactions/{id}:
        get:
            description: |
                Fetch transaction details.
            operationId: GetCardTransaction
            parameters:
                - description: Unique identifier of the transaction.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                cardTransactionDetail:
                                    summary: Card transaction detail example
                                    value:
                                        billingAmount: "250.00"
                                        billingCurrency: USD
                                        cardId: b1234567-89ab-4cde-f012-3456789abcde
                                        exchangeRate: "1.00"
                                        id: f1234567-89ab-4cde-f012-3456789abcd4
                                        merchantCode: "1234"
                                        merchantName: Acme Store
                                        meta: {}
                                        referenceId: g1234567-89ab-4cde-f012-3456789abcd5
                                        timestamp: "2025-01-02T12:00:00Z"
                                        transactionAmount: "250.00"
                                        transactionCurrency: USD
                                        type: topup
                            schema:
                                $ref: '#/components/schemas/CardTransaction'
                    description: Successfully retrieved card transaction.
            summary: Retrieve Transaction
            tags:
                - Transactions
    /v1/exchange/orders:
        post:
            description: |
                Creates a market sell order and waits for completion. The server polls
                the exchange internally and returns the final result once the order is
                filled (or returns an error on timeout/failure).
            operationId: CreateExchangeOrder
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ExchangeOrderRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExchangeOrderResponse'
                    description: Order completed.
                "408":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Timeout waiting for order completion.
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Exchange rejected the order.
            summary: Create exchange order
            tags:
                - Exchange
    /v1/exchange/orders/{orderId}:
        get:
            description: Returns the current status of an exchange order.
            operationId: GetExchangeOrder
            parameters:
                - in: path
                  name: orderId
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExchangeOrderResponse'
                    description: Order status retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Order not found.
            summary: Get exchange order status
            tags:
                - Exchange
    /v1/exchange/rates:
        get:
            description: Returns current USDC exchange rates for specified fiat currencies.
            operationId: GetExchangeRates
            parameters:
                - description: Comma-separated trading pairs (default "USDCUSD,USDCEUR").
                  in: query
                  name: pairs
                  required: false
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExchangeRatesResponse'
                    description: Exchange rates retrieved.
            summary: Get exchange rates
            tags:
                - Exchange
    /v1/exchange/settlement/balance:
        get:
            description: Returns the current settlement provider cash balance.
            operationId: GetSettlementBalance
            parameters:
                - description: Settlement currency (e.g. USD, EUR). Defaults to USD.
                  in: query
                  name: currency
                  required: false
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SettlementBalanceResponse'
                    description: Balance retrieved.
            summary: Get settlement balance
            tags:
                - Exchange
    /v1/exchange/settlement/check-increase:
        post:
            description: |
                Checks if the settlement balance has increased by at least the expected
                amount compared to a previous snapshot (99% threshold for fees/rounding).
            operationId: CheckSettlementBalanceIncrease
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CheckBalanceIncreaseRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CheckBalanceIncreaseResponse'
                    description: Balance check result.
            summary: Check settlement balance increase
            tags:
                - Exchange
    /v1/exchange/withdrawal-destinations:
        get:
            description: |
                Returns the withdrawal keys a caller may name on POST /v1/exchange/withdrawals,
                read from the exchange account itself: they are registered and whitelisted
                there by a human. Exchange.Kraken.WithdrawKeys, when configured, narrows
                the list further.
            operationId: ListExchangeWithdrawalDestinations
            parameters:
                - description: Fiat currency code (e.g. USD, EUR). Defaults to USD.
                  in: query
                  name: currency
                  required: false
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExchangeWithdrawalDestinationsResponse'
                    description: Destinations retrieved.
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Destinations could not be read from the exchange.
            summary: List allowed withdrawal destinations
            tags:
                - Exchange
    /v1/exchange/withdrawals:
        post:
            description: |
                Initiates a fiat withdrawal from the exchange to the settlement provider.
                The withdrawal destination key is configured server-side.
            operationId: CreateExchangeWithdrawal
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ExchangeWithdrawalRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExchangeWithdrawalResponse'
                    description: Withdrawal initiated.
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Withdrawal rejected.
            summary: Create fiat withdrawal
            tags:
                - Exchange
    /v1/exchange/withdrawals/{withdrawalId}:
        get:
            description: Returns status and fee details for a withdrawal.
            operationId: GetExchangeWithdrawal
            parameters:
                - in: path
                  name: withdrawalId
                  required: true
                  schema:
                    type: string
                - description: Fiat currency code (e.g. USD, EUR). Defaults to USD.
                  in: query
                  name: currency
                  required: false
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExchangeWithdrawalStatusResponse'
                    description: Withdrawal status retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Withdrawal not found.
            summary: Get withdrawal status
            tags:
                - Exchange
    /v1/gas-station/config/{chain}:
        get:
            operationId: GetWalletPoolConfig
            parameters:
                - in: path
                  name: chain
                  required: true
                  schema:
                    enum:
                        - ETH
                        - BASE
                        - SOL
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WalletPoolConfig'
                    description: Configuration retrieved.
            summary: Get chain configuration
            tags:
                - GasStation
        put:
            operationId: UpdateWalletPoolConfig
            parameters:
                - in: path
                  name: chain
                  required: true
                  schema:
                    enum:
                        - ETH
                        - BASE
                        - SOL
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/WalletPoolConfigUpdate'
                required: true
            responses:
                "200":
                    description: Configuration updated.
            summary: Update chain configuration
            tags:
                - GasStation
    /v1/gas-station/generate:
        post:
            description: Generate new wallets and add them to the pool.
            operationId: GenerateWallets
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/GenerateWalletsRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GenerateWalletsResponse'
                    description: Wallets generated.
            summary: Generate new wallets
            tags:
                - GasStation
    /v1/gas-station/operations:
        get:
            description: Returns all pending gas station operations.
            operationId: ListPendingOperations
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GasStationOperationsResponse'
                    description: Pending operations retrieved.
            summary: List pending operations
            tags:
                - GasStation
        post:
            description: |
                Creates a sweep operation record for manual execution.
                The actual blockchain transaction is executed externally.
                If autoTopup is true and wallet has insufficient gas, a gas topup operation is created first.
            operationId: CreateSweepOperation
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateSweepOperationRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CreateSweepOperationResponse'
                    description: Sweep operation created.
            summary: Create a sweep operation
            tags:
                - GasStation
    /v1/gas-station/operations/{id}:
        get:
            description: Get details of a specific gas station operation.
            operationId: GetGasStationOperation
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GasStationOperation'
                    description: Operation details retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Operation not found.
            summary: Get operation details
            tags:
                - GasStation
    /v1/gas-station/operations/{id}/confirm:
        post:
            description: |
                Confirms a sweep operation after the transaction has been executed.
                Called after manually executing the blockchain transaction.
            operationId: ConfirmSweepOperation
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ConfirmSweepRequest'
                required: true
            responses:
                "200":
                    description: Operation confirmed.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Operation not found.
            summary: Confirm sweep operation
            tags:
                - GasStation
    /v1/gas-station/operations/{id}/export:
        get:
            description: |
                Returns all data needed to manually execute a sweep transaction,
                including the decrypted private key. Use with extreme caution.
            operationId: ExportSweepData
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SweepExportData'
                    description: Export data retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Operation not found.
            summary: Export sweep data for manual execution
            tags:
                - GasStation
    /v1/gas-station/operations/{id}/fail:
        post:
            description: Marks a sweep operation as failed.
            operationId: FailSweepOperation
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/FailSweepRequest'
                required: true
            responses:
                "200":
                    description: Operation marked as failed.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Operation not found.
            summary: Mark operation as failed
            tags:
                - GasStation
    /v1/gas-station/operations/history:
        get:
            description: Returns all gas station operations with optional filtering by chain, type, and status.
            operationId: ListGasStationOperationsHistory
            parameters:
                - description: Filter by blockchain chain.
                  in: query
                  name: chain
                  required: false
                  schema:
                    enum:
                        - ETH
                        - BASE
                        - SOL
                    type: string
                - description: Filter by operation type.
                  in: query
                  name: type
                  required: false
                  schema:
                    enum:
                        - sweep
                        - gas_topup
                    type: string
                - description: Filter by operation status.
                  in: query
                  name: status
                  required: false
                  schema:
                    enum:
                        - pending
                        - submitted
                        - confirmed
                        - failed
                    type: string
                - description: Maximum number of operations to return.
                  in: query
                  name: limit
                  required: false
                  schema:
                    default: 50
                    maximum: 100
                    type: integer
                - description: Number of operations to skip.
                  in: query
                  name: offset
                  required: false
                  schema:
                    default: 0
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GasStationOperationsHistoryResponse'
                    description: Operations history retrieved.
            summary: List all operations
            tags:
                - GasStation
    /v1/gas-station/station-topups:
        get:
            description: List records of external topups to gas station wallets.
            operationId: ListStationTopups
            parameters:
                - in: query
                  name: chain
                  schema:
                    type: string
                - in: query
                  name: limit
                  schema:
                    type: integer
                - in: query
                  name: offset
                  schema:
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListStationTopupsResponse'
                    description: List of station topup records.
            summary: List station topup records
            tags:
                - GasStation
    /v1/gas-station/station-topups/scan:
        post:
            description: |
                Scan the gas station wallet on-chain balance to detect external topups.
                Compares current balance with last known balance, accounting for outflows
                (gas topup operations). Records any detected inflow as a station topup.
                On first scan, establishes the baseline balance without detecting topups.
            operationId: ScanStationTopups
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ScanStationTopupsRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ScanStationTopupsResponse'
                    description: Scan result.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request or gas station not configured.
            summary: Scan for station topups
            tags:
                - GasStation
    /v1/gas-station/status/{chain}:
        get:
            description: Returns comprehensive status of the gas station for a chain including wallets needing gas, pending operations, etc.
            operationId: GetGasStationStatus
            parameters:
                - in: path
                  name: chain
                  required: true
                  schema:
                    enum:
                        - ETH
                        - BASE
                        - SOL
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GasStationStatus'
                    description: Gas station status retrieved.
            summary: Get gas station status
            tags:
                - GasStation
    /v1/gas-station/sweep-candidates:
        get:
            description: Returns all wallets with confirmed deposits that can be swept to treasury.
            operationId: ListSweepCandidates
            parameters:
                - description: Blockchain chain (ETH, BASE, SOL).
                  in: query
                  name: chain
                  required: true
                  schema:
                    enum:
                        - ETH
                        - BASE
                        - SOL
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SweepCandidatesResponse'
                    description: Sweep candidates retrieved.
            summary: List wallets eligible for sweeping
            tags:
                - GasStation
    /v1/gas-station/sweep-preflight/{walletId}:
        get:
            description: Checks if a wallet is ready for sweep or needs gas topup first.
            operationId: PreflightSweep
            parameters:
                - in: path
                  name: walletId
                  required: true
                  schema:
                    format: uuid
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SweepPreflightResult'
                    description: Preflight check completed.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Wallet not found.
            summary: Preflight check for sweep
            tags:
                - GasStation
    /v1/gas-station/topup-candidates:
        get:
            description: Returns wallets that have confirmed deposits but low gas balance.
            operationId: ListGasTopupCandidates
            parameters:
                - in: query
                  name: chain
                  required: true
                  schema:
                    enum:
                        - ETH
                        - BASE
                        - SOL
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GasTopupCandidatesResponse'
                    description: Gas topup candidates retrieved.
            summary: List wallets needing gas refill
            tags:
                - GasStation
    /v1/gas-station/topup-operations:
        post:
            description: Create a new gas topup operation to send gas from the gas station wallet to a pool wallet.
            operationId: CreateGasTopupOperation
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateGasTopupRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GasStationOperation'
                    description: Gas topup operation created.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
                "412":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Gas station wallet not configured or wallet already has sufficient gas.
            summary: Create gas topup operation
            tags:
                - GasStation
    /v1/gas-station/topup-operations/{id}/confirm:
        post:
            description: Confirms the gas topup was executed and updates the wallet's gas balance.
            operationId: ConfirmGasTopupOperation
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    format: uuid
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ConfirmGasTopupRequest'
                required: true
            responses:
                "200":
                    description: Gas topup confirmed.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Operation not found.
            summary: Confirm gas topup operation
            tags:
                - GasStation
    /v1/gas-station/topup-operations/{id}/export:
        get:
            description: Returns the gas station private key and transaction details for manual execution.
            operationId: ExportGasTopupData
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    format: uuid
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GasTopupExportData'
                    description: Export data retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Operation not found.
            summary: Export gas topup data for manual execution
            tags:
                - GasStation
    /v1/gas-station/topup-operations/{id}/fail:
        post:
            description: Marks a gas topup operation as failed.
            operationId: FailGasTopupOperation
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    format: uuid
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/FailSweepRequest'
                required: true
            responses:
                "200":
                    description: Operation marked as failed.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Operation not found.
            summary: Fail gas topup operation
            tags:
                - GasStation
    /v1/gas-station/wallet:
        put:
            description: Configure the gas station wallet for a blockchain chain. The private key will be encrypted.
            operationId: SetGasStationWallet
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/SetGasStationWalletRequest'
                required: true
            responses:
                "200":
                    description: Gas station wallet configured.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Chain configuration not found.
            summary: Set gas station wallet
            tags:
                - GasStation
    /v1/gas-station/wallet/generate:
        post:
            description: Generate a new wallet and configure it as the gas station for a blockchain chain. The wallet will be created with a new keypair and the private key will be encrypted and stored securely.
            operationId: GenerateGasStationWallet
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/GenerateGasStationWalletRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GenerateGasStationWalletResponse'
                    description: Gas station wallet generated and configured.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Chain configuration not found.
            summary: Generate gas station wallet
            tags:
                - GasStation
    /v1/gas-station/wallets:
        get:
            description: Returns a paginated list of all wallets in the pool with optional filtering by chain and status.
            operationId: ListGasStationWallets
            parameters:
                - description: Filter by blockchain chain (ETH, BASE, SOL).
                  in: query
                  name: chain
                  required: false
                  schema:
                    enum:
                        - ETH
                        - BASE
                        - SOL
                    type: string
                - description: Filter by wallet status.
                  in: query
                  name: status
                  required: false
                  schema:
                    enum:
                        - available
                        - allocated
                        - sweeping
                        - disabled
                    type: string
                - description: Maximum number of wallets to return (default 50, max 100).
                  in: query
                  name: limit
                  required: false
                  schema:
                    default: 50
                    maximum: 100
                    type: integer
                - description: Number of wallets to skip for pagination.
                  in: query
                  name: offset
                  required: false
                  schema:
                    default: 0
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListWalletsResponse'
                    description: Wallets list retrieved.
            summary: List all wallets in the pool
            tags:
                - GasStation
    /v1/networks:
        get:
            description: Returns network information for all configured blockchain chains.
            operationId: ListNetworks
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/NetworksResponse'
                    description: Network configurations retrieved.
            summary: List all network configurations
            tags:
                - Networks
    /v1/networks/{chain}:
        get:
            operationId: GetNetworkInfo
            parameters:
                - in: path
                  name: chain
                  required: true
                  schema:
                    enum:
                        - ETH
                        - BASE
                        - SOL
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/NetworkInfo'
                    description: Network configuration retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Chain not found.
            summary: Get network configuration for a chain
            tags:
                - Networks
        put:
            operationId: UpdateNetworkConfig
            parameters:
                - in: path
                  name: chain
                  required: true
                  schema:
                    enum:
                        - ETH
                        - BASE
                        - SOL
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UpdateNetworkConfigRequest'
                required: true
            responses:
                "200":
                    description: Network configuration updated.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Chain not found.
            summary: Update network configuration
            tags:
                - Networks
    /v1/users:
        get:
            description: Retrieve a paginated list of users created by the client.
            operationId: ListUsers
            parameters:
                - description: Maximum number of users to return. Default is 10.
                  in: query
                  name: limit
                  schema:
                    type: integer
                - description: Offset for pagination. Default is 0.
                  in: query
                  name: offset
                  schema:
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                usersPage:
                                    value:
                                        data:
                                            - account:
                                                balance:
                                                    available: "0.00"
                                                    pending: "0.00"
                                                bins: []
                                                currency: USD
                                                id: b8b5e4e1-6afd-4b27-9b26-2bd5b30d6a77
                                                status: active
                                              id: 7f1e2b8e-5d0e-4c5a-9a3c-1a2b3c4d5e6f
                                              meta: {}
                                              status: active
                                        page: 1
                                        total: 2
                            schema:
                                $ref: '#/components/schemas/UsersResponse'
                    description: Successfully retrieved users.
            summary: List Users
            tags:
                - Users
        post:
            description: |
                Create a new end-user under the authenticated client.
                - If `userId` is provided, it will be used; otherwise a new UUID will be generated.
                - `bins` config defines which BINs are enabled for this user and what fees the client wants to charge.
                - `status` is optional and defaults to `pending` if omitted.
                - Optional `meta` allows storing arbitrary JSON.
            operationId: CreateUser
            requestBody:
                content:
                    application/json:
                        examples:
                            createUser:
                                summary: Basic user creation
                                value:
                                    bins:
                                        - bin: "411111"
                                          currencyCode: USD
                                          fees:
                                            authorization:
                                                - range: 0-100
                                                  value: "0.50"
                                            decline:
                                                - range: 0-100
                                                  value: "0.25"
                                            issueFee: "5.00"
                                            minCardBalance: "100.00"
                                            monthlyFee: "2.00"
                                          isTokenizable: true
                                          provider: visa
                                          settings:
                                            minCardBalance: "100.00"
                                    meta:
                                        segment: pro
                                    status: pending
                                    userId: c0ffee00-feed-face-cafe-babecafecafe
                        schema:
                            $ref: '#/components/schemas/UserCreateRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            examples:
                                createdUser:
                                    value:
                                        userAccountId: b8b5e4e1-6afd-4b27-9b26-2bd5b30d6a77
                                        userId: 7f1e2b8e-5d0e-4c5a-9a3c-1a2b3c4d5e6f
                            schema:
                                $ref: '#/components/schemas/UserCreateResponse'
                    description: User successfully created.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Create User
            tags:
                - Users
    /v1/users/{id}:
        get:
            operationId: GetUserById
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/User'
                    description: Successfully retrieved user.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Not found.
            summary: Get User by ID
            tags:
                - Users
    /v1/users/{id}/account/transactions:
        get:
            description: |
                Retrieve transactions for the user's internal account. Results can be paginated using limit and offset.
            operationId: GetUserAccountTransactions
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Maximum number of transactions to return. Default is 10.
                  in: query
                  name: limit
                  schema:
                    type: integer
                - description: Offset from where to start returning transactions. Default is 0.
                  in: query
                  name: offset
                  schema:
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AccountTransactionsResponse'
                    description: Successfully retrieved account transactions.
            summary: List User Account Transactions
            tags:
                - Users
    /v1/users/{id}/bins:
        post:
            description: Add or update a BIN configuration for the user's account.
            operationId: UpsertUserBin
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        examples:
                            upsert:
                                value:
                                    bin: "411111"
                                    fees:
                                        authorization: []
                                        decline: []
                                        issueFee: "1.00"
                                        minCardBalance: "1"
                                        monthlyFee: "0.00"
                        schema:
                            $ref: '#/components/schemas/UserBinUpsertRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BinsResponse'
                    description: Updated list of account BINs.
            summary: Upsert User BIN
            tags:
                - Users
    /v1/users/{id}/card/transactions:
        get:
            description: |
                Retrieve all card transactions associated with the user's cards. Results can be paginated using limit and offset.
            operationId: GetUserCardTransactions
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Maximum number of transactions to return. Default is 10.
                  in: query
                  name: limit
                  schema:
                    type: integer
                - description: Offset from where to start returning transactions. Default is 0.
                  in: query
                  name: offset
                  schema:
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CardTransactionsResponse'
                    description: Successfully retrieved user card transactions.
            summary: List User Card Transactions
            tags:
                - Users
    /v1/users/{id}/cardholder:
        get:
            description: Get the cardholder status for the given user.
            operationId: GetUserCardholder
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CardholderResponse'
                    description: Cardholder details.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: No cardholder found.
            summary: Get User Cardholder
            tags:
                - Users
        post:
            description: |
                Create a cardholder for the given user.
                Personal data is read from the user's `meta` field (see required fields below).

                What the endpoint does depends on the BIN's `providerCardHolderModel`:

                - **B2B** — short form. Only `firstName`, `lastName` and `email` are
                  required in the user's `meta`; no identity data is collected or sent
                  anywhere. The response already carries `status: "pass_audit"`, so the
                  cardholder can be used to issue a card immediately — there is no review
                  step to poll for. Calling it again for the same user and BIN returns the
                  existing cardholder.
                - **B2C** — full identity check. Every field below is required, the user's
                  KYC must be `completed`, and the cardholder goes through async review
                  (`pending_review` → `wait_audit` → `pass_audit` / `reject`).

                **Required user `meta` fields for a B2C cardholder:**

                | Field | Type | Constraints |
                |-------|------|-------------|
                | `firstName` | string | Latin letters, space, hyphen, apostrophe and period only; must start with a letter; max 40 chars. `TEST`, `MOCK` and `SANDBOX` are rejected as substrings — a real legal name is required, also in sandbox. |
                | `lastName` | string | Same rules as `firstName`. |
                | `email` | string | **Max 50 chars.** 3DS OTP codes are sent here. A placeholder built from a full UUID (e.g. `no-reply+<uuid>@example.com`, 56 chars) does not fit — use a shortened alias. |
                | `phone` | string | Digits only, 7–15 digits, **without** the country code. Must be a **mobile** number for `country` — a landline is rejected (e.g. an Argentine number missing its `9` mobile token). |
                | `phoneCode` | string | `+` followed by 1–4 digits, e.g. `"+371"`. A missing `+` is added automatically. |
                | `birthday` | string | Date of birth, `YYYY-MM-DD`. |
                | `country` | string | Country code from `/v1/cardholders/regions`; validated against the live list. |
                | `town` | string | City code from `/v1/cardholders/cities?region=<country>`; validated against the live list. A free-text city name is rejected. |
                | `address` | string | Letters, digits, hyphens and spaces only — **no commas, periods, `#`, `/` or other punctuation** — max 40 chars. Keep it ASCII: accented or non-Latin letters are rejected by the card provider. |
                | `postCode` | string | Letters and digits only, max 15 chars. Spaces are stripped automatically (`SW3 4RP` → `SW34RP`); hyphens and other punctuation are rejected. |

                **Identity fields, B2C only:**

                | Field | Type | Constraints |
                |-------|------|-------------|
                | `gender` | string | `"M"` or `"F"`. |
                | `idType` | string | One of `PASSPORT`, `DLN`, `HK_HKID`, `GOVERNMENT_ISSUED_ID_CARD` (case-insensitive). A national ID card is `GOVERNMENT_ISSUED_ID_CARD` — `NATIONAL_ID` is rejected. |
                | `idNo` | string | Document number. |
                | `idIssueDate` | string | Document issue date, `YYYY-MM-DD`. **Required**, even though the schema marks it optional. |
                | `idExpiryDate` | string | Document expiry date, `YYYY-MM-DD`. Optional, but must not be earlier than `idIssueDate`. |
                | `nationality` | string | Country code, see `/v1/cardholders/regions`. |
                | `occupation` | string | Occupation code, see `/v1/cardholders/occupations`. |
                | `annualSalary` | string | Annual salary range (optional, free text). |
                | `accountPurpose` | string | Purpose of the account (optional, free text). |
                | `expectedMonthlyVolume` | string | Expected monthly transaction volume (optional, free text). |
                | `ipAddress` | string | User's IP address (optional). |

                **Where the rules are enforced**

                `POST /v1/users` and `PATCH /v1/users/{id}` store `meta` as given and do
                **not** validate it. Everything above is checked here and in
                `PATCH /v1/cardholders/{id}`, and a violation comes back as `400` with the
                offending field in the message — so validate at the point your user fills
                the form rather than at card issuance. Length limits count bytes, so a
                non-ASCII character consumes more than one of the 40/50 budget.

                On a **B2B** BIN only `firstName`, `lastName` and `email` are read and
                validated (same name and length rules as above); the identity fields are
                neither required nor used. `email` must be unique per BIN — reusing one
                that another cardholder on the same BIN already holds is rejected with
                `ErrAlreadyExists`.

                **B2C requirements:**
                - User must have KYC status `completed` before calling this endpoint.
                - KYC documents (idFrontImg, idBackImg, idHoldImg) are automatically uploaded from the KYC system.
            operationId: CreateUserCardholder
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateCardholderRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CardholderResponse'
                    description: Cardholder created (status will be pending_review until admin approves).
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Missing personal data or invalid request.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: User not found.
                "412":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: 'B2C only: KYC not completed or required documents missing.'
            summary: Create User Cardholder
            tags:
                - Users
    /v1/users/{id}/kyc:
        get:
            description: Retrieve KYC status and document summary for a user.
            operationId: GetUserKYCStatus
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/KYCStatusResponse'
                    description: KYC status retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: User not found.
            summary: Get User KYC Status
            tags:
                - KYC
    /v1/users/{id}/kyc/documents:
        get:
            description: Retrieve all KYC documents for a user.
            operationId: ListKYCDocuments
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/KYCDocumentsResponse'
                    description: Documents retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: User not found.
            summary: List KYC Documents
            tags:
                - KYC
        post:
            description: |
                Upload a KYC document for a user. `fileContent` must be base64 encoded.

                **Formats and size**

                - Accepted MIME types: `image/jpeg`, `image/jpg`, `image/png`,
                  `application/pdf`.
                - Max 20MB decoded per file.
                - The card provider caps document uploads at **2MB**. JPEG and PNG images
                  above that are recompressed automatically, so you do not need to resize
                  them; a PDF cannot be recompressed, so **send identity documents as
                  JPG or PNG** if they exceed 2MB.

                **Document types**

                `passport`, `id_card`, `driving_licence`, `residence_permit` count as
                identity documents; `selfie_with_document` and `proof_of_address` are
                separate. `POST /v1/users/{id}/kyc/submit` requires at least one identity
                document **plus** a `selfie_with_document`.

                **Two-sided documents**

                For an ID with a front and a back, include `back` (or `rear` /
                `reverse`) as a word in the file name of the reverse side, e.g.
                `id-card-back.jpg`. That is how the sides are routed to the provider;
                without the hint the upload order decides, and swapped sides are
                rejected. Within each slot the newest non-rejected upload wins, so a
                re-upload replaces an earlier scan.
            operationId: UploadKYCDocument
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/KYCDocumentUploadRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/KYCDocumentResponse'
                    description: Document uploaded.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request (file too large, invalid type, etc.).
            summary: Upload KYC Document
            tags:
                - KYC
    /v1/users/{id}/kyc/documents/{docId}:
        delete:
            description: Delete a KYC document and its file from storage.
            operationId: DeleteKYCDocument
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Document identifier.
                  in: path
                  name: docId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    description: Document deleted.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Document not found.
            summary: Delete KYC Document
            tags:
                - KYC
        get:
            description: Retrieve metadata for a specific KYC document.
            operationId: GetKYCDocument
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Document identifier.
                  in: path
                  name: docId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/KYCDocumentResponse'
                    description: Document metadata retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Document not found.
            summary: Get KYC Document
            tags:
                - KYC
    /v1/users/{id}/kyc/documents/{docId}/content:
        get:
            description: Download the file content of a KYC document.
            operationId: GetKYCDocumentContent
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Document identifier.
                  in: path
                  name: docId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/octet-stream:
                            schema:
                                format: binary
                                type: string
                    description: File content.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Document not found.
            summary: Download KYC Document Content
            tags:
                - KYC
    /v1/users/{id}/kyc/documents/{docId}/status:
        patch:
            description: Approve or reject a specific KYC document.
            operationId: UpdateKYCDocumentStatus
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Document identifier.
                  in: path
                  name: docId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/KYCDocumentStatusUpdateRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/KYCDocumentResponse'
                    description: Document status updated.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Update KYC Document Status (Admin)
            tags:
                - KYC
    /v1/users/{id}/kyc/notes:
        patch:
            description: Update internal admin notes for KYC review.
            operationId: UpdateUserKYCNotes
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/KYCNotesUpdateRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/KYCStatusResponse'
                    description: Notes updated.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: User not found.
            summary: Update User KYC Notes (Admin)
            tags:
                - KYC
    /v1/users/{id}/kyc/status:
        patch:
            description: Change KYC status for a user. Only valid admin transitions are allowed.
            operationId: UpdateUserKYCStatus
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/KYCStatusUpdateRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/KYCStatusResponse'
                    description: KYC status updated.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid status transition.
            summary: Update User KYC Status (Admin)
            tags:
                - KYC
    /v1/users/{id}/kyc/submit:
        post:
            description: |
                Submit the user's KYC documents for review. Transitions KYC status to 'pending'.
                Requires at least one identity document and a selfie with document.
            operationId: SubmitUserKYC
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/KYCStatusResponse'
                    description: KYC submitted for review.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Missing required documents or invalid status transition.
            summary: Submit KYC for Review
            tags:
                - KYC
    /v1/users/{id}/status:
        patch:
            description: Change the lifecycle status of a user and cascade status changes to their cards.
            operationId: UpdateUserStatus
            parameters:
                - description: User identifier.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UserStatusUpdateRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/User'
                    description: Updated user resource.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid status transition.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: User not found.
            summary: Update User Status
            tags:
                - Users
    /v1/users/transfer:
        post:
            description: Moves funds between Payca user or client accounts owned by the client.
            operationId: TransferPaycaAccounts
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UserTransferRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UserTransferResponse'
                    description: Transfer created.
            summary: Transfer between Payca accounts
            tags:
                - Users
    /v1/wallets/{address}/balance:
        get:
            description: Get information about a wallet including its allocation status.
            operationId: GetWalletBalance
            parameters:
                - description: Wallet address.
                  in: path
                  name: address
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WalletBalanceResponse'
                    description: Wallet information retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Wallet not found.
            summary: Get wallet information
            tags:
                - Wallets
    /v1/wallets/{address}/gas-balance:
        put:
            description: Update the tracked gas balance for a wallet.
            operationId: UpdateWalletGasBalance
            parameters:
                - in: path
                  name: address
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UpdateGasBalanceRequest'
                required: true
            responses:
                "200":
                    description: Gas balance updated.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Wallet not found.
            summary: Update wallet gas balance
            tags:
                - WalletPool
    /v1/wallets/allocate:
        post:
            description: |
                Allocates an available wallet from the pool for receiving crypto deposits.
                The wallet is reserved for the specified duration (TTL).
            operationId: AllocateWallet
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/WalletAllocateRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WalletAllocateResponse'
                    description: Wallet allocated successfully.
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: No available wallets in pool.
            summary: Allocate a wallet for deposit
            tags:
                - Wallets
    /v1/wallets/deposit:
        post:
            description: |
                Confirms that a deposit has been received on an allocated wallet.
                Called by blockchain scanner when a transaction is detected.
            operationId: ConfirmDeposit
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/WalletDepositConfirmRequest'
                required: true
            responses:
                "200":
                    description: Deposit confirmed.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Wallet allocation not found.
            summary: Confirm a deposit
            tags:
                - Wallets
    /v1/wallets/maintenance/release-expired:
        post:
            description: |
                Manually triggers the release of all expired wallet allocations that don't have deposits.
                This is normally handled automatically by the maintenance workflow, but can be called
                manually for immediate cleanup.
            operationId: ReleaseExpiredAllocations
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    released:
                                        description: Number of allocations that were released
                                        type: integer
                                required:
                                    - released
                                type: object
                    description: Expired allocations released.
            summary: Release expired wallet allocations
            tags:
                - Wallets
    /v1/wallets/release:
        post:
            description: |
                Releases a previously allocated wallet back to the pool.
                Should be called when a deposit order is cancelled or expires.
            operationId: ReleaseWallet
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/WalletReleaseRequest'
                required: true
            responses:
                "200":
                    description: Wallet released successfully.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Wallet allocation not found.
            summary: Release an allocated wallet
            tags:
                - Wallets
    /v1/wallets/stats:
        get:
            description: Get statistics about the wallet pool for all chains.
            operationId: GetWalletPoolStats
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WalletPoolStatsResponse'
                    description: Pool statistics retrieved.
            summary: Get wallet pool statistics
            tags:
                - Wallets
    /v1/webhooks:
        delete:
            description: Delete a specific webhook by its ID.
            operationId: DeleteWebhook
            parameters:
                - description: The ID of the webhook to delete.
                  in: query
                  name: webhookId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    description: Webhook successfully deleted.
                "400":
                    content:
                        application/json:
                            examples:
                                deleteWebhookError:
                                    summary: Error deleting webhook
                                    value:
                                        code: ErrInvalidArg
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Delete Webhook
            tags:
                - Webhooks
        get:
            description: Retrieve a list of configured webhooks.
            operationId: ListWebhooks
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                listWebhooks:
                                    summary: List of webhooks
                                    value:
                                        - id: a1234567-89ab-4cde-f012-3456789abcd6
                                          type: account
                                          url: https://example.com/webhook
                                        - id: b1234567-89ab-4cde-f012-3456789abcd7
                                          type: card
                                          url: https://example.org/webhook
                            schema:
                                items:
                                    $ref: '#/components/schemas/WebhookResponse'
                                type: array
                    description: Successfully retrieved list of webhooks.
                "400":
                    content:
                        application/json:
                            examples:
                                listWebhooksError:
                                    summary: Error listing webhooks
                                    value:
                                        code: ErrInvalidArg
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: List Webhooks
            tags:
                - Webhooks
        post:
            description: |
                Configure a webhook URL to receive event notifications. Specify the type of events to subscribe to, such as card transactions or account transactions.
            operationId: SetWebhook
            requestBody:
                content:
                    application/json:
                        examples:
                            webhookRequest:
                                summary: Webhook request example
                                value:
                                    type: account
                                    url: https://example.com/webhook
                        schema:
                            $ref: '#/components/schemas/WebhookRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                webhookSet:
                                    summary: Webhook configured successfully
                                    value:
                                        id: a1234567-89ab-4cde-f012-3456789abcd6
                                        type: account
                                        url: https://example.com/webhook
                            schema:
                                $ref: '#/components/schemas/WebhookResponse'
                    description: Webhook successfully set.
                "400":
                    content:
                        application/json:
                            examples:
                                webhookSetError:
                                    summary: Error setting webhook
                                    value:
                                        code: ErrInvalidArg
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Set Webhook URL
            tags:
                - Webhooks
    /v1/webhooks/resend:
        post:
            description: |
                Re-dispatch previously generated webhook events. When `fromDate` is provided, only hooks created at or after that timestamp are resent.
            operationId: ResendWebhooks
            parameters:
                - description: ISO-8601 timestamp to limit which events are resent.
                  in: query
                  name: fromDate
                  required: false
                  schema:
                    format: date-time
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                resendWebhooks:
                                    summary: Hooks re-dispatched
                                    value:
                                        account: 2
                                        card: 3
                                        total: 5
                            schema:
                                $ref: '#/components/schemas/WebhookResendResponse'
                    description: Webhook resend jobs enqueued.
                "400":
                    content:
                        application/json:
                            examples:
                                resendWebhooksError:
                                    summary: Error resending webhooks
                                    value:
                                        code: ErrInvalidArg
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Resend Webhooks
            tags:
                - Webhooks
    /v2/accounts:
        get:
            description: |
                Fetch a list of primary accounts linked to the authenticated user, including their enabled BINs.
                Each account will include a 'bins' array containing BINs available for issuing cards. Fee/debt accounts are excluded.
            operationId: GetAccountsV2
            responses:
                "200":
                    content:
                        application/json:
                            examples:
                                sampleAccountsV2:
                                    summary: A sample accounts response with BINs
                                    value:
                                        accounts:
                                            - balance:
                                                available: "1500.00"
                                                pending: "100.00"
                                              bins:
                                                - bin: "411111"
                                                  currencyCode: USD
                                                  fees:
                                                    authorization:
                                                        - range: 0-100
                                                          value: "0.50"
                                                    decline:
                                                        - range: 0-100
                                                          value: "0.25"
                                                    issueFee: "5.00"
                                                    minCardBalance: "100.00"
                                                    monthlyFee: "2.00"
                                                  isTokenizable: true
                                                  provider: visa
                                                  settings:
                                                    minCardBalance: "100.00"
                                              currency: USD
                                              id: d290f1ee-6c54-4b01-90e6-d701748f0851
                                              status: active
                                            - balance:
                                                available: "0.00"
                                                pending: "0.00"
                                              bins:
                                                - bin: "537100"
                                                  currencyCode: USD
                                                  fees:
                                                    authorization:
                                                        - range: 0-0.01
                                                          value: "0"
                                                        - range: 0.01-25
                                                          value: "0.5"
                                                        - range: 25.01-50
                                                          value: "0.5"
                                                        - range: 50.01-1000000
                                                          value: "0"
                                                    decline:
                                                        - range: 0-0.15
                                                          value: "0.4"
                                                        - range: 0.16-0.3
                                                          value: "0.45"
                                                        - range: 0.31-0.45
                                                          value: "0.5"
                                                        - range: 0.46-1000000
                                                          value: "0.6"
                                                    issueFee: "1.50"
                                                    minCardBalance: "1.00"
                                                    monthlyFee: "0"
                                                  isTokenizable: false
                                                  name: vc-1
                                                  provider: mastercard
                                                  settings:
                                                    minCardBalance: "1.00"
                                              currency: USD
                                              id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                                              status: active
                            schema:
                                $ref: '#/components/schemas/AccountsWithBinsResponse'
                    description: Successfully retrieved accounts with BINs.
            summary: Retrieve Accounts with Enabled BINs
            tags:
                - Accounts
    /v2/accounts/{accountId}/deposit-quote:
        post:
            description: |
                Prices a deposit without opening an order. `amountMode` specifies whether
                `amount` is what the payer wants charged or what they want credited. The
                returned requested amount is the amount to pass to create. A caller that
                displays this quote should also send all expected quote values on create;
                create returns 409 instead of charging a changed price.
            operationId: QuoteAccountDeposit
            parameters:
                - in: path
                  name: accountId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/DepositQuoteRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/DepositQuote'
                    description: Deposit price calculated.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/DepositQuoteError'
                    description: |
                        Invalid or unsupported amount. When the amount is below the deposit
                        minimum, the response also includes the calculated quote and the
                        minimum valid amount for the input side selected by `amountMode`.
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Deposits are not enabled for this client.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Account not found.
            summary: Quote a deposit
            tags:
                - Deposits
    /v2/accounts/{accountId}/deposits:
        get:
            description: |
                Returns deposit orders for the account, newest first.
                Includes every attempt — pending, failed, cancelled and expired ones too,
                not only successful deposits.
                The funding provider is an internal routing decision and is never exposed.
            operationId: ListAccountDeposits
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: accountId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Filter by normalised deposit status.
                  in: query
                  name: status
                  required: false
                  schema:
                    $ref: '#/components/schemas/DepositStatus'
                - description: Maximum number of deposits to return (1-200, default 50).
                  in: query
                  name: limit
                  required: false
                  schema:
                    default: 50
                    format: int32
                    maximum: 200
                    minimum: 1
                    type: integer
                - description: Number of deposits to skip.
                  in: query
                  name: offset
                  required: false
                  schema:
                    default: 0
                    format: int32
                    minimum: 0
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/DepositListResponse'
                    description: Deposits retrieved.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Account not found.
            summary: List deposits for an account
            tags:
                - Deposits
        post:
            description: |
                Opens a deposit and returns it, including the `checkoutUrl` the payer must be
                sent to. The deposit is NOT money yet: it becomes `completed` only once the
                payment settles and the balance credit is recorded.

                Requires an `Idempotency-Key` header. A repeat of the same key returns the
                original deposit untouched rather than opening a second checkout the payer
                could also pay.

                Redirect URLs must match the prefixes allow-listed for the calling client.
                Both are required by the acquirer.
            operationId: CreateAccountDeposit
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: accountId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateDepositRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Deposit'
                    description: Deposit created.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Deposits are not enabled for this client.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Account not found.
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: |
                        The idempotency key was already used for a different request, or the
                        expected quote no longer matches the live tariff.
            summary: Create a deposit
            tags:
                - Deposits
    /v2/accounts/{accountId}/deposits/{depositId}:
        get:
            description: |
                Returns the current state of a single deposit order.
                A deposit reads as `completed` only after settlement was confirmed and the
                balance credit was recorded — a browser returning from a checkout page does
                not make a deposit complete.
            operationId: GetAccountDeposit
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: accountId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Unique identifier of the deposit.
                  in: path
                  name: depositId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Deposit'
                    description: Deposit retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Deposit not found.
            summary: Retrieve a deposit
            tags:
                - Deposits
    /v2/accounts/{accountId}/funding-options:
        get:
            description: |
                Returns the ways this account can be funded from outside Payca, with the
                amount limits that apply to each.

                Scoped to the account's own currency: a deposit is never converted on the way
                in, so an option in another currency would be an option this account cannot
                use. An empty list is a valid answer and means no method is available for this
                account's currency and the given country.
            operationId: GetAccountFundingOptions
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: accountId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: |
                    ISO 3166-1 alpha-2 billing country of the payer. Acquiring is licensed per
                    geography, so the same currency can be served differently depending on it.
                  in: query
                  name: country
                  required: true
                  schema:
                    maxLength: 2
                    minLength: 2
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/FundingOptionsResponse'
                    description: Funding options retrieved.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Account not found.
            summary: List funding options for an account
            tags:
                - Deposits
    /v2/accounts/{accountId}/payout-options:
        get:
            description: |
                Returns the ways this account can pay money out, with the limits and the fee
                tariff that apply to each.

                Scoped to the account's own currency: a payout is never converted on the way
                out, so an option in another currency would be one this account cannot use. An
                empty list is a valid answer and means no method is available for this
                account's currency, the given destination country, and this client.

                A method this client is not approved for is absent entirely rather than listed
                as unavailable — an option nobody may use is not an option.
            operationId: GetAccountPayoutOptions
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: accountId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: |
                    ISO 3166-1 alpha-2 country of the recipient. Payout licensing is per
                    geography, so the same currency can be served differently depending on it.
                  in: query
                  name: country
                  required: true
                  schema:
                    maxLength: 2
                    minLength: 2
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PayoutOptionsResponse'
                    description: Payout options retrieved.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Account not found.
            summary: List payout options for an account
            tags:
                - Payouts
    /v2/accounts/{accountId}/payout-quote:
        post:
            description: |
                Returns exactly what a payout with these parameters would cost: both fees, what
                the recipient receives, and the total debited from the account.

                Creates nothing, reserves nothing and is safe to call repeatedly — it exists so
                the amounts a user confirms are computed here rather than re-derived by the
                caller. Rounding a fee differently would produce a figure the create endpoint
                then refuses.

                The same request body as `POST /payouts`; the destination is optional here,
                since price does not depend on it.
            operationId: QuoteAccountPayout
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: accountId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/QuotePayoutRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PayoutQuote'
                    description: Quote computed.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: |
                        Invalid request, an unavailable route, an amount outside the route's
                        limits, or fees that would leave the recipient nothing.
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Payouts are not enabled for this client.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Account not found.
            summary: Price a payout without creating it
            tags:
                - Payouts
    /v2/accounts/{accountId}/payouts:
        get:
            description: |
                Returns payouts for the account, newest first. Includes every attempt —
                in-flight, failed, cancelled and those under manual review — not only
                successful ones. The payout provider is an internal routing decision and is
                never exposed.
            operationId: ListAccountPayouts
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: accountId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Filter by normalised payout status.
                  in: query
                  name: status
                  required: false
                  schema:
                    $ref: '#/components/schemas/PayoutStatus'
                - description: Maximum number of payouts to return (1-200, default 50).
                  in: query
                  name: limit
                  required: false
                  schema:
                    default: 50
                    format: int32
                    maximum: 200
                    minimum: 1
                    type: integer
                - description: Number of payouts to skip.
                  in: query
                  name: offset
                  required: false
                  schema:
                    default: 0
                    format: int32
                    minimum: 0
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PayoutListResponse'
                    description: Payouts retrieved.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Account not found.
            summary: List payouts for an account
            tags:
                - Payouts
        post:
            description: |
                Opens a payout and reserves the full debit — the recipient's amount plus both
                fees — on the account. The money is held, not yet gone: the payout reads
                `completed` only once the provider confirms it paid out AND the ledger debit is
                recorded.

                Requires an `Idempotency-Key` header. A repeat of the same key returns the
                original payout untouched rather than paying the recipient twice.

                The destination can be an opaque `card_token` or the recipient card requisites
                required by a payout-only rail. Card requisites are validated, encrypted before
                persistence, never returned by this API, and removed after a definitive provider
                submission result.
            operationId: CreateAccountPayout
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: accountId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreatePayoutRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Payout'
                    description: Payout created and funds reserved.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Payouts are not enabled for this client.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Account not found.
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: |
                        The idempotency key was already used for a different request.
            summary: Create a payout
            tags:
                - Payouts
    /v2/accounts/{accountId}/payouts/{payoutId}:
        get:
            description: |
                Returns the current state of a single payout. A payout reads as `completed`
                only after the provider confirmed the payment AND the ledger debit was
                recorded.
            operationId: GetAccountPayout
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: accountId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Unique identifier of the payout.
                  in: path
                  name: payoutId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Payout'
                    description: Payout retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Payout not found.
            summary: Retrieve a payout
            tags:
                - Payouts
    /v2/accounts/{id}/topup/{txId}:
        get:
            description: Retrieve the status of a card-funded account top-up.
            operationId: GetAccountCardTopupV2
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Payca transaction identifier.
                  in: path
                  name: txId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AccountCardTopUpResponse'
                    description: Top up status retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Not found.
            summary: Retrieve account card top-up status
            tags:
                - Accounts
    /v2/accounts/{id}/topup/card:
        post:
            description: |
                Initiate a card-funded top up for the specified account.
                - The account currency is derived from the account.
                - Only plain card details are supported for this endpoint.
                - The response may include a `nextAction` to complete authentication steps (3DS).
            operationId: TopUpAccountByCardV2
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/AccountCardTopUpRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AccountCardTopUpResponse'
                    description: Top up initiated.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Top up an account using an external payment card
            tags:
                - Accounts
    /v2/accounts/{id}/withdraw/{txId}:
        get:
            description: Retrieve the status of a card-funded account withdrawal.
            operationId: GetAccountCardWithdrawV2
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
                - description: Payca transaction identifier.
                  in: path
                  name: txId
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AccountCardWithdrawResponse'
                    description: Withdrawal status retrieved.
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Not found.
            summary: Retrieve account card withdrawal status
            tags:
                - Accounts
    /v2/accounts/{id}/withdraw/card:
        post:
            description: |
                Initiate a payout from the specified account to a recipient payment card.
                - The source account is the sender and is derived from the path parameter.
                - Destination currency defaults to the account currency unless explicitly provided.
            operationId: WithdrawAccountToCardV2
            parameters:
                - description: Unique identifier of the account.
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                    x-go-type: uuid.UUID
                    x-go-type-import:
                        path: github.com/google/uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/AccountCardWithdrawRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AccountCardWithdrawResponse'
                    description: Withdrawal initiated.
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                    description: Invalid request.
            summary: Withdraw funds from an account to an external payment card
            tags:
                - Accounts
security:
    - clientId: []
      clientSecret: []
servers:
    - description: Production server (uses live data)
      url: https://api.actisas.ee
    - description: Stage server
      url: https://b2bapi.stage.payca.vc
    - description: localhost
      url: http://localhost:8080
tags:
    - description: Service liveness/health probe.
      name: Health
    - description: Operations for listing accounts and their balances.
      name: Accounts
    - description: Issue, manage, and retrieve cards and details.
      name: Cards
    - description: Retrieve transactions and related activity.
      name: Transactions
    - description: |
        Provider-independent account deposits (top-ups from outside Payca).

        The funding provider is an internal routing decision and never appears in
        the API. Statuses are normalised: a deposit reads as `completed` only once
        settlement was confirmed AND the balance credit was recorded, so a browser
        returning from a checkout page never means funds are available.

        Integrations discover an available route, quote it, create an idempotent
        deposit order, redirect the payer to hosted checkout, and then use deposit
        status and webhooks to reconcile the final outcome.
      name: Deposits
    - description: Configure and manage webhooks.
      name: Webhooks
    - description: Endpoints for sandbox/testing flows.
      name: Sandbox
    - description: Deprecated endpoints to retrieve BINs and fees.
      name: Bins
    - description: |
        Step-by-step guide for issuing cards with cardholder verification.

        Which flow applies depends on the BIN's `providerCardHolderModel`, returned
        by the BIN catalogue on `GET /v1/accounts`: **B2B** BINs use the short form
        below, **B2C** BINs require a full identity check.

        ## B2B card issuance flow (short form)

        ### Step 1 — Create user

        Create a user via the Users API with `firstName`, `lastName` and `email` in
        the `meta` field. Nothing else is needed: cards on a B2B BIN are issued
        under the account's own card programme, so no identity documents, address
        or date of birth are collected.

        ### Step 2 — Create cardholder

        Call `CreateUserCardholder` — pass `accountId` and `bin`.

        The cardholder comes back immediately with `status: "pass_audit"`. There is
        no review step and no polling: it is ready to use in the same response.

        ### Step 3 — Issue card

        `POST /v1/cards` — pass `accountId`, `bin`, `balance`, and `cardholderId` (UUID from step 2).

        3DS OTP codes are delivered on the `card` webhook with
        `type: "3ds_code"`, keyed by `cardId` (the same channel carries
        `3ds_auth_url` and `activation_code`).

        > **Note:** A cardholder in `pass_audit` status is still required to issue a
        > card — it is what ties each card to your end user. The system resolves it
        > in this order: explicit `cardholderId` → the user's approved cardholder
        > linked to the account. If no approved cardholder is found, the request is
        > rejected.

        ## B2C card issuance flow (full identity check)

        ### Step 1 — Create user

        Create a user via the Users API with cardholder personal data in the `meta` field:
        `firstName`, `lastName`, `email`, `phone`, `phoneCode`, `birthday`,
        `country`, `town`, `address`, `postCode`, plus the B2C-only fields documented
        on `POST /v1/users/{id}/cardholder`.

        Use `/v1/cardholders/cities` for town codes, `/v1/cardholders/regions` for country codes.

        ### Step 2 — Create cardholder

        Call `CreateUserCardholder` — pass `accountId` and `bin`.
        Personal data is read from user meta automatically.

        The cardholder is created with `status: "pending_review"` and must be approved by a PayCA admin
        before being submitted to the card provider for audit.

        Poll `GET /v1/cardholders/{id}` until status reaches `pass_audit`, then issue
        the card exactly as in step 3 above.

        ## Cardholder statuses

        | Status | Description |
        |--------|-------------|
        | `pending_review` | Created, waiting for PayCA admin approval. |
        | `rejected_by_admin` | Rejected by PayCA admin (see `description` field for reason). |
        | `wait_audit` | Submitted to card provider, waiting for audit. |
        | `under_review` | Provider is reviewing the cardholder. |
        | `pass_audit` | Approved — ready for card issuance. |
        | `reject` | Rejected by provider (see `description` and `statusFlowLocation`). |

        ## Required user meta fields (B2B)

        | Field | Type | Constraints |
        |-------|------|-------------|
        | `firstName` | string | Latin letters, space, hyphen, apostrophe, period; max 40 chars; no `TEST`/`MOCK`/`SANDBOX`. |
        | `lastName` | string | Same rules as `firstName`. |
        | `email` | string | Max 50 chars. |

        Any other field you store in `meta` is kept as-is and ignored by the
        cardholder flow.

        ## Required user meta fields (B2C)

        | Field | Type | Constraints |
        |-------|------|-------------|
        | `firstName` | string | Latin letters, space, hyphen, apostrophe, period; max 40 chars; no `TEST`/`MOCK`/`SANDBOX`. |
        | `lastName` | string | Same rules as `firstName`. |
        | `email` | string | Max 50 chars. 3DS OTP codes are sent here. |
        | `phone` | string | Digits only, 7–15, without country code; must be a mobile number. |
        | `phoneCode` | string | `+` and 1–4 digits, e.g. `"+1"`. |
        | `birthday` | string | Date of birth (`YYYY-MM-DD`). |
        | `country` | string | Country code (see `/v1/cardholders/regions`). |
        | `town` | string | City code (see `/v1/cardholders/cities`). |
        | `address` | string | Letters, digits, hyphens, spaces only (no commas or other punctuation); max 40 chars. |
        | `postCode` | string | Letters and digits only, max 15 chars; spaces are stripped automatically. |

        Full per-field rules, including the B2C-only fields, are documented on
        `POST /v1/users/{id}/cardholder`. Note that `POST /v1/users` does not
        validate `meta` — the rules are enforced when the cardholder is created.

        ## Related endpoints

        | Endpoint | Purpose |
        |----------|---------|
        | `GET /v1/cardholders` | List all cardholders for the client. |
        | `GET /v1/cardholders/{id}` | Get cardholder by ID (poll for status). |
        | `PATCH /v1/cardholders/{id}` | Fix the data of a rejected/failed cardholder (auto-resubmits `submission_failed`). |
        | `POST /v1/cardholders/{id}/submit` | Submit a reviewed `pending_review` cardholder. |
        | `POST /v1/cardholders/{id}/retry` | Retry a `submission_failed` cardholder unchanged. |
        | `GET /v1/cardholders/cities` | City codes for registration. |
        | `GET /v1/cardholders/regions` | Country/region codes. |
        | `POST /v1/cardholders/files` | Upload identity documents (optional). |
      name: Card Issuance Flows
    - description: |
        User management: create, update, and retrieve users and their accounts.
      name: Users
    - description: Wallet pool management for crypto deposits (offramp).
      name: Wallets
    - description: Gas station operations for fund collection (admin).
      name: GasStation
    - description: |
        Cardholder management: list, get, create cardholders.
        Reference data for registration (cities, occupations, regions) and file upload.
      name: Cardholders
    - description: |
        KYC verification for B2C card issuance. Upload identity documents and selfie,
        submit for admin review, track status via webhooks.
      name: KYC
    - description: Exchange operations (rates, orders, withdrawals) and settlement balance queries.
      name: Exchange
