Nexus Integration Recipe

Below are the six steps of a typical deposit flow, wired up to the exact Nexus calls. You create one openDeposit payment per client and stamp it with your internal client id. Nexus returns a stable address for that payment. Every time the client sends crypto to that address, Nexus confirms it on chain and POSTs you a webhook with your client id echoed back.

Step 1Register your webhook URL with Nexus one-time setup

You give Nexus the URL you want events delivered to. Nexus generates an id for the webhook, which doubles as its signing secret, and starts pushing every deposit and payout event to that URL. Store that id somewhere safe on your server. You will need it to verify every incoming delivery. A merchant can register up to five webhooks. Every enabled webhook receives every event, so one URL is enough for deposits and payouts.

curl -X POST "https://YOUR_NEXUS_HOST/v1/webhook" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "url":   "https://your-server.example.com/webhooks/nexus",
    "label": "Deposits and payouts"
  }'

{
  "success": true,
  "message": "",
  "web_hook": {
    "id":      "8f3c27d4-55b1-4c2e-9a7e-1f0b9a3e4d22",
    "url":     "https://your-server.example.com/webhooks/nexus",
    "enabled": true,
    "label":   "Deposits and payouts",
    "created": "2026-11-06T09:58:12.481Z"
  }
}

Save web_hook.id. This recipe calls it the webhook_id, and it is the secret you hash into every signature check. There is no separate "secret" field in the request body. PUT /v1/webhook/{id} toggles the webhook between enabled and disabled, and DELETE /v1/webhook/{id} removes it. To rotate the secret, register a new webhook, switch your verifier to the new id, then delete the old one.

Step 2Request an address for a client (one client, one address)

Nexus does not take your client id directly when issuing an address. Instead, you create an openDeposit payment once per client and store your client id on it (the field is called merchant_order_id). After that, every time you call the address endpoint with the same payment id and the same currency and network, Nexus returns the same address. That gives you exactly the one client, one address property you want.

So this step maps to two calls. The first happens once per client (a quick provisioning call); the second can happen as often as you like and will keep returning the same address.

2a. Create the openDeposit payment for this client once per client

This is the call that "registers" the client on Nexus's side. Set type to openDeposit so the address can receive any number of deposits of any size. Pass your internal client id as merchant_order_id. Nexus will echo it back on every webhook delivery for this client, which is how you will recognise who deposited.

curl -X POST "https://YOUR_NEXUS_HOST/v1/payment" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "type":                       "openDeposit",
    "pricing_mode":               "convertOnArrival",
    "merchant_order_id":          "YOUR_INTERNAL_CLIENT_ID",
    "merchant_order_metadata":    "{ \"client_id\": \"YOUR_INTERNAL_CLIENT_ID\" }"
  }'

A few notes on the fields. pricing_mode can be longLivedQuote (lock a rate up front) or convertOnArrival (convert at the moment the deposit lands). type and pricing_mode are both required. merchant_order_currency_id is only used for invoice payments; on an openDeposit it is ignored. merchant_order_id is your internal client identifier, up to 36 characters, and it is echoed back on every deposit event. merchant_order_metadata accepts any JSON value (here a string) and is echoed back unchanged. Also optional: merchant_order_description; expiration, a duration such as "30.00:00:00" with a minimum of 1 hour (leave it out so the deposit payment never expires); and passthrough_fees, which defaults to the account setting.

{
  "payment": {
    "id":                            "a427fc2a-be6b-44b4-9ebb-f0041496be70",
    "owner_user_id":                 "674016eb-a47f-4c56-9a09-12fd0bccba4a",
    "status":                        "New",
    "kyt_status":                    null,
    "currency_id":                   null,
    "expiration":                    null,
    "target_currency_amount_required": null,
    "target_currency_amount_paid":   null,
    "merchant_label":                null,
    "merchant_order_id":             "INT_CLIENT_0000001",
    "merchant_order_metadata":       "{ \"client_id\": \"INT_CLIENT_0000001\" }",
    "merchant_order_description":    null,
    "own_merchant_fee":              null,
    "created":                       "2026-04-28T09:00:14.291904+00:00",
    "type":                          "Open Deposit",
    "pricing_mode":                  "Convert On Arrival",
    "fees_in_price":                 true,
    "passthrough_fees":              false,
    "updated":                       "2026-04-28T09:00:14.291904+00:00",
    "expired":                       null
  },
  "success": true,
  "message": ""
}

