openapi: 3.1.2
info:
  title: Paisr API
  version: 2.7.0
  description: Paisr is the payment infrastructure for the Caribbean.
  contact:
    name: Customer Support
    email: support@paisr.tech
    url: https://paisr.tech/contact
  termsOfService: https://paisr.tech/legal/terms-of-service
externalDocs:
  url: https://docs.paisr.tech
servers:
  - url: https://api.live.paisr.tech/{version}
    description: Live Server
    variables:
      version:
        default: v2
        enum:
          - v2
        description: Live API version
  - url: https://api.staging.paisr.tech/{version}
    description: Staging Server
    variables:
      version:
        default: v2
        enum:
          - v2
        description: Staging API version
security:
  - bearerAuth: []
tags:
  - name: Health
    description: Monitor the health of the API.
  - name: Access Tokens
    description: >
      Access tokens authenticate your API requests. Each token carries a set of permission scopes that determine which resources it can read or write. Create tokens with limited scope and expiry to follow the principle of least privilege.
  - name: Webhooks
    description: >
      Webhooks let you subscribe to events that occur in your Paisr account.
      When an event fires, Paisr sends an HTTP POST to your endpoint with an
      HMAC-SHA256 signed payload. Each webhook can subscribe to one or more
      event triggers and can be paused, tested, and monitored independently.
  - name: Wallets
    description: >
      Wallets are the primary financial container in Paisr. Each wallet holds
      one or more currency balances, supports peer-to-peer and bank transfers, and can be configured with a PIN, and public profile.
  - name: Balances
    description: >
      Balances represent a currency-denominated store of funds within a wallet. A wallet can hold multiple balances, one per currency, each backed by a treasurer account at a partner bank.
  - name: Accounts
    description: >
      Connected accounts are verified bank accounts linked to a wallet. Once
      ownership is confirmed via micro-deposit verification, an account can be used as a destination for outbound bank transfers.
  - name: Contacts
    description: >
      Contacts are saved wallet addresses other Paisr users you transact with
      regularly. Adding a contact by cashtag lets you reference them by ID
      when initiating peer transfers.
  - name: Statements
    description: >
      Statements are monthly summaries of wallet activity. Once generated, a
      statement PDF can be downloaded for record-keeping, reconciliation, or
      compliance purposes.
  - name: Transactions
    description: >
      Transactions record every movement of funds into or out of a wallet.
      They are immutable once settled and include a full quote breakdown of fees, taxes, and any currency conversion applied.
  - name: Transfers
    description: >
      Transfers move funds between balances, wallets, or bank accounts. P2P and ACH transfers start in a pending-approval state and require a cryptographic signature from the source wallet before funds are released.
  - name: Invoices
    description: >
      Invoices are payment requests issued to a customer. Each invoice tracks its own line items, voucher discounts, due date, and payment status. Once sent, a customer can pay via a hosted checkout session.
  - name: Subscriptions
    description: >
      Subscriptions automate recurring billing against a plan. Each subscription ties a customer and payment method to one or more plan options, generating invoices automatically at each billing interval.
  - name: Customers
    description: >
      Customers represent the people or businesses you bill. Storing a customer lets you attach billing and shipping details, a default currency, and gives them access to a self-service billing portal.
  - name: Vouchers
    description: >
      Vouchers are discount codes applied to eligible invoices at checkout. You control the maximum number of redemptions, and the expiry date.
  - name: Plans
    description: >
      Plans define the pricing structure of your subscriptions. Each plan holds one or more price options with combinations of unit price, billing interval, and an optional attributes.
  - name: Payments
    description: >
      Payments capture the movement of funds through a supported payment
      method to your wallet. Each payment moves through a lifecycle from initiated to approved to settled.
  - name: Provider Connections
    description: >
      Provider connections link your account to third-party payment processors. External connections store the credentials needed to route payments through that provider.
  - name: Static Pages
    description: >
      Static pages are payment pages that can be used to accept payments without attaching them to an invoice.
  - name: Metrics
    description: >
      Metrics give you a real-time snapshot of invoice, subscription, payment, and customer activity. Use these endpoints to power dashboards or monitor the health of your billing operations.
  - name: Logs
    description: >
      The API log records every request made against your account, including the authentication method, route, response status, and body. Use it to debug integrations or audit API activity.

