# invoq

> Stablecoin payments you plug into a site, an app or a Telegram bot. Buyers pay
> USDT or USDC on nine networks and the money settles straight to the merchant's
> own wallet, which invoq never holds and cannot redirect. The whole integration
> is three REST endpoints and two signed webhook events.

- Base URL: `https://api.invoq.money`
- Hosted checkout: `https://pay.invoq.money/<invoice id>`
- Dashboard `https://app.invoq.money`, where a person creates API keys, sets
  the webhook URL and pastes the receiving wallet address. None of that is
  scriptable, on purpose. The developer sets those values themselves: read the
  keys from the environment, never ask anyone to paste a key to you, and never
  write one into code.

The loop, end to end:

1. Your server calls `POST /v1/invoices` with a secret key and gets an invoice `id`.
2. The buyer pays. Send them `https://pay.invoq.money/<id>`, open the same
   checkout in a modal with `@invoq/checkout`, or read the address and amount
   out of `payment_options` and render your own.
3. invoq confirms the transfer on-chain and POSTs a signed `invoice.paid`
   webhook to your server. Fulfill the order there.

Build against a `sk_test_` key first. Test invoices touch no chain and need no
receiving wallet, and `POST /v1/invoices/{id}/test-payments` drives the whole
unpaid to paid to webhook loop without a buyer, so an integration can be proven
end to end before any real money exists.

What to get right, because none of it is guessable:

- Fulfill on the `invoice.paid` webhook only. `checkout_status` is a display
  state and never authorizes fulfillment.
- The other event, `invoice.payment_reversed`, means a paid invoice dropped back
  below its amount — a chain reorg, say. Handle it, or an order stays fulfilled
  on a payment that no longer exists.
- Amounts are decimal strings, never floats. Read `amount_due` and
  `amount_overpaid` instead of subtracting money yourself.
- Unknown body keys are rejected with `400 invalid_request`. `currency` and
  `mode` are not request fields: currency is always USD, and mode comes from
  the key.
- Webhook delivery is at-least-once and can arrive out of order. Deduplicate by
  event `id` and keep the snapshot with the highest `payment_revision`.
- Verify the `Invoq-Signature` header against the raw request body, before
  parsing it.
- `invoice.paid` can arrive long after the checkout showed `expired`, and no
  field distinguishes it. Reconcile against your own order state.

## Docs

- [Integration brief](https://invoq.money/llms-full.txt): every endpoint,
  field, status, webhook rule and test-mode step in one file, plus a worked
  example and the mistakes that get made. One fetch, no follow-ups.
- [REST API reference](https://raw.githubusercontent.com/invoqmoney/api/main/README.md):
  the canonical prose contract. Where it and anything else disagree, it wins.
- [OpenAPI 3.1](https://api.invoq.money/openapi.json): the machine-readable
  contract, including the two webhooks. Served by the API itself and generated
  from the same schemas it validates with, so it cannot describe a different
  server than the one answering. Use it to generate a client for a language
  with no SDK.
- [How the money moves](https://invoq.money/how-it-works): the non-custodial
  path and the settlement contracts, with their on-chain addresses.

## SDKs

Six server SDKs wrap exactly these endpoints, and each ships a check for this,
named to its own language (`verifyWebhook`, `verify_webhook`, `VerifyWebhook`).
Any other language calls the REST API directly; there is nothing an SDK does
that the HTTP contract can't.

- [Node.js](https://github.com/invoqmoney/sdk-js): `npm install @invoq/server`,
  plus `@invoq/checkout` for the in-page modal.
- [Python](https://github.com/invoqmoney/sdk-python): `pip install invoq`
- [PHP](https://github.com/invoqmoney/sdk-php): `composer require invoq/invoq-php`
- [Go](https://github.com/invoqmoney/sdk-go): `go get github.com/invoqmoney/sdk-go`
- [Rust](https://github.com/invoqmoney/sdk-rust): `cargo add invoq`
- [Ruby](https://github.com/invoqmoney/sdk-ruby): `gem install invoq`

## Optional

- [The reference in nine more languages](https://github.com/invoqmoney/api):
  Indonesian, Spanish, French, Portuguese, Vietnamese, Turkish, Thai,
  Simplified and Traditional Chinese. The contract is identical in all ten.
- [Terms](https://invoq.money/terms) and [Privacy](https://invoq.money/privacy)
- [Support](https://invoq.money/help): Telegram https://t.me/invoqmoney,
  Discord https://discord.gg/V8cVrg4dET, help@invoq.money