Chimoney Interledger API

openapi: 3.2.0
info:
  title: Chimoney API Docs Interledger API
  version: 0.2.4
  description: This is the latest version of the Chimoney API. For deprecated version routes, please refer to /v0.2/api-docs.
servers:
- url: https://api.chimoney.io/
  description: Prod Server
- url: https://api-v2-sandbox.chimoney.io
  description: Sandbox API v2 (v0.2.4)
security:
- apiKeyAuth: []
tags:
- name: Interledger
paths:
  /v0.2.4/sub-account/create:
    post:
      description: Production KYC follows organization settings and ignores requireKyc or requireKYC when supplied. In sandbox only, false skips KYC for this test account; omitted follows organization policy.
      summary: Create a new sub-account
      tags:
      - Interledger
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of owner of Wallet.
                  example: Mide Jones
                email:
                  type: string
                  description: Email of owner of Wallet.
                  example: user@mail.com
                firstName:
                  type: string
                  description: First Name of owner.
                  example: Mide
                lastName:
                  type: string
                  description: Last Name of owner.
                  example: Jones
                phoneNumber:
                  type: string
                  description: Phone Number with country code starting with a +.
                  example: '+16471234567'
                requireKyc:
                  type: boolean
                  description: In production this deprecated input is ignored. In sandbox, false skips KYC for this account and true requires KYC. Omit to follow organization policy. Cannot be combined with requireKYC in sandbox.
                requireKYC:
                  type: boolean
                  description: Legacy spelling of requireKyc. Ignored in production; uses the same override rules in sandbox. Send at most one spelling in sandbox.
                country:
                  type: object
                  description: Optional declared legal residence used for product capability resolution before KYC.
                  required:
                  - code
                  - name
                  properties:
                    code:
                      type: string
                      minLength: 2
                      maxLength: 2
                      example: GB
                    name:
                      type: string
                      example: United Kingdom
                meta:
                  type: object
                  description: Metadata to store about the account.
              required:
              - name
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    description: Message indicating the result of the operation.
                    example: Sub-account created successfully
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Unique identifier for the created sub-account.
                        example: 907b90ef-d723-4b07-9f74-480afb5f09ef
                      lastName:
                        type: string
                        description: Last name of the sub-account owner.
                        example: Okeeke
                      parent:
                        type: string
                        description: Parent account ID.
                        example: qP3P6bjbjLZUMxVfxgEqzOF0hNM2
                      feePercent:
                        type: number
                        description: Fee percentage for the sub-account.
                        example: 0
                      accountSecondCurrencies:
                        type: array
                        description: List of secondary currencies associated with the account.
                        items:
                          type: string
                      verified:
                        type: boolean
                        description: Whether the sub-account is verified.
                        example: true
                      subscription:
                        type: object
                        properties:
                          subscription_end_timestamp:
                            type: object
                            properties:
                              _seconds:
                                type: integer
                                example: 1883676344
                              _nanoseconds:
                                type: integer
                                example: 773000000
                          subscription_start_timestamp:
                            type: object
                            properties:
                              _seconds:
                                type: integer
                                example: 1725909944
                              _nanoseconds:
                                type: integer
                                example: 773000000
                          id:
                            type: string
                            example: partner-white-glove
                      isScrimUser:
                        type: boolean
                        example: false
                      subAccount:
                        type: boolean
                        example: true
                      firstName:
                        type: string
                        example: Madueke
                      preferredExchangeRate:
                        type: boolean
                        example: false
                      uid:
                        type: string
                        example: 907b90ef-d723-4b07-9f74-480afb5f09ef
                      approved:
                        type: boolean
                        example: true
                      createdDate:
                        type: string
                        example: '2024-09-09T19:25:44.773Z'
                      joinDate:
                        type: string
                        example: '2024-09-09T19:25:44.773Z'
                      phoneNumber:
                        type: string
                        example: '+2348139955333'
                      tier:
                        type: object
                        properties:
                          id:
                            type: string
                            example: tier-3
                      meta:
                        type: object
                        properties:
                          email:
                            type: string
                            example: Okyson@mail.com
                      approvals:
                        type: array
                        items:
                          type: object
                          properties:
                            changedFields:
                              type: array
                              items:
                                type: string
                              example:
                              - all
                            deviceTime:
                              type: string
                              example: 9/9/2024
                            timestamp:
                              type: string
                              example: '2024-09-09T19:25:33.918Z'
                      name:
                        type: string
                        example: Madueke Okeeke
                      apiUseEnabled:
                        type: boolean
                        example: true
                      email:
                        type: string
                        example: Okyson@mail.com
                      p_id:
                        type: number
                        example: 60250680
                      verification:
                        type: object
                        properties:
                          status:
                            type: string
                            example: completed
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: postV024SubAccountCreate
      x-operation-id-source: derived
  /v0.2.4/payouts/interledger-wallet-address:
    post:
      summary: Payout to a Interledger Wallet Address
      tags:
      - Interledger
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subAccount:
                  type: string
                  description: Subaccount (Wallet Account) to payout from if any.
                  example: '1234567'
                turnOffNotification:
                  type: boolean
                  description: disables email and other notifications from Chimoney.
                  example: 'false'
                debitCurrency:
                  type: string
                  description: Wallet Currency to debit from to settle the amountToDeliver values.
                  example: CAD
                interledgerWallets:
                  type: array
                  description: Interledger Wallet Address payload.
                  items:
                    type: object
                    properties:
                      interledgerWalletAddress:
                        type: string
                        description: Interledger Wallet Address (Payment Pointer) to settle the Payment in. Must be issued by a Chimoney Interledger pair
                        example: https://ilp-sandbox.chimoney.com/username
                      currency:
                        type: string
                        description: Currency/ILP Asset ID to deliver to the user.
                        example: USD
                      amountToDeliver:
                        type: number
                        description: Amount to deliver to the user.
                        example: 10
                      amount:
                        type: number
                        description: DEPRECATED. Value in 'currency' to send.
                        example: 200
                      valueInUSD:
                        type: number
                        description: DEPRECATED. Value in USD to send.
                        example: 2500
                      narration:
                        type: string
                        description: Narration/Description of payment to be included notification to user
                        example: Interledger Salary Payment
                      collectionPaymentIssueID:
                        type: string
                        description: issue ID for the payment payout initiated.
                        example: '1209992222'
                    required:
                    - interledgerWalletAddress
              required:
              - interledgerWallets
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Status of the request.
                    example: success
                  message:
                    type: string
                    description: Message of the request.
                    example: Payout to Chimoney wallets completed successfully.
                  data:
                    type: object
                    properties:
                      paymentLink:
                        type: string
                        example: undefined/pay/?issueID=XQTUvRBntIU3AHgQ3jFuN9ZcHIC3_2_1661118346647
                      data:
                        type: array
                        items:
                          type: object
                      chimoneys:
                        type: array
                        items:
                          type: object
                      error:
                        type: string
                        example: None
                      payouts:
                        type: object
                        properties:
                          additionalProperties:
                            type: object
                          issueID:
                            type: string
                            example: eaabe2eb-e774-4f81-8ba9-ede2ea2d0058_11_1726579317119
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: postV024PayoutsInterledgerWalletAddress
      x-operation-id-source: derived
  /v0.2.4/multicurrency-wallets/transfer:
    post:
      summary: Transfer from multicurrency wallet to another wallet, an email or a phone number
      tags:
      - Interledger
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sender:
                  type: string
                  description: ID of Multicurrency Account. Leave blank to transfer from parent.
                subAccount:
                  type: string
                  description: ID of Sub/Multicurrency Account. Overrides sender.
                  example: 82628206-0253-4d37-b919-569efe896506
                amountToSend:
                  type: string
                  description: Amount in originCurrency currency to transfer/swap.
                  example: '2'
                originCurrency:
                  type: string
                  description: ISO Currency String like CAD, USD, etc. of the wallet to transfer from.
                  example: USD
                receiver:
                  type: string
                  description: Valid Chimoney Multi-currency Account, User or Organization ID.
                  example: '1234567'
                email:
                  type: string
                  description: Send transfer to an email. Ignored if receiver is valid
                  example: user@mail.com
                phoneNumber:
                  type: string
                  description: Send transfer to a phone number. Ignored if receiver or email is valid
                  example: '+16471234567'
                destinationCurrency:
                  type: string
                  description: ISO Currency String like CAD, USD, etc. of the wallet to transfer to.
                  example: USD
                narration:
                  type: string
                  description: Narration/Description of the payment to be included in the notification to the user.
                  example: Cross wallet transfer
                turnOffNotification:
                  type: boolean
                  description: Disables email and other notifications from Chimoney.
                  example: false
                sendViaInterledger:
                  type: boolean
                  description: Instructs the transaction to be sent via Interledger. Sender is required to have a valid originCurrency payment Pointer and Receiver is required to have a valid destinationCurrency payment pointer.
                  example: true
              required:
              - amountToSend
              - originCurrency
              - destinationCurrency
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Payout to Chimoney wallets completed successfully.
                  data:
                    type: object
                    properties:
                      paymentLink:
                        type: string
                        example: http://localhost:4000/pay/?issueID=82628206-0253-4d37-b919-569efe896506_2_1725919202472
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              example: RnNDSRhA9xzTe9qSiBfb
                            valueInUSD:
                              type: string
                              example: '2'
                            chimoney:
                              type: integer
                              example: 2000
                            issueID:
                              type: string
                              example: 82628206-0253-4d37-b919-569efe896506_2_1725919202472
                            receiver:
                              type: string
                              example: ae07bf52-002b-489a-bc12-202f3beb3260
                            personalizedMessage:
                              type: string
                              example: Cross wallet transfer
                            fee:
                              type: number
                              example: 1
                            type:
                              type: string
                              example: chimoney
                            issuer:
                              type: string
                              example: 82628206-0253-4d37-b919-569efe896506
                            t_id:
                              type: integer
                              example: 633011
                            chiRef:
                              type: string
                              example: 3f4ca4f3-7bd7-44d0-bc8f-089bd9052b5e
                            narration:
                              type: string
                              example: Cross wallet transfer
                            integration:
                              type: object
                              properties:
                                reference:
                                  type: string
                                appID:
                                  type: string
                                  example: TyGlLVepVqfOj3635qrC
                            issueDate:
                              type: string
                              format: date-time
                              example: '2024-09-09T22:00:18.901Z'
                            redeemLink:
                              type: string
                              example: http://localhost:4000/redeem/?chi=3f4ca4f3-7bd7-44d0-bc8f-089bd9052b5e
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: postV024MulticurrencyWalletsTransfer
      x-operation-id-source: derived
  /v0.2.4/accounts/public-profile:
    post:
      summary: Get Public profile of a Chimoney User
      tags:
      - Interledger
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userID:
                  type: string
                  description: User ID of Chimoney user. Must provide one of userID, linkCode, p_id, or interledgerWalletAddress.
                p_id:
                  type: string
                  description: User Public profile ID of Chimoney user. Must provide one of userID, linkCode, p_id, or interledgerWalletAddress.
                linkCode:
                  type: string
                  description: NFC Link Code. Must provide one of userID, linkCode, p_id, or interledgerWalletAddress.
                interledgerWalletAddress:
                  type: string
                  description: Interledger wallet address (Payment Pointer) in format $ilp.chimoney.io/username or https://ilp.chimoney.io/username. Must provide one of userID, linkCode, p_id, or interledgerWalletAddress.
                  example: $ilp.chimoney.io/alice
            example:
              userID: x2Zfuf0ZHBWOqlgzlpEK3Z3TVkw2
              linkCode: '202310001'
              p_id: '9876543'
              interledgerWalletAddress: $ilp.chimoney.io/alice
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Status of the request.
                    example: success
                  message:
                    type: string
                    description: Success message.
                    example: User profile retrieved successfully
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: User's unique identifier.
                      accountSecondCurrencies:
                        type: array
                        description: Array of secondary currencies linked to the account.
                        items:
                          type: string
                        example: []
                      preferredExchangeRate:
                        type: boolean
                        description: Whether the user has set a preferred exchange rate.
                      createdDate:
                        type: string
                        format: date-time
                        description: The date and time when the user account was created.
                      joinDate:
                        type: string
                        format: date-time
                        description: The date and time when the user joined.
                      email:
                        type: string
                        description: The user's email address.
                      verification:
                        type: object
                        description: User's verification status.
                        properties:
                          status:
                            type: string
                            description: Verification status of the user.
                            example: completed
                      firstName:
                        type: string
                        description: The user's first name.
                      lastName:
                        type: string
                        description: The user's last name.
                      career:
                        type: string
                        description: The user's career field.
                      purposeOfChimoney:
                        type: string
                        description: The user's reason for using Chimoney.
                      socials:
                        type: object
                        properties:
                          links:
                            type: array
                            description: Links to the user's social profiles.
                            items:
                              type: object
                      updatedDate:
                        type: string
                        format: date-time
                        description: The last date the user's profile was updated.
                      p_id:
                        type: integer
                        description: User's profile ID.
                      points:
                        type: integer
                        description: The user's accumulated points.
                      badges:
                        type: array
                        description: User's earned badges.
                        items:
                          type: string
                      paymentData:
                        type: object
                        description: User's payment information.
                        properties:
                          interledgerWalletAddress:
                            type: string
                            description: The user's interledger wallet address.
                            example: https://ilp-sandbox.chimoney.com/4252496
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Error related to resource not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Status of the error
                    example: error
                  type:
                    type: string
                    description: Type of error
                    example: Resource Not Found
                  code:
                    type: string
                    description: Error code
                    example: USER_NOT_FOUND
                  message:
                    type: string
                    description: Detailed error message
                    example: User not found for the provided ID
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: postV024AccountsPublicProfile
      x-operation-id-source: derived
  /v0.2.4/accounts/issue-wallet-address:
    post:
      summary: Issue an Interledger wallet address for a user
      tags:
      - Interledger
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userID:
                  type: string
                  example: user123
                ilpUsername:
                  type: string
                  example: chimoney_user123
      responses:
        '200':
          description: Successfully issued wallet address
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    description: Success message.
                    example: Wallet Address issued succesfully
                  data:
                    type: string
                    example: walletAddress123
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: postV024AccountsIssueWalletAddress
      x-operation-id-source: derived