paths:
  /health:
    get:
      tags:
        - Health
      operationId: healthCheck
      summary: Health check
      description: Retrieves the health check status of the API.
      responses:
        "200":
          description: Successfully retrieved health check status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The health check data.
                    properties:
                      name:
                        type: string
                        description: The name of the API.
                        example: Paisr API
                      version:
                        type: string
                        description: The version of the API.
                        example: v2
                      environment:
                        type: string
                        description: The environment of the API.
                        example: production
        "500":
          $ref: "#/components/responses/500Response"

  /access-tokens:
    get:
      tags:
        - Access Tokens
      operationId: listAccessTokens
      summary: List access tokens
      description: Retrieves a list of all access tokens associated with your account.
      responses:
        "200":
          description: Successfully retrieved the list of access tokens.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The access tokens data.
                    properties:
                      tokens:
                        type: array
                        description: The list of access tokens.
                        items:
                          $ref: "#/components/schemas/AccessToken"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Access Tokens
      operationId: createAccessToken
      summary: Create an access token
      description: Creates a new access token with the specified scopes.
      requestBody:
        description: Request body for creating an access token.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostAccessTokenRequest"
      responses:
        "200":
          description: Successfully created token. Store the secret — it will not be shown again.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
  /access-tokens/{token_id}:
    get:
      tags:
        - Access Tokens
      operationId: getAccessToken
      summary: Retrieve an access token
      description: Returns the details of an existing access token.
      parameters:
        - name: token_id
          in: path
          description: The ID of the API access token.
          required: true
          schema:
            type: string
            pattern: "^tkn_{32}"
      responses:
        "200":
          description: Successfully retrieved access token details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The access token data.
                    $ref: "#/components/schemas/AccessToken"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    put:
      tags:
        - Access Tokens
      operationId: updateAccessToken
      summary: Update an access token
      description: Updates the details of an existing access token.
      parameters:
        - name: token_id
          in: path
          description: The ID of the token to update.
          required: true
          schema:
            type: string
            pattern: "^tkn_.*$"
      requestBody:
        description: The new description to apply to the token.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutAccessTokenRequest"
      responses:
        "200":
          description: Successfully updated token.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Access Tokens
      operationId: revokeAccessToken
      summary: Revoke an access token
      description: Permanently revokes a token. Revoked tokens are rejected immediately on the next request. This action cannot be undone.
      parameters:
        - name: token_id
          in: path
          description: The ID of the API access token to revoke.
          required: true
          schema:
            type: string
            pattern: "^tkn_.*$"
      responses:
        "200":
          description: Successfully revoked token.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /access-tokens/{token_id}/permissions:
    post:
      tags:
        - Access Tokens
      operationId: addTokenPermission
      summary: Add a permission
      description: Grants one or more additional permission scopes to an existing token.
      parameters:
        - name: token_id
          in: path
          description: The ID of the API access token to add permissions to.
          required: true
          schema:
            type: string
            pattern: "^tkn_.*$"
      requestBody:
        description: The scopes to add to the token.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostAccessTokenPermissionRequest"
      responses:
        "200":
          description: Successfully added permissions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /access-tokens/{token_id}/permissions/{permission_id}:
    delete:
      tags:
        - Access Tokens
      operationId: removeTokenPermission
      summary: Remove a permission
      description: Removes a specific permission scope from a token. The token remains active with its remaining scopes.
      parameters:
        - name: token_id
          in: path
          description: The ID of the API access token to remove permissions from.
          required: true
          schema:
            type: string
            pattern: "^tkn_.*$"
        - name: permission_id
          in: path
          description: The ID of the permission to remove.
          required: true
          schema:
            type: string
            pattern: "^tpm_.*$"
      responses:
        "200":
          description: Successfully removed permission.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /webhooks:
    get:
      tags:
        - Webhooks
      operationId: listWebhooks
      summary: List webhooks
      description: Returns a list of all webhooks configured on your account.
      responses:
        "200":
          description: Successfully retrieved the list of profile webhooks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The webhooks data.
                    properties:
                      webhooks:
                        type: array
                        description: The list of webhooks.
                        items:
                          $ref: "#/components/schemas/Webhook"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Webhooks
      operationId: createWebhook
      summary: Create a webhook
      description: Creates a new webhook endpoint. Retrieve the signing secret using the Retrieve webhook secret endpoint after creation, it is not included in this response.
      requestBody:
        description: The endpoint URL and event triggers to subscribe to.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostWebhookRequest"
      responses:
        "200":
          description: Successfully created webhook.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookSecretResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
  /webhooks/{webhook_id}:
    get:
      tags:
        - Webhooks
      operationId: getWebhook
      summary: Retrieve a webhook
      description: Returns the details of a specific webhook.
      parameters:
        - name: webhook_id
          in: path
          description: The ID of the webhook to retrieve.
          required: true
          schema:
            type: string
            description: The Webhook ID.
            pattern: "^whk_.*$"
      responses:
        "200":
          description: Successfully retrieved webhook details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The webhook data.
                    $ref: "#/components/schemas/Webhook"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    put:
      tags:
        - Webhooks
      operationId: updateWebhook
      summary: Update a webhook
      description: Updates the details of an existing webhook.
      parameters:
        - name: webhook_id
          in: path
          description: The ID of the webhook to update.
          required: true
          schema:
            type: string
            pattern: "^whk_.*$"
      requestBody:
        description: The fields to update on the webhook.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutWebhookRequest"
      responses:
        "200":
          description: Successfully updated webhook.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Webhooks
      operationId: deleteWebhook
      summary: Delete a webhook
      description: Permanently deletes the webhook and all its associated triggers. Any events already queued for delivery will not be retried. This action cannot be undone.
      parameters:
        - name: webhook_id
          in: path
          description: The ID of the webhook to delete.
          required: true
          schema:
            type: string
            pattern: "^whk_.*$"
      responses:
        "200":
          description: Successfully removed webhook.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /webhooks/{webhook_id}/test:
    post:
      tags:
        - Webhooks
      operationId: testWebhook
      summary: Send a test event
      description: Sends a synthetic test payload to the webhook endpoint. Use this to confirm your endpoint is reachable and correctly validating the HMAC-SHA256 signature before going live.
      parameters:
        - name: webhook_id
          in: path
          description: The ID of the webhook to test.
          required: true
          schema:
            type: string
            pattern: "^whk_.*$"
      responses:
        "200":
          description: Successfully triggered test event.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /webhooks/{webhook_id}/pause:
    post:
      tags:
        - Webhooks
      operationId: pauseWebhook
      summary: Pause a webhook
      description: Pauses event delivery for the webhook. Events that fire while a webhook is paused are not queued but are silently dropped.
      parameters:
        - name: webhook_id
          in: path
          description: The ID of the webhook to pause.
          required: true
          schema:
            type: string
            pattern: "^whk_.*$"
      responses:
        "200":
          description: Successfully paused webhook.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /webhooks/{webhook_id}/resume:
    post:
      tags:
        - Webhooks
      operationId: resumeWebhook
      summary: Resume a webhook
      description: Resumes event delivery for a paused webhook. Only future events will be delivered; events that fired during the paused period are not replayed.
      parameters:
        - name: webhook_id
          in: path
          description: The ID of the webhook to resume.
          required: true
          schema:
            type: string
            pattern: "^whk_.*$"
      responses:
        "200":
          description: Successfully resumed webhook.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /webhooks/{webhook_id}/stats:
    get:
      tags:
        - Webhooks
      operationId: getWebhookStats
      summary: Retrieve webhook stats
      description: Returns delivery performance metrics for the webhook.
      parameters:
        - name: webhook_id
          in: path
          description: The ID of the webhook to retrieve stats for.
          required: true
          schema:
            type: string
            pattern: "^whk_.*$"
      responses:
        "200":
          description: Successfully retrieved webhook stats.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    $ref: "#/components/schemas/WebhookStats"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /webhooks/{webhook_id}/secret:
    get:
      tags:
        - Webhooks
      operationId: getWebhookSecret
      summary: Retrieve the webhook secret
      description: Returns the current HMAC-SHA256 signing secret for the webhook. Use this secret to verify that incoming payloads originate from Paisr.
      parameters:
        - name: webhook_id
          in: path
          description: The ID of the webhook to retrieve the secret for.
          required: true
          schema:
            type: string
            pattern: "^whk_.*$"
      responses:
        "200":
          description: Successfully retrieved webhook secret.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    $ref: "#/components/schemas/WebhookSecret"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    patch:
      tags:
        - Webhooks
      operationId: rotateWebhookSecret
      summary: Rotate the webhook secret
      description: Generates a new signing secret for the webhook. Paisr begins signing payloads with the new secret immediately, so update your endpoint before rotating to avoid rejected deliveries.
      parameters:
        - name: webhook_id
          in: path
          description: The ID of the webhook to rotate the secret for.
          required: true
          schema:
            type: string
            pattern: "^whk_.*$"
      responses:
        "200":
          description: Successfully rotated webhook secret.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    $ref: "#/components/schemas/WebhookSecret"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /webhooks/{webhook_id}/triggers:
    post:
      tags:
        - Webhooks
      operationId: addWebhookTrigger
      summary: Add a trigger
      description: Subscribes a webhook to one or more additional event types.
      parameters:
        - name: webhook_id
          in: path
          description: The ID of the webhook to add a trigger for.
          required: true
          schema:
            type: string
            pattern: "^whk_.*$"
      requestBody:
        description: The event types to subscribe the webhook to.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostWebhookTriggerRequest"
      responses:
        "200":
          description: Successfully added triggers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /webhooks/{webhook_id}/triggers/{trigger_id}:
    delete:
      tags:
        - Webhooks
      operationId: removeWebhookTrigger
      summary: Remove a trigger
      description: Unsubscribes a webhook from a specific event type. The webhook continues delivering events for its remaining triggers.
      parameters:
        - name: webhook_id
          in: path
          description: The ID of the webhook to remove the trigger for.
          required: true
          schema:
            type: string
            pattern: "^whk_.*$"
        - name: trigger_id
          in: path
          description: The ID of the trigger to remove.
          required: true
          schema:
            type: string
            pattern: "^wtr_.*$"
      responses:
        "200":
          description: Successfully removed trigger.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /webhooks/{webhook_id}/events:
    get:
      tags:
        - Webhooks
      operationId: listWebhookEvents
      summary: List webhook events
      description: Returns a list of event delivery attempts for the webhook.
      parameters:
        - name: webhook_id
          in: path
          description: The ID of the webhook to list events for.
          required: true
          schema:
            type: string
            pattern: "^whk_.*$"
      responses:
        "200":
          description: Successfully retrieved the list of webhook events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The webhook events data.
                    properties:
                      events:
                        type: array
                        description: The list of webhook events.
                        items:
                          $ref: "#/components/schemas/WebhookEvent"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /webhooks/{webhook_id}/events/{event_id}:
    post:
      tags:
        - Webhooks
      operationId: retryWebhookEvent
      summary: Retry a webhook event
      description: Triggers an immediate redelivery attempt for a failed webhook event. Only events where can_retry=true can be retried.
      parameters:
        - name: webhook_id
          in: path
          description: The ID of the webhook to retry the event for.
          required: true
          schema:
            type: string
            pattern: "^whk_.*$"
        - name: event_id
          in: path
          description: The ID of the event to retry.
          required: true
          schema:
            type: string
            pattern: "^wev_.*$"
      responses:
        "200":
          description: Successfully processed event.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /wallets:
    get:
      tags:
        - Wallets
      operationId: listWallets
      summary: List wallets
      description: Returns a list of all wallets on your account.
      responses:
        "200":
          description: Successfully retrieved the list of wallets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The wallets data.
                    properties:
                      wallets:
                        type: array
                        description: The list of wallets.
                        items:
                          $ref: "#/components/schemas/Wallet"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Wallets
      operationId: createWallet
      summary: Create a wallet
      description: Creates a new wallet. Once created, open one or more balances to start holding and moving funds.
      requestBody:
        description: The title and icon for the new wallet.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostWalletRequest"
      responses:
        "200":
          description: Successfully created wallet.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
  /wallets/{wallet_id}:
    get:
      tags:
        - Wallets
      operationId: getWallet
      summary: Retrieve a wallet
      description: Returns the details of a specific wallet, including its profile, PIN status, and current usage.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to retrieve.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
      responses:
        "200":
          description: Successfully retrieved wallet details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The wallet data.
                    $ref: "#/components/schemas/Wallet"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Wallets
      operationId: deleteWallet
      summary: Delete a wallet
      description: Permanently deletes a wallet. All associated balances must be closed and at zero before deletion. This action cannot be undone.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to delete.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
      responses:
        "200":
          description: Successfully removed wallet.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /wallets/{wallet_id}/pin:
    post:
      tags:
        - Wallets
      operationId: setWalletPin
      summary: Set or update the wallet PIN
      description: Sets or updates the 4-digit PIN for a wallet. Provide only the new PIN when setting a PIN for the first time. Include the old PIN when changing an existing PIN.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to update the PIN for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
      requestBody:
        description: The new PIN, and the existing PIN if one is already set.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostWalletPinRequest"
      responses:
        "200":
          description: Successfully updated wallet PIN.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /wallets/{wallet_id}/profile:
    post:
      tags:
        - Wallets
      operationId: updateWalletProfile
      summary: Update the wallet profile
      description: Updates the public-facing profile of a wallet, including its nickname, cashtag, and discoverability setting.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to update the profile for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
      requestBody:
        description: The profile fields to update.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostWalletProfileRequest"
      responses:
        "200":
          description: Successfully updated wallet profile.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /wallets/{wallet_id}/preferences:
    post:
      tags:
        - Wallets
      operationId: updateWalletPreferences
      summary: Update wallet preferences
      description: Updates configuration preferences for a wallet.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to update the preferences for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
      requestBody:
        description: The preference fields to update.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostWalletRequest"
      responses:
        "200":
          description: Successfully updated wallet preferences.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /wallets/{wallet_id}/statements:
    get:
      tags:
        - Statements
      operationId: listWalletStatements
      summary: List wallet statements
      description: Returns a list of monthly statements generated for the wallet. Each statement can be downloaded as a PDF for record-keeping or compliance.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to retrieve statements for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
        - name: start_date
          in: query
          description: The start date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
        - name: end_date
          in: query
          description: The end date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
      responses:
        "200":
          description: Successfully retrieved the list of wallet statements.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The statements data.
                    properties:
                      statements:
                        type: array
                        description: The list of wallet statements.
                        items:
                          $ref: "#/components/schemas/WalletStatement"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /wallets/{wallet_id}/transactions:
    get:
      tags:
        - Transactions
      operationId: listWalletTransactions
      summary: List transactions
      description: Returns a list of transactions for the wallet. Use the filters to narrow results. Each transaction type returns a different shape, see the response schema for details.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to retrieve transactions for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
        - name: balance_id
          in: query
          description: The ID of the balance you want to filter based on.
          required: false
          schema:
            type: string
            pattern: "^(ica_|bca_).*"
        - name: status
          in: query
          description: The status of the transactions you want to filter based on.
          required: false
          schema:
            type: string
            enum:
              - processing
              - settled
              - requires-approval
              - declined
              - failed
              - cancelled
        - name: type
          in: query
          description: The type of the transactions you want to filter based on.
          required: false
          schema:
            type: string
            enum:
              - debit
              - credit
        - name: method
          in: query
          description: The method of the transactions you want to filter based on.
          required: false
          schema:
            type: string
            enum:
              - P2P
              - A2A
              - TopUp
              - Payout
              - EcomPay
        - name: limit
          in: query
          description: The maximum number of transactions to return.
          required: false
          schema:
            $ref: "#/components/schemas/LimitFilter"
        - name: start_date
          in: query
          description: The start date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
        - name: end_date
          in: query
          description: The end date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
      responses:
        "200":
          description: Successfully retrieved the list of wallet transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The transactions data.
                    properties:
                      transactions:
                        type: array
                        description: The list of wallet transactions.
                        items:
                          oneOf:
                            - $ref: "#/components/schemas/WalletOutboundTransaction"
                            - $ref: "#/components/schemas/WalletInboundTransaction"
                            - $ref: "#/components/schemas/WalletPayTransaction"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /wallets/{wallet_id}/transactions/{transaction_id}:
    get:
      tags:
        - Transactions
      operationId: getWalletTransaction
      summary: Retrieve a transaction
      description: Returns the full details of a single transaction.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to retrieve the transaction for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
        - name: transaction_id
          in: path
          description: The ID of the transaction to retrieve.
          required: true
          schema:
            type: string
            pattern: "^tra_.*$"
      responses:
        "200":
          description: Successfully retrieved transaction details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The transaction data.
                    oneOf:
                      - $ref: "#/components/schemas/WalletOutboundTransaction"
                      - $ref: "#/components/schemas/WalletInboundTransaction"
                      - $ref: "#/components/schemas/WalletPayTransaction"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /wallets/{wallet_id}/balances:
    get:
      tags:
        - Balances
      operationId: listWalletBalances
      summary: List balances
      description: Returns a list of all balances for the wallet, optionally filtered by type or currency.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to retrieve balances for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
        - name: type
          in: query
          description: The type of balances you want to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/WalletBalanceType"
        - name: currency
          in: query
          description: The currency you want to filter based on.
          required: false
          schema:
            type: string
            pattern: ^[A-Z]{3}$
      responses:
        "200":
          description: Successfully retrieved the list of wallet balances.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The balances data.
                    properties:
                      balances:
                        type: array
                        description: The list of wallet balances.
                        items:
                          $ref: "#/components/schemas/WalletBalance"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Balances
      operationId: createWalletBalance
      summary: Open a balance
      description: Opens a new currency balance within the wallet. Each balance is denominated in a single currency and backed by a treasurer account.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to open a balance for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
      requestBody:
        description: The title, currency, and type for the new balance.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostWalletBalanceRequest"
      responses:
        "200":
          description: Successfully created wallet balance.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /wallets/{wallet_id}/balances/{balance_id}:
    get:
      tags:
        - Balances
      operationId: getWalletBalance
      summary: Retrieve a balance
      description: Returns the details of a specific balance, including its running and holding amounts.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to retrieve the balance for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
        - name: balance_id
          in: path
          description: The ID of the balance to retrieve.
          required: true
          schema:
            type: string
            pattern: "^(bca_|ica_).*"
      responses:
        "200":
          description: Successfully retrieved wallet balance details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The balance data.
                    $ref: "#/components/schemas/WalletBalance"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    put:
      tags:
        - Balances
      operationId: updateWalletBalance
      summary: Update a balance
      description: Updates the title of an existing wallet balance.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to update the balance for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
        - name: balance_id
          in: path
          description: The ID of the balance to update.
          required: true
          schema:
            type: string
            pattern: "^(bca_|ica_).*"
      requestBody:
        description: The new title for the balance.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutWalletBalanceRequest"
      responses:
        "200":
          description: Successfully updated wallet balance.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Balances
      operationId: deleteWalletBalance
      summary: Close a balance
      description: Permanently closes a balance. The balance must be at zero before it can be closed. This action cannot be undone.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to close the balance for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
        - name: balance_id
          in: path
          description: The ID of the balance to close.
          required: true
          schema:
            type: string
            pattern: "^(bca_|ica_).*"
      responses:
        "200":
          description: Successfully removed wallet balance.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /wallets/{wallet_id}/accounts:
    get:
      tags:
        - Accounts
      operationId: listWalletAccounts
      summary: List connected accounts
      description: Returns a list of all bank accounts connected to the wallet, including their verification status.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to list accounts for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
      responses:
        "200":
          description: Successfully retrieved the list of wallet accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The accounts data.
                    properties:
                      accounts:
                        type: array
                        description: The list of wallet accounts.
                        items:
                          $ref: "#/components/schemas/WalletAccount"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Accounts
      operationId: createWalletAccount
      summary: Connect a bank account
      description: Connects a new bank account to the wallet. After connecting, a verification step is required before the account can be used for transfers.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to connect the account to.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
      requestBody:
        description: The account holder details, account number, and bank information.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostWalletAccountRequest"
      responses:
        "200":
          description: Successfully created wallet account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /wallets/{wallet_id}/accounts/{account_id}:
    get:
      tags:
        - Accounts
      operationId: getWalletAccount
      summary: Retrieve a connected account
      description: Returns the details of a specific connected bank account, including its verification status.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to retrieve the account for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
        - name: account_id
          in: path
          description: The ID of the account to retrieve.
          required: true
          schema:
            type: string
            pattern: "^cwa_.*$"
      responses:
        "200":
          description: Successfully retrieved wallet account details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The account data.
                    $ref: "#/components/schemas/WalletAccount"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    patch:
      tags:
        - Accounts
      operationId: verifyWalletAccount
      summary: Verify a bank account
      description: Confirms ownership of a connected bank account using the 6-digit verification code sent via micro-deposit.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to verify the account for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
        - name: account_id
          in: path
          description: The ID of the account to verify.
          required: true
          schema:
            type: string
            pattern: "^cwa_.*$"
      requestBody:
        description: The 6-digit verification code received via micro-deposit.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchWalletAccountRequest"
      responses:
        "200":
          description: Successfully verified wallet account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Accounts
      operationId: deleteWalletAccount
      summary: Remove a connected account
      description: Permanently removes a bank account from the wallet. Any pending transfers to this account will be cancelled. This action cannot be undone.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to remove the account from.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
        - name: account_id
          in: path
          description: The ID of the account to remove.
          required: true
          schema:
            type: string
            pattern: "^cwa_.*$"
      responses:
        "200":
          description: Successfully removed wallet account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /wallets/{wallet_id}/contacts:
    get:
      tags:
        - Contacts
      operationId: listWalletContacts
      summary: List contacts
      description: Returns a list of all saved contacts for the wallet.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to list contacts for.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
      responses:
        "200":
          description: Successfully retrieved the list of wallet contacts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The contacts data.
                    properties:
                      contacts:
                        type: array
                        description: The list of contacts.
                        items:
                          $ref: "#/components/schemas/WalletContact"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Contacts
      operationId: addWalletContact
      summary: Add a contact
      description: Adds a Paisr wallet user to your contacts by their cashtag. Once added, you can reference the contact by ID when initiating peer transfers.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to add the contact to.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
      requestBody:
        description: The cashtag of the wallet to add as a contact.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostWalletContactRequest"
      responses:
        "200":
          description: Successfully created wallet contact.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /wallets/{wallet_id}/contacts/{contact_id}:
    get:
      tags:
        - Contacts
      operationId: getWalletContact
      summary: Retrieve a contact
      description: Returns the details of a specific wallet contact.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to retrieve the contact from.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
        - name: contact_id
          in: path
          description: The ID of the contact to retrieve.
          required: true
          schema:
            type: string
            pattern: "^fav_.*$"
      responses:
        "200":
          description: Successfully retrieved wallet contact details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The contact data.
                    $ref: "#/components/schemas/WalletContact"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Contacts
      operationId: deleteWalletContact
      summary: Remove a contact
      description: Removes a contact from the wallet. This does not affect the other party's wallet in any way.
      parameters:
        - name: wallet_id
          in: path
          description: The ID of the wallet to remove the contact from.
          required: true
          schema:
            type: string
            pattern: "^(buw_|inw_).*"
        - name: contact_id
          in: path
          description: The ID of the contact to remove.
          required: true
          schema:
            type: string
            pattern: "^fav_.*$"
      responses:
        "200":
          description: Successfully removed wallet contact.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /transfers:
    post:
      tags:
        - Transfers
      operationId: initiateTransfer
      summary: Initiate a transfer
      description: Initiates a transfer using the specified method. P2P and ACH transfers require a cryptographic signature from the source wallet before funds are released. Use the Approve transfer endpoint to complete the flow, or Cancel transfer to abort it.
      requestBody:
        description: The source, destination, amount, and optional reference for the transfer.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostTransferRequest"
      responses:
        "200":
          description: Successfully initiated transfer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransferResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
  /transfers/{transaction_id}/approve:
    post:
      tags:
        - Transfers
      operationId: approveTransfer
      summary: Approve a transfer
      description: Approves a pending transfer by submitting a cryptographic signature generated by the source wallet. Once approved, the transfer is processed and funds are debited from the source balance. This action is irreversible.
      parameters:
        - name: transaction_id
          in: path
          description: The ID of the transaction to approve.
          required: true
          schema:
            type: string
            pattern: "^tra_.*$"
      requestBody:
        description: The wallet signature authorizing this transfer.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostApproveTransferRequest"
      responses:
        "200":
          description: Successfully approved transfer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /transfers/{transaction_id}/cancel:
    post:
      tags:
        - Transfers
      operationId: cancelTransfer
      summary: Cancel a transfer
      description: Cancels a pending transfer before it has been approved. Once a transfer is approved, it cannot be cancelled.
      parameters:
        - name: transaction_id
          in: path
          description: The ID of the transaction to cancel.
          required: true
          schema:
            type: string
            pattern: "^tra_.*$"
      requestBody:
        description: An optional note explaining the reason for cancellation.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostCancelTransferRequest"
      responses:
        "200":
          description: Successfully canceled transfer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /customers:
    get:
      tags:
        - Customers
      operationId: listCustomers
      summary: List customers
      description: Returns a list of all customers on your account.
      responses:
        "200":
          description: Successfully retrieved the list of customers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The customers data.
                    properties:
                      customers:
                        type: array
                        description: The list of customers.
                        items:
                          $ref: "#/components/schemas/Customer"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Customers
      operationId: createCustomer
      summary: Create a customer
      description: Creates a new customer. Once created, you can issue invoices and create subscriptions against them.
      requestBody:
        description: The customer's name, email, and optional billing and shipping details.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostCustomerRequest"
      responses:
        "200":
          description: Successfully created customer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerSessionResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
  /customers/{customer_id}:
    get:
      tags:
        - Customers
      operationId: getCustomer
      summary: Retrieve a customer
      description: Returns the details of a specific customer, including their billing details and active payment portal session.
      parameters:
        - name: customer_id
          in: path
          description: The ID of the customer to retrieve.
          required: true
          schema:
            type: string
            pattern: "^cus_.*$"
      responses:
        "200":
          description: Successfully retrieved customer details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The customer data.
                    $ref: "#/components/schemas/Customer"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    put:
      tags:
        - Customers
      operationId: updateCustomer
      summary: Update a customer
      description: Updates information on an existing customer.
      parameters:
        - name: customer_id
          in: path
          description: The ID of the customer to update.
          required: true
          schema:
            type: string
            pattern: "^cus_.*$"
      requestBody:
        description: The customer fields to update.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutCustomerRequest"
      responses:
        "200":
          description: Successfully updated customer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Customers
      operationId: deleteCustomer
      summary: Delete a customer
      description: Permanently deletes a customer. All associated invoices and subscriptions must be resolved before deletion. This action cannot be undone.
      parameters:
        - name: customer_id
          in: path
          description: The ID of the customer to delete.
          required: true
          schema:
            type: string
            pattern: "^cus_.*$"
      responses:
        "200":
          description: Successfully removed customer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /customers/{customer_id}/archive:
    post:
      tags:
        - Customers
      operationId: archiveCustomer
      summary: Archive a customer
      description: Archives a customer, hiding them from default list views. Archived customers retain all their historical data and can be restored at any time.
      parameters:
        - name: customer_id
          in: path
          description: The ID of the customer to archive.
          required: true
          schema:
            type: string
            pattern: "^cus_.*$"
      responses:
        "200":
          description: Successfully archived customer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /customers/{customer_id}/restore:
    post:
      tags:
        - Customers
      operationId: restoreCustomer
      summary: Restore a customer
      description: Restores an archived customer to active status, making them visible in list views again.
      parameters:
        - name: customer_id
          in: path
          description: The ID of the customer to restore.
          required: true
          schema:
            type: string
            pattern: "^cus_.*$"
      responses:
        "200":
          description: Successfully restored customer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /vouchers:
    get:
      tags:
        - Vouchers
      operationId: listVouchers
      summary: List vouchers
      description: Returns a list of all vouchers on your account.
      responses:
        "200":
          description: Successfully retrieved the list of vouchers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The vouchers data.
                    properties:
                      vouchers:
                        type: array
                        description: The list of vouchers.
                        items:
                          $ref: "#/components/schemas/Voucher"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Vouchers
      operationId: createVoucher
      summary: Create a voucher
      description: Creates a new discount voucher. Once created, share the code with customers to apply at checkout.
      requestBody:
        description: The voucher type, code, discount amount, and redemption limits.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostVoucherRequest"
      responses:
        "200":
          description: Successfully created voucher.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
  /vouchers/apply:
    post:
      tags:
        - Vouchers
      operationId: applyVoucher
      summary: Apply a voucher
      description: Applies a voucher code to an open invoice, calculating and recording the discount. A voucher can only be applied while the invoice is unpaid.
      requestBody:
        description: The invoice ID and voucher code to apply.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostApplyVoucherRequest"
      responses:
        "200":
          description: Successfully applied voucher.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
  /vouchers/{voucher_id}:
    get:
      tags:
        - Vouchers
      operationId: getVoucher
      summary: Retrieve a voucher
      description: Returns the details of a specific voucher, including its redemption count and expiry.
      parameters:
        - name: voucher_id
          in: path
          description: The ID of the voucher to retrieve.
          required: true
          schema:
            type: string
            pattern: "^vch_.*$"
      responses:
        "200":
          description: Successfully retrieved voucher details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The voucher data.
                    $ref: "#/components/schemas/Voucher"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    put:
      tags:
        - Vouchers
      operationId: updateVoucher
      summary: Update a voucher
      description: Updates the description, discount amount, redemption limit, or expiry of an existing voucher.
      parameters:
        - name: voucher_id
          in: path
          description: The ID of the voucher to update.
          required: true
          schema:
            type: string
            pattern: "^vch_.*$"
      requestBody:
        description: The voucher fields to update.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutVoucherRequest"
      responses:
        "200":
          description: Successfully updated voucher.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Vouchers
      operationId: deleteVoucher
      summary: Delete a voucher
      description: Permanently deletes a voucher. Invoices that have already had this voucher applied are not affected. This action cannot be undone.
      parameters:
        - name: voucher_id
          in: path
          description: The ID of the voucher to delete.
          required: true
          schema:
            type: string
            pattern: "^vch_.*$"
      responses:
        "200":
          description: Successfully removed voucher.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /plans:
    get:
      tags:
        - Plans
      operationId: listPlans
      summary: List plans
      description: Returns a list of all subscription plans on your account, optionally filtered by type, currency, or option status.
      parameters:
        - name: type
          in: query
          description: The type you want to filter based on.
          required: false
          schema:
            type: string
            enum:
              - standard
              - metered
        - name: currency
          in: query
          description: The currency you want to filter based on.
          required: false
          schema:
            type: string
            pattern: ^[A-Z]{3}$
        - name: active
          in: query
          description: The state of options you want to filter based on.
          required: false
          schema:
            type: boolean
        - name: limit
          in: query
          description: The number of plans to return.
          required: false
          schema:
            $ref: "#/components/schemas/LimitFilter"
      responses:
        "200":
          description: Successfully retrieved the list of plans.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The plans data.
                    properties:
                      plans:
                        type: array
                        description: The list of plans.
                        items:
                          $ref: "#/components/schemas/Plan"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Plans
      operationId: createPlan
      summary: Create a plan
      description: Creates a new subscription plan with one or more price options. Customers subscribe to individual options within a plan.
      requestBody:
        description: The plan title, currency, and initial price options.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostPlanRequest"
      responses:
        "200":
          description: Successfully created plan.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
  /plans/{plan_id}:
    get:
      tags:
        - Plans
      operationId: getPlan
      summary: Retrieve a plan
      description: Returns the details of a specific plan, including all of its price options.
      parameters:
        - name: plan_id
          in: path
          description: The ID of the plan to retrieve.
          required: true
          schema:
            type: string
            pattern: "^pln_.*$"
        - name: active
          in: query
          description: Filter by active options only.
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: Successfully retrieved plan details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The plan data.
                    $ref: "#/components/schemas/Plan"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    put:
      tags:
        - Plans
      operationId: updatePlan
      summary: Update a plan
      description: Updates the title, summary, or currency of an existing plan. Changing the currency does not affect active subscriptions.
      parameters:
        - name: plan_id
          in: path
          description: The ID of the plan to update.
          required: true
          schema:
            type: string
            pattern: "^pln_.*$"
      requestBody:
        description: The plan fields to update.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutPlanRequest"
      responses:
        "200":
          description: Successfully updated plan.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Plans
      operationId: deletePlan
      summary: Delete a plan
      description: Permanently deletes a plan. Plans with active subscribers cannot be deleted. This action cannot be undone.
      parameters:
        - name: plan_id
          in: path
          description: The ID of the plan to delete.
          required: true
          schema:
            type: string
            pattern: "^pln_.*$"
      responses:
        "200":
          description: Successfully removed plan.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /plans/{plan_id}/options:
    post:
      tags:
        - Plans
      operationId: addPlanOptions
      summary: Add price options
      description: Adds one or more price options to an existing plan. Each option defines a unit price, billing interval, and optional trial period.
      parameters:
        - name: plan_id
          in: path
          description: The ID of the plan to add options to.
          required: true
          schema:
            type: string
            pattern: "^pln_.*$"
      requestBody:
        description: An array of price options to add to the plan.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostPlanOptionRequest"
      responses:
        "200":
          description: Successfully created plan options.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /plans/{plan_id}/options/{option_id}:
    put:
      tags:
        - Plans
      operationId: updatePlanOption
      summary: Update a price option
      description: Updates the unit price, billing interval, trial period, or custom attributes on an existing price option.
      parameters:
        - name: plan_id
          in: path
          description: The ID of the plan to update.
          required: true
          schema:
            type: string
            pattern: "^pln_.*$"
        - name: option_id
          in: path
          description: The ID of the option to update.
          required: true
          schema:
            type: string
            pattern: "^plo_.*$"
      requestBody:
        description: The option fields to update.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutPlanOptionRequest"
      responses:
        "200":
          description: Successfully updated plan option.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    patch:
      tags:
        - Plans
      operationId: togglePlanOption
      summary: Toggle a price option
      description: Toggles a price option between active and inactive. Inactive options are hidden from new subscriptions but do not affect existing subscribers.
      parameters:
        - name: plan_id
          in: path
          description: The ID of the plan to toggle the option on.
          required: true
          schema:
            type: string
            pattern: "^pln_.*$"
        - name: option_id
          in: path
          description: The ID of the option to toggle.
          required: true
          schema:
            type: string
            pattern: "^plo_.*$"
      responses:
        "200":
          description: Successfully modified plan option.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Plans
      operationId: removePlanOption
      summary: Remove a price option
      description: Permanently removes a price option from a plan. Options with active subscribers cannot be removed.
      parameters:
        - name: plan_id
          in: path
          description: The ID of the plan to remove the option from.
          required: true
          schema:
            type: string
            pattern: "^pln_.*$"
        - name: option_id
          in: path
          description: The ID of the option to remove.
          required: true
          schema:
            type: string
            pattern: "^plo_.*$"
      responses:
        "200":
          description: Successfully removed plan option.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /invoices:
    get:
      tags:
        - Invoices
      operationId: listInvoices
      summary: List invoices
      description: Returns a list of invoices, optionally filtered by a related resource (customer, subscription, or voucher), currency, or status.
      parameters:
        - name: resource_id
          in: query
          description: The ID of the resource you want to filter based on. (e.g. Customer, Subscription or Voucher ID's)
          required: false
          schema:
            type: string
        - name: currency
          in: query
          description: The currency you want to filter based on.
          required: false
          schema:
            type: string
            pattern: ^[A-Z]{3}$
        - name: status
          in: query
          description: The status you want to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/InvoiceStatus"
        - name: limit
          in: query
          description: The number of items to return.
          required: false
          schema:
            $ref: "#/components/schemas/LimitFilter"
        - name: start_date
          in: query
          description: The start date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
        - name: end_date
          in: query
          description: The end date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
      responses:
        "200":
          description: Successfully retrieved the list of invoices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The invoices data.
                    properties:
                      invoices:
                        type: array
                        description: The list of invoices.
                        items:
                          $ref: "#/components/schemas/Invoice"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Invoices
      operationId: createInvoice
      summary: Create an invoice
      description: Creates a new invoice for a customer. The response includes a hosted checkout session URL that the customer can use to pay.
      requestBody:
        description: The customer, line items, currency, and optional due date for the invoice.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostInvoiceRequest"
      responses:
        "200":
          description: Successfully created invoice.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvoiceSessionResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
  /invoices/{invoice_id}:
    get:
      tags:
        - Invoices
      operationId: getInvoice
      summary: Retrieve an invoice
      description: Returns the full details of a specific invoice, including its line items, applied voucher, and payment session.
      parameters:
        - name: invoice_id
          in: path
          description: The ID of the invoice to retrieve.
          required: true
          schema:
            type: string
            pattern: "^inv_.*$"
      responses:
        "200":
          description: Successfully retrieved invoice details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    $ref: "#/components/schemas/InvoiceDetails"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    put:
      tags:
        - Invoices
      operationId: updateInvoice
      summary: Update an invoice
      description: Updates the summary, currency, or due date of an unpaid invoice.
      parameters:
        - name: invoice_id
          in: path
          description: The ID of the invoice to update.
          required: true
          schema:
            type: string
            pattern: "^inv_.*$"
      requestBody:
        description: The invoice fields to update.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutInvoiceRequest"
      responses:
        "200":
          description: Successfully updated invoice.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Invoices
      operationId: deleteInvoice
      summary: Delete an invoice
      description: Permanently deletes an unpaid invoice. Paid invoices cannot be deleted. This action cannot be undone.
      parameters:
        - name: invoice_id
          in: path
          description: The ID of the invoice to delete.
          required: true
          schema:
            type: string
            pattern: "^inv_.*$"
      responses:
        "200":
          description: Successfully removed invoice.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /invoices/{invoice_id}/send:
    post:
      tags:
        - Invoices
      operationId: sendInvoice
      summary: Send an invoice
      description: Delivers the invoice to the customer's email as a PDF attachment with a link to the hosted checkout session. Sending a paid invoice delivers a receipt instead.
      parameters:
        - name: invoice_id
          in: path
          description: The ID of the invoice to send.
          required: true
          schema:
            type: string
            pattern: "^inv_.*$"
      responses:
        "200":
          description: Successfully sent invoice.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /invoices/{invoice_id}/items:
    post:
      tags:
        - Invoices
      operationId: addInvoiceItems
      summary: Add line items
      description: Appends one or more line items to an unpaid invoice. Adding items to a paid invoice is not permitted.
      parameters:
        - name: invoice_id
          in: path
          description: The ID of the invoice to add items to.
          required: true
          schema:
            type: string
            pattern: "^inv_.*$"
      requestBody:
        description: An array of line items to add, each with a description, quantity, and unit price.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostInvoiceItemRequest"
      responses:
        "200":
          description: Successfully created invoice items.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /invoices/{invoice_id}/items/{item_id}:
    put:
      tags:
        - Invoices
      operationId: updateInvoiceItem
      summary: Update a line item
      description: Updates the description, quantity, or unit price of a line item on an unpaid invoice.
      parameters:
        - name: invoice_id
          in: path
          description: The ID of the invoice that contains the item to update.
          required: true
          schema:
            type: string
            pattern: "^inv_.*$"
        - name: item_id
          in: path
          description: The ID of the item to update.
          required: true
          schema:
            type: string
            description: The Item ID.
            pattern: "^itm_.*$"
      requestBody:
        description: The line item fields to update.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutInvoiceItemRequest"
      responses:
        "200":
          description: Successfully updated invoice item.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Invoices
      operationId: deleteInvoiceItem
      summary: Remove a line item
      description: Removes a line item from an unpaid invoice. The invoice totals are recalculated immediately.
      parameters:
        - name: invoice_id
          in: path
          description: The ID of the invoice that contains the item to delete.
          required: true
          schema:
            type: string
            pattern: "^inv_.*$"
        - name: item_id
          in: path
          description: The ID of the item to delete.
          required: true
          schema:
            type: string
            pattern: "^itm_.*$"
      responses:
        "200":
          description: Successfully removed invoice item.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /subscriptions:
    get:
      tags:
        - Subscriptions
      operationId: listSubscriptions
      summary: List subscriptions
      description: Returns a list of subscriptions, optionally filtered by a related resource (customer or payment method), currency, or status.
      parameters:
        - name: resource_id
          in: query
          description: The ID of the resource you want to filter based on. (e.g. Customer or Payment method ID's)
          required: false
          schema:
            type: string
        - name: currency
          in: query
          description: The currency you want to filter based on.
          required: false
          schema:
            type: string
            pattern: ^[A-Z]{3}$
        - name: status
          in: query
          description: The status you want to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/SubscriptionStatus"
        - name: limit
          in: query
          description: The number of results to return.
          required: false
          schema:
            $ref: "#/components/schemas/LimitFilter"
        - name: start_date
          in: query
          description: The start date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
        - name: end_date
          in: query
          description: The end date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
      responses:
        "200":
          description: Successfully retrieved the list of subscriptions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The subscriptions data.
                    properties:
                      subscriptions:
                        type: array
                        description: The list of subscriptions.
                        items:
                          $ref: "#/components/schemas/Subscription"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Subscriptions
      operationId: createSubscription
      summary: Create a subscription
      description: Creates a new subscription for a customer. The response includes a hosted payment session URL where the customer completes their initial payment method setup.
      requestBody:
        description: The customer, plan options, auto-renewal preference, and optional trial period.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostSubscriptionRequest"
      responses:
        "200":
          description: Successfully created subscription.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionSessionResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
  /subscriptions/{subscription_id}:
    get:
      tags:
        - Subscriptions
      operationId: getSubscription
      summary: Retrieve a subscription
      description: Returns the full details of a specific subscription, including its line items, billing schedule, and current status.
      parameters:
        - name: subscription_id
          in: path
          description: The ID of the subscription to retrieve.
          required: true
          schema:
            type: string
            pattern: "^sub_.*$"
      responses:
        "200":
          description: Successfully retrieved subscription details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    $ref: "#/components/schemas/SubscriptionDetails"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    patch:
      tags:
        - Subscriptions
      operationId: toggleAutoRenewal
      summary: Toggle auto-renewal
      description: Enables or disables automatic renewal for a subscription. Disabling auto-renewal allows the subscription to expire at the end of the current billing period without generating a new invoice.
      parameters:
        - name: subscription_id
          in: path
          description: The ID of the subscription to toggle auto-renewal for.
          required: true
          schema:
            type: string
            pattern: "^sub_.*$"
      responses:
        "200":
          description: Successfully modified subscription.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Subscriptions
      operationId: deleteSubscription
      summary: Delete a subscription
      description: Permanently deletes a subscription and all its associated data. Active subscriptions should be cancelled before deletion. This action cannot be undone.
      parameters:
        - name: subscription_id
          in: path
          description: The ID of the subscription to delete.
          required: true
          schema:
            type: string
            pattern: "^sub_.*$"
      responses:
        "200":
          description: Successfully removed subscription.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /subscriptions/{subscription_id}/restore:
    post:
      tags:
        - Subscriptions
      operationId: restoreSubscription
      summary: Restore a subscription
      description: Restores a subscription that entered a suspended. This triggers a new payment attempt using the customer's saved payment method.
      parameters:
        - name: subscription_id
          in: path
          description: The ID of the subscription to restore.
          required: true
          schema:
            type: string
            pattern: "^sub_.*$"
      responses:
        "200":
          description: Successfully restored subscription.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /subscriptions/{subscription_id}/cancel:
    post:
      tags:
        - Subscriptions
      operationId: cancelSubscription
      summary: Cancel a subscription
      description: Cancels an active subscription. The subscription remains accessible until the end of the current billing period, after which no further invoices are generated.
      parameters:
        - name: subscription_id
          in: path
          description: The ID of the subscription to cancel.
          required: true
          schema:
            type: string
            pattern: "^sub_.*$"
      responses:
        "200":
          description: Successfully cancelled subscription.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /payments:
    get:
      tags:
        - Payments
      operationId: listPayments
      summary: List payments
      description: Returns a list of payments, optionally filtered by invoice, currency, status, or payment method.
      parameters:
        - name: resource_id
          in: query
          description: The ID of the resource you want to filter based on (e.g. Invoice).
          required: false
          schema:
            type: string
        - name: currency
          in: query
          description: The currency you want to filter based on.
          required: false
          schema:
            type: string
            pattern: ^[A-Z]{3}$
        - name: status
          in: query
          description: The status you want to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/PaymentStatus"
        - name: method
          in: query
          description: The method you want to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/PaymentSourceType"
        - name: limit
          in: query
          description: The number of results to return.
          required: false
          schema:
            $ref: "#/components/schemas/LimitFilter"
        - name: start_date
          in: query
          description: The start date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
        - name: end_date
          in: query
          description: The end date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
      responses:
        "200":
          description: Successfully retrieved the list of payments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The payments data.
                    properties:
                      payments:
                        type: array
                        description: The list of payments.
                        items:
                          $ref: "#/components/schemas/Payment"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Payments
      operationId: initiatePayment
      summary: Initiate a payment
      description: >-
        Initiates a payment against an existing invoice. The response shape
        varies by method: wallet and bank payments return a redirect session URL,
        card payments are settled synchronously, and QR payments return a
        scannable code with an in-app deep link.
      requestBody:
        description: The invoice ID, payment method details, and billing information.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostPaymentRequest"
      responses:
        "200":
          description: Successfully initiated payment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "402":
          $ref: "#/components/responses/402Response"
        "403":
          $ref: "#/components/responses/403Response"
        "422":
          $ref: "#/components/responses/422Response"
        "500":
          $ref: "#/components/responses/500Response"
        "501":
          $ref: "#/components/responses/501Response"
  /payments/{payment_id}:
    get:
      tags:
        - Payments
      operationId: getPayment
      summary: Retrieve a payment
      description: Returns the full details of a specific payment, including its amount breakdown, billing details, and current lifecycle status.
      parameters:
        - name: payment_id
          in: path
          description: The ID of the payment to retrieve.
          required: true
          schema:
            type: string
            pattern: "^pmt_.*$"
      responses:
        "200":
          description: Successfully retrieved payment details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The payment data.
                    $ref: "#/components/schemas/Payment"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
  /payments/{payment_id}/refund:
    post:
      tags:
        - Payments
      operationId: refundPayment
      summary: Refund a payment
      description: Issues a full refund against a settled or approved payment. If attached to an invoice, the invoice status will return to an unpaid state.
      parameters:
        - name: payment_id
          in: path
          description: The ID of the payment to refund.
          required: true
          schema:
            type: string
            pattern: "^pmt_.*$"
      requestBody:
        description: The refund type (full or partial), optional amount, and optional reason note.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostRefundPaymentRequest"
      responses:
        "200":
          description: Successfully refunded payment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /providers:
    get:
      tags:
        - Provider Connections
      operationId: listProviders
      summary: List provider connections
      description: Returns a list of all payment provider connections on your account, including their status and supported currencies.
      responses:
        "200":
          description: Successfully retrieved the list of providers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The providers data.
                    properties:
                      providers:
                        type: array
                        description: The list of payment providers.
                        items:
                          $ref: "#/components/schemas/PaymentProvider"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Provider Connections
      operationId: connectProvider
      summary: Connect a provider
      description: Connects a new payment provider using your provider-specific API credentials. Once connected, the provider becomes available as a payment method for initiating payments.
      requestBody:
        description: The provider slug and API credentials.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostProviderRequest"
      responses:
        "200":
          description: Successfully connected provider.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
  /providers/{connection_id}:
    put:
      tags:
        - Provider Connections
      operationId: updateProvider
      summary: Update a connection
      description: Replaces the API credentials stored for a provider connection. Use this when rotating API keys with your payment provider.
      parameters:
        - name: connection_id
          in: path
          description: The ID of the provider connection to update.
          required: true
          schema:
            type: string
            pattern: "^bpc_.*$"
      requestBody:
        description: The updated merchant ID and secret key.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutProviderRequest"
      responses:
        "200":
          description: Successfully updated provider connection.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    patch:
      tags:
        - Provider Connections
      operationId: toggleProviderConnection
      summary: Enable or disable a connection
      description: Toggles a provider connection between enabled and disabled. Disabled connections cannot be used to process payments.
      parameters:
        - name: connection_id
          in: path
          description: The ID of the provider connection to toggle.
          required: true
          schema:
            type: string
            pattern: "^bpc_.*$"
      responses:
        "200":
          description: Successfully modified provider connection.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Provider Connections
      operationId: disconnectProvider
      summary: Disconnect a provider
      description: Permanently removes a provider connection. Any payment methods linked to this provider will no longer function. This action cannot be undone.
      parameters:
        - name: connection_id
          in: path
          description: The ID of the provider connection to disconnect.
          required: true
          schema:
            type: string
            pattern: "^bpc_.*$"
      responses:
        "200":
          description: Successfully removed provider connection.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /pages:
    get:
      tags:
        - Static Pages
      operationId: listStaticPages
      summary: List static pages
      description: Returns a list of all static payment pages on your account, including their session.
      responses:
        "200":
          description: Successfully retrieved the list of pages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The pages data.
                    properties:
                      pages:
                        type: array
                        description: The list of static pages.
                        items:
                          $ref: "#/components/schemas/StaticPage"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
    post:
      tags:
        - Static Pages
      operationId: createStaticPage
      summary: Create a page
      description: Creates a new static payment page with a 30-day session.
      requestBody:
        description: The page description and fields.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostStaticPageRequest"
      responses:
        "200":
          description: Successfully created page.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageSessionResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"
  /pages/{page_id}:
    put:
      tags:
        - Static Pages
      operationId: updateStaticPage
      summary: Update a page
      description: Update the configuration of a page.
      parameters:
        - name: page_id
          in: path
          description: The ID of the page to update.
          required: true
          schema:
            type: string
            pattern: "^stp_.*$"
      requestBody:
        description: The page description and fields.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostStaticPageRequest"
      responses:
        "200":
          description: Successfully updated page.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"
    delete:
      tags:
        - Static Pages
      operationId: deleteStaticPage
      summary: Delete a page
      description: Permanently removes a page. This action cannot be undone.
      parameters:
        - name: page_id
          in: path
          description: The ID of the page to delete.
          required: true
          schema:
            type: string
            pattern: "^stp_.*$"
      responses:
        "200":
          description: Successfully removed page.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaseResponse"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "404":
          $ref: "#/components/responses/404Response"
        "500":
          $ref: "#/components/responses/500Response"

  /metrics:
    get:
      tags:
        - Metrics
      operationId: getMetrics
      summary: Retrieve metrics for analytical purposes
      description: Returns the corresponding metrics based on the provided filter
      parameters:
        - name: filter
          in: query
          description: The resource to filter based on
          required: false
          schema:
            type: string
            enum:
              - volume
              - payments
              - customers
              - invoices
              - subscriptions
            example: volume
        - name: start_date
          in: query
          description: The start date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
        - name: end_date
          in: query
          description: The end date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
      responses:
        "200":
          description: Successfully retrieved metrics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    description: The metrics data.
                    oneOf:
                      - $ref: "#/components/schemas/VolumeMetrics"
                      - $ref: "#/components/schemas/CustomerMetrics"
                      - $ref: "#/components/schemas/InvoiceMetrics"
                      - $ref: "#/components/schemas/SubscriptionMetrics"
                      - $ref: "#/components/schemas/PaymentMetrics"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"

  /logs:
    get:
      tags:
        - Logs
      operationId: listLogs
      summary: List API logs
      description: Returns a paginated list of API request logs for your account. Logs include the request method, route, authentication flow, response status, and response body. Use the filters to narrow results to a specific resource, HTTP method, or auth flow.
      parameters:
        - name: resource_id
          in: query
          description: Filter logs by a specific resource ID. Defaults to the account profile ID if not provided.
          required: false
          schema:
            type: string
        - name: method
          in: query
          description: The method to filter based on.
          required: false
          schema:
            type: string
            enum:
              - GET
              - POST
              - PUT
              - PATCH
              - DELETE
        - name: auth_flow
          in: query
          description: The authentication flow to filter based on.
          required: false
          schema:
            type: string
            enum:
              - token
              - user
        - name: limit
          in: query
          description: The number of logs to return in the response.
          required: false
          schema:
            $ref: "#/components/schemas/LimitFilter"
        - name: start_date
          in: query
          description: The start date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
        - name: end_date
          in: query
          description: The end date to filter based on.
          required: false
          schema:
            $ref: "#/components/schemas/DateFilter"
      responses:
        "200":
          description: Successfully retrieved the list of logs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: "#/components/schemas/SuccessState"
                  data:
                    type: object
                    description: The logs data.
                    properties:
                      logs:
                        type: array
                        description: The list of audit logs.
                        items:
                          $ref: "#/components/schemas/AuditLog"
        "400":
          $ref: "#/components/responses/400Response"
        "401":
          $ref: "#/components/responses/401Response"
        "403":
          $ref: "#/components/responses/403Response"
        "500":
          $ref: "#/components/responses/500Response"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token for authentication.

  schemas:
    # Filters
    DateFilter:
      type: string
      example: 2026-10-01
      description: The date to filter based on
    LimitFilter:
      type: number
      description: The number of results to return in the response.
      minimum: 1
      maximum: 1000

    # States
    SuccessState:
      type: boolean
      example: true
      description: Indicates that the request was successful.
      default: true
    FailureState:
      type: boolean
      example: false
      description: Indicates that the request was unsuccessful.
      default: false

    # Responses
    BaseResponse:
      type: object
      properties:
        success:
          $ref: "#/components/schemas/SuccessState"
        message:
          type: string
          description: A descriptive message regarding the result.
          example: Request was successful.
    DataResponse:
      type: object
      properties:
        success:
          $ref: "#/components/schemas/SuccessState"
        data:
          type: object
          description: The data of the newly created resource.
          properties:
            id:
              type: string
              description: The ID of the newly created resource.
    InvoiceSessionResponse:
      type: object
      properties:
        success:
          $ref: "#/components/schemas/SuccessState"
        data:
          type: object
          description: Invoice session data.
          properties:
            id:
              type: string
              description: The ID of the newly created invoice.
              example: inv_123456
            status:
              type: string
              description: The status of the newly created invoice.
              example: unpaid
            session:
              $ref: "#/components/schemas/InvoiceSessionData"
    SubscriptionSessionResponse:
      type: object
      properties:
        success:
          $ref: "#/components/schemas/SuccessState"
        data:
          type: object
          description: Subscription session data.
          properties:
            id:
              type: string
              description: The ID of the newly created subscription.
              example: sub_123456
            status:
              type: string
              description: The status of the newly created subscription.
              example: pending
            session:
              $ref: "#/components/schemas/InvoiceSessionData"
    CustomerSessionResponse:
      type: object
      properties:
        success:
          $ref: "#/components/schemas/SuccessState"
        data:
          type: object
          description: Customer session data.
          properties:
            id:
              type: string
              description: The ID of the newly created customer.
              example: cus_123456
            session:
              $ref: "#/components/schemas/CustomerSessionData"
    PageSessionResponse:
      type: object
      properties:
        success:
          $ref: "#/components/schemas/SuccessState"
        data:
          type: object
          description: Page session data.
          properties:
            id:
              type: string
              description: The ID of the newly created page.
              example: stp_123456
            session:
              $ref: "#/components/schemas/PageSessionData"
    TokenResponse:
      type: object
      properties:
        success:
          $ref: "#/components/schemas/SuccessState"
        data:
          type: object
          description: The data of the newly created token.
          properties:
            id:
              type: string
              description: The ID of the newly created token.
              example: tkn_123456
            secret:
              type: string
              description: The secret key of the token. This is not viewable after so make sure to save it somewhere safe.
              example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
    WebhookSecretResponse:
      type: object
      properties:
        success:
          $ref: "#/components/schemas/SuccessState"
        data:
          type: object
          description: The data of the newly created webhook.
          properties:
            id:
              type: string
              description: The ID of the newly created webhook.
              example: whk_123456
            secret:
              type: string
              description: The webhook signing secret.
              example: ey7bTCm6tur63CR6mzbuq23r
    TransferResponse:
      type: object
      properties:
        success:
          $ref: "#/components/schemas/SuccessState"
        data:
          type: object
          description: The transfer data.
          properties:
            id:
              type: string
              description: The ID of the newly created transfer.
              example: tra_123456
            status:
              type: string
              description: The status of the newly created transfer.
              example: pending-approval
    PaymentResponse:
      type: object
      properties:
        success:
          $ref: "#/components/schemas/SuccessState"
        data:
          type: object
          description: The payment response data.
          properties:
            id:
              type: string
              description: The ID of the newly created payment.
              example: pmt_123456
            status:
              type: string
              description: The status of the newly created payment.
              example: pending
            next_action:
              type: object
              description: The next action to take for the payment.
              oneOf:
                - $ref: "#/components/schemas/NextActionPresentOrTrigger"
                - $ref: "#/components/schemas/NextActionRedirect"

    # Enums
    WalletType:
      type: string
      enum:
        - fiat
      example: fiat
      description: Type of wallet.
    WalletIconType:
      type: string
      enum:
        - bitcoin
        - blend
        - dollar-sign
        - flame
        - gem
        - headset
        - heart
        - infinity
        - landmark
        - leaf
        - piggy-bank
        - pyramid
        - snowflake
        - sparkles
        - tree-palm
        - trophy
        - vault
        - wallet
        - zap
      example: wallet
      description: Custom icon of the wallet
    WalletBalanceType:
      type: string
      enum:
        - primary
        - saving
      example: primary
      description: Type of balance.
    WalletAccountType:
      type: string
      enum:
        - checking
        - saving
      example: checking
      description: Type of account.
    RateType:
      type: string
      enum:
        - percentage
        - fixed
      example: percentage
      description: The applicable rate type.
    CurrencyType:
      type: string
      enum:
        - SRD
        - USD
        - EUR
      example: SRD
      description: Currency code in ISO 4217 format.
    BankSwiftType:
      type: string
      enum:
        - SURBSRPA
        - FBNASRPA
        - GODOSRPA
        - HAKRSRPA
        - RBNKSRPA
        - SOUOSRPP
        - BOTBBSNS
        - NOSCBSNS
        - COMWBSNS
        - ROYCBSNS
        - BTAMBSNS
        - FCIBBSNS
        - CITIBSNA
        - SDPOSRPA
        - SURCSRPA
      example: SOUOSRPP
      description: Swift Code of the bank.
    InvoiceStatus:
      type: string
      description: Status of the invoice.
      enum:
        - draft
        - unpaid
        - paid
        - void
      example: paid
      default: draft
    SubscriptionStatus:
      type: string
      description: Status of the subscription.
      enum:
        - pending
        - expired
        - trial
        - active
        - suspended
        - cancelled
      example: active
    PaymentStatus:
      type: string
      description: Status of the payment.
      enum:
        - pending
        - failed
        - approved
        - settled
        - refunded
        - cancelled
      example: approved
      default: pending
    PaymentSourceType:
      type: string
      description: Type of payment method.
      enum:
        - wallet
        - qr
        - card
        - bank
        - other
      example: wallet
    PaymentProviderType:
      type: string
      enum:
        - pcb
        - pbb
        - card
        - uni5pay
        - mope
        - lightning
      example: card
      description: Unique slug for the provider.

    QrCodeProvider:
      type: string
      description: The slug of the QR code provider.
      enum:
        - uni5pay
        - mope
        - lightning
      example: uni5pay
    WalletProvider:
      type: string
      description: The slug of the wallet provider.
      enum:
        - pcb
      example: pcb

    # Data Schemas
    InvoiceSessionData:
      type: object
      description: The session details for collecting payment
      properties:
        url:
          type: string
          description: The checkout url
          example: https://checkout.paisr.tech/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
        expires_at:
          type: string
          description: Session expiration time.
          format: date-time
    CustomerSessionData:
      type: object
      description: The session details for the customer
      properties:
        url:
          type: string
          description: The customer portal url
          example: https://portal.paisr.tech/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
        expires_at:
          type: string
          description: Session expiration time.
          format: date-time
    PageSessionData:
      type: object
      description: The session details for the page
      properties:
        url:
          type: string
          description: The payment page url
          example: https://page.paisr.tech/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
        expires_at:
          type: string
          description: Session expiration time.
          format: date-time

    QrPaymentData:
      type: object
      title: QR
      required:
        - provider
      properties:
        provider:
          $ref: "#/components/schemas/QrCodeProvider"
    BankPaymentData:
      type: object
      title: Bank
      required:
        - swift_code
      properties:
        swift_code:
          $ref: "#/components/schemas/BankSwiftType"
        redirect_url:
          type: string
          format: uri
          description: The url to redirect the customer to after completing their payment
          example: https://your-company.com/callback
    WalletPaymentData:
      type: object
      title: Wallet
      required:
        - provider
      properties:
        provider:
          $ref: "#/components/schemas/WalletProvider"
        redirect_url:
          type: string
          format: uri
          description: The url to redirect the customer to after completing their payment
          example: https://your-company.com/callback
    CardPaymentData:
      type: object
      title: Card
      required:
        - holder_name
        - number
        - expiry
        - cvc
      properties:
        holder_name:
          type: string
          description: The full name of the card holder
          example: John Doe
        number:
          type: string
          description: The 16-19 digit card number. Never submit plain card details unless you have a valid reason for doing so and are fully compliant with PCI DSS.
          example: "4111111111111111"
        cvc:
          type: string
          description: The 3-4 digit CVC or PIN. Never submit plain CVC or PIN details unless you have a valid reason for doing so and are fully compliant with PCI DSS.
          example: "123"
        expiry:
          type: object
          required:
            - month
            - year
          description: The expiration details
          properties:
            month:
              type: string
              description: Expiration month (MM)
              example: "12"
              lenght: 2
            year:
              type: string
              description: Expiration year (YY)
              example: "28"
              lenght: 2

    NextActionRedirect:
      type: object
      title: Redirect action
      properties:
        type:
          type: string
          default: redirect
          description: The type of action to perform
        provider:
          type: string
          description: The provider slug
        redirect_url:
          type: string
          description: The url to redirect the customer to
          default: https://wallet.paisr.tech/pay/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
    NextActionPresentOrTrigger:
      type: object
      title: Present or trigger action
      properties:
        type:
          type: string
          default: present_or_trigger
          description: The type of action to perform
        provider:
          type: string
          description: The provider slug
        qr_code:
          type: string
          description: The encoded code value. Present this value as a QR code to the customer
        deep_link:
          type: string
          description: The deeplink url used to trigger the app on the customer's device

    AuditLog:
      type: object
      properties:
        timestamp:
          type: string
          description: The date and time the audit log entry was created.
          format: date-time
        method:
          type: string
          enum:
            - GET
            - PUT
            - POST
            - PATCH
            - DELETE
          example: POST
          description: The HTTP method used for the request.
        route:
          type: string
          example: /v2/wallets
          description: The route of the request.
        user_agent:
          type: string
          example: PostmanRuntime
          description: The user agent of the request.
        request:
          type: object
          description: The request details.
          properties:
            body:
              type: object
              description: The request body.
              example: {}
        response:
          type: object
          description: The response details.
          properties:
            status:
              type: number
              description: The HTTP status code of the response.
              example: 200
            body:
              type: object
              description: The response body.
              example: {}
        auth:
          type: object
          description: The authentication details.
          properties:
            flow:
              type: string
              enum:
                - token
                - user
              example: token
              description: The authentication flow type.
            uuid:
              type: string
              example: tkn_123456
              description: The authentication UUID.

    AccessToken:
      type: object
      properties:
        id:
          type: string
          description: The access token ID.
          example: tkn_123456
        description:
          type: string
          description: The access token description.
          example: Postman
        permissions:
          type: array
          description: The list of permissions granted by the access token.
          items:
            type: object
            properties:
              id:
                type: string
                description: The permission ID.
                example: tpm_12345
              type:
                type: string
                description: The permission type.
                example: invoices.read
        created_at:
          type: string
          format: date-time
          description: The date and time the access token was created.
        created_by:
          type: string
          description: The ID of the member or token that created the access token.
          example: tem_123456
        expires_at:
          type: string
          format: date-time
          description: The date and time the access token expires.

    Webhook:
      type: object
      properties:
        id:
          type: string
          description: The ID of the webhook.
          example: whk_123456
        description:
          type: string
          description: The description of the webhook.
          example: Checkout Callback
        endpoint:
          type: string
          format: uri
          description: The endpoint URL of the webhook.
          example: https://api.example.com/callback
        paused:
          type: boolean
          description: Whether the webhook is paused.
          example: false
        triggers:
          type: array
          description: The list of triggers for the webhook.
          items:
            type: object
            properties:
              id:
                type: string
                description: The ID of the trigger.
                example: wtr_12345
              type:
                type: string
                description: The type of the trigger.
                example: invoice.paid
        created_at:
          type: string
          format: date-time
          description: The date and time the webhook was created.
        created_by:
          type: string
          description: The ID of the member who created the webhook.
          example: tem_123456
    WebhookStats:
      type: object
      description: The webhook stats.
      properties:
        success:
          type: number
          description: The number of successful webhook events.
          example: 10
        failed:
          type: number
          description: The number of failed webhook events.
          example: 2
        pending:
          type: number
          description: The number of pending webhook events.
          example: 0
    WebhookSecret:
      type: object
      description: The webhook secret.
      properties:
        secret:
          type: string
          description: The webhook signing secret.
          example: ey7bTCm6tur63CR6mzbuq23r
    WebhookEvent:
      type: object
      properties:
        id:
          type: string
          description: The webhook event ID.
          example: wev_123456
        body:
          type: object
          description: The webhook event body.
          properties:
            id:
              type: string
              description: The ID of the resource that triggered the webhook event.
              example: inv_123456
            event:
              type: string
              description: The type of event that triggered the webhook.
              example: invoice.paid
        status:
          type: string
          description: The webhook event status.
          enum:
            - pending
            - success
            - failed
          example: success
        type:
          type: string
          description: The webhook event type.
          example: invoice.paid
        can_retry:
          type: boolean
          description: Whether the webhook event can be retried.
          default: false
        retry_count:
          type: number
          description: The number of times the webhook event has been retried.
          default: 0
        last_retry_at:
          type: string
          description: The date and time the webhook event was last retried.
          format: date-time
        next_retry_at:
          type: string
          description: The date and time the webhook event will be retried next.
          format: date-time
        created_at:
          type: string
          description: The date and time the webhook event was created.
          format: date-time

    Wallet:
      type: object
      properties:
        id:
          type: string
          description: The ID of the wallet.
          example: buw_123456
        beneficiary:
          type: object
          description: The beneficiary details.
          properties:
            name:
              type: string
              description: The name of the beneficiary.
              example: Acme Inc
            email:
              type: string
              description: The email of the beneficiary.
              example: finance@acme.com
        profile:
          type: object
          description: The profile details.
          properties:
            nickname:
              type: string
              description: The nickname of the profile.
              example: Acme
            cashtag:
              type: string
              description: The cashtag of the profile.
              example: acmeinc
            preview_url:
              type: string
              description: The payment URL of the profile.
              example: https://wallet.paisr.tech/pay/me/acmeinc
            public:
              type: boolean
              description: Whether the profile is public.
              example: false
        pin:
          type: object
          description: The PIN details.
          properties:
            is_set:
              type: boolean
              description: Whether the PIN is set.
              example: false
            updated_at:
              type: string
              description: The date and time the PIN was last updated.
              format: date-time
        icon:
          type: string
          description: The icon of the wallet.
          example: vault
        title:
          type: string
          description: The title of the wallet.
          example: Cash Wallet
        locked:
          type: boolean
          description: Whether the wallet is locked.
          example: false
        default:
          type: boolean
          description: Whether the wallet is the default wallet.
          example: true
        type:
          $ref: "#/components/schemas/WalletType"
        sub_type:
          type: string
          enum:
            - personal
            - business
          example: business
          description: The sub-type of the wallet.
        usage:
          type: object
          description: The usage and limits of the wallet.
          properties:
            transfers:
              type: object
              description: The transfers usage and limits of the wallet.
              properties:
                current:
                  type: number
                  format: float
                  description: The current balance of transfers.
                  example: 3598.75
                max:
                  type: number
                  format: float
                  description: The maximum balance of transfers.
                  example: 25000
            deposits:
              type: object
              description: The deposits usage and limits of the wallet.
              properties:
                current:
                  type: number
                  format: float
                  description: The current balance of deposits.
                  example: 550
                max:
                  type: number
                  format: float
                  description: The maximum balance of deposits.
                  example: 5000
            withdrawals:
              type: object
              description: The withdrawals usage and limits of the wallet.
              properties:
                current:
                  type: number
                  format: float
                  description: The current balance of withdrawals.
                  example: 4075
                max:
                  type: number
                  format: float
                  description: The maximum balance of withdrawals.
                  example: 25000
            resets_at:
              type: string
              description: The date and time when the limits reset.
              format: date-time
        created_at:
          type: string
          description: The date and time when the wallet was created.
          format: date-time
    WalletBalance:
      type: object
      properties:
        id:
          type: string
          description: The balance ID.
          example: bca_123456
        title:
          type: string
          description: The balance title.
          example: SRD Balance
        currency:
          $ref: "#/components/schemas/CurrencyType"
        balance:
          type: object
          description: The balance details.
          properties:
            running:
              type: number
              format: float
              description: The running balance.
              example: 2802.75
            holding:
              type: number
              format: float
              description: The holding balance.
              example: 0
        frozen:
          type: boolean
          description: Whether the balance is frozen.
          example: false
        type:
          $ref: "#/components/schemas/WalletBalanceType"
        treasurer:
          type: object
          description: The treasurer details.
          properties:
            name:
              type: string
              description: The name of the treasurer.
              example: PAISR Treasury
            iban:
              type: string
              description: The IBAN of the treasurer.
              example: ABC123456789
            type:
              type: string
              description: The type of the treasurer.
              example: checking
            bank:
              type: object
              description: The bank details.
              properties:
                name:
                  type: string
                  description: The name of the bank.
                  example: Southern Commercial Bank
                swift:
                  $ref: "#/components/schemas/BankSwiftType"
        created_at:
          type: string
          description: The date and time the balance was created.
          format: date-time
    WalletAccount:
      type: object
      properties:
        id:
          type: string
          description: The account ID.
          example: cwa_123456
        account_holder:
          type: string
          description: The name of the account holder.
          example: John Doe
        account_number:
          type: string
          description: The account number.
          example: "AC123456789"
        routing_number:
          type: string
          description: The routing number. Available on US accounts.
          example: "123456789"
        account_type:
          $ref: "#/components/schemas/WalletAccountType"
        currency:
          $ref: "#/components/schemas/CurrencyType"
        verified:
          type: boolean
          description: Whether the account is verified.
          example: true
        bank:
          type: object
          description: The bank details.
          properties:
            name:
              type: string
              description: The bank name.
              example: Southern Commercial Bank
            swift_code:
              $ref: "#/components/schemas/BankSwiftType"
        created_at:
          type: string
          description: The date and time the account was created.
          format: date-time
    WalletContact:
      type: object
      properties:
        id:
          type: string
          description: The contact ID.
          example: fav_123456
        full_name:
          type: string
          description: The full name of the contact.
          example: Jane Smith
        nickname:
          type: string
          description: The nickname of the contact.
          example: Jane
        cashtag:
          type: string
          description: The cashtag of the contact.
          example: janesmith
        avatar:
          type: string
          description: The avatar of the contact.
          example: https://gravatar.com/avatars/uhofasobobao
        created_at:
          type: string
          description: The date and time the contact was created.
          format: date-time
    WalletStatement:
      type: object
      properties:
        id:
          type: string
          description: The statement ID.
          example: wst_123456
        timeline:
          type: string
          description: The timeline of the statement.
          example: November 2023
        source:
          type: string
          description: The source of the statement.
          example: https://files.paisr.tech/statements/wst_123456
        created_at:
          type: string
          description: The date and time the statement was created.
          format: date-time
    WalletPayTransaction:
      title: E-Commerce
      type: object
      properties:
        id:
          type: string
          description: The transaction ID.
          example: tra_123456
        type:
          type: string
          enum:
            - debit
          example: debit
          description: The transaction type.
        method:
          type: string
          enum:
            - EcomPay
          description: The transaction method.
        status:
          type: string
          enum:
            - processing
            - settled
          description: The transaction status.
          example: settled
        destination:
          type: object
          description: The transaction destination.
          properties:
            name:
              type: string
              description: The destination name.
              example: Acme Inc
        quote:
          type: object
          description: The transaction quote.
          properties:
            base:
              type: object
              description: The base quote.
              properties:
                total:
                  type: number
                  format: float
                  description: The total amount of the base quote.
                  example: 100.0
                currency:
                  type: string
                  description: The currency of the base quote.
                  example: SRD
            tax:
              type: object
              description: The tax quote.
              properties:
                collected:
                  type: boolean
                  description: Whether the tax is collected.
                  example: true
                country:
                  type: string
                  description: The country of the tax.
                  example: SR
                type:
                  type: string
                  description: The type of tax.
                  example: VAT
                rate:
                  type: number
                  format: float
                  description: The tax rate.
                  example: 0.10
                total:
                  type: number
                  format: float
                  description: The total amount of the tax.
                  example: 10.0
            due:
              type: object
              description: The due quote.
              properties:
                total:
                  type: number
                  format: float
                  description: The total amount of the due quote.
                  example: 110.0
                currency:
                  type: string
                  description: The currency of the due quote.
                  example: SRD
        reference:
          type: string
          description: The reference of the transaction.
          example: "Payment for Invoice #199027"
        balance_before:
          type: number
          description: The balance before the transaction.
          example: 75.00
        balance_after:
          type: number
          description: The balance after the transaction.
          example: 50.00
        created_at:
          type: string
          description: The date and time the transaction was created.
          format: date-time
        processed_at:
          type: string
          description: The date and time the transaction was processed.
          format: date-time
    WalletOutboundTransaction:
      title: Outbound
      type: object
      properties:
        id:
          type: string
          description: The transaction ID.
          example: tra_123456
        type:
          type: string
          enum:
            - debit
          example: debit
          description: The transaction type.
        method:
          type: string
          enum:
            - P2P
            - A2A
            - ACH
          example: P2P
          description: The transaction method.
        status:
          type: string
          enum:
            - pending
            - processing
            - settled
            - requires-approval
            - cancelled
          example: processing
          description: The transaction status.
        destination:
          type: object
          description: The destination of the transaction.
          properties:
            name:
              type: string
              example: Jane Smith
              description: The name of the destination.
        quote:
          type: object
          description: The quote for the transaction.
          properties:
            base:
              type: object
              description: The base quote.
              properties:
                total:
                  type: number
                  format: float
                  description: The total amount of the base quote.
                  example: 100.0
                currency:
                  type: string
                  example: SRD
                  description: The currency of the base quote.
            tax:
              type: object
              description: The tax quote.
              properties:
                collected:
                  type: boolean
                  description: Whether the tax is collected.
                  example: false
                country:
                  type: string
                  description: The country of the tax.
                  example: SR
                type:
                  type: string
                  description: The type of the tax.
                  example: VAT
                rate:
                  type: number
                  format: float
                  description: The rate of the tax.
                  example: 0
                total:
                  type: number
                  format: float
                  description: The total amount of the tax.
                  example: 0
            fee:
              type: object
              description: The fee quote.
              properties:
                conversion:
                  type: object
                  description: The conversion fee.
                  properties:
                    rate:
                      type: number
                      format: float
                      description: The rate of the conversion fee.
                      example: 0
                    total:
                      type: number
                      format: float
                      description: The total amount of the conversion fee.
                      example: 0
                interchange:
                  type: object
                  description: The interchange fee.
                  properties:
                    rate:
                      type: number
                      format: float
                      description: The rate of the interchange fee.
                      example: 0
                    total:
                      type: number
                      format: float
                      description: The total amount of the interchange fee.
                      example: 0
                total:
                  type: number
                  format: float
                  description: The total amount of the fee.
                  example: 0
            due:
              type: object
              description: The due quote.
              properties:
                total:
                  type: number
                  format: float
                  description: The total amount of the due quote.
                  example: 100
                currency:
                  type: string
                  description: The currency of the due quote.
                  example: SRD
            conversion:
              type: object
              description: The conversion quote.
              properties:
                input:
                  type: number
                  format: float
                  description: The input amount.
                  example: 100
                from:
                  type: string
                  description: The currency of the input amount.
                  example: SRD
                to:
                  type: string
                  description: The currency of the output amount.
                  example: SRD
                rate:
                  type: number
                  format: float
                  description: The exchange rate of the conversion.
                  example: 1
                total:
                  type: number
                  format: float
                  description: The total amount of the output.
                  example: 100.0
            output:
              type: object
              description: The output quote.
              properties:
                total:
                  type: number
                  format: float
                  description: The total amount of the output.
                  example: 100.0
                currency:
                  type: string
                  description: The currency of the output amount.
                  example: SRD
        reference:
          type: string
          description: The reference of the transaction.
          example: For services rendered
        balance_before:
          type: number
          description: The balance before the transaction.
          example: 75.00
        balance_after:
          type: number
          description: The balance after the transaction.
          example: 50.00
        created_at:
          type: string
          description: The date and time the transaction was created.
          format: date-time
        processed_at:
          type: string
          description: The date and time the transaction was processed.
          format: date-time
    WalletInboundTransaction:
      title: Inbound
      type: object
      properties:
        id:
          type: string
          description: The transaction ID.
          example: tra_123456
        type:
          type: string
          enum:
            - credit
          example: credit
          description: The transaction type.
        method:
          type: string
          enum:
            - P2P
            - A2A
            - TopUp
            - Payout
          example: P2P
          description: The transaction method.
        status:
          type: string
          enum:
            - settled
          example: settled
          description: The transaction status.
        source:
          type: object
          description: The source of the transaction.
          properties:
            name:
              type: string
              description: The name of the source.
              example: John Doe
        quote:
          type: object
          description: The quote of the transaction.
          properties:
            output:
              type: object
              description: The output quote.
              properties:
                total:
                  type: number
                  description: The total amount of the quote.
                  format: float
                  example: 75.00
                currency:
                  type: string
                  description: The currency of the quote.
                  example: SRD
        reference:
          type: string
          description: The reference of the quote.
          example: Order #123
        balance_before:
          type: number
          description: The balance before the transaction.
          example: 0.00
        balance_after:
          type: number
          description: The balance after the transaction.
          example: 75.00
        created_at:
          type: string
          description: The date and time the transaction was created.
          format: date-time
        processed_at:
          type: string
          description: The date and time the transaction was processed.
          format: date-time

    Customer:
      type: object
      properties:
        id:
          type: string
          description: The ID of the customer.
          example: cus_123456
        name:
          type: string
          description: The name of the customer.
          example: Jane Smith
        email:
          type: string
          description: The email of the customer.
          example: jane@example.com
        phone:
          type: string
          description: The phone number of the customer.
          example: "+597-8123456"
        default_currency:
          $ref: "#/components/schemas/CurrencyType"
        billing_details:
          $ref: "#/components/schemas/CustomerBaseBillingDetails"
        shipping_details:
          $ref: "#/components/schemas/CustomerFullBillingDetails"
        metadata:
          type: object
          description: The metadata of the customer.
          default: {}
        session:
          $ref: "#/components/schemas/CustomerSessionData"
        created_at:
          type: string
          description: The date and time the customer was created.
          format: date-time
    CustomerPreview:
      type: object
      description: The customer details.
      properties:
        id:
          type: string
          description: The ID of the customer.
          example: cus_123456
        name:
          type: string
          description: The name of the customer.
          example: Jane Smith
        email:
          type: string
          description: The email of the customer.
          example: jane@example.com
        billing_details:
          $ref: "#/components/schemas/CustomerBaseBillingDetails"
        shipping_details:
          $ref: "#/components/schemas/CustomerFullBillingDetails"
    CustomerBaseBillingDetails:
      type: object
      default: null
      description: Customer billing details.
      required:
        - line_1
        - city
        - country
      properties:
        line_1:
          type: string
          description: Address line 1.
          example: Example Street 10
        line_2:
          type: string
          description: Address line 2.
          example: Example Street 11
        city:
          type: string
          description: City.
          example: Paramaribo
        state:
          type: string
          description: State.
          example: Kwatta
        zip_code:
          type: string
          description: Zip code.
          example: "12345"
        country:
          type: string
          description: Country code in ISO 3166-1 alpha-2 format.
          example: SR
    CustomerFullBillingDetails:
      type: object
      default: null
      description: Customer shipping details schema.
      required:
        - name
        - line_1
        - city
        - country
      properties:
        name:
          type: string
          description: Full name of the customer.
          example: Jane Smith
        phone:
          type: string
          description: Phone number of the customer. (e.g. +597-8123456)
          example: "+597-8123456"
        line_1:
          type: string
          description: Address line 1.
          example: Example Street 10
        line_2:
          type: string
          description: Address line 2.
          example: Example Street 11
        city:
          type: string
          description: City.
          example: Paramaribo
        state:
          type: string
          description: State.
          example: Kwatta
        zip_code:
          type: string
          description: Zip code.
          example: "12345"
        country:
          type: string
          description: Country code in ISO 3166-1 alpha-2 format.
          example: SR
    CustomerProviderPreview:
      title: Provider
      type: object
      properties:
        id:
          type: string
          description: The ID of the payment method.
          example: cpm_123456
        type:
          type: string
          enum:
            - credits
            - wallet
          description: The type of the payment method.
          example: wallet
        provider:
          type: string
          description: The payment method provider name.
          example: Paisr Pay
    CustomerCardPreview:
      title: Card
      type: object
      properties:
        id:
          type: string
          description: The ID of the payment method.
          example: cmp_123456
        type:
          type: string
          description: The type of the payment method.
          default: card
          example: card
        last_four:
          type: string
          description: The last four digits of the card.
          example: "4242"
        brand:
          type: string
          description: The brand of the card.
          example: visa

    Voucher:
      type: object
      properties:
        id:
          type: string
          description: The ID of the voucher.
          example: vch_123456
        description:
          type: string
          description: The description of the voucher.
          example: End of the month sale
        code:
          type: string
          description: The code of the voucher.
          example: EOTM10
        amount:
          type: number
          format: float
          description: The amount of the voucher.
          example: 10
        redeems:
          type: object
          description: The redeems of the voucher.
          properties:
            count:
              type: number
              description: The count of redeems.
              example: 75
            max:
              type: number
              description: The maximum count of redeems.
              example: 100
        archived:
          type: boolean
          description: Whether the voucher is archived.
          example: false
        created_at:
          type: string
          description: The date and time the voucher was created.
          format: date-time
        expires_at:
          type: string
          description: The date and time the voucher expires.
          format: date-time
    VoucherPreview:
      type: object
      description: The details of the voucher applied to the invoice.
      default: null
      properties:
        id:
          type: string
          description: The ID of the voucher.
          example: vch_123456
        rate:
          type: number
          description: The rate of the voucher.
          example: 10

    Plan:
      type: object
      properties:
        id:
          type: string
          description: The ID of the plan.
          example: pln_123456
        title:
          type: string
          description: The title of the plan.
          example: Premium Service
        summary:
          type: string
          description: The summary of the plan.
          example: Get started with using our premium service.
        type:
          type: string
          enum:
            - standard
            - metered
          default: standard
          description: The type of the plan.
          example: standard
        currency:
          type: string
          description: The currency of the plan.
          example: SRD
        created_at:
          type: string
          description: The date and time the plan was created.
          format: date-time
        options:
          type: array
          description: The list of options attached to the plan.
          items:
            $ref: "#/components/schemas/PlanOption"
    PlanOption:
      type: object
      properties:
        id:
          type: string
          description: The ID of the plan option.
          example: plo_123456
        description:
          type: string
          description: The description of the plan option.
          example: Monthly
        active:
          type: boolean
          default: true
          description: Whether the plan option is active.
          example: true
        unit_price:
          type: number
          description: The unit price of the plan option.
          example: 9.99
        billing_interval:
          type: number
          description: The billing interval of the plan option.
          example: 30
        subscribers:
          type: number
          description: The number of subscribers to the plan option.
          example: 10
        attributes:
          type: object
          description: The attributes of the plan option.
          default: {}
          example: {}
        created_at:
          type: string
          description: The date and time the plan option was created.
          format: date-time
    PlanLineOption:
      type: object
      required:
        - description
        - unit_price
        - billing_interval
      properties:
        description:
          type: string
          description: Short description about the option.
        unit_price:
          type: number
          format: float
          minimum: 0.01
          description: Price per unit.
        billing_interval:
          type: number
          minimum: 1
          maximum: 365
          description: The number of days for each billing interval. (e.g. 30 for monthly or 365 for yearly)
        attributes:
          type: object
          maxProperties: 16
          description: Custom key-value pairs that can be used for option specific features.

    Invoice:
      type: object
      properties:
        id:
          type: string
          description: The ID of the invoice.
          example: inv_123456
        sid:
          type: number
          description: The Serial ID of the invoice.
          example: 600783
        subscription_id:
          type: string
          description: The ID of the subscription the invoice is associated with.
          default: null
          example: sub_123456
        customer:
          $ref: "#/components/schemas/CustomerPreview"
        voucher:
          $ref: "#/components/schemas/VoucherPreview"
        summary:
          type: string
          description: The summary of the invoice.
          example: A simple pizza order
        amount:
          type: object
          description: The amount details of the invoice.
          properties:
            sub_total:
              type: number
              description: The sub total of the invoice.
              format: float
              example: 150
            discount_total:
              type: number
              description: The discount total of the invoice.
              format: float
              example: 15
            net_total:
              type: number
              description: The net total of the invoice.
              format: float
              example: 135
        status:
          $ref: "#/components/schemas/InvoiceStatus"
        currency:
          type: string
          description: The currency of the invoice.
          example: SRD
        session:
          $ref: "#/components/schemas/InvoiceSessionData"
        due_at:
          type: string
          description: The due date of the invoice.
          format: date-time
        paid_at:
          type: string
          description: The date and time the invoice was paid.
          format: date-time
        void_at:
          type: string
          description: The date and time the invoice was voided.
          format: date-time
        created_at:
          type: string
          description: The date and time the invoice was created.
          format: date-time
    InvoiceDetails:
      type: object
      description: The invoice details.
      properties:
        id:
          type: string
          description: The ID of the invoice.
          example: inv_123456
        sid:
          type: number
          description: The Serial ID of the invoice.
          example: 600783
        subscription_id:
          type: string
          description: The ID of the subscription associated with the invoice.
          default: null
          example: sub_123456
        customer:
          $ref: "#/components/schemas/CustomerPreview"
        voucher:
          $ref: "#/components/schemas/VoucherPreview"
        summary:
          type: string
          description: The summary of the invoice.
          example: A simple pizza order
        amount:
          type: object
          description: The amount details of the invoice.
          properties:
            sub_total:
              type: number
              description: The sub total of the invoice.
              format: float
              example: 150
            discount_total:
              type: number
              description: The discount total of the invoice.
              format: float
              example: 15
            net_total:
              type: number
              description: The net total of the invoice.
              format: float
              example: 135
        status:
          $ref: "#/components/schemas/InvoiceStatus"
        currency:
          type: string
          description: The currency of the invoice.
          example: SRD
        session:
          $ref: "#/components/schemas/InvoiceSessionData"
        line_items:
          type: array
          description: The line items of the invoice.
          items:
            $ref: "#/components/schemas/InvoiceItem"
        due_at:
          type: string
          description: The due date and time of the invoice.
          format: date-time
        paid_at:
          type: string
          description: The date and time the invoice was paid.
          format: date-time
        void_at:
          type: string
          description: The date and time the invoice was voided.
          format: date-time
        created_at:
          type: string
          description: The date and time the invoice was created.
          format: date-time
    InvoiceItem:
      type: object
      description: The line item details.
      properties:
        id:
          type: string
          description: The ID of the line item.
          example: itm_123456
        description:
          type: string
          description: The description of the line item.
          example: Small Pizza
        quantity:
          type: number
          description: The quantity of the line item.
          example: 2
        total:
          type: object
          description: The total details of the line item.
          properties:
            unit:
              type: number
              description: The unit price of the line item.
              format: float
              example: 75
            calculated:
              type: number
              description: The calculated total of the line item.
              format: float
              example: 150
        created_at:
          type: string
          description: The date and time the line item was created.
          format: date-time
    InvoiceLineItem:
      type: object
      required:
        - description
        - quantity
        - unit_price
      properties:
        description:
          type: string
          description: Detailed description about the item.
        quantity:
          type: number
          minimum: 1
          description: Number of units.
        unit_price:
          type: number
          format: float
          minimum: 0
          description: Price per unit.

    Subscription:
      type: object
      properties:
        id:
          type: string
          description: The ID of the subscription.
          example: sub_123456
        customer:
          $ref: "#/components/schemas/CustomerPreview"
        payment_method:
          type: object
          description: The payment method details.
          oneOf:
            - $ref: "#/components/schemas/CustomerProviderPreview"
            - $ref: "#/components/schemas/CustomerCardPreview"
        status:
          $ref: "#/components/schemas/SubscriptionStatus"
        currency:
          type: string
          description: The currency of the subscription.
          example: SRD
        auto_renew:
          type: boolean
          description: Whether the subscription should auto-renew.
          example: true
        billing_interval:
          type: number
          description: The billing interval in days.
          example: 30
        billing_start:
          type: string
          description: The start date of the billing period.
          format: date-time
        billing_end:
          type: string
          description: The end date of the billing period.
          format: date-time
        last_renew_at:
          type: string
          description: The date of the last renewal.
          format: date-time
        next_renew_at:
          type: string
          description: The date of the next renewal.
          format: date-time
        created_at:
          type: string
          description: The date and time the subscription was created.
          format: date-time
    SubscriptionDetails:
      type: object
      description: The subscription details.
      properties:
        id:
          type: string
          description: The ID of the subscription.
          example: sub_123456
        customer:
          $ref: "#/components/schemas/CustomerPreview"
        payment_method:
          type: object
          description: The payment method details.
          oneOf:
            - $ref: "#/components/schemas/CustomerProviderPreview"
            - $ref: "#/components/schemas/CustomerCardPreview"
        status:
          $ref: "#/components/schemas/SubscriptionStatus"
        currency:
          type: string
          description: The currency of the subscription.
          example: SRD
        auto_renew:
          type: boolean
          description: Whether the subscription should auto-renew.
          example: true
        billing_interval:
          type: number
          description: The billing interval in days.
          example: 30
        billing_start:
          type: string
          description: The start date of the billing period.
          format: date-time
        billing_end:
          type: string
          description: The end date of the billing period.
          format: date-time
        last_renew_at:
          type: string
          description: The date and time the subscription was last renewed.
          format: date-time
        next_renew_at:
          type: string
          description: The date and time the subscription will be renewed next.
          format: date-time
        cancelled_at:
          type: string
          description: The date and time the subscription was cancelled.
          format: date-time
          default: null
        created_at:
          type: string
          description: The date and time the subscription was created.
          format: date-time
        line_items:
          type: array
          description: The line items of the subscription.
          items:
            $ref: "#/components/schemas/SubscriptionItem"
    SubscriptionItem:
      type: object
      properties:
        id:
          type: string
          description: The ID of the subscription item.
          example: stm_123456
        title:
          type: string
          description: The title of the subscription item.
          example: Premium Service - Monthly
        quantity:
          type: number
          description: The quantity of the subscription item.
          example: 1
        option:
          type: object
          description: The option the subscription item is associated with.
          properties:
            id:
              type: string
              description: The ID of the option.
              example: plo_123456
            plan_id:
              type: string
              description: The ID of the plan the option belongs to.
              example: pln_123456
            available:
              type: boolean
              description: Whether the option is available.
              example: true
            unit_price:
              type: number
              format: float
              description: The unit price of the option.
              example: 9.99
        created_at:
          type: string
          description: The date and time the subscription item was created.
          format: date-time
    SubscriptionLineItem:
      type: object
      required:
        - option_id
        - quantity
      properties:
        option_id:
          type: string
          description: The ID of the plan option to subscribe to.
        quantity:
          type: number
          minimum: 1
          description: Number of units.

    Payment:
      type: object
      properties:
        id:
          type: string
          description: The ID of the payment.
          example: pmt_123456
        sid:
          type: number
          description: The Serial ID of the payment.
          example: 680297
        invoice_id:
          type: string
          description: The ID of the invoice associated with the payment.
          default: null
          example: inv_123456
        description:
          type: string
          description: The description or reference of the payment.
          example: "Payment for Invoice #600783"
        currency:
          type: string
          description: The currency of the payment.
          example: SRD
        status:
          $ref: "#/components/schemas/PaymentStatus"
        payment_method:
          type: object
          description: The payment method used for the payment.
          properties:
            provider:
              type: string
              description: The provider of the payment method.
              example: Paisr Pay
            type:
              $ref: "#/components/schemas/PaymentSourceType"
            metadata:
              type: object
              description: The metadata of the payment method.
              default: null
              example: null
        amount:
          type: object
          description: The amount details of the payment.
          properties:
            sub_total:
              type: number
              description: The sub total of the payment.
              format: float
              example: 135
            tax:
              type: object
              description: The tax details of the payment.
              properties:
                rate:
                  type: number
                  description: The tax rate of the payment.
                  format: float
                  example: 0
                type:
                  $ref: "#/components/schemas/RateType"
                total:
                  type: number
                  description: The total tax amount of the payment.
                  format: float
                  example: 0
            due_total:
              type: number
              description: The total due amount of the payment.
              format: float
              example: 135
            fee_total:
              type: number
              description: The total fee amount of the payment.
              format: float
              example: 2.56
            output_total:
              type: number
              description: The total output amount of the payment.
              format: float
              example: 132.44
        billing_details:
          $ref: "#/components/schemas/CustomerFullBillingDetails"
        notes:
          type: string
          description: The notes of the payment.
          default: null
        metadata:
          type: object
          description: The metadata of the payment.
          default: {}
        initiated_at:
          type: string
          description: The date and time the payment was initiated.
          format: date-time
        approved_at:
          type: string
          description: The date and time the payment was approved.
          format: date-time
        settled_at:
          type: string
          description: The date and time the payment was settled.
          default: null
          format: date-time
        cancelled_at:
          type: string
          description: The date and time the payment was cancelled.
          default: null
          format: date-time
        cancelled_by:
          type: string
          description: The ID of the member who cancelled the payment.
          default: null
        reversed_at:
          type: string
          description: The date and time the payment was reversed.
          default: null
          format: date-time
        reversed_by:
          type: string
          description: The ID of the member who reversed the payment.
          default: null
        est_settlement_at:
          type: string
          description: The estimated settlement date and time of the payment.
          default: null
          format: date-time

    PaymentProvider:
      type: object
      properties:
        id:
          type: string
          description: The ID of the payment provider.
          example: bpc_123456
        name:
          type: string
          description: The name of the payment provider.
          example: Paisr Pay
        summary:
          type: string
          description: A brief summary of the payment provider.
          example: A payment provider that supports multiple payment methods.
        description:
          type: string
          description: The description of the payment provider.
          example: A payment provider that supports multiple payment methods.
        logo:
          type: string
          description: The logo of the payment provider.
          example: https://wallet.paisr.tech/logo.png
        method:
          type: string
          description: The payment method supported by the provider.
          example: card
        slug:
          type: string
          description: The slug of the payment provider.
          example: pcb
        available:
          type: boolean
          description: Whether the payment provider is available.
          example: true
        external:
          type: boolean
          description: Whether the payment provider is external.
          example: false
        config:
          type: object
          description: The configuration of the payment provider.
          properties:
            type:
              type: string
              description: The type of configuration.
              example: managed
            status:
              type: string
              description: The status of the configuration.
              example: active
            fee_strategy:
              type: object
              description: The fee strategy of the configuration.
              properties:
                type:
                  type: string
                  description: The type of fee strategy.
                  example: custom
                interchange:
                  type: object
                  description: The interchange fee details.
                  properties:
                    fee_type:
                      type: string
                      description: The type of interchange fee.
                      example: percentage
                    fee_total:
                      type: number
                      description: The total interchange fee.
                      example: 0.05
                    fee_cap:
                      type: number
                      description: The cap on the interchange fee.
                      example: 1000
            metadata:
              type: object
              description: The custom metadata used for the connection.
        attributes:
          type: object
          description: The attributes of the payment method.
          properties:
            min_amount:
              type: number
              description: The minimum amount for the payment method.
              example: 0.01
            max_amount:
              type: number
              description: The maximum amount for the payment method.
              example: 100000
            allows_recurring:
              type: boolean
              description: Whether recurring payments are supported.
              example: true
            allows_refunds:
              type: boolean
              description: Whether refunds are supported.
              example: true
            allows_disputes:
              type: boolean
              description: Whether disputes are supported.
              example: true
            confirmation_window:
              type: string
              description: The confirmation window for the payment method.
              example: immediately
            supported_currencies:
              type: array
              format: string
              description: The supported currencies for the payment method.
              items:
                type: string
                examples:
                  - SRD
                  - USD
        created_at:
          type: string
          description: The date and time the payment method was created.
          format: date-time

    StaticPage:
      type: object
      properties:
        id:
          type: string
          description: The ID of the static page.
          example: stp_123456
        description:
          type: string
          description: The description of the static page.
          example: Web POS
        fields:
          type: object
          description: The fields of the static page.
          example: {}
        session:
          $ref: "#/components/schemas/PageSessionData"
        created_at:
          type: string
          description: The date and time the static page was created.
          format: date-time

    InvoiceMetrics:
      title: Invoices
      type: object
      properties:
        total:
          type: number
          description: The total number of invoices.
          default: 0
          example: 49
        unpaid:
          type: number
          description: The number of unpaid invoices.
          default: 0
          example: 9
        paid:
          type: number
          description: The number of paid invoices.
          default: 0
          example: 40
        voided:
          type: number
          description: The number of voided invoices.
          default: 0
          example: 0
        series:
          type: array
          description: Day by day invoice metrics.
          items:
            type: object
            properties:
              day:
                type: string
                description: The date of the day.
                example: 2026-01-01
              new:
                type: number
                description: The number of new invoices on the day.
                default: 0
                example: 1
              paid:
                type: number
                description: The number of paid invoices on the day.
                default: 0
                example: 1
              voided:
                type: number
                description: The number of voided invoices on the day.
                default: 0
                example: 0
    SubscriptionMetrics:
      title: Subscriptions
      type: object
      properties:
        total:
          type: number
          description: The total number of subscriptions.
          default: 0
          example: 67
        pending:
          type: number
          description: The number of pending subscriptions.
          default: 0
          example: 9
        active:
          type: number
          description: The number of active subscriptions.
          default: 0
          example: 40
        suspended:
          type: number
          description: The number of suspended subscriptions.
          default: 0
          example: 3
        cancelled:
          type: number
          description: The number of cancelled subscriptions.
          default: 0
          example: 4
        series:
          type: array
          description: Day by day subscription metrics.
          items:
            type: object
            properties:
              day:
                type: string
                description: The date of the day.
                example: 2026-01-01
              new:
                type: number
                description: The number of new subscriptions on the day.
                example: 5
              started:
                type: number
                description: The number of started subscriptions on the day.
                example: 10
              ended:
                type: number
                description: The number of ended subscriptions on the day.
                example: 2
    PaymentMetrics:
      title: Payments
      type: object
      properties:
        total:
          type: number
          description: The total number of payments.
          default: 0
          example: 15
        failed:
          type: number
          description: The number of failed payments.
          default: 0
          example: 3
        pending:
          type: number
          description: The number of pending payments.
          default: 0
          example: 2
        settled:
          type: number
          description: The number of settled payments.
          default: 0
          example: 10
        refunded:
          type: number
          description: The number of refunded payments.
          default: 0
          example: 0
        cancelled:
          type: number
          description: The number of cancelled payments.
          default: 0
          example: 0
        series:
          type: array
          description: Day by day payment metrics.
          items:
            type: object
            properties:
              day:
                type: string
                description: The date of the day.
                example: 2026-01-01
              initiated:
                type: number
                description: The number of payments initiated on the day.
                default: 0
                example: 10
              approved:
                type: number
                description: The number of payments approved on the day.
                default: 0
                example: 8
              cancelled:
                type: number
                description: The number of payments cancelled on the day.
                default: 0
                example: 2
    CustomerMetrics:
      title: Customers
      type: object
      properties:
        total:
          type: number
          description: The total number of customers.
          default: 0
          example: 24
        new:
          type: number
          description: The total number of customers created within the timeframe.
          default: 0
          example: 3
        series:
          type: array
          description: Day by day customer metrics.
          items:
            type: object
            properties:
              day:
                type: string
                description: The date of the day.
                example: 2026-01-01
              new:
                type: number
                description: The total number of new customers on the day.
                default: 0
                example: 3
    VolumeMetrics:
      title: Volume
      type: object
      properties:
        results:
          type: array
          description: The volume metrics results
          items:
            type: object
            properties:
              currency:
                type: string
                description: The currency code.
                example: SRD
              gross_volume:
                type: number
                description: The gross volume.
                default: 0.00
                example: 1200.00
              incoming_volume:
                type: number
                description: The incoming volume.
                default: 0.00
                example: 200.00
              settled_volume:
                type: number
                description: The settled volume.
                default: 0.00
                example: 1000.00
              refunded_volume:
                type: number
                description: The refunded volume.
                default: 0.00
                example: 0.00
              lost_volume:
                type: number
                description: The lost volume.
                default: 0.00
                example: 500.00
              fee_volume:
                type: number
                description: The fee volume.
                default: 0.00
                example: 50.00
              tax_volume:
                type: number
                description: The tax volume.
                default: 0.00
                example: 0.00

    # Request Schemas
    PostAccessTokenRequest:
      type: object
      description: Post access token request schema.
      required:
        - description
        - scopes
      properties:
        description:
          type: string
          description: Clear description on the token use case.
          example: Postman
          pattern: ^[a-zA-Z0-9() ]{4,48}$
        scopes:
          type: array
          format: string
          description: List scopes to attach to the token.
          example:
            - invoices.read
            - invoices.write
          minItems: 1
          items:
            type: string
    PutAccessTokenRequest:
      type: object
      description: Put access token request schema.
      required:
        - description
      properties:
        description:
          type: string
          description: Clear description on the token use case.
          example: Postman
          pattern: ^[a-zA-Z0-9() ]{4,48}$
    PostAccessTokenPermissionRequest:
      type: object
      description: Post access token permission request schema.
      required:
        - scopes
      properties:
        scopes:
          type: array
          format: string
          description: List of scopes to attach to the token.
          example:
            - invoices.read
            - invoices.write
          minItems: 1
          items:
            type: string

    # Profile Webhooks
    PostWebhookRequest:
      type: object
      description: Post webhook request schema.
      required:
        - description
        - endpoint
        - events
      properties:
        description:
          type: string
          description: Clear description on the webhook use case.
          example: Checkout Callback
          pattern: ^[a-zA-Z0-9() ]{4,48}$
        endpoint:
          type: string
          format: uri
          description: Full url of the webhook.
          example: https://my-checkout.com/callback
        events:
          type: array
          format: string
          description: List of events to attach to the webhook.
          example:
            - invoice.paid
          minItems: 1
          items:
            type: string
            example: invoice.paid
    PutWebhookRequest:
      type: object
      description: Put webhook request schema.
      properties:
        description:
          type: string
          description: Clear description on the webhook use case.
          example: Checkout Callback
          pattern: ^[a-zA-Z0-9() ]{4,48}$
        endpoint:
          type: string
          format: uri
          description: Full url of the webhook.
          example: https://my-checkout.com/callback
    PostWebhookTriggerRequest:
      type: object
      description: Post webhook trigger request schema.
      required:
        - events
      properties:
        events:
          type: array
          format: string
          description: List of events to attach to the webhook.
          example:
            - invoice.paid
          minItems: 1
          items:
            type: string

    # Wallets
    PostWalletRequest:
      type: object
      description: Post wallet request schema.
      properties:
        title:
          type: string
          description: Short title or name for the wallet.
          example: Acme Cash
          pattern: ^[a-zA-Z0-9 ]{6,48}$
        icon:
          $ref: "#/components/schemas/WalletIconType"
    PostWalletProfileRequest:
      type: object
      description: Post wallet profile request schema.
      properties:
        nickname:
          type: string
          description: Short nickname.
          example: Acme Finance
          pattern: ^[a-zA-Z0-9 ]{6,48}$
        cashtag:
          type: string
          description: Unique cashtag used for transfer purposes.
          example: acmefinance
          pattern: ^[a-z0-9]{6,48}$
        public:
          type: boolean
          description: Flag indicating if wallet is discoverable by other users.
          example: true
    PostWalletPinRequest:
      type: object
      description: Post wallet pin request schema.
      required:
        - new_pin
      properties:
        new_pin:
          type: string
          description: The PIN to set.
          example: "1234"
          pattern: ^[0-9]{4}$
        old_pin:
          type: string
          description: The PIN to verify before updating. Required when updating an existing PIN.
          example: "4321"
          pattern: ^[0-9]{4}$

    PostWalletBalanceRequest:
      type: object
      description: Post wallet balance request schema.
      required:
        - title
        - currency
        - type
      properties:
        title:
          type: string
          description: Short title or name for the balance.
          example: SRD Revenue
          pattern: ^[a-zA-Z0-9 ]{6,48}$
        currency:
          $ref: "#/components/schemas/CurrencyType"
        type:
          $ref: "#/components/schemas/WalletBalanceType"
    PutWalletBalanceRequest:
      type: object
      description: Put wallet balance request schema.
      required:
        - title
      properties:
        title:
          type: string
          description: Short title or name for the balance.
          example: SRD Revenue
          pattern: ^[a-zA-Z0-9 ]{6,48}$

    PostWalletAccountRequest:
      type: object
      description: Post wallet account request schema.
      required:
        - account_holder
        - account_number
        - account_type
        - swift_code
        - currency
      properties:
        account_holder:
          type: string
          description: Full account holder name.
          example: John Doe
        account_number:
          type: string
          description: Full account number / IBAN.
          example: AC123456789
        routing_number:
          type: string
          description: Routing number. Required for US accounts.
          example: "123456789"
        account_type:
          $ref: "#/components/schemas/WalletAccountType"
        swift_code:
          $ref: "#/components/schemas/BankSwiftType"
        currency:
          $ref: "#/components/schemas/CurrencyType"
    PatchWalletAccountRequest:
      type: object
      description: Patch wallet account request schema.
      required:
        - code
      properties:
        code:
          type: string
          description: Six digit verification code.
          example: "123456"
          minLength: 6
          maxLength: 6

    PostWalletContactRequest:
      type: object
      description: Post wallet contact request schema.
      required:
        - cashtag
      properties:
        cashtag:
          type: string
          description: Unique cashtag of the wallet.
          example: acmecorp

    # Transfers
    PostTransferRequest:
      type: object
      description: Post transfer request schema.
      required:
        - method
        - source
        - destination
        - amount
      properties:
        method:
          type: string
          enum:
            - P2P
            - A2A
            - ACH
          description: The payment rail that will be used for the transfer.
          example: P2P
        source:
          type: string
          description: Source balance ID.
          example: ica_<string>
        destination:
          type: string
          description: Depending on the method, this can be a contact ID or cashtag for P2P, a balance ID for A2A, or an account ID for ACH.
          example: acmecorp
        amount:
          type: number
          format: float
          description: Amount to transfer. Must be at least 0.10 for P2P, 0.01 for A2A, or 25.00 for ACH.
          example: 100.00
        reference:
          type: string
          description: Summary about the transfer. This value is required when the method is set to P2P or ACH and omitted when set to A2A.
          example: Order #12345
    PostApproveTransferRequest:
      type: object
      description: Request body for approving a transfer.
      required:
        - signature
      properties:
        signature:
          type: string
          description: Signature of the transfer signed by the source wallet.
          example: hmac-signature
    PostCancelTransferRequest:
      type: object
      description: Request body for cancelling a transfer.
      required:
        - note
      properties:
        note:
          type: string
          description: Reason for cancellation.
          example: Last minute mind change

    # Customers
    PostCustomerRequest:
      type: object
      description: Request body for creating a customer.
      required:
        - email
      properties:
        name:
          type: string
          description: The name of the customer.
          example: John Doe
        email:
          type: string
          format: email
          description: The email address of the customer.
          example: john.doe@example.com
        phone:
          type: string
          format: tel
          description: The phone number of the customer. (eg +597-8123456).
          example: +597-8123456
        default_currency:
          $ref: "#/components/schemas/CurrencyType"
        billing_details:
          $ref: "#/components/schemas/CustomerBaseBillingDetails"
        shipping_details:
          $ref: "#/components/schemas/CustomerFullBillingDetails"
        metadata:
          type: object
          description: Custom metadata. Can be up to 5 custom key-value pairs.
    PutCustomerRequest:
      type: object
      description: Request body for updating a customer.
      properties:
        name:
          type: string
          description: The name of the customer.
          example: John Doe
        email:
          type: string
          format: email
          description: The email address of the customer.
          example: john.doe@example.com
        phone:
          type: string
          format: tel
          description: The phone number of the customer. (eg +597-8123456).
          example: +597-8123456
        default_currency:
          $ref: "#/components/schemas/CurrencyType"
        billing_details:
          $ref: "#/components/schemas/CustomerBaseBillingDetails"
        shipping_details:
          $ref: "#/components/schemas/CustomerFullBillingDetails"
        metadata:
          type: object
          description: Custom metadata. Can be up to 5 custom key-value pairs.

    # Vouchers
    PostVoucherRequest:
      type: object
      description: Request body for creating a voucher.
      required:
        - description
        - code
        - amount
        - max_redeems
        - expires
      properties:
        description:
          type: string
          description: Short description about the voucher.
          example: Discount voucher for loyal customers.
        code:
          type: string
          description: Unique code that will be used to redeem the voucher.
          example: DISCOUNT123
        amount:
          type: number
          format: float
          minimum: 1
          description: Discount amount.
          example: 10.0
        max_redeems:
          type: number
          minimum: 1
          maximum: 1000000
          description: Max number of redeems.
          example: 100
        expires:
          type: string
          description: Expiration date in relative time. (e.g. 'In 3 days')
          example: In 3 days
    PutVoucherRequest:
      type: object
      description: Request body for updating a voucher.
      properties:
        description:
          type: string
          description: Short description about the voucher.
          example: Discount voucher for loyal customers.
        amount:
          type: number
          format: float
          minimum: 1
          description: Discount amount.
          example: 10.0
        max_redeems:
          type: number
          minimum: 1
          maximum: 1000000
          description: Max number of redeems.
          example: 100
        expires:
          type: string
          description: Expiration date in relative time. (e.g. 'In 3 days')
          example: In 3 days
    PostApplyVoucherRequest:
      type: object
      description: Request body for applying a voucher to an invoice.
      required:
        - invoice_id
        - code
      properties:
        invoice_id:
          type: string
          description: ID of the invoice redeeming the voucher.
          example: inv_123
        code:
          type: string
          description: Unique code of the voucher.
          example: DISCOUNT123

    # Plans
    PostPlanRequest:
      type: object
      description: Request body for creating a plan.
      required:
        - title
        - summary
        - currency
      properties:
        title:
          type: string
          description: Short description about the plan
          example: Premium Plan
        summary:
          type: string
          description: A detailed summary explaining what the plan is about.
          example: This plan includes all premium features and access to exclusive content.
        currency:
          $ref: "#/components/schemas/CurrencyType"
        options:
          type: array
          minItems: 1
          maxItems: 10
          description: List of plan line options.
          items:
            $ref: "#/components/schemas/PlanLineOption"
    PutPlanRequest:
      type: object
      description: Request body for updating a plan.
      properties:
        title:
          type: string
          description: Short description about the plan
          example: Premium Plan
        summary:
          type: string
          description: A detailed summary detailing what the plan is about.
          example: This plan includes all premium features and access to exclusive content.
        currency:
          $ref: "#/components/schemas/CurrencyType"
    PostPlanOptionRequest:
      type: object
      description: Request body for creating a plan option.
      properties:
        options:
          type: array
          minItems: 1
          maxItems: 10
          description: List of plan line options.
          items:
            $ref: "#/components/schemas/PlanLineOption"
    PutPlanOptionRequest:
      type: object
      description: Request body for updating a plan option.
      properties:
        description:
          type: string
          description: Detailed description about the option.
          example: Option description
        unit_price:
          type: number
          format: float
          minimum: 0.01
          description: Price per unit.
          example: 10.99
        billing_interval:
          type: number
          minimum: 1
          maximum: 365
          description: The number of days for each billing interval. (e.g. 30 for monthly or 365 for yearly)
          example: 30
        attributes:
          type: object
          maxProperties: 16
          description: Custom key-value pairs that can be used for option specific features.
          example: { "key": "value" }

    # Invoices
    PostInvoiceRequest:
      type: object
      description: Request body for creating an invoice.
      required:
        - customer
        - summary
        - due
      properties:
        customer:
          type: string
          description: ID or email address of the customer being billed.
          example: john@example.com
        summary:
          type: string
          description: Detailed description about the invoice.
          example: Invoice for services rendered
        currency:
          $ref: "#/components/schemas/CurrencyType"
        due:
          type: string
          description: Due date in relative time. (e.g. 'In 3 days')
          example: In 3 days
        line_items:
          type: array
          minItems: 0
          maxItems: 50
          description: List of line items for the invoice.
          items:
            $ref: "#/components/schemas/InvoiceLineItem"
    PutInvoiceRequest:
      type: object
      description: Request body for updating an invoice.
      properties:
        summary:
          type: string
          description: Detailed description about the invoice.
          example: Invoice for services rendered
        currency:
          $ref: "#/components/schemas/CurrencyType"
        due:
          type: string
          description: Due date in relative time. (e.g. 'In 3 days')
          example: In 3 days
    PostInvoiceItemRequest:
      type: object
      description: Request body for creating an invoice item.
      required:
        - line_items
      properties:
        line_items:
          type: array
          minItems: 1
          maxItems: 500
          description: List of line items for the invoice.
          items:
            $ref: "#/components/schemas/InvoiceLineItem"
    PutInvoiceItemRequest:
      type: object
      description: Request body for updating an invoice item.
      properties:
        description:
          type: string
          description: Detailed description about the item.
          example: Invoice item for services rendered
        quantity:
          type: number
          description: Number of units.
          example: 1
        unit_price:
          type: number
          format: float
          description: Price per unit.
          example: 100.00

    # Subscriptions
    PostSubscriptionRequest:
      type: object
      description: Request body for creating a subscription.
      required:
        - customer
        - auto_renew
        - line_items
      properties:
        customer:
          type: string
          description: ID or email address of the customer being billed.
          example: customer@example.com
        auto_renew:
          type: boolean
          description: Flag indicating if the subscription should auto renew at each billing cycle.
          example: true
        line_items:
          type: array
          minItems: 1
          maxItems: 10
          description: List of line items for the subscription.
          items:
            $ref: "#/components/schemas/SubscriptionLineItem"

    # Payments
    PostPaymentRequest:
      type: object
      description: Request body for creating a payment.
      required:
        - invoice_id
        - payment_method
      properties:
        invoice_id:
          type: string
          description: The ID of the invoice being paid
          pattern: "^inv_.*$"
          example: inv_123
        payment_method:
          type: object
          description: The payment method to be used
          required:
            - type
            - data
          properties:
            type:
              type: string
              description: Type of payment method
              enum:
                - wallet
                - qr
                - card
                - bank
              example: qr
            data:
              type: object
              description: Payment method data
              oneOf:
                - $ref: "#/components/schemas/QrPaymentData"
                - $ref: "#/components/schemas/WalletPaymentData"
                - $ref: "#/components/schemas/CardPaymentData"
                - $ref: "#/components/schemas/BankPaymentData"
        billing_details:
          $ref: "#/components/schemas/CustomerFullBillingDetails"
    PostRefundPaymentRequest:
      type: object
      description: Request body for refunding a payment.
      required:
        - note
      properties:
        note:
          type: string
          description: Reason for the refund.
          example: Refund for late payment

    # Payment Providers
    PostProviderRequest:
      type: object
      description: Request body for creating a payment provider.
      required:
        - slug
        - type
      properties:
        slug:
          $ref: "#/components/schemas/PaymentProviderType"
        type:
          type: string
          enum:
            - managed
            - custom
          description: Type of provider connection. Managed providers use Paisr's managed infrastructure, while custom providers use your own API credentials.
          example: managed
        attributes:
          type: object
          description: Provider specific attributes.
          properties:
            merchant_id:
              type: string
              description: Provider specific Merchant ID.
              example: STORE_ID
            secret_key:
              type: string
              description: Provider specific API credentials.
              example: API_KEY
    PutProviderRequest:
      type: object
      description: Request body for updating a payment provider.
      required:
        - merchant_id
        - secret_key
      properties:
        merchant_id:
          type: string
          description: Provider specific Merchant ID.
          example: STORE_ID
        secret_key:
          type: string
          description: Provider specific API credentials.
          example: API_KEY

    # Static Pages
    PostStaticPageRequest:
      type: object
      description: Request body for creating a static page.
      required:
        - description
        - fields
      properties:
        description:
          type: string
          description: Name of description of the page
          example: Page Description
        fields:
          type: array
          description: Form fields to be visible on the page
          example: []
          items:
            type: string

  responses:
    400Response:
      description: Bad Request.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                $ref: "#/components/schemas/FailureState"
              error:
                type: object
                properties:
                  type:
                    type: string
                    description: Type of error.
                    example: request_error
                  message:
                    type: string
                    description: Human-readable error message.
                    example: A human-readable error message.
                  data:
                    type: object
                    description: Additional error data.
                    default: null
    401Response:
      description: Unauthorized.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                $ref: "#/components/schemas/FailureState"
              error:
                type: object
                properties:
                  type:
                    type: string
                    description: Type of error.
                    example: authentication_error
                  message:
                    type: string
                    description: Human-readable error message.
                    example: Invalid or expired credentials.
                  data:
                    type: object
                    description: Additional error data.
                    default: null
    402Response:
      description: Payment Required.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                $ref: "#/components/schemas/FailureState"
              error:
                type: object
                properties:
                  type:
                    type: string
                    description: Type of error.
                    enum:
                      - card_error
                      - processing_error
                    example: card_error
                  message:
                    type: string
                    description: Human-readable error message.
                    example: Invalid or unsupported card.
                  data:
                    type: object
                    description: Additional error data.
                    default: null
                    properties:
                      id:
                        type: string
                        description: The unique identifier of the payment.
                        example: pmt_123456
                      status:
                        type: string
                        description: The status of the payment.
                        example: failed
    403Response:
      description: Forbidden.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                $ref: "#/components/schemas/FailureState"
              error:
                type: object
                properties:
                  type:
                    type: string
                    description: Type of error.
                    example: authorization_error
                  message:
                    type: string
                    description: Human-readable error message.
                    example: Unauthorized to perform this action.
                  data:
                    type: object
                    description: Additional error data.
                    default: null
    404Response:
      description: Not Found.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                $ref: "#/components/schemas/FailureState"
              error:
                type: object
                properties:
                  type:
                    type: string
                    description: Type of error.
                    example: request_error
                  message:
                    type: string
                    description: Human-readable error message.
                    example: Resource not found.
                  data:
                    type: object
                    description: Additional error data.
                    default: null
    422Response:
      description: Unprocessable Entity.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                $ref: "#/components/schemas/FailureState"
              error:
                type: object
                properties:
                  type:
                    type: string
                    description: Type of error.
                    enum:
                      - invoice_error
                      - provider_error
                    example: invoice_error
                  message:
                    type: string
                    description: Human-readable error message.
                    example: Invoice not found, or is not in the correct state to receive payments.
                  data:
                    type: object
                    description: Additional error data.
                    default: null
    500Response:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                $ref: "#/components/schemas/FailureState"
              error:
                type: object
                properties:
                  type:
                    type: string
                    description: Type of error.
                    example: server_error
                  message:
                    type: string
                    description: Human-readable error message.
                    example: Something went wrong on our end.
                  data:
                    type: object
                    description: Additional error data.
                    default: null
    501Response:
      description: Service Unavailable.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                $ref: "#/components/schemas/FailureState"
              error:
                type: object
                properties:
                  type:
                    type: string
                    description: Type of error.
                    example: server_error
                  message:
                    type: string
                    description: Human-readable error message.
                    example: This operation is still under development.
                  data:
                    type: object
                    description: Additional error data.
                    default: null