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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

orderReferencestringRequired

Your unique order reference to use for identifying an order. This must be unique per merchant. This reference will be returned in order status responses and webhook notifications, allowing you to correlate API responses with your internal order records.

Example: ORD-2024-001234

bnplProviderstring · enumRequired

The APM provider to place the order against. This value must be one of the providers returned from the GET /options endpoint. The provider determines which payment service will process the transaction.

Example: KLARNAPossible values:

purchaseCountrystringRequired

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

Example: AU

purchaseCurrencystringRequired

The currency the purchase is being made in. Must be in ISO 4217 format. The currency must be supported by the selected payment provider in the GET /options endpoint.

Example: AUD

localestringRequired

The locale for the order, used to determine language and regional formatting on the checkout page. Should be in RFC 1766 standard format.

Example: en_US

shippingAmountnumberOptional

The shipping cost for the order. Must be a non-negative number with up to 2 decimal places. If not provided, defaults to 0.

Example: 0

discountAmountnumberOptional

The total discount amount applied to the order. Must be a non-negative number with up to 2 decimal places. Can be used for promotional discounts, coupon codes, or other price reductions.

Example: 183

taxAmountnumberOptional

The total tax amount for the order. Must be a non-negative number with up to 2 decimal places. This is included in the order amount.

Example: 0

orderAmountnumberRequired

The total order amount, including tax, shipping, and discounts. Must equal the sum of all order item total amounts plus shipping and tax, minus any discount. Formula: orderAmount = sum(orderItems.totalAmount) + shippingAmount + taxAmount - discountAmount. Must be a non-negative number with up to 2 decimal places.

Example: 107

shippingTypestring · enumOptional

The shipping type for this order.

Example: normalPossible values:

shippingMethodstring · enumOptional

The shipping method for this order. Indicates how the order will be delivered. Use "digital" for digital products or services that do not require physical shipping. Use "delivery" for standard home delivery, "pick-up" for store pickup, "store" for in-store purchases, etc.

Example: digitalPossible values:

autoCapturebooleanOptional

Determines if payment should be automatically captured immediately after authorization. If false, the payment will need to be captured manually later using the capture endpoint. Defaults to True.

Example: true

additionalDataobjectOptional

Additional metadata or configuration data specific to the APM provider. This is a flexible object that can contain provider-specific fields and values.

Example: {"customField":"customValue","metadata":"additional information"}

dynamicRedirectUrlstringOptional

A custom URL to redirect the customer to after payment is completed. Must be a valid HTTPS URL. The customer will be redirected to this URL after completing payment, regardless of whether the payment was successful, declined, pending, canceled. You should handle all possible payment statuses on this page.

Example: https://google.com

dynamicCallbackUrlstringOptional

A custom webhook URL to receive payment status updates for ORDER_ASYNC_CALLBACK events. Must be a valid HTTPS URL. This endpoint will receive asynchronous notifications when the order status changes to a final state (SUCCESSFUL, DECLINED, CANCELED, ERROR). Always handle PENDING status on initial response and wait for webhook notifications for final status.

Example: https://webhook.site/15351f15-3ef6-4f2a-a100-e8a84b25d47b

cancellationTimeoutnumberOptional

The timeout in seconds from order creation after which an unpaid order will be automatically cancelled by the system. After this timeout expires, the order status will change to CANCELED with cancelledBy set to "SYSTEM" and we will cancel the checkout with the APM provider. You will receive an ORDER_ASYNC_CALLBACK webhook notification when this occurs.

Example: 3600

partnerConfigurationobjectOptional

Partner-specific configuration settings. This object can contain custom configuration parameters required by specific partners or integrations.

Example: {"partnerId":"partner-123","customSettings":{}}

getTokenbooleanOptional

Set to true to generate a payment token returned in the webhook notification when the order reaches a successful status. This token can be used for future merchant-initiated payments using the 'token' field without requiring the customer to re-enter payment details. The token will be included in the ORDER_ASYNC_CALLBACK webhook notification.

Example: false

tokenstringOptional

A previously obtained payment token to use for merchant-initiated repeat payments. This allows processing a payment without requiring the customer to re-enter their payment details. The token must have been obtained from a previous transaction with getToken set to true. When using a token, you must also set customerPresent to indicate whether the customer is physically present during the transaction. It is then unnessecary to redirect a customer to the redirectUrl as the payment will be completed immediately.

