Place Order

POST

api

payment

domains

{domain}

place-order

Place Order

curl --request POST \
  --url https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: <x-firmly-authorization>' \
  --data '
{
  "encrypted_card": "<string>",
  "billing_info": {},
  "shipping_info": {},
  "items": [
    {}
  ],
  "captcha_token": "<string>"
}
'

import requests

url = "https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order"

payload = {
    "encrypted_card": "<string>",
    "billing_info": {},
    "shipping_info": {},
    "items": [{}],
    "captcha_token": "<string>"
}
headers = {
    "x-firmly-authorization": "<x-firmly-authorization>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-firmly-authorization': '<x-firmly-authorization>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    encrypted_card: '<string>',
    billing_info: {},
    shipping_info: {},
    items: [{}],
    captcha_token: '<string>'
  })
};

fetch('https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'encrypted_card' => '<string>',
    'billing_info' => [
        
    ],
    'shipping_info' => [
        
    ],
    'items' => [
        [
                
        ]
    ],
    'captcha_token' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-firmly-authorization: <x-firmly-authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order"

	payload := strings.NewReader("{\n  \"encrypted_card\": \"<string>\",\n  \"billing_info\": {},\n  \"shipping_info\": {},\n  \"items\": [\n    {}\n  ],\n  \"captcha_token\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-firmly-authorization", "<x-firmly-authorization>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order")
  .header("x-firmly-authorization", "<x-firmly-authorization>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"encrypted_card\": \"<string>\",\n  \"billing_info\": {},\n  \"shipping_info\": {},\n  \"items\": [\n    {}\n  ],\n  \"captcha_token\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-firmly-authorization"] = '<x-firmly-authorization>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"encrypted_card\": \"<string>\",\n  \"billing_info\": {},\n  \"shipping_info\": {},\n  \"items\": [\n    {}\n  ],\n  \"captcha_token\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "cart_id": "<string>",
  "platform_order_number": "<string>",
  "cart_status": "<string>",
  "submitted_at": "<string>",
  "display_name": "<string>",
  "platform_id": "<string>",
  "shop_id": "<string>",
  "urls": {
    "thank_you_page": "<string>"
  },
  "line_items": [
    {
      "line_item_id": "<string>",
      "sku": "<string>",
      "quantity": 123,
      "description": "<string>",
      "price": {},
      "line_price": {},
      "image": {}
    }
  ],
  "shipping_info": {},
  "billing_info": {},
  "shipping_method": {},
  "payment_summary": {
    "payment_type": "<string>",
    "last_four": "<string>",
    "card_type": "<string>",
    "month": 123,
    "year": 123
  },
  "total": {},
  "sub_total": {},
  "shipping_total": {},
  "tax": {},
  "cart_discount": {}
}

Overview

Creates a new cart, add items, set shipping information, and place an order - all in one API call. This endpoint is ideal for simple checkout flows where you want to minimize API calls.

Authentication

string

required

Device authentication token from Browser Session

Path Parameters

string

required

The merchant domain (e.g., “staging.luma.gift”)

Query Parameters

string

default:"false"

Enable Server-Sent Events for real-time progress updates. Set to “true” to receive events.

Request Body

string

required

JWE-encrypted credit card data using the public key from Get Public Key endpoint

object

required

Billing address information (same structure as shipping_info)

object

required

Shipping address informationRequired fields:

first_name (string): Customer’s first name
last_name (string): Customer’s last name
email (string): Email address
phone (string): Phone number
address1 (string): Primary address line
city (string): City name
state_or_province (string): State/province code
country (string): Country name or code
postal_code (string): ZIP or postal code

Optional fields:

address2 (string): Secondary address line
company (string): Company name

array

required

Array of items to add to cart. Each item must have:

Show Item Schema

string

required

Product variant identifier from the catalog

number

required

Quantity to purchase (minimum: 1)

string

Captcha verification token when required by merchant

Response

Returns a comprehensive order confirmation object including cart details, order information, and payment confirmation.

string

Unique identifier for the cart

string

The order number from the merchant platform

string

Status of the cart (e.g., “submitted”)

string

ISO timestamp when the order was submitted

string

Merchant’s display name

string

E-commerce platform identifier (e.g., “magento”, “shopify”)

string

Merchant domain

object

Relevant URLs for the order

Show URLs

string

URL to the merchant’s order confirmation page

array

Array of items in the order

Show Line Item Details

string

Unique identifier for the line item

string

Product SKU

number

Quantity ordered

string

Product description

object

Unit price

object

Total price for this line item

object

Product image information

