> ## Documentation Index > Fetch the complete documentation index at: https://docs.opencharge.network/llms.txt > Use this file to discover all available pages before exploring further. # Create Order > Create and sign an order when requested by a payment app For detailed flow diagrams and implementation guidance, see the [Merchant Orders guide](/guides/protocol/merchant-orders#merchant-flow). ## 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: ```javascript theme={null} 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 ```json theme={null} { "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" } } ``` ## OpenAPI ````yaml merchant-api/endpoint/merchant-api/openapi.json post /orders/create openapi: 3.1.0 info: title: Opencharge Merchant API description: >- API specification for merchants integrating with the Opencharge protocol. These endpoints are implemented by merchants and called by payment apps and gateways. version: 0.1.0 license: name: MIT servers: - url: https://api.merchant.example/opencharge description: Example merchant Opencharge endpoint security: [] paths: /orders/create: post: summary: Create order description: >- Payment apps call this endpoint to request a signed order from your merchant. Create the order, sign it, and return it with status URLs. The payment app can then process payment and notify you via the transfer webhook or the status URL. operationId: createOrder parameters: - $ref: '#/components/parameters/X-OC-ID' - $ref: '#/components/parameters/X-OC-Timestamp' - $ref: '#/components/parameters/X-OC-Nonce' - $ref: '#/components/parameters/X-OC-Signature' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderCreateRequest' example: 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 responses: '200': description: Signed order returned successfully content: application/json: schema: $ref: '#/components/schemas/OrderCreateMerchantResponse' example: 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 '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: X-OC-ID: name: X-OC-ID in: header required: true description: Sender's OCID (Opencharge ID) schema: type: string example: '200' X-OC-Timestamp: name: X-OC-Timestamp in: header required: true description: Unix timestamp in seconds schema: type: string example: '1706500000' X-OC-Nonce: name: X-OC-Nonce in: header required: true description: Unique request identifier for replay protection schema: type: string example: req_abc123 X-OC-Signature: name: X-OC-Signature in: header required: true description: secp256k1 ECDSA signature of the canonical request schema: type: string example: a1b2c3d4...7f1b schemas: OrderCreateRequest: type: object required: - id - ocid - amount - currency description: Request from a payment app to create and sign an order properties: id: type: string description: Unique order identifier ocid: type: integer description: Your merchant's OCID reference: type: string description: Your internal reference amount: type: string description: Total amount as decimal string currency: type: string description: ISO 4217 currency code items: type: array items: $ref: '#/components/schemas/OrderItem' description: Line items in the order memo: type: string description: Customer-facing note expiresAt: type: integer description: Unix timestamp when order expires OrderCreateMerchantResponse: type: object required: - order - signature description: Your response containing the signed order properties: order: $ref: '#/components/schemas/Order' signature: type: string description: Your secp256k1 signature of the canonicalized order JSON urls: type: object required: - completed - cancelled description: Callback URLs for order lifecycle properties: order: type: array items: type: string format: uri description: URLs where the order can be retrieved completed: type: string format: uri description: URL to redirect user after successful payment cancelled: type: string format: uri description: URL to redirect user if payment is cancelled Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Error code enum: - INVALID_SIGNATURE - TIMESTAMP_EXPIRED - NONCE_REUSED - UNKNOWN_OCID - INVALID_PROOF - PROOF_SIGNATURE_INVALID - ISSUER_NOT_ACCEPTED - ORDER_NOT_FOUND - ORDER_EXPIRED message: type: string description: Human-readable error message details: type: object description: Additional error context OrderItem: type: object required: - id - name - quantity - price description: A line item within an order properties: id: type: string description: Item identifier name: type: string description: Display name quantity: type: number description: Quantity ordered price: type: string description: Unit price as decimal string Order: type: object required: - id - ocid - amount - currency - createdAt description: An order object signed by your merchant's private key. properties: id: type: string description: Unique order identifier ocid: type: integer description: Your merchant's OCID reference: type: string description: Your internal reference amount: type: string description: Total amount as decimal string currency: type: string description: ISO 4217 currency code items: type: array items: $ref: '#/components/schemas/OrderItem' description: Line items in the order memo: type: string description: Customer-facing note expiresAt: type: integer description: Unix timestamp when order expires createdAt: type: integer description: Unix timestamp of order creation accepts: type: array items: type: integer description: OCIDs accepted for payment settlement ````