Example: nx5so6w6gprawk7ur

customerPresentbooleanRequired

Indicates whether the customer is physically present during the transaction. Required when using token-based payments for merchant-initiated transactions. This is to confirm the merchant initiated transaction is compliant with the selected APM provider and token.

Example: false

channelstringOptional

Channel alias identifier, should be the same channel alias passed in this order flows GET /options call.

Example: mobile-app-v2

sessionIdstringOptional

The unique session identifier for the payment session. Must be a valid UUID. Used to track and link multiple requests within the same payment session.

Example: 123e4567-e89b-12d3-a456-426614174000

partnerOrderReferencestringOptional

A reference number or identifier provided by the partner or third-party system (grandparent or parent). Used for tracking and reconciliation purposes between systems.

Example: PARTNER-REF-2024-001234

checkoutSessionTimeoutnumberOptional

The timeout duration in seconds starting AFTER a customer has completed the checkout process. After this time, the order will be canceled if it has remained in a PENDING state. This is different from cancellationTimeout - checkoutSessionTimeout begins when the customer completes checkout process, while cancellationTimeout begins when the order is created.

Example: 1800

isActivatedViaOAuthbooleanRequired

Tells if the provider is activated by oAuth or apiKey/ password

Example: true

Responses

201Success

application/json

orderIdstringRequired

The unique identifier of the order generated by Optty. This is a UUID that uniquely identifies the order in Optty's system.

Example: 4ab02bfa-ef51-4ded-99d5-e7b2fd2e71cd

orderTokenstringRequired

The order token returned from the APM provider. This token is used by the payment provider to identify the order.

Example: 29536751

redirectUrlstringOptional

The redirect URL provided by the APM provider where the customer should be redirected to complete payment. For merchant-initiated payments using tokens, this URL will redirect back to dynamicRedirectURL with payment status, allowing reuse of existing status page for customer present merchant initiated transactions. The customer should be redirected to this URL to complete the payment process.

Example:

https://develop.checkout.test.merchant-services-np.lfscnp.com/wallet/checkout?token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...&transactionId=4ab02bfa-ef51-4ded-99d5-e7b2fd2e71cd

bnplProviderstring · enumRequired

The APM provider that is processing this order. This matches the bnplProvider value that was sent in the create order request.

Example: LATITUDE_IF_AUPossible values:

orderReferencestringRequired

The order reference that was submitted when creating the order. This is your unique identifier for the order that you provided in the create order request. Use this reference to track and correlate the order with your internal systems.

Example: ORD-2024-001234

orderAmountnumberRequired

The total order amount, including tax, shipping, and discounts. This matches the orderAmount value that was sent in the create order request. The amount is in the currency specified in purchaseCurrency.

Example: 5

orderPaymentOptionstringRequired

A human-readable description of the type of the payment method selected for the order (e.g., "buy now pay later", "debit/credit", "digital wallet").

Example: buy now pay later

orderDatestring · date-timeRequired

The date and time when the order was created. This is in ISO 8601 format (UTC).

Example: 2025-02-06T13:54:13.550Z

paymentStatusstringRequired

The current payment status of the order (SUCCESSFUL, CANCELLED, DECLINED, PENDING). Always handle PENDING status on initial response and wait for webhook notifications for final status updates.

Example: PENDING

transactionReferencestringRequired

A non UUID transaction reference generated by Optty for this order.

Example: b4ca0e6579

surchargenumberOptional

The surcharge fee charged to the customer for using this payment method. This amount is added to the order total and is configured in the Universal Payment Platform (UPP). If no surcharge is configured, this field will be 0.

Example: 0

partitionLocationstringOptional

The partition location for spanner

Example: europe-west1

bnplLateFeeTextstringOptional

Custom text configured by the merchant regarding late fees for this payment provider. Display this text to inform customers about potential late payment fees. This text is configured in the Universal Payment Platform UPP by the merchant.

Example: Late fees may apply if payment is not received on time.

bnplCustomerFeeTextstringOptional

Custom text configured by the merchant regarding processing fees for this payment provider. Display this text to inform customers about any processing fees they may incur and ensure they have accepted the fee. This text is configured in the UPP.

