POST /orders
When a user selects an Optty integrated APM, you should send through the order via this method.
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.
ORD-2024-001234The 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.
KLARNAPossible values: The country code the purchase is originating from. Must be in ISO 3166 alpha-2 format.
AUThe 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.
AUDThe locale for the order, used to determine language and regional formatting on the checkout page. Should be in RFC 1766 standard format.
en_USThe shipping cost for the order. Must be a non-negative number with up to 2 decimal places. If not provided, defaults to 0.
0The 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.
183The 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.
0The 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.
107Information about the customer placing the order. Includes name, email, and phone number. Required for payment processing and order fulfillment.
{"firstName":"john","lastName":"doe","email":"[email protected]","phoneNumber":"+971500000001"}The customer's billing address. Required for payment processing and address verification. These values are conditionally mandatory based on the selected payment provider, the GET /options endpoint outlines these requirements.
{"firstName":"john","lastName":"doe","email":"[email protected]","phoneNumber":"+971500000001","streetAddress":"89 Corio Street","streetAddress2":"","city":"Sydney","country":"AU","state":"NSW","region":"Bondi","postalCode":"2024"}The customer's shipping address.
{"firstName":"john","lastName":"doe","email":"[email protected]","phoneNumber":"+971500000001","streetAddress":"89 Corio Street","streetAddress2":"","city":"Sydney","country":"AU","state":"NSW","region":"Bondi","postalCode":"2024"}The shipping type for this order.
normalPossible values: 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.
digitalPossible values: 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.
trueAdditional metadata or configuration data specific to the APM provider. This is a flexible object that can contain provider-specific fields and values.
{"customField":"customValue","metadata":"additional information"}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.
https://google.comA 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.
https://webhook.site/15351f15-3ef6-4f2a-a100-e8a84b25d47bThe 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.
3600Partner-specific configuration settings. This object can contain custom configuration parameters required by specific partners or integrations.
{"partnerId":"partner-123","customSettings":{}}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.
falseA 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.
nx5so6w6gprawk7urIndicates 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.
falseChannel alias identifier, should be the same channel alias passed in this order flows GET /options call.
mobile-app-v2The unique session identifier for the payment session. Must be a valid UUID. Used to track and link multiple requests within the same payment session.
123e4567-e89b-12d3-a456-426614174000A reference number or identifier provided by the partner or third-party system (grandparent or parent). Used for tracking and reconciliation purposes between systems.
PARTNER-REF-2024-001234The 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.
1800Sample 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":"[email protected]",
"phoneNumber":"(415) 200-0000"
},
"billingAddress":{
"firstName":"Your FirstName",
"lastName":"Your LastName",
"email":"[email protected]",
"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":"[email protected]",
"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
}Last updated