Store payment.id alongside your client record in your own database. From now on, that single value is what you will use to fetch this client's deposit address, and the merchant_order_id you set is what you will look up when webhooks arrive.

2b. Fetch the deposit address stable, callable any time

Pass the payment id from 2a along with the currency and network you want an address on. The first call generates the address. Every subsequent call with the same payment id, currency, and network returns the very same address. So you can either call it once and cache, or you can call it every time the client opens their deposit page, the result will not change.

curl -X POST "https://YOUR_NEXUS_HOST/v1/client/address" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id":       "PAYMENT_ID_FROM_STEP_2A",
    "currency":         "ETH",
    "currency_network": "SEPOLIA"
  }'

currency and currency_network must be a pair that was enabled on your account when the payment was created, because each payment keeps a snapshot of the currency settings at that moment. A currency enabled later won't work on an older payment. currency_network is converted to upper case. This endpoint sits under /v1/client, which is the unauthenticated client side namespace. The payment_id itself is the credential. Treat it as semi sensitive on your side, but you do not need a Bearer token to call this endpoint.

{
  "address_id":               "a1ff35ed-276f-4db4-9b35-01f28b97338a",
  "address":                  "0xbC0B3C687496aB9D053b09BFcAfA05C184072aA4",
  "address_currency_id":      "ETH",
  "address_currency_network": "SEPOLIA",
  "tag_type":                 null,
  "tag_value":                null,
  "success":                  true,
  "message":                  ""
}

On the Demo (testnet) environment Ethereum lives under the SEPOLIA network; in production the same call returns an ETHEREUM mainnet address. If you need addresses on multiple chains for the same client (for example, ETH on SEPOLIA and USDT on TRC20), call this endpoint once per (currency, network) combination and store each address under that combination. tag_type and tag_value are null for chains like Ethereum. They are populated only on chains that require a memo, such as XRP or XLM. If you support those chains, you must show the tag to the client alongside the address, and warn them that omitting it will misroute their funds.

Step 3Show the address and network to the client

This step is entirely on your side. You already have everything you need from step 2b. Display the address, the address_currency_network, and (if the chain has one) the tag_value. Be explicit about which network the funds must be sent on (for the testnet flow that is Sepolia, not Ethereum mainnet). Sending crypto on the wrong chain is one of the most common ways funds go missing, and it is not recoverable on your end.

Step 4Client sends crypto to the address

This step happens entirely off your platform. The client opens their wallet, scans the QR or pastes the address, and broadcasts the transaction. There is nothing to call. Nexus's chain watcher picks the transaction up automatically once it appears on chain.

Step 5Nexus sends you a webhook when the transaction confirms

A deposit produces a series of deliveries, all with the same payment_id and on-chain crypto_transaction_id. A delivery is sent each time the exchange reports a change for the transaction: first when Nexus sees it on chain, then on each further confirmation update, with transaction_status: "Detected" and a growing confirmations count. If your account uses a custom (lower) confirmation count for the currency, you also get "ClientCompleted" when that count is reached. When the exchange marks the deposit final, the status becomes "Completed". "Completed" normally arrives twice: once straight away, then again after Nexus has processed fees and any conversion. The second delivery carries the final parent_fee and, if converted, preferred_currency_amount_received. A transaction the exchange rejects arrives as "Rejected". For an openDeposit, payment_status moves to "Processing" on the first transaction and stays there.

Detected (transaction_status: "Detected"). The deposit has been seen on chain. Do not credit the balance yet.

POST /webhooks/nexus HTTP/1.1
Host: your-server.example.com
Content-Type: application/json
x-webhook-signature: 7c1f4a93b8e2d6f0a5c8b4e7d2a9f6c3b1e8d5a7c4f9b6e3d0a7c4f1b8e5d2a9

{
  "payment_id":                         "23ad8d20-d8bb-4541-81a7-51ee8e61d1c4",
  "payment_status":                     "Processing",
  "transaction_status":                 "Detected",
  "crypto_transaction_id":              "0x3c4f2dca512f44238302678fe881789ec94beba9bc898aa8bd48b6a2ea72f1ea",
  "confirmations":                      1,
  "address":                            "0xbC0B3C687496aB9D053b09BFcAfA05C184072aA4",
  "currency":                           "ETH",
  "currency_network":                   "SEPOLIA",
  "currency_amount_paid":               0.05,
  "parent_fee":                         0,
  "is_converted":                       false,
  "is_overpayment":                     false,
  "preferred_currency_amount_received": null,
  "preferred_currency_id":              "USD",
  "merchant_order_id":                  "INT_CLIENT_0000001",
  "merchant_order_metadata":            "{ \"client_id\": \"INT_CLIENT_0000001\" }"
}