components:
  schemas:
    ValidationError:
      type: object
      properties:
        status:
          type: string
          description: Status of the validation error.
          example: error
        type:
          type: string
          description: Type of validation error.
          example: Validation Error
        code:
          type: string
          description: Error code indicating validation issue.
          example: INVALID_REQUEST
        message:
          type: string
          description: Detailed validation error message.
          example: The request parameters are invalid.
    Forbidden:
      type: object
      properties:
        status:
          type: string
          description: Status of the response.
          example: error
        error:
          type: string
          description: Error message indicating forbidden access.
          example: API Access not enabled for account Test. Email support@chimoney.io
    Unauthorized:
      type: object
      properties:
        status:
          type: string
          description: Status of the response.
          example: error
        error:
          type: string
          description: Error message indicating unauthorized access.
          example: API key is not defined. Generate a new one from the developer portal.
    ServerError:
      type: object
      properties:
        status:
          type: string
          description: Status of the error.
          example: error
        type:
          type: string
          description: Type of server error.
          example: server error
        code:
          type: string
          description: Specific error code for server issues.
          example: INTERNAL_SERVER_ERROR
        message:
          type: string
          description: Detailed message explaining the issue.
          example: An internal server error occurred.
  responses:
    Forbidden:
      description: Access to this resource is forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Forbidden'
    ValidationError:
      description: Validation error in the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    ServerError:
      description: Indicates an internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerError'
    Unauthorized:
      description: Access to this resource is not available for unauthenticated users.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Unauthorized'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
x-provenance:
  method: harvested
  publisher: Chimoney
  source: https://api.chimoney.io/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)