<!-- canonical: https://docs.costplus.io/api-reference/orders/createOrder -->

> Create a new payment order.

The response shape depends on the request body:
- If you send a `transactions` array, each transaction object in the response contains its own `payment_url`. Redirect the customer to that URL.
- If you omit `transactions`, the order has a top-level `order_url` instead — the hosted page lets the customer pick from all enabled payment methods.

See the [Hosted Payment Page guide](/docs/guides/hosted-payment-page) for both flows side by side.

# Create a new order

Create a new payment order.

The response shape depends on the request body:
- If you send a `transactions` array, each transaction object in the response contains its own `payment_url`. Redirect the customer to that URL.
- If you omit `transactions`, the order has a top-level `order_url` instead — the hosted page lets the customer pick from all enabled payment methods.

See the [Hosted Payment Page guide](/docs/guides/hosted-payment-page) for both flows side by side.

## Endpoint

```
POST /orders
```

## Authentication

HTTP Basic — use your API key as the username with an empty password.

```bash
curl -u YOUR_API_KEY: https://api.costplus.online/v1/orders/
```

## Request body

Content-Type: `application/json` (required)

Fields:

- `id` — string. Order identifier
- `project_id` — string. Project identifier
- `merchant_id` — string. Merchant identifier used to create the order
- `order_url` — string. The order URL if available
- `refund_of_order_id` — string. Order ID of the original order, if this is a refund
- `refund_orders` — array. Order IDs of related refund orders
- `refunded_amount` — integer. Amount refunded on this order
- `chargeback_of_order_id` — string. Order ID of the original order, if this is a chargeback
- `chargeback_orders` — array. Order IDs of related chargeback orders
- `reversal_of_order_id` — string. Order ID of the original order, if this is a reversal
- `reversal_orders` — array. Order IDs of related reversal orders
- `related_order_id` — string. Order ID of the original order
- `related_orders` — array. Order IDs of related orders
- `related_payment_link_id` — string. ID of the related payment link
- `merchant_order_id` — string,null. Merchant's internal order identifier
- `merchant_bulk_id` — string,null. Merchant bulk ID (for grouping transactions for payouts)
- `merchant_name` — string,null. Merchant name (for payouts)
- `merchant_iban` — string,null. Merchant IBAN (for payouts)
- `merchant_bic` — string,null. Merchant BIC (for payouts)
- `created` — string. Creation timestamp (ISO 8601)
- `modified` — string,null. Last modified timestamp (ISO 8601)
- `completed` — string,null. Completion timestamp (ISO 8601)
- `expiration_period` — string,null. Order expiration interval (ISO 8601 duration, e.g. PT30M)
- `capture_mode` — string. Capture mode. `delayed` requires `expiration_period`.
- `currency` — string (required). ISO 4217 currency code
- `amount` — integer (required). Order amount in minor units (e.g. cents), including VAT
- `description` — string. Order description
- `status` — string. Current order status
- `flags` — array. Order flags
- `locale` — string,null. Language for the hosted payment page. Supported: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
- `payment_methods` — array. Filter available payment methods for this order. Omit to show all enabled methods, or pass a single value to restrict to one method. To offer multiple specific methods, use the `transactions` array instead (one entry per method).
- `transactions` — array. Collection of transactions
- `return_url` — string,null. URL to redirect the customer after a successful or non-failure payment. Acts as the default redirect for all statuses when `failure_url` is not provided.
- `failure_url` — string,null. URL to redirect the customer when the order status is `cancelled`, `expired`, or `error`. Only used when both `return_url` and `failure_url` are provided.
- `webhook_url` — string. URL for status change notifications
- `order_lines` — array. Order line items
- `customer` — object. Customer details
- `client` — object. Client integration details
- `extra` — object. Free-form data stored with the order

Example:

```json
{
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-order-id-1",
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "payment_method": "credit-card"
    }
  ]
}
```

## Responses

### 200 — The created order

```json
{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "merchant_order_id": "my-order-id-1",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "created": "2026-01-15T12:00:05.433502+00:00",
  "modified": "2026-01-15T12:00:05.553125+00:00",
  "expiration_period": "PT1H",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "new",
      "amount": 1295,
      "currency": "EUR",
      "channel": "ecom",
      "credit_debit": "credit",
      "is_capturable": false,
      "expiration_period": "PT30M",
      "payment_url": "https://api.costplus.online/pay/4851e31c.../select-payment-method/credit-card/d291f03f.../",
      "payment_method_details": {}
    }
  ]
}
```

### 401 — Invalid or missing API key

### 403 — No authorization for the requested resource

## cURL

```bash
curl -u YOUR_API_KEY: \
  -X POST https://api.costplus.online/v1/orders/ \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1295,
    "currency": "EUR",
    "merchant_order_id": "ORDER-1",
    "description": "Test order",
    "return_url": "https://example.com/return",
    "failure_url": "https://example.com/cancel",
    "webhook_url": "https://example.com/webhook",
    "transactions": [{ "payment_method": "credit-card" }]
  }'
```