Postman Collection

A ready-made Postman collection for the whole merchant API: payments, verification, transaction inquiry, the public payment endpoints, and the signed cashout API. Import it, add your API key, and send your first request in about a minute.

Download

Download Postman Collection

One self-contained file: every request with example bodies and descriptions, the scripts that chain them together, and its variables. There is no separate environment file to import.

It points at staging (https://api-staging.finomesh.com/api/v1) — build and test there first.

Set up

1. In Postman, click Import and drop in the downloaded file.

2. Open the Finomesh Merchant API collection and go to its Variables tab.

3. Fill in the Current value column:

   Variable	Needed for	Where to get it
   baseUrl	Every request	Pre-filled with staging — change it only to go to production
   apiKey	Everything except the public endpoints	Dashboard → your gateway (Authentication)
   cashoutSecret	The Cashout folder	Dashboard → your gateway, when you enable the cashout API

4. Save, then open the Sandbox walkthrough folder and send its four requests in order — or run the folder with the Collection Runner.

Those three are the only settings. Everything else is passed directly on the request that uses it, as an example value in its body — edit it there:

Field	In	Replace with
callbackUrl	Create sandbox payment, Create payment (hosted), Create open-amount payment	Your result page, if you want to follow the redirect
webhookUrl	Create sandbox payment, Create payment (hosted / API mode)	Any URL that accepts a POST — your own endpoint, or a request-inspection service while testing. Required in API mode; delete it on hosted payments to send no webhook
address	Estimate fee, Create settlement	A destination address on the asset's chain (a testnet address on staging)

Keep secrets in "Current value"

Enter apiKey and cashoutSecret in the Current value column only. The Initial value is synced to your Postman workspace and visible to everyone in it.

What's inside

Folder	Requests	Auth
Sandbox walkthrough	Create sandbox payment → Get payment → Simulate sandbox outcome → Verify payment	API key (the two public requests send none)
Payments	Create payment (hosted), Create payment (API mode), Create open-amount payment, Verify payment, Submit transaction inquiry	API key
Public payment endpoints	Get payment, Get payment status (slim), Select offer (API mode), Expire payment, Simulate sandbox outcome	None
Cashout	Get balances, Estimate fee, Create settlement, List settlements, Get settlement, Approve / Retry / Cancel settlement	API key + signature

Requests chain through collection variables, so you never copy an ID by hand:

Variable	Set by
paymentId	Any create-payment request
offerId	Get payment, or an API-mode create
assetId	Get balances (its first asset — edit the request body to use another)
settlementId	Create settlement

Each request's description summarizes its contract and links to its reference page here.

Cashout signing

Every request in the Cashout folder is signed for you. The folder's pre-request script builds the signature from cashoutSecret — HMAC_SHA256(secret, X-Timestamp + "." + rawBody) over the exact bytes Postman sends — and fills in X-Timestamp and X-Signature. Edit the request bodies freely; the signature follows.

Money-moving requests (create, approve, retry, cancel) send a fresh Idempotency-Key on every click, so sending Create settlement twice creates two settlements. To test a safe retry, replace the header's {{$guid}} with a fixed value and send twice.

Going to production

In the collection's Variables tab, set baseUrl to https://api.finomesh.com/api/v1 and apiKey to your production key. Every request then goes to the live API — see the warning below before sending anything from the Cashout folder.

Things to know

• IP allowlist. Cashout requests and API-mode payments are accepted only from allowlisted source IPs. Use the Postman desktop app — or the web app with the Postman Desktop Agent — and allowlist your own IP in the dashboard. Requests sent through Postman's Cloud Agent come from Postman's servers and are refused — public API-mode endpoints (create/read/select/expire/simulate) with 403 forbidden, cashout endpoints with 403 ip_not_allowlisted.
• Production moves real funds. With baseUrl pointed at production, Create settlement pays out real money. There is no sandbox for cashouts — rehearse on staging, which settles on test networks (Test Cashout).
• Inquiry attempts are scarce. Submit transaction inquiry has 5 attempts per payment, shared with your dashboard. Don't loop it in the Collection Runner.
• Sandbox proves your integration, not settlement. The simulator exercises the callback, webhook, and verify flow exactly as production does, but no chain is involved.
• Staying current. Download the file again after an API change and import it over the old one — Postman offers to replace the existing collection.