object

Delivery address details

object

Billing address details

object

Selected shipping method with pricing

object

Summary of payment method used

Show Payment Summary

string

Type of payment (e.g., “CreditCard”)

string

Last four digits of the card

string

Card brand (e.g., “Visa”, “Mastercard”)

number

Card expiration month

number

Card expiration year

object

Grand total including all costs

object

Subtotal before shipping and tax

object

Shipping cost

object

Tax amount

object

Total discount applied

Server-Sent Events

When sse=true, the endpoint streams progress events:

creating-cart - Cart creation started
item-added - Item added to cart (includes cart data)
shipping-updated - Shipping info set (includes cart data)
order-placed - Order successfully placed (includes order data)
error - Error occurred (includes error details)

Code Example

// Place order with SSE for progress updates
const eventSource = new EventSource(
  'https://cc.firmly.work/api/v1/payment/domains/staging.luma.gift/place-order?sse=true',
  {
    method: 'POST',
    headers: {
      'x-firmly-authorization': authToken,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      encrypted_card: encryptedCard,
      billing_info: billingInfo,
      shipping_info: {
        first_name: 'John',
        last_name: 'Smith',
        email: 'john@staging.luma.gift',
        phone: '2065551212',
        address1: '123 Main St',
        city: 'Seattle',
        state_or_province: 'WA',
        country: 'US',
        postal_code: '98101'
      },
      items: [
        {
          variant_id: 'WS12-XS-Orange',
          quantity: 2
        },
        {
          variant_id: 'MH07-XS-Gray',
          quantity: 1
        }
      ]
    })
  }
);

eventSource.addEventListener('order-placed', (event) => {
  const order = JSON.parse(event.data).order;
  console.log('Order placed:', order.platform_order_number);
});

eventSource.addEventListener('error', (event) => {
  const error = JSON.parse(event.data).error;
  console.error('Order failed:', error.message);
});

Request Example

{
  "encrypted_card": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoidjEifQ...",
  "billing_info": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@staging.luma.gift",
    "phone": "2065551212",
    "address1": "123 Main St",
    "city": "Seattle",
    "state_or_province": "WA",
    "country": "US",
    "postal_code": "98101"
  },
  "shipping_info": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@staging.luma.gift",
    "phone": "2065551212",
    "address1": "123 Main St",
    "city": "Seattle",
    "state_or_province": "WA",
    "country": "US",
    "postal_code": "98101"
  },
  "items": [
    {
      "variant_id": "WS12-XS-Orange",
      "quantity": 2
    },
    {
      "variant_id": "MH07-XS-Gray",
      "quantity": 1
    }
  ]
}

// Without SSE
const response = await fetch('https://cc.firmly.work/api/v1/payment/domains/staging.luma.gift/place-order', {
  method: 'POST',
  headers: {
    'x-firmly-authorization': authToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    encrypted_card: encryptedCard,
    billing_info: billingInfo,
    shipping_info: shippingInfo,
    items: [
      {
        variant_id: 'WS12-XS-Orange',
        quantity: 1
      }
    ]
  })
});

const order = await response.json();

Response Example

{
  "cart_id": "9cf76530-1344-420f-9ca6-c7a96fb6db45",
  "platform_order_number": "6800018416",
  "cart_status": "submitted",
  "submitted_at": "2024-07-22T18:58:25.000Z",
  "display_name": "LUMA By Firmly",
  "platform_id": "magento",
  "shop_id": "staging.luma.gift",
  "urls": {
    "thank_you_page": "https://staging.luma.gift/checkout/onepage/success/"
  },
  "line_items": [
    {
      "line_item_id": "3e66bef5-43f5-4a80-8957-91c5c8233163",
      "sku": "MT12",
      "quantity": 4,
      "description": "Cassius Sparring Tank",
      "price": {
        "currency": "USD",
        "value": 18,
        "number": 1800,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 72,
        "number": 7200,
        "symbol": "$"
      },
      "image": {
        "url": "https://staging.luma.gift/pub/media/catalog/product/m/t/mt12-blue_main_1.jpg"
      }
    }
  ],
  "shipping_info": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@staging.luma.gift",
    "phone": "(206) 555-1212",
    "address1": "123 Main St",
    "city": "Seattle",
    "state_or_province": "Washington",
    "country": "US",
    "postal_code": "98101"
  },
  "billing_info": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@staging.luma.gift",
    "phone": "(206) 555-1212",
    "address1": "123 Main St",
    "city": "Seattle",
    "state_or_province": "Washington",
    "country": "US",
    "postal_code": "98101"
  },
  "shipping_method": {
    "id": "s2_2_day",
    "description": "2-Day Shipping",
    "price": {
      "currency": "USD",
      "value": 12,
      "number": 1200,
      "symbol": "$"
    }
  },
  "payment_summary": {
    "payment_type": "CreditCard",
    "last_four": "1111",
    "card_type": "Visa",
    "month": 6,
    "year": 2028
  },
  "total": {
    "currency": "USD",
    "value": 91.08,
    "number": 9108,
    "symbol": "$"
  },
  "sub_total": {
    "currency": "USD",
    "value": 72,
    "number": 7200,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 12,
    "number": 1200,
    "symbol": "$"
  },
  "tax": {
    "currency": "USD",
    "value": 7.08,
    "number": 708,
    "symbol": "$"
  },
  "cart_discount": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  }
}

