openapi: 3.0.0
info:
  description: APIs for interacting with Cadana Embedded Consumer Wallets
  version: 1.0.0
  title: Embedded Consumer Wallets Balances Virtual Accounts 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: Virtual Accounts
  description: APIs for managing virtual accounts
paths:
  /v1/users/{userId}/virtual-accounts:
    post:
      summary: Create Virtual Account
      description: Create a new virtual account for a user
      tags:
      - Virtual Accounts
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/XMultiTenantKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVirtualAccountRequest'
            examples:
              virtualAccountRequest:
                summary: Example virtual account creation request. Use `99999900` as customIdentification.number for automatic account creation
                value:
                  currency: USD
                  customIdentification:
                    type: ssn
                    number: 123-45-6789
                  jobInformation:
                    employerName: Acme Corp
                    address:
                      line1: 123 Main St
                      city: Anytown
                      postalCode: '12345'
                      state: CA
                      countryCode: US
                    employerWebsite: ''
                    title: Software Engineer
                    type: full-time
                    netPay:
                      amount: 10000
                      currency: USD
                    frequency: monthly
                    contractStartDate: '2021-01-01'
                    contractEndDate: '2025-05-06'
                  suppressNotification: true
      responses:
        '204':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequestError'
        5XX:
          $ref: '#/components/responses/InternalError'
    get:
      summary: Get Virtual Accounts
      description: Retrieve virtual accounts for a user
      tags:
      - Virtual Accounts
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/XMultiTenantKey'
      responses:
        '200':
          $ref: '#/components/responses/GetVirtualAccountsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        5XX:
          $ref: '#/components/responses/InternalError'
  /v1/sandbox/users/{userId}/virtual-accounts/{virtualAccountId}/deposit:
    post:
      summary: Simulate virtual account deposit
      description: Simulate a virtual account deposit for an active virtual account
      tags:
      - Virtual Accounts
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/virtualAccountId'
      - $ref: '#/components/parameters/XMultiTenantKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateVirtualAccountDepositRequest'
            examples:
              simulateVirtualAccountDepositRequest:
                summary: Example virtual account creation request
                value:
                  amount:
                    amount: 10000
                    currency: USD
                  reference: c06f3427-3bbe-4d70-9a54-28acda267e48
                  description: Payroll 10/10
      responses:
        '204':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequestError'
        5XX:
          $ref: '#/components/responses/InternalError'