Completed (transaction_status: "Completed"). The deposit is final. Credit the balance on the first Completed delivery for a transaction.

{
  "payment_id":                         "23ad8d20-d8bb-4541-81a7-51ee8e61d1c4",
  "payment_status":                     "Processing",
  "transaction_status":                 "Completed",
  "crypto_transaction_id":              "0x3c4f2dca512f44238302678fe881789ec94beba9bc898aa8bd48b6a2ea72f1ea",
  "confirmations":                      1,
  "address":                            "0xbC0B3C687496aB9D053b09BFcAfA05C184072aA4",
  "currency":                           "ETH",
  "currency_network":                   "SEPOLIA",
  "currency_amount_paid":               0.05,
  "parent_fee":                         0,
  "is_converted":                       false,
  "is_overpayment":                     false,
  "preferred_currency_amount_received": null,
  "preferred_currency_id":              "USD",
  "merchant_order_id":                  "INT_CLIENT_0000001",
  "merchant_order_metadata":            "{ \"client_id\": \"INT_CLIENT_0000001\" }"
}

A few practical things. preferred_currency_id reflects the merchant's preferred-currency setting; on testnet that is currently "USD". preferred_currency_amount_received is only populated when is_converted is true (the deposit was actually converted at arrival); otherwise it stays null regardless of the preferred-currency setting. parent_fee is the parent-merchant fee on the transaction: an estimate on interim deliveries, and the amount actually charged on the final Completed delivery. payment_status and transaction_status are sent as code names (for example "ClientCompleted", with no space). Respond with a 2xx within a few seconds, otherwise Nexus will retry (three attempts in total; see Retry policy). The same delivery can land more than once across retries, so make your handler idempotent; see step 6 for how to dedupe.

Step 6Verify the signature, identify the client, credit the balance

Three things happen in your handler when a delivery lands. They run in this order.

6a. Verify the signature

Compute SHA-256 over webhook_id concatenated with the raw request body, hex encode it, and compare against the x-webhook-signature header. If they do not match, reject the request with 401 and stop. The full signature scheme and a sample implementation are in the Webhook signature verification section near the end. The same code path covers deposit and payout deliveries.

6b. Identify the client

Read merchant_order_id from the payload. That is the value you set in step 2a, so it is your internal client id. Look the client up in your database. If you also stored payment_id on the client row, you can additionally use it as a sanity check.

6c. Credit the balance

Only credit on transaction_status: "Completed". "Detected" and "ClientCompleted" are informational, and the deposit is not yet final. Do nothing on "Rejected". When you do credit, use currency_amount_paid as the amount and currency as the asset. If is_converted is true (the deposit was converted at arrival), preferred_currency_amount_received and preferred_currency_id hold the converted amount and target currency; if is_converted is false, preferred_currency_amount_received stays null regardless of the preferred-currency setting on the merchant account.

Reading the payment status on demand public, no Bearer needed

Webhooks are the right way to stay in sync. But occasionally you will want to read the live status of a payment without waiting for a delivery. For that, Nexus exposes a public read endpoint keyed by payment_id.

curl -X GET "https://YOUR_NEXUS_HOST/v1/client/payment/PAYMENT_ID"

Useful for a customer facing "deposit status" screen, or for backfilling state if your webhook endpoint was down for a while. The response is { "success", "message", "payment": { ..., "client_status", ... }, "transactions": [ ... ], ... }. payment.client_status is the payment status, and transactions lists the on-chain transactions detected so far.

Payouts run through the Nexus REST API, on the same host, with the same Bearer token and the same webhook as deposits. A payout has two parts: you create it, which validates the request, quotes the fees and records it as Pending. Then you approve it, which debits your balance and sends the funds on-chain. Nexus pushes a payout.* webhook event at every status change until the payout is payout.completed or payout.rejected.

Step 1Configure payout settings one-time setup

Three account settings decide how a backend-driven payout behaves. Review them once before you send your first payout.

