Create Order

Create and sign an order when requested by a payment app

POST /orders/create

Create order

cURL

curl --request POST \
  --url https://api.merchant.example/opencharge/orders/create \
  --header 'Content-Type: application/json' \
  --header 'X-OC-ID: <x-oc-id>' \
  --header 'X-OC-Nonce: <x-oc-nonce>' \
  --header 'X-OC-Signature: <x-oc-signature>' \
  --header 'X-OC-Timestamp: <x-oc-timestamp>' \
  --data '
{
  "id": "ord_abc123",
  "ocid": 500,
  "reference": "store-42",
  "amount": "15.00",
  "currency": "USD",
  "items": [
    {
      "id": "item_001",
      "name": "Large Coffee",
      "quantity": 2,
      "price": "5.00"
    },
    {
      "id": "item_002",
      "name": "Croissant",
      "quantity": 1,
      "price": "5.00"
    }
  ],
  "memo": "Table 5",
  "expiresAt": 1706400000
}
'

200

{
  "order": {
    "id": "ord_abc123",
    "ocid": 500,
    "reference": "store-42",
    "amount": "15.00",
    "currency": "USD",
    "items": [
      {
        "id": "item_001",
        "name": "Large Coffee",
        "quantity": 2,
        "price": "5.00"
      },
      {
        "id": "item_002",
        "name": "Croissant",
        "quantity": 1,
        "price": "5.00"
      }
    ],
    "memo": "Table 5",
    "createdAt": 1706313600,
    "expiresAt": 1706400000,
    "accepts": [
      100,
      101,
      102
    ]
  },
  "signature": "a1b2c3d4e5f6...7f1b",
  "urls": {
    "order": [
      "https://merchant.example/orders/ord_abc123"
    ],
    "completed": "https://merchant.example/checkout/success",
    "cancelled": "https://merchant.example/checkout/cancelled"
  }
}

For detailed flow diagrams and implementation guidance, see the Merchant Orders guide.

Flow

1. Payment app sends order details to your endpoint
2. You validate the request and create the order in your system
3. You sign the order with your private key
4. You return the signed order with callback URLs

Signing the Order

Canonicalize and sign the order object:

const order = {
  id: "ord_abc123",
  ocid: 500,  // Your merchant OCID
  amount: "15.00",
  currency: "USD",
  items: [
    { id: "item_001", name: "Large Coffee", quantity: 2, price: "5.00" },
    { id: "item_002", name: "Croissant", quantity: 1, price: "5.00" }
  ],
  createdAt: 1706313600,
  expiresAt: 1706400000,
  accepts: [100, 101, 102]
};

// Canonicalize: sort keys alphabetically
const canonical = JSON.stringify(order, Object.keys(order).sort());
const signature = secp256k1_sign(privateKey, SHA256(canonical));

Callback URLs

Include URLs in your response so payment apps know where to redirect users:

URL	Purpose
urls.order	Where the order can be retrieved
urls.completed	Redirect after successful payment
urls.cancelled	Redirect if payment is cancelled

Example Response

{
  "order": {
    "id": "ord_abc123",
    "ocid": 500,
    "amount": "15.00",
    "currency": "USD",
    "createdAt": 1706313600,
    "expiresAt": 1706400000,
    "accepts": [100, 101, 102]
  },
  "signature": "a1b2c3d4e5f6...7f1b",
  "urls": {
    "order": ["https://merchant.example/orders/ord_abc123"],
    "completed": "https://merchant.example/checkout/success",
    "cancelled": "https://merchant.example/checkout/cancelled"
  }
}

Headers

X-OC-ID · string · required

Sender's OCID (Opencharge ID)

X-OC-Timestamp · string · required

Unix timestamp in seconds

X-OC-Nonce · string · required

Unique request identifier for replay protection

X-OC-Signature · string · required

secp256k1 ECDSA signature of the canonical request

Body

application/json

Request from a payment app to create and sign an order

id · string · required

Unique order identifier

ocid · integer · required

Your merchant's OCID

amount · string · required

Total amount as decimal string

currency · string · required

ISO 4217 currency code

reference · string

Your internal reference

items · object[]

Line items in the order

Show child attributes

memo · string

Customer-facing note

expiresAt · integer

Unix timestamp when order expires

Response

200

application/json

Signed order returned successfully

Your response containing the signed order

order · object · required

An order object signed by your merchant's private key.

Show child attributes

signature · string · required

Your secp256k1 signature of the canonicalized order JSON

urls · object

Callback URLs for order lifecycle

Show child attributes