components:
  responses:
    GetVirtualAccountsResponse:
      description: Virtual accounts retrieved successfully
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                nullable: true
                items:
                  $ref: '#/components/schemas/VirtualAccount'
              node:
                $ref: '#/components/schemas/node'
          examples:
            requested:
              summary: Virtual account in requested status
              value:
                data:
                - id: 3f70be8e-426f-4e89-b883-9c97a1c334d5
                  status: Requested
                  currency: USD
                  createdTimestamp: 1755693297
                  lastUpdatedTimestamp: 1755693297
                node:
                  previous: null
                  next: null
            approved:
              summary: Virtual account in approved status with account information
              value:
                data:
                - id: dba72ddb-6bb5-465b-a9db-318b8f4567e6
                  status: Approved
                  currency: USD
                  accountInformation:
                    accountNumber: '000000000000'
                    accountName: John Doe
                    bankName: Example Bank
                    bankCode: '000000000'
                    countryCode: US
                    accountType: Checking
                    routingNumber: '000000000'
                    bankAddress: 123 Main St, San Francisco, CA 94100
                  createdTimestamp: 1660722175
                  lastUpdatedTimestamp: 1751891253
                node:
                  previous: null
                  next: null
            empty:
              summary: No virtual accounts exist
              value:
                data: null
                node:
                  previous: null
                  next: null
    InternalError:
      description: Internal error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalError'
    BadRequestError:
      description: Bad input provided by client
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
  parameters:
    userId:
      name: userId
      in: path
      description: The unique identifier for the user
      required: true
      schema:
        type: string
        format: uuid
        example: c06f3427-3bbe-4d70-9a54-28acda267e48
    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.
    virtualAccountId:
      name: virtualAccountId
      in: path
      description: The unique identifier for the virtual account
      required: true
      schema:
        type: string
        format: uuid
        example: c06f3427-3bbe-4d70-9a54-28acda267e48
  schemas:
    JobInformation:
      type: object
      required:
      - employerName
      - address
      - title
      - type
      - netPay
      - frequency
      - contractStartDate
      properties:
        employerName:
          type: string
          description: Name of the employer
          example: Tesla
        address:
          $ref: '#/components/schemas/address'
        employerWebsite:
          type: string
          description: Website of the employer (optional)
          example: ''
        title:
          type: string
          description: Job title
          example: Software Engineer
        type:
          type: string
          enum:
          - contract
          - full-time
          - part-time
          description: Type of employment
          example: full-time
        netPay:
          $ref: '#/components/schemas/Amount'
        frequency:
          type: string
          enum:
          - weekly
          - daily
          - monthly
          - hourly
          description: Payment frequency
          example: monthly
        contractStartDate:
          type: string
          format: date
          description: Start date of the contract
          example: '2021-01-01'
        contractEndDate:
          type: string
          format: date
          description: End date of the contract (optional)
          example: '2025-05-06'
    VirtualAccount:
      type: object
      required:
      - id
      - status
      - currency
      - createdTimestamp
      - lastUpdatedTimestamp
      properties:
        id:
          type: string
          format: uuid
          example: 3f70be8e-426f-4e89-b883-9c97a1c334d5
        status:
          type: string
          enum:
          - Requested
          - Approved
          - Rejected
          - Deactivated
          example: Requested
        currency:
          type: string
          example: USD
        accountInformation:
          $ref: '#/components/schemas/AccountInformation'
        createdTimestamp:
          type: integer
          description: Unix timestamp when the virtual account was created
          example: 1755693297
        lastUpdatedTimestamp:
          type: integer
          description: Unix timestamp when the virtual account was last updated
          example: 1755693297
    SimulateVirtualAccountDepositRequest:
      description: Simulate virtual account deposit payload
      required:
      - amount
      - reference
      - description
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/amount'
        reference:
          $ref: '#/components/schemas/uuid'
        description:
          type: string
          example: Payroll 10/10
    uuid:
      type: string
      format: uuid
      example: 8ef9a712-cdae-4110-b1ea-9ba95abbee6e
    InternalError:
      description: Internal server error
      allOf:
      - $ref: '#/components/schemas/Error'
      example:
        code: internal_error
        message: An unexpected error occurred. Please try again later.
    CustomIdentification:
      type: object
      required:
      - type
      - number
      properties:
        type:
          type: string
          enum:
          - ssn
          - bvn
          description: Type of identification
          example: ssn
        number:
          type: string
          description: The identification number
          example: 123-45-6789
    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.
    amount:
      type: object
      required:
      - value
      - currency
      properties:
        value:
          type: integer
          description: value in lowest denomination
          example: 10000
        currency:
          type: string
          description: currency
          example: USD
    AccountInformation:
      type: object
      required:
      - accountNumber
      - accountName
      - bankName
      - bankCode
      - countryCode
      - accountType
      - routingNumber
      - bankAddress
      properties:
        accountNumber:
          type: string
          description: The virtual account number
          example: '000000000000'
        accountName:
          type: string
          description: The name on the account
          example: John Doe
        bankName:
          type: string
          description: The name of the bank
          example: Example Bank
        bankCode:
          type: string
          description: The bank identification code
          example: '000000000'
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: US
        accountType:
          type: string
          enum:
          - Checking
          - Savings
          description: The type of account
          example: Checking
        routingNumber:
          type: string
          description: The routing number for the account
          example: '000000000'
        bankAddress:
          type: string
          description: The address of the bank
          example: 123 Main St, San Francisco, CA 94100
    Amount:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: integer
          description: Value in lowest denomination of the currency (e.g., cents)
          example: 100000
        currency:
          type: string
          description: ISO 4217 currency code
          example: COP
    CreateVirtualAccountRequest:
      type: object
      required:
      - currency
      - jobInformation
      properties:
        currency:
          type: string
          description: ISO 4217 currency code for the virtual account
          example: USD
        customIdentification:
          $ref: '#/components/schemas/CustomIdentification'
        jobInformation:
          $ref: '#/components/schemas/JobInformation'
        suppressNotification:
          type: boolean
          description: Whether to suppress notifications for this virtual account, defaults to false
          example: true
    node:
      type: object
      description: Node pagination
      properties:
        previous:
          type: string
          nullable: true
          example: null
        next:
          type: string
          nullable: true
          example: ca_123
    address:
      type: object
      required:
      - line1
      - city
      - postalCode
      - state
      - countryCode
      properties:
        line1:
          type: string
          description: Address line 1
          example: Lane 1
        line2:
          type: string
          description: Address line 2
          example: Apt 1
        city:
          type: string
          description: The city of the address
          example: Gotham City
        postalCode:
          type: string
          description: The postal code
          example: '10001'
        state:
          type: string
          description: The state for the address
          example: NY
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: US
    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
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      bearerFormat: API_SECRET_KEY
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true