---
updatedAt: 2026-02-28T11:25:19.000Z
agentTools:
  projectIndex: https://neutronpay.readme.io/llms.txt
---

# 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.

```json
{
  "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](/reference/fiat-out)  |

### 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](/reference/fiat-out) |

### 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

```bash
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)

```bash
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:

```json
{
  "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](/reference/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](/reference/createtransaction) — API reference
* [Transaction Status Types](/reference/transaction-status-types) — All states explained
* [Fiat Payouts](/reference/fiat-out) — KYC and sourceOfFunds details
* [Webhook Guide](/reference/purpose) — Receive transaction updates