OpenStockConnect any processor
Use a processor OpenStock doesn’t list by describing its checkout and status API.
Set it up#
Check what the processor offers
You need two API endpoints: one that creates a hosted checkout and returns its URL and an ID, and one that returns that checkout’s status. Most card, crypto and local-payment processors have both.
Describe the checkout request
In Payments → Payment setup → Custom processor, enter the create URL, the request body and the headers. Put the API key in the API key field and write {{api_key}} where it goes, for example Authorization: Bearer {{api_key}}. Then say where the response puts the checkout URL and the ID, like data.url and data.id.
Describe the status check
Enter the status URL with {{ref}} where the ID goes, the field that holds the status, and which values mean paid and failed. Add the amount and currency fields so an order only confirms when the full total was paid.
Connect and test
Select Connect. OpenStock checks the status URL with a made-up ID, so a wrong key is caught now. Place a test order with the processor’s sandbox before switching to live keys.
Placeholders#
The request body is JSON, sent as JSON or as a form. A value that is exactly one placeholder keeps its type, so "{{amount}}" becomes the number 10.5 while "Order {{order_id}}" stays text.
Available: order_id, store_id, amount (10.5), amount_string ("10.50"), amount_minor (1050), currency (USD), currency_lower, description, email, return_url, cancel_url, webhook_url, store_name, api_key and api_key_base64. The status URL can also use ref.
Example: BTCPay Server#
Create URL https://your-btcpay/api/v1/stores/STORE_ID/invoices with header Authorization: token {{api_key}} and body {"amount": "{{amount_string}}", "currency": "{{currency}}", "metadata": {"orderId": "{{order_id}}"}, "checkout": {"redirectURL": "{{return_url}}"}}. Checkout URL field checkoutLink, reference field id.
Status URL https://your-btcpay/api/v1/stores/STORE_ID/invoices/{{ref}}, paid when status is Settled, failed when Expired or Invalid, amount field amount, currency field currency. The key needs only the create-invoice and view-invoices permissions for that store.
Using your own server#
Left at their defaults, the fields describe a small contract. OpenStock POSTs {order_id, amount, currency, description, email, return_url, cancel_url, webhook_url, store_name} to your create URL and expects {id, url} back, then GETs your status URL and expects {status: "paid", amount, currency}.
How orders confirm#
Orders confirm only from the status URL. A webhook is optional: when it carries a valid HMAC-SHA256 or SHA512 signature of the raw body, OpenStock re-checks that payment straight away instead of on its next poll.
Endpoints must be public https URLs. Redirects, private networks and secrets in the URL are refused, and changing an endpoint or header means entering the API key again.
If something does not work#
What to check
If connecting fails with a 401 or 403, the headers or key are wrong. If checkout fails, compare the request body with the processor’s API reference and check the checkout URL and reference fields against a real response. If orders stay pending, check the status field and the paid values, which must be final states such as paid or settled.
Still stuck? Contact support with the store, affected page, and relevant order or request reference.