openapi: 3.0.0
info:
  description: APIs for interacting with Cadana Embedded Consumer Wallets
  version: 1.0.0
  title: Embedded Consumer Wallets Balances Resources API
  termsOfService: https://cadanapay.com/terms-and-conditions
  contact:
    email: api@cadanapay.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.cadanapay.com
  description: Prod Server
- url: https://dev-api.cadanapay.com
  description: Dev Server
security:
- Authorization: []
tags:
- name: Resources
  description: Resource APIs to access and manage foundational data
paths:
  /v1/payment-requirements:
    get:
      summary: Payment corridor requirements
      description: 'Returns a Draft-07 JSON-Schema fragment that specifies every field, enum, regex and conditional rule for the requested `countryCode` + `currency` + `paymentMethod`.

        '
      tags:
      - Resources
      operationId: getPaymentRequirements
      parameters:
      - name: countryCode
        in: query
        required: true
        schema:
          type: string
          example: CO
      - name: paymentMethod
        in: query
        required: true
        schema:
          type: string
          example: bank
      - name: currency
        in: query
        required: true
        schema:
          type: string
          example: COP
      - $ref: '#/components/parameters/XMultiTenantKey'
      responses:
        '200':
          description: Draft-07 JSON-Schema fragment
          content:
            application/schema+json:
              schema:
                $ref: '#/components/schemas/JSONSchemaDraft07'
              examples:
                colombiaBank:
                  $ref: '#/components/examples/coBankSchema'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        5XX:
          $ref: '#/components/responses/InternalError'
  /v1/providers:
    get:
      summary: Get payout providers
      description: Get a list of providers for a given country code
      tags:
      - Resources
      parameters:
      - name: countryCode
        in: query
        required: true
        description: The country code in ISO 3166-1 alpha-2 format
        schema:
          type: string
        example: BR
      - $ref: '#/components/parameters/XMultiTenantKey'
      responses:
        '200':
          $ref: '#/components/responses/GetProvidersResponse'
  /v1/providers/resolve:
    get:
      summary: Resolve bank provider
      description: "Resolves a bank code, SWIFT code, or ACH routing number to the corresponding bank name and details. The behaviour depends on the `paymentMethod` parameter:\n- **swift** — resolves an 8 or 11-character SWIFT/BIC code\n- **ach** — resolves a 9-digit US ACH routing number\n- **bank** — resolves against Cadana's internal bank provider list\n  for the given currency"
      tags:
      - Resources
      parameters:
      - name: code
        in: query
        required: true
        description: The bank code, SWIFT code, or routing number to look up
        schema:
          type: string
        example: '341'
      - name: currency
        in: query
        required: true
        description: ISO 4217 currency code
        schema:
          type: string
        example: BRL
      - name: paymentMethod
        in: query
        required: true
        description: 'Payment method type: swift, ach, or bank'
        schema:
          type: string
          enum:
          - swift
          - ach
          - bank
        example: bank
      - $ref: '#/components/parameters/XMultiTenantKey'
      responses:
        '200':
          $ref: '#/components/responses/ResolveCodeResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
  /v1/payment-methods:
    get:
      summary: Get payment methods
      description: Get a list of available payment methods for a given country code
      tags:
      - Resources
      operationId: getPaymentMethods
      parameters:
      - name: countryCode
        in: query
        required: false
        description: The country code in ISO 3166-1 alpha-2 format
        schema:
          type: string
        example: BR
      - name: paymentMethod
        in: query
        required: false
        description: The payment method to filter by
        schema:
          type: string
        example: bank
      - name: currency
        in: query
        required: false
        description: The currency to filter by
        schema:
          type: string
        example: USD
      - $ref: '#/components/parameters/XMultiTenantKey'
      responses:
        '200':
          $ref: '#/components/responses/GetPaymentMethodsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        5XX:
          $ref: '#/components/responses/InternalError'
