openapi: 3.0.3
info:
  title: api-onboarding Account Usage Demo API
  version: v1
  description: Requests that are only available in the Demo environment.
servers:
- url: /onboarding
  description: Relative URL
- url: https://api.currencycloud.com/onboarding
  description: Production server (uses live data)
- url: https://devapi.currencycloud.com/onboarding
  description: Dev server (uses test data)
tags:
- name: Demo
  description: Requests that are only available in the Demo environment.
paths:
  /demo/funding/create:
    post:
      tags:
      - Demo
      x-api-group: collect
      summary: Emulate inbound funds
      description: Triggers a production-like flow for processing funds, topping up CM balance or rejecting the transaction without topping up CM balance. This resource is only available in the Currencycloud Demo environment; it is not implemented in the Production environment.
      operationId: SimulateFunding
      consumes:
      - multipart/form-data
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - name: id
        in: formData
        required: true
        type: string
        description: Unique value in UUID format, user-generated with each request.
        format: uuid
      - name: sender_name
        in: formData
        required: false
        type: string
        default: Test sender
        description: Sender's name.
        minLength: 1
        maxLength: 255
      - name: sender_address
        in: formData
        required: false
        type: string
        description: Sender's address.
        minLength: 1
        maxLength: 255
      - name: sender_country
        in: formData
        required: false
        type: string
        description: Two character ISO sender country code.
        format: iso3166-1-alpha-2
        pattern: ^[A-Z]{2}$
      - name: sender_reference
        in: formData
        required: false
        type: string
        description: Sender reference.
        minLength: 1
        maxLength: 255
      - name: sender_account_number
        in: formData
        required: false
        type: string
        description: Sender account number.
        minLength: 1
        maxLength: 255
      - name: sender_routing_code
        in: formData
        required: false
        type: string
        description: Sender routing code.
        minLength: 1
        maxLength: 255
      - name: receiver_account_number
        in: formData
        required: true
        type: string
        description: A client's virtual account number or its sub-account (as seen in Find Funding Accounts).
        minLength: 1
        maxLength: 255
      - name: receiver_routing_code
        in: formData
        required: false
        type: string
        description: A client's virtual account routing code or its sub-account (as seen in Find Funding Accounts).
        minLength: 1
        maxLength: 255
      - name: amount
        in: formData
        required: true
        type: number
        description: Amount of the emulated transaction.
        pattern: ^\d+(\.\d{1,3})?$
      - name: currency
        in: formData
        required: true
        type: string
        description: Three-digit currency code.
        format: iso-4217
        pattern: ^[A-Z]{3}$
      - name: action
        in: formData
        required: false
        type: string
        enum:
        - approve
        - reject
        default: approve
        description: Allows you to trigger approval or rejection behaviour.
      - name: on_behalf_of
        in: formData
        required: false
        type: string
        description: A contact UUID for the sub-account you're acting on behalf of.
        format: uuid
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/SimulateFunding'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - code: id_cant_be_blank
            category: id
            message: ID can't be blank
            params: ''
          - code: id_has_invalid_format
            category: id
            message: ID should be in UUID format
            params: ''
          - code: receiver_account_number_cant_be_blank
            category: receiver_account_number
            message: Receiver account number can't be blank
            params: ''
          - code: receiver_account_number_not_found
            category: receiver_account_number
            message: Receiver account number not found
            params: ''
          - code: sender_country_is_invalid
            category: sender_country
            message: Sender country is invalid
            params: ''
          - code: sender_country_has_invalid_format
            category: sender_country
            message: Sender country is not a valid ISO 3166 country code
            params: ''
          - code: amount_cant_be_blank
            category: amount
            message: Amount can't be blank
            params: ''
          - code: amount_must_be_greater_than_0
            category: amount
            message: Amount must be greater than 0
            params: ''
          - code: amount_must_be_less_than_1000000000000
            category: amount
            message: Amount must be less than 1 000 000 000 000
            params: ''
          - code: amount_is_invalid
            category: amount
            message: Amount should be numeric with 2 decimal points separated by '.'
            params: ''
          - code: action_is_invalid
            category: action
            message: 'Action is invalid, should be in range: approve, reject'
            params: ''
          - code: currency_cant_be_blank
            category: currency
            message: Currency can't be blank
            params: ''
          - code: currency_is_invalid
            category: currency
            message: Currency is invalid
            params: ''
          - code: currency_has_invalid_format
            category: currency
            message: Currency is not a valid ISO 4217 currency code
            params: ''
          - code: currency_not_supported_by_account
            category: currency
            message: Currency not supported by account
            params: ''
          - code: on_behalf_of_is_not_valid_uuid
            category: on_behalf_of
            message: on_behalf_of should be in UUID format
            params: ''
          - code: on_behalf_of_self
            category: on_behalf_of
            message: You cannot act on behalf of your own Contact
            params: ''
          - code: id_has_already_been_taken
            category: id
            message: ID was already used in a previous request
            params: ''
          schema:
            $ref: '#/definitions/CreateSimulateFundingError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          schema:
            $ref: '#/definitions/UnauthorizedError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '403':
          description: Forbidden.
          x-errors:
          - code: permission_denied
            message: permission_denied
            params: ''
          schema:
            $ref: '#/definitions/ForbiddenError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '404':
          description: Resource not found.
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '429':
          description: Too many requests.
          x-errors:
          - code: too_many_requests
            category: base
            message: Too many requests have been made to the api. Please refer to the Developer Center for more information
            params: ''
          schema:
            $ref: '#/definitions/RateLimitError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '503':
          description: Service is temporary unavailable
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
components:
  securitySchemes:
    AuthToken:
      type: apiKey
      in: header
      name: X-Auth-Token