1a. Turn off the per-payout 2FA code (skip_payout_mfa)

By default, approving a payout needs the merchant user's current 6-digit 2FA code (mfa_code). A server can't supply that code on every request. So for an automated integration, the merchant turns skip_payout_mfa on once. That setting can only be changed from the Nexus merchant dashboard in a browser, and turning it on needs a valid 2FA code. Calls from a server or an API key are rejected with 403. After that, approvals need no body at all. A merchant with skip_payout_mfa on also no longer needs 2FA enabled on the exchange account just to create payouts.

curl -X GET "https://YOUR_NEXUS_HOST/v1/user/settings" \
  -H "Authorization: Bearer YOUR_JWT"

{
  "payout_passthrough_fees": false,
  "skip_payout_mfa":         true
}

1b. Choose who pays the payout fees (payout_passthrough_fees)

A payout can be charged up to three fees: the exchange's network/withdrawal fee (fee), your parent merchant's fee (parent_merchant_fee) and your own payout fee (own_merchant_fee). The passthrough setting decides how they are applied:

• false (default): fees are deducted from amount, and the recipient receives final_amount = amount - fee - parent_merchant_fee - own_merchant_fee.
• true: the recipient receives exactly amount (final_amount = amount). Your account covers the fees.

You can set the account default with PATCH /v1/user/settings/payout-passthrough/{true|false}. You can also override it per payout with the passthrough_fees field in Step 3. If you use passthrough, keep enough free balance to cover both the amount and the fees.

curl -X PATCH "https://YOUR_NEXUS_HOST/v1/user/settings/payout-passthrough/true" \
  -H "Authorization: Bearer YOUR_JWT"

1c. Optional: lock payouts to your server IPs

You can whitelist up to 10 IP addresses or CIDR ranges (minimum /16 for IPv4, /48 for IPv6). Once at least one entry exists, payout create and approve calls from any other IP are rejected with 403. An empty list means no restriction. The IP checked is the one the Nexus load balancer sees, so add your servers' public egress IPs.

curl -X POST "https://YOUR_NEXUS_HOST/v1/user/settings/whitelisted-ips" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "ip_address": "203.0.113.0/24",
    "label":      "Payout workers"
  }'

List entries with GET, edit one with PUT /v1/user/settings/whitelisted-ips/{id} and remove one with DELETE /v1/user/settings/whitelisted-ips/{id}. The whitelist covers only payout create and approve. Reads, fee estimates and rejects work from any IP.

Step 2Check routes, limits and fees cache routes; check limits and fees per payout

2a. Supported payout routes

This returns the currency and network pairs you can send payouts on. It can differ from the deposit list in Before you start, so build your payout form from this call. If crypto_tag_type is present (for example a memo or destination tag), that route needs a tag on the destination.

curl -X GET "https://YOUR_NEXUS_HOST/v1/payout/payment-routes" \
  -H "Authorization: Bearer YOUR_JWT"

{
  "payment_routes": [
    { "currency": "ETH",  "crypto_network": "SEPOLIA" },
    { "currency": "USDT", "crypto_network": "TRC20" }
  ]
}

2b. Balance and limits for a currency

This returns your free balance, the minimum payout amount and the remaining periodic payout limits for one currency. Call it before you create a payout, so that a request your account cannot fund fails on your side first.

curl -X GET "https://YOUR_NEXUS_HOST/v1/payout/info/ETH" \
  -H "Authorization: Bearer YOUR_JWT"

{
  "account_balance": {
    "free_balance":    1.25,
    "total_balance":   1.30,
    "exposed_balance": 0.05
  },
  "payment_limit": {
    "currency":              "ETH",
    "payout_minimal_amount": 0.001,
    "payout_daily_limit":    5,
    "payout_weekly_limit":   20,
    "payout_monthly_limit":  50
  },
  "pending_payouts_amount": 0.05
}

The payout_*_limit values are the remaining amounts for the current day, week and month, not the configured caps. pending_payouts_amount is the total of payouts you have created but that haven't finished yet. free_balance is the figure that Step 4 checks against.

2c. Estimate the fees optional, read only

This quotes the fees and the amount the recipient would receive for a payout, without creating anything. It uses the same calculation as the create call. Pass passthroughFees to preview either fee mode. If you leave it out, your account default is used.