components:
  responses:
    GetPaymentMethodsResponse:
      description: Available payment methods, one entry per country matching the query
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              required:
              - country
              - paymentMethods
              properties:
                country:
                  type: string
                  description: The country code in ISO 3166-1 alpha-2 format
                  example: BR
                countryName:
                  type: string
                  description: The country's display name
                  example: Brazil
                paymentMethods:
                  type: array
                  items:
                    $ref: '#/components/schemas/PaymentMethod'
          examples:
            brazilPaymentMethods:
              $ref: '#/components/examples/brazilPaymentMethods'
    NotFoundError:
      description: Requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    InternalError:
      description: Internal error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalError'
    GetProvidersResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/Provider'
    ResolveCodeResponse:
      description: Resolved bank provider details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResolvedProvider'
          examples:
            bankCodeLookup:
              summary: Bank code lookup (BRL)
              value:
                bankName: Itaú Unibanco
                countryCode: BR
                city: ''
                routingNumber: ''
                swiftCode: ITAUBRSP
            swiftCodeLookup:
              summary: SWIFT code lookup (MXN)
              value:
                bankName: Banco Nacional de Mexico S.A.
                countryCode: MX
                city: Mexico City
                routingNumber: ''
                swiftCode: BNMXMXMM
            achLookup:
              summary: ACH routing number lookup (USD)
              value:
                bankName: JPMorgan Chase
                countryCode: US
                city: Tampa
                routingNumber: '021000021'
                swiftCode: CHASUS33
    BadRequestError:
      description: Bad input provided by client
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
  schemas:
    Provider:
      type: object
      required:
      - code
      - name
      - countryCode
      - currency
      - type
      properties:
        code:
          type: string
          example: BR123
        name:
          type: string
          example: Nubank Brazil
        countryCode:
          type: string
          description: The country code in ISO 3166-1 alpha-2 format
          example: BR
        currency:
          type: string
          description: The currency in ISO 4217 format
          example: BRL
        type:
          type: string
          enum:
          - bank
          - momo
          example: bank
    NotFoundError:
      description: Not Found
      allOf:
      - $ref: '#/components/schemas/Error'
      example:
        code: resource_not_found
        message: Requested resource could not be found.
    InternalError:
      description: Internal server error
      allOf:
      - $ref: '#/components/schemas/Error'
      example:
        code: internal_error
        message: An unexpected error occurred. Please try again later.
    BadRequestError:
      description: Bad input provided by client
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        properties:
          params:
            description: A map for meta data around the error that occurred
            type: object
      example:
        code: invalid_request_body
        message: The request body provided is not valid
        params:
          field: Value is invalid.
    PaymentMethod:
      type: object
      required:
      - type
      - currency
      - status
      properties:
        type:
          type: string
          description: The type of payment method
          enum:
          - bank
          - swift
          - proxy
          - momo
          - ach
          example: bank
        currency:
          type: string
          description: The currency in ISO 4217 format
          example: KES
        status:
          type: string
          description: The status of the payment method
          enum:
          - active
          - inactive
          example: active
    JSONSchemaDraft07:
      description: "This is a Draft-07 JSON Schema fragment. For the full meta-schema, see https://json-schema.org/draft-07/schema#. \nRely on the provided example for the expected structure.\n"
    ResolvedProvider:
      type: object
      required:
      - bankName
      - countryCode
      properties:
        bankName:
          type: string
          description: The name of the resolved bank or financial institution
          example: Itaú Unibanco
        countryCode:
          type: string
          description: The country code in ISO 3166-1 alpha-2 format
          example: BR
        city:
          type: string
          description: City of the bank branch (populated for SWIFT and ACH lookups)
          example: ''
        routingNumber:
          type: string
          description: ACH routing number (populated for ACH lookups)
          example: ''
        swiftCode:
          type: string
          description: SWIFT/BIC code (populated when available)
          example: ITAUBRSP
    Error:
      type: object
      properties:
        code:
          description: A machine parsable error code
          type: string
          enum:
          - invalid_request_body
          - resource_not_found
          - forbidden
          - internal_error
        message:
          description: A human readable message describing the error
          type: string
  examples:
    brazilPaymentMethods:
      summary: Brazil Payment Methods
      value:
      - country: BR
        countryName: Brazil
        paymentMethods:
        - type: bank
          currency: BRL
          status: active
        - type: proxy
          currency: BRL
          status: active
        - type: swift
          currency: USD
          status: active
    coBankSchema:
      summary: Colombia - bank payment method schema
      value:
        $schema: http://json-schema.org/draft-07/schema#
        $id: https://api.cadana.com/schemas/paymentDetails.bank.CO.json
        title: Colombia - bank payment details
        type: object
        additionalProperties: false
        required:
        - accountName
        - accountNumber
        - bankCode
        - bankName
        - accountType
        - beneficiaryId
        - address
        - email
        properties:
          accountName:
            type: string
            maxLength: 60
          accountNumber:
            type: string
            pattern: ^[0-9]{9,16}$
            description: 9-16-digit Colombian account number
          bankCode:
            type: string
            pattern: ^[A-Za-z0-9]{1,11}$
            description: 1-11 alphanumeric bank code
          accountType:
            type: string
            enum:
            - Checking
            - Saving
          email:
            type: string
            format: email
            maxLength: 100
          beneficiaryId:
            type: object
            additionalProperties: false
            required:
            - type
            - value
            properties:
              type:
                type: string
                enum:
                - NIT
                - CC
                - CE
                - TI
                - PASS
              value:
                type: string
            allOf:
            - if:
                properties:
                  type:
                    const: NIT
              then:
                properties:
                  value:
                    pattern: ^\d{9,11}$
            - if:
                properties:
                  type:
                    const: CC
              then:
                properties:
                  value:
                    pattern: ^\d{6,10}$
          address:
            type: object
            additionalProperties: false
            required:
            - line1
            - city
            - countryCode
            properties:
              line1:
                type: string
                maxLength: 70
              city:
                type: string
                maxLength: 50
              countryCode:
                const: CO
  parameters:
    XMultiTenantKey:
      name: X-MultiTenantKey
      in: header
      required: false
      schema:
        type: string
      description: Required when using a Platform API token. The tenant key identifying which business to operate on.
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      bearerFormat: API_SECRET_KEY
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true