definitions:
  SimulateFunding:
    type: object
    description: SimulateFunding
    required:
    - id
    - account_id
    - state
    - sender_name
    - sender_address
    - sender_country
    - sender_reference
    - sender_account_number
    - sender_routing_code
    - receiver_account_number
    - receiver_routing_code
    - amount
    - currency
    - action
    - short_reference
    - updated_at
    - created_at
    additionalProperties: false
    properties:
      id:
        type: string
        description: The unique UUID for the simulated fund.
      account_id:
        type: string
        description: The account UUID the simulated fund was created for.
      state:
        type: string
        description: The state of the simulated fund.
      sender_name:
        type: string
        description: The sender's name.
      sender_address:
        type: string
        description: The sender's address.
      sender_country:
        type: string
        description: Two-digit sender country.
      sender_reference:
        type: string
        description: Sender reference.
      sender_account_number:
        type: string
        description: Sender account number.
      sender_routing_code:
        type: string
        description: Sender routing code.
      receiver_account_number:
        type: string
        description: A client or its sub-account's account number.
      receiver_routing_code:
        type: string
        description: Routing code for a client or its sub-account.
      amount:
        type: string
        description: Amount of the emulated transaction.
      currency:
        type: string
        description: Three-digit currency code.
      action:
        type: string
        description: Allows you to trigger approval or rejection behaviour.
        enum:
        - approve
        - reject
      short_reference:
        type: string
        description: The reference generated by the system to identify the fund.
      created_at:
        type: string
        description: The date-time the SSI was added to the account.
        format: date-time
      updated_at:
        type: string
        description: The date-time the SSI was last updated on the account.
        format: date-time
    example:
      id: 2090939e-b2f7-3f2b-1363-jfy28d74kc72
      account_id: 2090939e-b2f7-3f2b-1363-4d235b3f58af
      state: pending
      sender_name: Mr. Sender
      sender_address: Some Street
      sender_country: GB
      sender_reference: sender-ref"
      sender_account_number: 22223333
      sender_routing_code: 222333
      receiver_account_number: 22213332
      receiver_routing_code: 776813
      amount: '150.53'
      currency: GBP
      action: reject
      short_reference: REF-22122
      created_at: '2018-05-14T14:18:30+00:00'
      updated_at: '2018-05-14T14:18:30+00:00'
  RateLimitError:
    type: object
    description: Too many requests.
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this validation/error.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
  UnauthorizedError:
    type: object
    description: Authorization error.
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
        enum:
        - auth_failed
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
    example:
      error_code: auth_failed
      error_messages:
        api_key:
        - code: invalid_supplied_credentials
          message: Authentication failed with the supplied credentials
          params: {}
  ForbiddenError:
    type: object
    description: Permission error.
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
        enum:
        - auth_failed
      error_messages:
        type: object
        description: Detailed error information on what permissions are missing so that the request could not be fulfilled
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents the reasons why the request was not permitted.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
  CreateSimulateFundingError:
    type: object
    description: 'Client error information for the Create Simulated Funding endpoint.

      '
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255