curl -X GET "https://YOUR_NEXUS_HOST/v1/payout/fee-estimation/ETH/SEPOLIA/0.01?passthroughFees=false" \
  -H "Authorization: Bearer YOUR_JWT"

{
  "fee_estimation": 0.0002,
  "final_amount":   0.0098,
  "fees": {
    "exchange_fee":        0.0002,
    "parent_merchant_fee": 0,
    "merchant_fee":        0
  }
}

fee_estimation is the total of the three fees. The exchange fee here is an estimate. The fee actually charged is fixed at approval and appears as fee on the payout record.

Step 3Create the payout

This call validates the request: your account status, that the route is enabled, that the destination address is valid for the network, the minimum amount and the fee quote. It records the payout as Pending/New. No funds move yet and your balance is not touched.

curl -X POST "https://YOUR_NEXUS_HOST/v1/payout" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "currency_id":         "ETH",
    "network":             "SEPOLIA",
    "amount":              0.01,
    "destination_address": "0x4e83362442B8d1bec281594CEa3050C8eB01311C",
    "note":                "INT_CLIENT_0000001:WD-000123",
    "passthrough_fees":    false
  }'

{
  "id":                  "6f1d2c3b-8a47-4e0f-9b52-0c7e1a9d4f21",
  "currency":            "ETH",
  "network":             "SEPOLIA",
  "amount":              0.01,
  "fee":                 0.0002,
  "parent_merchant_fee": 0,
  "own_merchant_fee":    0,
  "final_amount":        0.0098,
  "destination_address": "0x4e83362442B8d1bec281594CEa3050C8eB01311C",
  "tag_type":            null,
  "tag_value":           null,
  "exchange_payment_id": null,
  "blockchain_hash":     null,
  "note":                "INT_CLIENT_0000001:WD-000123",
  "approval_status":     "Pending",
  "execution_status":    "New",
  "created_at":          "2026-11-06T10:15:02.184Z",
  "updated_at":          "2026-11-06T10:15:02.184Z",
  "kyt":                 null,
  "payout_passthrough_fees": false,
  "is_refund":           false,
  "manual_refund":       null
}

Store id against the client's withdrawal request. It is the payout id for every later call, and every webhook carries it as payout_id. A payout.initiated webhook fires as soon as this call returns.

Step 4Approve the payout

Approval checks your free_balance against amount, books the payout fees, and sends the payout to the exchange for on-chain execution. If it succeeds, the payout moves to Approved/Processing and exchange_payment_id is filled in. If you run payouts straight through, call approve right after create.

curl -X PATCH "https://YOUR_NEXUS_HOST/v1/payout/PAYOUT_ID/approve" \
  -H "Authorization: Bearer YOUR_JWT"

curl -X PATCH "https://YOUR_NEXUS_HOST/v1/payout/PAYOUT_ID/approve" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "mfa_code": "123456" }'

The body is optional. mfa_code is only checked when skip_payout_mfa is off. wallet_id is also optional, and selects which exchange wallet to debit when your account has more than one. Leave it out to use the default wallet.

{
  "id":                  "6f1d2c3b-8a47-4e0f-9b52-0c7e1a9d4f21",
  "currency":            "ETH",
  "network":             "SEPOLIA",
  "amount":              0.01,
  "fee":                 0.000029,
  "parent_merchant_fee": 0,
  "own_merchant_fee":    0,
  "final_amount":        0.009971,
  "destination_address": "0x4e83362442B8d1bec281594CEa3050C8eB01311C",
  "tag_type":            null,
  "tag_value":           null,
  "exchange_payment_id": "019dd623-f9fb-72ab-9163-03d8d87dd90e",
  "blockchain_hash":     null,
  "note":                "INT_CLIENT_0000001:WD-000123",
  "approval_status":     "Approved",
  "execution_status":    "Processing",
  "created_at":          "2026-11-06T10:15:02.184Z",
  "updated_at":          "2026-11-06T10:15:03.902Z",
  "kyt":                 null,
  "payout_passthrough_fees": false,
  "is_refund":           false,
  "manual_refund":       null
}

At approval, fee is replaced by the fee the exchange actually charged, so final_amount can differ slightly from the Step 2c estimate. A payout can be approved only once. A second call returns Withdrawal was already approved or rejected.. If approval fails with a 400 (for example insufficient balance), the payout stays Pending. You can retry the approval once you've fixed the cause, or cancel it with PATCH /v1/payout/{id}/reject.

