Skip to main content

​
Overview

The Merchant API defines the endpoints that merchants implement to accept payments via the Opencharge protocol. Payment apps and gateways call these endpoints on your server to create orders, check payment status, and notify you of completed payments.

OpenAPI Specification

View the complete Merchant OpenAPI specification

​
Base URL

Host your Merchant API at the endpoint you register in the Router Registry: 
https://api.yourmerchant.com/opencharge

​
Endpoints you implement on your server

EndpointMethodDescription
/metadata.jsonGETYour OCID metadata (public key, capabilities)
/capabilitiesGETPartner-specific capabilities
/orders/createPOSTCreate and sign an order
/orders/{orderId}/statusGETReturn order payment status
/inventoryGETReturn available items
/transfer/webhookPOSTReceive payment notifications

​
Authentication

Requests to your endpoints include secp256k1 ECDSA signatures in these headers:
HeaderDescriptionExample
X-OC-IDCaller’s OCID (Opencharge ID)200
X-OC-TimestampUnix timestamp in seconds1706500000
X-OC-NonceUnique request identifierreq_abc123
X-OC-SignatureSignature of canonical requesta1b2c3...1b
Verify these signatures using the caller’s public key from their /metadata.json endpoint. See Request Authentication for details.

​
Signing Orders

When you create an order, you must sign it with your private key: 
const order = {
  id: "ord_abc123",
  ocid: 500,  // Your merchant OCID
  amount: "15.00",
  currency: "USD",
  createdAt: Math.floor(Date.now() / 1000),
  expiresAt: Math.floor(Date.now() / 1000) + 3600,
  accepts: [100, 101, 102]  // Settlement providers you accept
};

const canonical = JSON.stringify(order, Object.keys(order).sort());
const signature = secp256k1_sign(privateKey, SHA256(canonical));
See Merchant Orders for complete implementation guidance.

​
Error Handling

Return errors in this format: 
{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order ord_xyz does not exist"
  }
}
See Error Codes for the complete list.