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

File	What it is
Finomesh Merchant API — collection	Every request, with example bodies, descriptions, and scripts that chain them together.
Finomesh Staging — environment	Points the collection at https://api-staging.finomesh.com/api/v1. Start here.
Finomesh Production — environment	Points the collection at https://api.finomesh.com/api/v1.

If a link opens the JSON in your browser instead of downloading it, save the page (Ctrl+S / Cmd+S) — or copy the link and paste it into Postman's Import dialog directly.

Set up

1. In Postman, click Import and drop in all three files at once.

2. Pick Finomesh Staging in the environment selector (top right).

3. Open that environment and fill in the Current value column:

   Variable	Needed for	Where to get it
   apiKey	Everything except the public endpoints	Dashboard → your gateway (Authentication)
   signingSecret	The Cashout folder	Dashboard → your gateway, when you enable the cashout API
   cashoutAddress	Estimate fee, Create settlement	A destination address on the asset's chain (a testnet address on staging)
   callbackUrl	Hosted payments	Pre-filled with an example; point it at your own result page if you want to follow the redirect
   webhookUrl	Optional on hosted, required for API mode	Any URL that accepts a POST — your own endpoint, or a request-inspection service while testing

4. Open the Sandbox walkthrough folder and send its four requests in order — or run the folder with the Collection Runner.

Keep secrets in "Current value"

Enter apiKey and signingSecret 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 signingSecret — 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.

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 with 403 forbidden.
• Production moves real funds. With Finomesh Production selected, 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 files again after an API change and import them over the old ones — Postman offers to replace the existing collection.