Step 5Verify the signature and finalise on webhooks

Payout events go to the same URL as deposits, with the same x-webhook-signature header, verified with the same webhook id (see Webhook signature verification). Unlike deposit deliveries, payout deliveries come in an envelope: { "event": "payout.*", "data": { ... } }. Branch on event and match data.payout_id to the id you stored in Step 3.

A healthy payout produces payout.initiated (create), then payout.processing (approve), and finally payout.completed once the transaction confirms on chain. payout.processing can arrive more than once while the exchange reports progress. Treat repeats as no-ops.

Sample deliveries

payout.initiated. Fires right after Step 3. Nothing has moved.

{
  "event": "payout.initiated",
  "data": {
    "payout_id":                   "6f1d2c3b-8a47-4e0f-9b52-0c7e1a9d4f21",
    "blockchain_transaction_hash": null,
    "status":                      "payout.initiated",
    "amount":                      0.01,
    "destination_address":         "0x4e83362442B8d1bec281594CEa3050C8eB01311C",
    "exchange_payment_id":         null,
    "note":                        "INT_CLIENT_0000001:WD-000123",
    "currency":                    "ETH",
    "timestamp":                   "2026-11-06T10:15:02.2214567Z",
    "kyt":                         null
  }
}

payout.processing. Fires on approval, and again on each progress update from the exchange. exchange_payment_id is now populated.

{
  "event": "payout.processing",
  "data": {
    "payout_id":                   "6f1d2c3b-8a47-4e0f-9b52-0c7e1a9d4f21",
    "blockchain_transaction_hash": null,
    "status":                      "payout.processing",
    "amount":                      0.01,
    "destination_address":         "0x4e83362442B8d1bec281594CEa3050C8eB01311C",
    "exchange_payment_id":         "019dd623-f9fb-72ab-9163-03d8d87dd90e",
    "note":                        "INT_CLIENT_0000001:WD-000123",
    "currency":                    "ETH",
    "timestamp":                   "2026-11-06T10:15:03.9551204Z",
    "kyt":                         null
  }
}

payout.completed. Fires once the transaction has confirmed. blockchain_transaction_hash is the on-chain txid you can link to a block explorer. This is the event that should mark the payout as final on your side.

{
  "event": "payout.completed",
  "data": {
    "payout_id":                   "6f1d2c3b-8a47-4e0f-9b52-0c7e1a9d4f21",
    "blockchain_transaction_hash": "0x2887de8e5ce88810f7501b24af05a9abdd10c03ad6dc4ce97e86306af1f4fb28",
    "status":                      "payout.completed",
    "amount":                      0.01,
    "destination_address":         "0x4e83362442B8d1bec281594CEa3050C8eB01311C",
    "exchange_payment_id":         "019dd623-f9fb-72ab-9163-03d8d87dd90e",
    "note":                        "INT_CLIENT_0000001:WD-000123",
    "currency":                    "ETH",
    "timestamp":                   "2026-11-06T10:16:41.0087312Z",
    "kyt":                         null
  }
}

payout.rejected. Fires in two situations: you rejected a Pending payout yourself, or the exchange rejected it after approval (compliance, risk or an on-chain failure). In the second case, payout fees that were booked are refunded automatically. In both cases no funds reached the destination, so give the amount back to the client's internal balance.

amount in the webhook is always the gross amount from Step 3. For the net amount and the fee breakdown, read the payout record (below). kyt holds the KYT screening result when screening is enabled on your account, and is null otherwise.

Reading payout state on demand

Use these calls when your handler was down, for reconciliation, or for an operator screen. Both return the same payout object as Steps 3 and 4.

curl -X GET "https://YOUR_NEXUS_HOST/v1/payout/PAYOUT_ID" \
  -H "Authorization: Bearer YOUR_JWT"

curl -X GET "https://YOUR_NEXUS_HOST/v1/payout/list?pageIndex=1&pageSize=50&executionStatus=Processing" \
  -H "Authorization: Bearer YOUR_JWT"

The list response is { "results": [ ... ], "total_count": n, "page": n, "size": n }, newest first. pageIndex is 1-based. The optional filters are currency, approvalStatus (Pending, Approved, Rejected), executionStatus (New, Processing, Completed, Rejected), startDate, endDate and search. search matches a payout id or exchange_payment_id exactly, or any payout whose note contains the text. That is how you find a payout by your own reference.