Error Responses

Code	Description
`ErrorInvalidInputBody`	Request validation failed
`ErrorProductNotFound`	Variant ID not found
`ErrorNotEnoughStock`	Insufficient inventory
`ErrorPaymentDeclined`	Payment was declined
`ErrorStoreUnavailable`	Merchant temporarily unavailable

Get Public Key - Get encryption key
Complete Order - Alternative flow with existing cart

⌘I

Place Order

curl --request POST \
  --url https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: <x-firmly-authorization>' \
  --data '
{
  "encrypted_card": "<string>",
  "billing_info": {},
  "shipping_info": {},
  "items": [
    {}
  ],
  "captcha_token": "<string>"
}
'

import requests

url = "https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order"

payload = {
    "encrypted_card": "<string>",
    "billing_info": {},
    "shipping_info": {},
    "items": [{}],
    "captcha_token": "<string>"
}
headers = {
    "x-firmly-authorization": "<x-firmly-authorization>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-firmly-authorization': '<x-firmly-authorization>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    encrypted_card: '<string>',
    billing_info: {},
    shipping_info: {},
    items: [{}],
    captcha_token: '<string>'
  })
};

fetch('https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'encrypted_card' => '<string>',
    'billing_info' => [
        
    ],
    'shipping_info' => [
        
    ],
    'items' => [
        [
                
        ]
    ],
    'captcha_token' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-firmly-authorization: <x-firmly-authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order"

	payload := strings.NewReader("{\n  \"encrypted_card\": \"<string>\",\n  \"billing_info\": {},\n  \"shipping_info\": {},\n  \"items\": [\n    {}\n  ],\n  \"captcha_token\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-firmly-authorization", "<x-firmly-authorization>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order")
  .header("x-firmly-authorization", "<x-firmly-authorization>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"encrypted_card\": \"<string>\",\n  \"billing_info\": {},\n  \"shipping_info\": {},\n  \"items\": [\n    {}\n  ],\n  \"captcha_token\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://cc.firmly.work/api/v1/payment/domains/{domain}/place-order")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-firmly-authorization"] = '<x-firmly-authorization>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"encrypted_card\": \"<string>\",\n  \"billing_info\": {},\n  \"shipping_info\": {},\n  \"items\": [\n    {}\n  ],\n  \"captcha_token\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "cart_id": "<string>",
  "platform_order_number": "<string>",
  "cart_status": "<string>",
  "submitted_at": "<string>",
  "display_name": "<string>",
  "platform_id": "<string>",
  "shop_id": "<string>",
  "urls": {
    "thank_you_page": "<string>"
  },
  "line_items": [
    {
      "line_item_id": "<string>",
      "sku": "<string>",
      "quantity": 123,
      "description": "<string>",
      "price": {},
      "line_price": {},
      "image": {}
    }
  ],
  "shipping_info": {},
  "billing_info": {},
  "shipping_method": {},
  "payment_summary": {
    "payment_type": "<string>",
    "last_four": "<string>",
    "card_type": "<string>",
    "month": 123,
    "year": 123
  },
  "total": {},
  "sub_total": {},
  "shipping_total": {},
  "tax": {},
  "cart_discount": {}
}

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Overview

Authentication

Path Parameters

Query Parameters

Request Body

Response

Server-Sent Events

Code Example

Request Example

Response Example

Error Responses

​Overview

​Authentication

​Path Parameters

​Query Parameters

​Request Body

​Response

​Server-Sent Events

​Code Example

​Request Example

​Response Example

​Error Responses

​Related Endpoints

Overview

Authentication

Path Parameters

Query Parameters

Request Body

Response

Server-Sent Events

Code Example

Request Example

Response Example

Error Responses

Related Endpoints