Example: A small processing fee may be applied to your payment.

400Error

application/json

401Error

application/json

404Error

application/json

post/orders

POST /orders HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1548

{
  "orderReference": "ORD-2024-001234",
  "bnplProvider": "KLARNA",
  "purchaseCountry": "AU",
  "purchaseCurrency": "AUD",
  "locale": "en_US",
  "shippingAmount": 0,
  "discountAmount": 183,
  "taxAmount": 0,
  "orderAmount": 107,
  "orderItems": [
    {
      "name": "Striped Silk Tie",
      "sku": "793775370033M",
      "quantity": 1,
      "unitPrice": 290,
      "totalAmount": 290
    }
  ],
  "customer": {
    "firstName": "john",
    "lastName": "doe",
    "email": "johndoe@example.com",
    "phoneNumber": "+971500000001"
  },
  "billingAddress": {
    "firstName": "john",
    "lastName": "doe",
    "email": "johndoe@example.com",
    "phoneNumber": "+971500000001",
    "streetAddress": "89 Corio Street",
    "streetAddress2": "",
    "city": "Sydney",
    "country": "AU",
    "state": "NSW",
    "region": "Bondi",
    "postalCode": "2024"
  },
  "shippingAddress": {
    "firstName": "john",
    "lastName": "doe",
    "email": "johndoe@example.com",
    "phoneNumber": "+971500000001",
    "streetAddress": "89 Corio Street",
    "streetAddress2": "",
    "city": "Sydney",
    "country": "AU",
    "state": "NSW",
    "region": "Bondi",
    "postalCode": "2024"
  },
  "shippingType": "normal",
  "shippingMethod": "digital",
  "autoCapture": true,
  "additionalData": {
    "customField": "customValue",
    "metadata": "additional information"
  },
  "dynamicRedirectUrl": "https://google.com",
  "dynamicCallbackUrl": "https://webhook.site/15351f15-3ef6-4f2a-a100-e8a84b25d47b",
  "cancellationTimeout": 3600,
  "partnerConfiguration": {
    "partnerId": "partner-123",
    "customSettings": {}
  },
  "getToken": false,
  "token": "nx5so6w6gprawk7ur",
  "customerPresent": false,
  "channel": "mobile-app-v2",
  "sessionId": "123e4567-e89b-12d3-a456-426614174000",
  "partnerOrderReference": "PARTNER-REF-2024-001234",
  "checkoutSessionTimeout": 1800,
  "isActivatedViaOAuth": true
}

{
  "orderId": "4ab02bfa-ef51-4ded-99d5-e7b2fd2e71cd",
  "orderToken": "29536751",
  "redirectUrl": "https://develop.checkout.test.merchant-services-np.lfscnp.com/wallet/checkout?token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...&transactionId=4ab02bfa-ef51-4ded-99d5-e7b2fd2e71cd",
  "bnplProvider": "LATITUDE_IF_AU",
  "orderReference": "ORD-2024-001234",
  "orderAmount": 5,
  "orderPaymentOption": "buy now pay later",
  "orderDate": "2025-02-06T13:54:13.550Z",
  "paymentStatus": "PENDING",
  "transactionReference": "b4ca0e6579",
  "surcharge": 0,
  "partitionLocation": "europe-west1",
  "bnplLateFeeText": "Late fees may apply if payment is not received on time.",
  "bnplCustomerFeeText": "A small processing fee may be applied to your payment."
}

Sample Request/Response

{
   "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":"test@test.test",
      "phoneNumber":"(415) 200-0000"
   },
   "billingAddress":{
      "firstName":"Your FirstName",
      "lastName":"Your LastName",
      "email":"test@test.test",
      "phoneNumber":"(415) 200-0000",
      "streetAddress":"Your Address",
      "streetAddress2":"Your Address2",
      "city":"Sydney",
      "country":"AU",
      "region":"Oceanian",
      "postalCode":"2000",
      "state": "NSW"
   }
   "shippingAddress":{
      "firstName":"Your FirstName",
      "lastName":"Your LastName",
      "email":"test@test.test",
      "phoneNumber":"(415) 200-0000",
      "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
}

{
    "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"
}

{
    "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"
}

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

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

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

PreviousGET /options

NextGET /orders

Last updated 4 months ago