Schema & Sample Payloads

Quick reference for transaction request/response structure. Use these samples for testing in Postman, curl, or your integration code.

Transaction Request Structure

Every transaction follows the same schema — only the method, ccy, and reqDetails change based on what you're doing.

{
  "extRefId": "your-unique-ref-123",
  "note": "Optional internal note",
  "deductNetworkFeesFromDest": false,
  "sourceReq": {
    "ccy": "BTC",
    "method": "neutronpay",
    "amtRequested": 0.001,
    "reqDetails": {},
    "kyc": { }
  },
  "destReq": {
    "ccy": "BTC",
    "method": "lightning",
    "reqDetails": {
      "paymentRequest": "lnbc..."
    },
    "kyc": { }
  },
  "sourceOfFunds": {
    "purpose": 1,
    "source": 5,
    "relationship": 3
  }
}

Top-Level Fields

Field	Type	Required	Description
`extRefId`	string	❌	Your own reference ID — must be unique per transaction
`note`	string	❌	Internal note (not sent to recipient)
`deductNetworkFeesFromDest`	boolean	❌	If `true`, fees are deducted from the sent amount
`sourceReq`	object	✅	Where funds come from
`destReq`	object	✅	Where funds go to
`sourceOfFunds`	object	❌	Required only for fiat payouts

sourceReq / destReq Fields

Field	Type	Description
`ccy`	string	Currency code (`"BTC"`, `"USDT"`, `"VND"`, `"USD"`, etc.)
`method`	string	Payment method (see table below)
`amtRequested`	number	Amount — set on one side only
`reqDetails`	object	Method-specific details (address, invoice, bank info, etc.)
`kyc`	object	KYC info — only required for fiat payouts

Payment Methods

Method	Direction	Description
`neutronpay`	Source or Dest	Internal Neutron wallet
`lightning`	Source or Dest	Lightning Network
`on-chain`	Source or Dest	Bitcoin on-chain
`tron`	Dest only	USDT via TRON (TRC-20)
`eth`	Dest only	USDT via Ethereum (ERC-20) — coming soon
`vnd-instant`	Dest only	Vietnamese Dong bank payout

reqDetails by Method

Method	reqDetails	Example
`neutronpay`	`{}` (empty)	—
`lightning` (send)	`{ "paymentRequest": "lnbc..." }`	Bolt11 invoice
`lightning` (receive)	`{}` (empty)	Invoice generated in response
`on-chain` (send)	`{ "address": "bc1q..." }`	Bitcoin address
`on-chain` (receive)	`{}` (empty)	Address generated in response
`tron`	`{ "address": "T..." }`	TRON address
`vnd-instant`	`{ "bankAcctNum": "...", "institutionCode": "..." }`	Bank details

Sample: Lightning Receive

curl -X POST https://api.neutron.me/api/v2/transaction/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "sourceReq": {
      "ccy": "BTC",
      "method": "lightning",
      "reqDetails": {}
    },
    "destReq": {
      "ccy": "BTC",
      "method": "neutronpay",
      "amtRequested": 0.0001,
      "reqDetails": {}
    }
  }'

Sample: Fiat Payout (VND)

curl -X POST https://api.neutron.me/api/v2/transaction/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "extRefId": "payout-001",
    "sourceReq": {
      "ccy": "BTC",
      "method": "neutronpay",
      "amtRequested": 0.001
    },
    "destReq": {
      "ccy": "VND",
      "method": "vnd-instant",
      "reqDetails": {
        "bankAcctNum": "0123456789",
        "institutionCode": "970422"
      },
      "kyc": {
        "type": "individual",
        "details": {
          "legalFullName": "LE VAN A",
          "countryCode": "VN"
        }
      }
    },
    "sourceOfFunds": {
      "purpose": 1,
      "source": 5,
      "relationship": 3
    }
  }'

Transaction Response Structure

All transaction endpoints return the same response shape:

{
  "txnId": "d3f1458a-121b-4a90-bf2d-f01c821eab61",
  "accountId": "ne01-abc123def456",
  "accountDisplayName": "My Account",
  "extRefId": "your-unique-ref-123",
  "txnState": "quoted",
  "sourceReq": {
    "ccy": "BTC",
    "method": "neutronpay",
    "amtRequested": 0.001,
    "amtSettled": null,
    "neutronpayFees": 0,
    "networkFees": 0.0000005,
    "reqStatus": "0",
    "expiresAt": 1770345600000,
    "createAt": 1770342000000,
    "updatedAt": 1770342000000
  },
  "destReq": {
    "ccy": "VND",
    "method": "vnd-instant",
    "amtRequested": 300000,
    "amtSettled": null,
    "reqStatus": "0",
    "reqDetails": {
      "bankAcctNum": "0123456789",
      "institutionCode": "970422"
    }
  },
  "fxRate": 2750000000,
  "createdAt": 1770342000000
}

Response Fields

Field	Type	Description
`txnId`	string	Unique transaction ID
`accountId`	string	Your account ID
`extRefId`	string	Your reference ID (if provided)
`txnState`	string	Current state — see Transaction Status Types
`sourceReq`	object	Source side with amounts, fees, and status
`destReq`	object	Destination side with amounts and status
`fxRate`	number	Exchange rate applied (1 for same-currency transactions)
`sourceReq.amtSettled`	number	Actual amount settled (populated after completion)
`sourceReq.neutronpayFees`	number	Neutron service fee
`sourceReq.networkFees`	number	Network/mining fee
`sourceReq.reqStatus`	string	Request status code
`sourceReq.expiresAt`	integer	Expiry timestamp (ms)

Related

Create Transaction — API reference
Transaction Status Types — All states explained
Fiat Payouts — KYC and sourceOfFunds details
Webhook Guide — Receive transaction updates