POST /orders

When a user selects an Optty integrated APM, you should send through the order via this method.

Creates an order ---- [auth scope: api-user]

post

Authorizations

Body

orderReferencestringRequired

A unique order reference to use for identifying an order internally.

bnplProviderstring · enumRequired

The APM provider to place the order against (returned in GET Options).

Possible values:

purchaseCountrystringRequired

The country code the purchase is originating from. in ISO 3166 alpha-2 format.

purchaseCurrencystringRequired

The country currency the purchase is being made in, using ISO 4217 format.

localestringRequired

The country locale in RFC 1766 standard.

shippingAmountnumberOptional

The shipping amount for the order

discountAmountnumberOptional

The discount amount for the order

taxAmountnumberOptional

The tax amount for the order

orderAmountnumberRequired

The order amount, including tax.

customerall ofRequired

The customer placing the order.

billingAddressall ofRequired

The customer`s billing address.

shippingAddressall ofOptional

The customer`s shipping address.

shippingTypestring · enumOptional

The shipping type for this order

Possible values:

shippingMethodstring · enumOptional

The shipping method for this order

Possible values:

autoCapturebooleanOptional

Determine if payment should be auto captured or not

additionalDataobjectOptional

Additional Data for BNPLs

dynamicRedirectUrlstringOptional

A redirect url to once a payment is completed

dynamicCallbackUrlstringOptional

A callback url once payment is completed

cancellationTimeoutnumberOptional

The cancellation timeout for the order

partnerConfigurationobjectOptional

The partner configuration

isMPGSbooleanOptional

To check if MPGS

surchargenumberOptional

Fee borne by the paying customer

initiatorstring · enumOptional

