Skip to main content

Quickstart

Accept your first crypto payment in five steps. You need an API key from your dashboard — everything else is below. Use the staging environment (api-staging.finomesh.com) and sandbox mode until your integration is complete.

1. Create a payment​

Your server (never the browser — the API key must stay secret) creates a payment:

curl -X POST https://api-staging.finomesh.com/api/v1/payments \
  -H "X-Api-Key: $FINOMESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currencyCode": "USD",
    "amount": "49.99",
    "callbackUrl": "https://shop.example.com/payment/result",
    "callbackParams": { "orderId": "ORD-1042" },
    "webhookUrl": "https://shop.example.com/api/finomesh-webhook",
    "timeoutSeconds": 3600
  }'

The response contains the payment id and the hosted-checkout URL:

{
  "success": true,
  "data": {
    "paymentUid": "0d9f3a64-4f0c-4b6e-9f6e-2f4f4c1b8a21",
    "paymentUrl": "https://checkout-staging.finomesh.com/p/0d9f3a64-4f0c-4b6e-9f6e-2f4f4c1b8a21"
  }
}

Store data.paymentUid against your order — it is your correlation key for everything that follows. The payable assets, deposit addresses, and amounts live on the hosted checkout (and in verify), not in this response.

2. Redirect the customer to the checkout​

Send the customer to the paymentUrl from step 1:

https://checkout-staging.finomesh.com/p/{paymentUid}

The hosted checkout shows the available assets, the deposit address and QR code, and a live countdown. Finomesh monitors the chain and updates the page in real time when the deposit confirms.

3. Receive the result​

Two notifications fire when the payment reaches a terminal status — both carry only paymentId and status:

  • Callback (browser) — the customer is redirected to your callbackUrl with your callbackParams plus paymentId and status appended as query parameters:

    https://shop.example.com/payment/result?orderId=ORD-1042&paymentId=0d9f3a64-…&status=SUCCESS

  • Webhook (server, optional) — if you set webhookUrl, Finomesh POSTs a signed JSON body to your server, retrying until you answer 2xx. See Webhooks.

    { "paymentId": "0d9f3a64-4f0c-4b6e-9f6e-2f4f4c1b8a21", "status": "SUCCESS" }

4. Verify before fulfilling​

The callback is forgeable and the webhook is only a trigger. Confirm the real outcome from your server:

curl -X POST https://api-staging.finomesh.com/api/v1/payments/0d9f3a64-…/verify \
  -H "X-Api-Key: $FINOMESH_API_KEY"
{
  "success": true,
  "data": {
    "paymentId": "0d9f3a64-4f0c-4b6e-9f6e-2f4f4c1b8a21",
    "status": "SUCCESS",
    "isVerified": true,
    "verifiedAt": "2026-06-12T10:21:43Z",
    "amount": "49.99",
    "currencyCode": "USD",
    "amountUsd": "49.99",
    "txHash": "0xabc…",
    "expectedAmount": "51.69",
    "receivedAmount": "51.69",
    "assetSymbol": "USDT",
    "deviationUsd": "0"
  }
}

5. Fulfil on the verified status​

SUCCESS or ACCEPTABLE  → fulfil the order
MISMATCH               → hold for manual review (check deviationUsd)
EXPIRED                → cancel the order
PENDING                → not paid yet — wait

That's the whole integration. Next: