---
title: "Create incoming payment"
method: POST
path: "/simulator/{connected_account_id}/incoming_payments"
tags: ["Bank Simulator"]
---

# Create incoming payment

`POST /simulator/{connected_account_id}/incoming_payments`

## Request

- Base URL: `https://sandbox.numeral.io/v1`
- URL: `https://sandbox.numeral.io/v1/simulator/{connected_account_id}/incoming_payments`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/numeral/apis/payments/docs/simulator/:connected_account_id/incoming_payments/post.ts> (a function with typed inputs; its response is checked against the schema)

Create an incoming payment to test your integration. This endpoint can only be used in the sandbox environment.

## Path parameters

- `connected_account_id` string, uuid, required

## Request body

- object[]
  - `type` 'sepa' | 'sepa_instant' | 'swift': The type of payment. Only `sepa`, `sepa_instant` and `swift` are supported for now.
  - `direction` 'credit' | 'debit': Either `credit` or `debit`. Describes the direction the money is flowing. A credit moves money from someone else's account to your account. A debit moves money from your account to someone else's account.
  - `amount` integer: The absolute amount of a payment, in the specified currency's smallest units. For euro payments, the smallest unit is cents. €20 is represented as `2000`.
  - `currency` string: The three-letter ISO 4217 currency code, in lowercase.
  - `reference` string: The reference that will appear on the origin and destination account statements, with a maximum of 140 characters.
  - `requested_execution_date` string, date: The requested execution date of the incoming payment.
  - `fee_options` 'originator' | 'receiver' | 'shared': Network payment fee preference. Only applicable to Swift payments. Supported values include `originator` (fee paid by the originating party), `receiver` (paid by the receiving party), or `shared` (fee split between the originating and the receiving party).
  - `purpose` string: The purpose code of the incoming payment, ensuring compliance with regulatory requirements of certain beneficiary countries. Only applicable to `swift` and `chaps` payment types.
  - `category_purpose_code` string: The category purpose of the incoming payment. Recommended for CHAPS payments.
  - `bank_data` object: Bank data, such as message and transaction IDs, in JSON format.
    - `message_id` string
    - `transaction_id` string
    - `end_to_end_id` string
    - `instruction_id` string
  - `originating_account` object: The account from which the payment originates.
    - `account_number` string: The account number, for example an IBAN.
    - `bank_code` string: The bank code. For example, a BIC or SWIFT code.
    - `holder_name` string: The name of the legal entity or individual holding the account.
    - `holder_address` object: The address of the account holder.
      - `line_1` string: Line 1.
      - `line_2` string: Line 2.
      - `building_number` string: Building number.
      - `street_name` string: Street name.
      - `postal_code` string: Postal / zip code.
      - `region_state` string: Region or state.
      - `city` string: City.
      - `country` string: ISO 3166 alpha-2 country code.
      - `department` string, nullable: Department name or code.
      - `sub_department` string, nullable: Sub-department name.
      - `building_name` string, nullable: Name of the building.
      - `floor` string, nullable: Floor number or identifier.
      - `postal_box` string, nullable: Postal box.
      - `room` string, nullable: Room number.
      - `city_location_name` string, nullable: Specific city location or landmark.
      - `district_name` string, nullable: District name or administrative region.
    - `creditor_identifier` string: The unique reference for organisations collecting payments by SEPA Direct Debit. Required only if direction is `debit`.
    - `organization_identification` object: The organization identification of the originating account.
      - `legal_entity_identifier` string: The legal entity identifier (LEI) of the originating account. Recommended for CHAPS payments.
  - `receiving_account` object: The receiving account of the payment.
    - `creditor_identifier` string: The unique reference for organisations collecting payments by SEPA Direct Debit. Required only if direction is `debit`.
    - `account_number` string: The account number, for example an IBAN.
    - `bank_code` string: The bank code. For example, a BIC or SWIFT code.
    - `holder_name` string: The name of the legal entity or individual holding the account.
    - `holder_address` object: The address of the account holder.
      - `line_1` string: Line 1.
      - `line_2` string: Line 2.
      - `building_number` string: Building number.
      - `street_name` string: Street name.
      - `postal_code` string: Postal / zip code.
      - `region_state` string: Region or state.
      - `city` string: City.
      - `country` string: ISO 3166 alpha-2 country code.
      - `department` string, nullable: Department name or code.
      - `sub_department` string, nullable: Sub-department name.
      - `building_name` string, nullable: Name of the building.
      - `floor` string, nullable: Floor number or identifier.
      - `postal_box` string, nullable: Postal box.
      - `room` string, nullable: Room number.
      - `city_location_name` string, nullable: Specific city location or landmark.
      - `district_name` string, nullable: District name or administrative region.
    - `organization_identification` object: The organization identification of the receiving account.
      - `legal_entity_identifier` string: The legal entity identifier (LEI) of the receiving account. Recommended for CHAPS payments.
  - `direct_debit_mandate` object, nullable: The mandate authorizing the direct debit.
    - `reference` string, required: The unique code that is assigned to a mandate. The mandate reference is displayed in the destination account statements when a direct debit is debited.
    - `signature_date` string, date, required: The signature date of the mandate.
    - `type` 'sepa_core' | 'sepa_b2b' | 'bacs_debit', required: The type of the mandate.
    - `sequence` 'one_off' | 'recurring': Deprecated, use `frequency` instead.
    - `frequency` 'one_off' | 'recurring': The frequency of the mandate, either `one_off` or `recurring`. Mandatory when type is `sepa_core` or `sepa_b2b`.
  - `intermediary_agents` object[]: Intermediary financial institution agents via which the payment should be processed. Only applicable to `swift`, `swift_fi_to_fi`, and `chaps` payments.
    - `financial_institution_identification` object, required: ISO 20022 financial institution identification of the agent.
      - `swift_code` string: SWIFT BIC of the agent used as the network identifier (e.g. for SWIFT gpi routing).
      - `bank_code` string: Domestic or scheme-specific bank code of the agent (e.g. BIC for SEPA/Target2, sort code for CHAPS).
      - `bank_code_format` 'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other': Format of `bank_code` (e.g. `bic`, `other`).
      - `name` string: Name of the agent's financial institution.
      - `legal_entity_identifier` string: Legal entity identifier (LEI) of the agent.
      - `postal_address` object: Postal address of the agent.
        - `line_1` string
        - `line_2` string
        - `building_number` string
        - `street_name` string
        - `postal_code` string
        - `region_state` string: Region or state.
        - `city` string
        - `country` string: ISO 3166 alpha-2 country code.
      - `other` object: Other proprietary identification of the agent.
        - `identification` string: Identification value.
        - `identification_type` 'bank_identification' | 'central_bank_identification' | 'clearing_house_identification' | 'company_incorporation_number' | 'company_identification' | 'customer_number' | 'duns_number' | 'employee_number' | 'global_location_number' | 'siren' | 'siret' | 'tax_number' | 'telephone_number' | 'business_domain_identification' | 'other_identification' | 'unknown': Type of identification. Use `custom_identification_type` for values not covered by this list.
        - `custom_identification_type` string: Proprietary identification type, used when `identification_type` does not cover the use case.
        - `identification_issuer` string: Entity that issued the identification.
    - `account_number` string: Account number held at the intermediary agent.
    - `account_number_format` string: Format of `account_number` (e.g. `iban`, `bban`).

## Response `200`

Incoming payment was successfully created.

- SimulatorV2Response
  - `files` object[], required: The created files
    - `file_id` string, uuid: The created file ID. This field will be available only in some particular case like instant incoming payments.
    - `file_name` string, required: The created file name.
    - `created_at` string, date-time, required: The UTC timestamp representing the moment we ingested the file.

## Other responses

- `400`: Bad request. Validation error or missing required fields.
- `401`: Unauthorized. API key is missing or invalid.
- `403`: Forbidden. Feature is not enabled for this API key.

---

[API](https://skmtc.dev/numeral/apis/payments.md) - [All operations](https://skmtc.dev/numeral/apis/payments/llms.txt) - [OpenAPI document](https://skmtc.dev/numeral/apis/payments/revisions/220f101cc2ef?raw)