Payment initiation source (i.e. payment-link (optty-direct), regular, e.t.c.

Possible values:

invoiceNumberstringOptional

The invoice number for Optty-direct/Payment-link transaction

getTokenbooleanOptional

To receive token for repeat payments in notifications/webhooks

tokenstringOptional

Token For repeat payments

channelstringOptional

Channel Alias

sessionIdstringOptional

The session ID of the payment

customerTokenstringOptional

The JWT Token of the customer

partnerOrderReferencestringOptional

Partner order reference

Responses

201Success

application/json

400Error

application/json

401Error

application/json

404Error

application/json

post

HTTPcURLJavaScriptPython

POST /orders HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 1400

{
  "orderReference": "text",
  "bnplProvider": "KLARNA",
  "purchaseCountry": "text",
  "purchaseCurrency": "text",
  "locale": "text",
  "shippingAmount": 1,
  "discountAmount": 1,
  "taxAmount": 1,
  "orderAmount": 1,
  "orderItems": [
    {
      "name": "text",
      "imageUrl": "text",
      "sku": "text",
      "quantity": 1,
      "unitPrice": 1,
      "totalAmount": 1,
      "type": "text",
      "departureDate": "text",
      "flightNumber": "text",
      "origin": "text",
      "destination": "text",
      "title": "text",
      "unitAmount": 1,
      "unitTaxAmount": 1,
      "unitDiscountAmount": 1
    }
  ],
  "customer": {
    "firstName": "text",
    "lastName": "text",
    "email": "text",
    "phoneNumber": "text"
  },
  "billingAddress": {
    "title": "text",
    "firstName": "text",
    "lastName": "text",
    "phoneNumber": "text",
    "email": "text",
    "streetAddress": "text",
    "streetAddress2": "N/A",
    "city": "text",
    "state": "text",
    "country": "text",
    "region": "text",
    "postalCode": "text"
  },
  "shippingAddress": {
    "title": "text",
    "firstName": "text",
    "lastName": "text",
    "phoneNumber": "text",
    "email": "text",
    "streetAddress": "text",
    "streetAddress2": "N/A",
    "city": "text",
    "state": "text",
    "country": "text",
    "region": "text",
    "postalCode": "text"
  },
  "shippingType": "normal",
  "shippingMethod": "store",
  "autoCapture": true,
  "additionalData": {},
  "dynamicRedirectUrl": "text",
  "dynamicCallbackUrl": "text",
  "cancellationTimeout": 1,
  "partnerConfiguration": {},
  "isMPGS": true,
  "surcharge": 1,
  "initiator": "widget",
  "invoiceNumber": "text",
  "getToken": true,
  "token": "text",
  "channel": "text",
  "sessionId": "text",
  "customerToken": "text",
  "partnerOrderReference": "text"
}

{
  "orderId": "text",
  "orderToken": "text",
  "redirectUrl": "text",
  "bnplProvider": "KLARNA",
  "orderReference": "text",
  "orderAmount": 1,
  "orderPaymentOption": "text",
  "orderDate": "2025-07-14T10:54:24.878Z",
  "paymentStatus": "text",
  "transactionReference": "text",
  "surcharge": 1,
  "bnplLateFeeText": "text",
  "bnplCustomerFeeText": "text",
  "preferredDisplayMode": "text",
  "incontextDisplayMode": "text"
}

Sample Request/Response

Sample Request

{
   "bnplProvider":"LATITUDEPAY_AU",
   "locale":"en_AU",
   "customerToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkZW50aWZpZXIiOiI5OWIwODI1MDA4OTUxMDNjMmNjNTNiZmNhMGVlZTNjOTdjMjE2MGM4ZGFhMGM0MmQ4NmI3M2M4NWU5NjA0NTE5ZGEzMDI4MWE3MjlhYzYwMWZjYzMyZDc4ZTdjZmQ1NmJkMjllNjIwZTI2YWU0ZTYzYTRjZTVlOTc2NWE2ZjA3NCIsIm1lcmNoYW50SWQiOiJkNmJiZmQ5Zi02OWZhLTQ3MjgtOTU0YS04MWU0NWI4YWFkMmQiLCJpYXQiOjE2MDE2NjAwMTUsImV4cCI6MTYwMTY2MzYxNX0.Y0UKdtSNPVnJlLN3Xv53Y1_o2AbLPhjxJ1P5O0DSpnE",
   "orderReference":"LP000_OrderID",
   "orderAmount":144.89,
   "taxAmount":6.9,
   "shippingAmount":7.99,
   "discountAmount":0,
   "purchaseCountry":"AU",
   "purchaseCurrency":"AUD",
   "orderItems":[
      {
         "name":"Optty Striped Dress Shirt",
         "quantity":1,
         "sku":"69309284M-1",
         "unitPrice":130,
         "totalAmount":130
      }
   ],
   "customer":{
      "firstName":"Your FirstName",
      "lastName":"Your LastName",
      "email":"[email protected]",
      "phoneNumber":"[phone]"
   },
   "billingAddress":{
      "firstName":"Your FirstName",
      "lastName":"Your LastName",
      "email":"[email protected]",
      "phoneNumber":"[phone]",
      "streetAddress":"Your Address",
      "streetAddress2":"Your Address2",
      "city":"Sydney",
      "country":"AU",
      "region":"Oceanian",
      "postalCode":"2000",
      "state": "NSW"
   }
   "shippingAddress":{
      "firstName":"Your FirstName",
      "lastName":"Your LastName",
      "email":"[email protected]",
      "phoneNumber":"[phone]",
      "streetAddress":"Your Address",
      "streetAddress2":"Your Address2",
      "city":"Sydney",
      "country":"AU",
      "region":"Oceanian",
      "postalCode":"2000",
      "state": "NSW"
   }
   "shippingType": "normal",
   "shippingMethod": "store pick-up",
   "dynamicRedirectUrl": "YOUR_URL",
   "dynamicCallbackUrl": "YOUR_URL",
   "cancellationTimeout": 2880
}

200 Order Created.

{
    "orderId": "LP000429e48ec-f6e3-49d2-bd38-8e1408d025c8",
    "orderToken": "5d47c4a0-9bfc-406d-9da1-bbc61202c722",
    "redirectUrl": "https://app.uat.latitudepay.com/r/NVXIFQBC",
    "bnplProvider": "LATITUDEPAY_AU",
    "orderReference": "LP000429e48ec-f6e3-49d2-bd38-8e1408d025c8",
    "orderAmount": 144.89,
    "orderPaymentOption": "buy now pay later",
    "orderDate": "2021-10-07T14:30:36.166Z",
    "paymentStatus": "pending",
    "transactionReference": "40ca337c3b"
}

400 Check the Data fields or Value that you sent to Optty

{
    "statusCode": 400,
    "message": [
        "billingAddress.country must be a valid ISO31661 Alpha2 code"
    ],
    "error": "Bad Request"
}

//OR

{
    "statusCode": 400,
    "message": "Unexpected token / in JSON at position 1333",
    "error": "Bad Request"
}

401 Check your credentials and accessToken / Environment live or Staging.

{
    "statusCode": 401,
    "message": "Unauthorized"
}

404 Check if you're in the correct endpoint for the API call.

{
    "statusCode": 404,
    "message": "Cannot POST /orders/a",
    "error": "Not Found"
}

500 Try a different BNPL if that works, or contact [email protected] for further investigation

{
    "statusCode": 500,
    "message": "Internal server error"
}