---
title: "Create order"
method: POST
path: "/v2/orders"
tags: ["Orders"]
---

# Create order

`POST /v2/orders`

Create a Scalapay order. The endpoint returns a `token` required to capture the payment and a `checkoutUrl` that redirects the customer to Scalapay Checkout, where the payment is authorized.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `totalAmount` Amount, required — The monetary amount.
    - `amount` string, required — Monetary value. Example: 187.95.
    - `currency` string, required — Currency code.
  - `consumer` object, required — Consumer information.
    - `phoneNumber` string, required — Customer phone number with country code.
    - `givenNames` string, required — Consumer first name.
    - `surname` string, required — Consumer last name.
    - `email` string, required — Consumer email address.
  - `billing` Address — Address information.
    - `phoneNumber` string — Customer phone number with country code.
    - `countryCode` string, iso-alpha-2 — Two-letter country code (e.g., IT for Italy).
    - `name` string — Name of the recipient.
    - `postcode` string — Postal code.
    - `suburb` string — Suburb or city.
    - `line1` string — Primary address line.
  - `shipping` Address, required — Address information.
    - `phoneNumber` string — Customer phone number with country code.
    - `countryCode` string, iso-alpha-2 — Two-letter country code (e.g., IT for Italy).
    - `name` string — Name of the recipient.
    - `postcode` string — Postal code.
    - `suburb` string — Suburb or city.
    - `line1` string — Primary address line.
  - `items` object[], required — List of items in the order.
    - `gtin` string — Global Trade Item Number (UPC, EAN, JAN, ISBN, ITF-14).
    - `quantity` integer, required — Quantity of the item.
    - `price` Amount, required — The monetary amount.
      - `amount` string, required — Monetary value. Example: 187.95.
      - `currency` string, required — Currency code.
    - `name` string, required — Name of the item.
    - `category` string, required — Category of the item.
    - `subcategory` string[] — Subcategories of the item.
    - `sku` string, required — Stock Keeping Unit (SKU) code.
    - `brand` string — Brand name.
    - `pageUrl` string — URL of the product page.
    - `imageUrl` string — URL of the product image.
  - `discounts` object[] — Discounts applied to the order.
    - `amount` Amount — The monetary amount.
      - `amount` string, required — Monetary value. Example: 187.95.
      - `currency` string, required — Currency code.
    - `displayName` string — Display name of the discount.
  - `merchant` object, required — Redirection URLs for completing the payment.
    - `redirectCancelUrl` string, required — Use https://portal.integration.scalapay.com/failure-url for testing.
    - `redirectConfirmUrl` string, required — Use https://portal.integration.scalapay.com/success-url for testing.
  - `merchantReference` string — Merchant reference for tracking the order in your system.
  - `shippingAmount` Amount — The monetary amount.
    - `amount` string, required — Monetary value. Example: 187.95.
    - `currency` string, required — Currency code.
  - `taxAmount` Amount — The monetary amount.
    - `amount` string, required — Monetary value. Example: 187.95.
    - `currency` string, required — Currency code.
  - `type` '' | 'online' | 'offline' | 'link' — Type of order. Use `online` for online orders, `offline` for offline orders, and `link` for orders sent by SMS. When using `link`, include the extensions field.
  - `product` '' | 'pay-in-3' | 'pay-in-4' | 'later' — Product type. Could be empty. Use `pay-in-3` for pay in 3, `pay-in-4` for pay in 4, and `later` for pay later.
  - `frequency` object — Specify the frequency of the payment. This is useful for pay later products. Do not include when using pay-in-3 or pay-in-4.
    - `number` integer
    - `frequencyType` string
  - `orderExpiryMilliseconds` integer — Length of time (in milliseconds) that the order is valid. The maximum value is determined by your Scalapay contract. To extend it, contact Scalapay support.
  - `extensions` Extensions — Additional extension properties for the order.
    - `industry` object — Industry-specific extensions.
      - `travel` object — Travel-related extension information.
        - `startDate` string, date — Travel start date.
        - `endDate` string, date — Travel end date.
    - `type` object — Extensions for link orders.
      - `link` object — Extensions for orders created via a link.
        - `notification` object, required — Notification details for the order.
          - `phoneCountryCode` string — Customer phone number country code. Required if SMS is selected as a notification channel.
          - `phoneNumber` string — Customer phone number. Required if SMS is selected as a notification channel.
          - `preferredLanguage` '' | 'english' | 'italiano' | 'francais' | 'deutsch' | 'espanol' | 'dutch' | 'suomi' | 'portuguese' — Customer's preferred language.
          - `emailAddress` string — Customer email address. Required if email is selected as a notification channel.
          - `channels` string[], required — Notification channels to use. Choose "email" and/or "sms".

## Response `200`

Successful order creation

- object
  - `token` string, required — The order token used to capture the payment.
  - `expires` string — Expiry timestamp of the order.
  - `checkoutUrl` string — URL that redirects the customer to Scalapay Checkout.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `409` — Conflict

---

[API](https://skmtc.net/scalapay/apis/scalapay-api.md) · [All operations](https://skmtc.net/scalapay/apis/scalapay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scalapay/scalapay-api/versions/c43238b80cb9/schema)