Create a Coinvay invoice from your backend with POST /api/invoices, using a server-calculated USD total and a merchant API key. Save the returned invoice ID and checkoutPath so your application can reconcile the order later.
Build a trusted request
Calculate the complete order total before creating an invoice. Include the appropriate tax, shipping or service charges from your own commerce system; do not let a customer submit a cheaper amount. Send amount as the documented decimal value, currency as USD and a recognizable order reference. Keep customer information limited to what your actual workflow needs. The API reference and OpenAPI schema are the authoritative field definitions.
Give retries a stable identity
Use a unique Idempotency-Key for the intended order, such as an internal order identifier with a payment-attempt suffix. Coinvay scopes this key to the merchant and reuses the original invoice when the key repeats, even if a later request body changes. Therefore, do not recycle the same key for a revised order total. Only the first 150 characters are significant, so put the unique portion near the beginning.
Persist before opening checkout
Consider an order totaling 49.00 USD. Your server creates one invoice, saves its ID with the 49.00 expectation and returns a checkout URL to the customer. If the network response is lost, retry with the original key and reconcile the returned ID. If the customer changes the cart after creation, review or cancel the unpaid request rather than fulfilling against a stale price. Created invoices consume the monthly allowance, including invoices later cancelled.
Practical checklist
- Use a unique, short idempotency key for each intended order or billing period.
- Store the returned invoice ID and original amount in a durable order record.
- Handle plan restrictions and rate limits without creating uncontrolled replacement invoices.
Common questions
Does cancelling an invoice restore the invoice allowance?+
Created invoices count toward the current UTC-month allowance even if later cancelled. Check the current plan and usage display for the configured limit.
What if my request times out?+
Retry the same intended creation with its original idempotency key, then compare the returned invoice to your saved order. Do not assume the timeout means nothing was created.
Sources and further reading
Primary references and Coinvay product documentation. Check the linked pages for current details.
AI-assisted drafting, published by Coinvay. Examples are illustrative. Read our editorial approach.