---
title: "Place an order"
method: POST
path: "/orders"
tags: ["Orders"]
---

# Place an order

`POST /orders`

It is possible to specify amount in the input or output in which case
the corresponding input or output amount will be computed.

The input or output amount can be estimated beforehand using the
dedicated endpoint, see "Estimate the amount of an order".

The input object must in principle contain the IBAN or crypto-address
which will be used to pay the order. In some cases, this is optional.
See "Estimate the amount of an order" to figure out if this information
can be omitted or not. Omitting the information increases the number of
situations were we can be required to cancel an order uppon
reception of the funds. To ensure a reliable execution of your order,
the crypto-address or IBAN must be provided and the paiment must be
made from the provided object.

## Request body

- PlaceOrderRequest — Exactly one of `input.amount` or `output.amount` must be specified.
  - `client_value` integer — An arbitrary integer provided by the API client. The property is shown in the order details and in the reporting API.
  - `contact_person` object — Information of a contact person to be used in case something unforeseen happens with the order. This information is optional. The customer can always get in touch with support via the order status page.
    - `email` string
  - `input` union, required
    - PlaceOrderRequestInputBankAccount — Input information for an order to be paid via a bank transfer. When the details of the bank account are present, the order must be paid from the corresponding bank account. The `input.object_information_optional` property in the amount estimate response indicates whether it is allowed to omit the details of the bank account.
      - `amount` string — Decimal number. Input amount of the exchange; amount to be sent by the customer. The input amount is all inclusive. Costs and fees are included.
      - `currency` string, required
      - `iban` string — IBAN of the bank account that will be used to pay the order.
      - `owner` object — Information about the owner of the bank account that will pay the order.
        - `address` string
        - `address_complement` string
        - `city` string
        - `country` string — Two-letter country code (ISO 3166-1 alpha-2).
        - `name` string
        - `state` string
        - `zip` string
      - `type` 'bank_account', required
    - PlaceOrderRequestInputBityAccount
      - `amount` string — Decimal number. Input amount of the exchange; amount to be sent by the customer. The input amount is all inclusive. Costs and fees are included.
      - `currency` string, required
      - `type` 'bity_account', required
    - PlaceOrderRequestInputCryptoAddress — Input information for an order to be paid via a crypto transaction. When the details of the crypto-address are present, the order must be paid from the corresponding crypto-address. The `input.object_information_optional` property in the amount estimate response indicates whether it is allowed to omit the details of the crypto-address.
      - `amount` string — Decimal number. Input amount of the exchange; amount to be sent by the customer. The input amount is all inclusive. Costs and fees are included.
      - `currency` string, required
      - `crypto_address` string — Crypto-address that will be used to pay the order.
      - `type` 'crypto_address', required
    - PlaceOrderRequestInputOnlineInstantPayment — Input object for an order to be paid via credit card or another form of electronic online paymint.
      - `amount` string — Decimal number. Input amount of the exchange; amount to be sent by the customer. The input amount is all inclusive. Costs and fees are included.
      - `currency` string, required
      - `type` 'online_instant_payment'
  - `output` union, required
    - PlaceOrderRequestOutputBankAccount — Output object for an order where the result of the exchange is sent to a bank account via a bank transfer.
      - `amount` string — Decimal number. Output amount of the exchange; amount to be received by the output object. The output amount is all inclusive. Costs and fees are included.
      - `currency` string, required
      - `bic_swift` string
      - `iban` string, required
      - `owner` union, required
        - object — Information about the owner of the bank account to which the output of the order is sent.
          - `name` string
          - `address` string
          - `address_complement` string
          - `city` string
          - `country` string — Two-letter country code (ISO 3166-1 alpha-2).
          - `state` string
          - `zip` string
        - object — Information about the owner of the bank account to which the output of the order is sent.
          - `name` string
          - `building_name` string
          - `building_number` string
          - `country` string — Two-letter country code (ISO 3166-1 alpha-2).
          - `country_subdivision` string — Identifies a subdivision of the country such as a state or region.
          - `department` string — Identifies a part of large organization or large building.
          - `district_name` string — Identifies a subdivision of the country subdivision.
          - `floor` string
          - `post_box` string
          - `post_code` string
          - `room` string
          - `street_name` string
          - `subdepartment` string — Identifies a subdivision within a department of a large organization or large building.
          - `town_location_name` string — Identifies a location within a town.
          - `town_name` string
      - `qr_reference` string — QR Bill reference (QR reference)
      - `reference` string — The length and the set of supported characters varies depending on the banks and networks involved. To avoid producing the "invalid_bank_account_reference" error, keep the reference short (32 characters or less is recommended) and use only simple characters (using only characters in a-z, A-Z, 0-9 and space is recommended).
      - `structured_creditor_reference` string — Structured creditor reference (ISO 11649).
      - `type` 'bank_account', required
      - `ultimate_debtor` union
        - object — Information about the ultimate debtor.
          - `name` string
          - `address` string
          - `address_complement` string
          - `city` string
          - `country` string — Two-letter country code (ISO 3166-1 alpha-2).
          - `state` string
          - `zip` string
        - object — Information about the ultimate debtor.
          - `name` string
          - `building_name` string
          - `building_number` string
          - `country` string — Two-letter country code (ISO 3166-1 alpha-2).
          - `country_subdivision` string — Identifies a subdivision of the country such as a state or region.
          - `department` string — Identifies a part of large organization or large building.
          - `district_name` string — Identifies a subdivision of the country subdivision.
          - `floor` string
          - `post_box` string
          - `post_code` string
          - `room` string
          - `street_name` string
          - `subdepartment` string — Identifies a subdivision within a department of a large organization or large building.
          - `town_location_name` string — Identifies a location within a town.
          - `town_name` string
    - PlaceOrderRequestOutputBityAccount
      - `amount` string — Decimal number. Output amount of the exchange; amount to be received by the output object. The output amount is all inclusive. Costs and fees are included.
      - `currency` string, required
      - `type` 'bity_account'
    - PlaceOrderRequestOutputCryptoAddress — Output object for an order where the result of the exchange is sent to a crypto-address.
      - `amount` string — Decimal number. Output amount of the exchange; amount to be received by the output object. The output amount is all inclusive. Costs and fees are included.
      - `currency` string, required
      - `crypto_address` string, required — Crypto-address to which the output of the order is sent.
      - `type` 'crypto_address', required
  - `partner_fee` PartnerFee — -> An additional fee perceived on behalf of the partner placing the order, expressed as a factor of the amount received from the customer.
    - `factor` union, required
      - number
      - string
  - `purpose` OrderPurpose — Information about the purpose of the order.
    - `category` string — Non-exhaustive list of possible values: - `bill_payment`: The purpose of the order is to pay a bill.
    - `comment` string — Comment about the purpose of the order. Users can use this comment in order to remember what was their purpose when placing the order.

## Response `201`

The order has been successfully created.

The `Location` header contains the URI (which can be relative) at
which the order status and details can be retrieved. That is the
`Location` header is meant to be interpreted as per RFC 7231 section
7.1.2.

## Other responses

- `400` — Following cases: - Unsupported currency pair. - Quota exceeded for the bank account or crypto-address. - Provided input payment address cannot be used currently. Please try again later. - Internal error.
- `429` — Rate-limited (request ignored)

---

[API](https://skmtc.dev/bity/apis/bity-exchange-api.md) · [All operations](https://skmtc.dev/bity/apis/bity-exchange-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bity/bity-exchange-api/revisions/fd48443fbac2/schema)