@siglume/direct-request-payment 0.4.14 → 0.4.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/README.md +10 -10
- package/dist/index.cjs +18 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +15 -6
- package/dist/index.d.ts +15 -6
- package/dist/index.js +18 -3
- package/dist/index.js.map +1 -1
- package/docs/announcement-ja.md +6 -6
- package/docs/api-reference.md +65 -12
- package/docs/metered-statements.md +33 -32
- package/docs/pricing.md +33 -41
- package/package.json +1 -1
package/docs/api-reference.md
CHANGED
|
@@ -537,15 +537,20 @@ accepted by these user-authenticated routes.
|
|
|
537
537
|
This client creates SDRP Standard Payment requirements for external merchant
|
|
538
538
|
checkout flows. Micro Payment and Nano Payment are applied automatically by
|
|
539
539
|
amount and settled on account-assigned weekly / monthly slots, or earlier when a
|
|
540
|
-
buyer/
|
|
541
|
-
explicitly through this client. Use the statement APIs
|
|
542
|
-
usage, the close time, the final-notice schedule, and
|
|
543
|
-
past-due revenue.
|
|
540
|
+
buyer / provider / token / pricing-band batch reaches JPY 10,000 / USD 100.00;
|
|
541
|
+
they are not created explicitly through this client. Use the statement APIs
|
|
542
|
+
below to see open-period usage, the close time, the final-notice schedule, and
|
|
543
|
+
settled / unsettled / past-due revenue.
|
|
544
544
|
|
|
545
545
|
Standard Payment requirements include `fee_bps` from the Siglume platform. The
|
|
546
546
|
SDK does not calculate merchant plan fees locally. For Micro / Nano, use the
|
|
547
547
|
statement API amount fields (`protocol_fee_minor`, `gross_buyer_debit_minor`,
|
|
548
|
-
`buyer_debit_minor`,
|
|
548
|
+
`buyer_debit_minor`, `provider_gross_amount_minor`, and
|
|
549
|
+
`rounding_delta_minor`); see [Pricing](./pricing.md).
|
|
550
|
+
`provider_gross_amount_minor` is canonical; `provider_usage_amount_minor` and
|
|
551
|
+
`gross_buyer_debit_minor` are compatibility aliases of the same provider gross
|
|
552
|
+
amount. Micro / Nano protocol fees are seller-borne, so
|
|
553
|
+
`buyer_debit_minor = provider_gross_amount_minor`.
|
|
549
554
|
|
|
550
555
|
```ts
|
|
551
556
|
const siglume = new DirectRequestPaymentClient({
|
|
@@ -772,6 +777,7 @@ returns `{items, next_cursor}`. When `next_cursor` is non-null, pass it back as
|
|
|
772
777
|
Buyer-facing amount names are centered on the debit:
|
|
773
778
|
|
|
774
779
|
- `estimated_buyer_debit_minor`
|
|
780
|
+
- `provider_gross_amount_minor`
|
|
775
781
|
- `provider_usage_amount_minor`
|
|
776
782
|
- `gross_buyer_debit_minor`
|
|
777
783
|
- `buyer_debit_minor`
|
|
@@ -837,6 +843,7 @@ back as `cursor` to fetch the next page.
|
|
|
837
843
|
|
|
838
844
|
Provider-facing amount names:
|
|
839
845
|
|
|
846
|
+
- `provider_gross_amount_minor`
|
|
840
847
|
- `provider_usage_amount_minor`
|
|
841
848
|
- `provider_receivable_minor`
|
|
842
849
|
- `gross_buyer_debit_minor`
|
|
@@ -892,13 +899,14 @@ curl https://siglume.com/v1/sdrp/metered/provider/settlement-batches/<batch-id>/
|
|
|
892
899
|
Columns:
|
|
893
900
|
|
|
894
901
|
```text
|
|
895
|
-
metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end,listing_id,capability_key,operation_key,currency,token_symbol,provider_usage_amount_minor,provider_receivable_minor,protocol_fee_minor,gross_buyer_debit_minor,rounding_delta_minor,buyer_debit_minor,status,settlement_batch_id,buyer_period_ref
|
|
902
|
+
metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end,listing_id,capability_key,operation_key,currency,token_symbol,provider_gross_amount_minor,provider_usage_amount_minor,provider_receivable_minor,protocol_fee_minor,gross_buyer_debit_minor,rounding_delta_minor,buyer_debit_minor,status,settlement_batch_id,buyer_period_ref
|
|
896
903
|
```
|
|
897
904
|
|
|
898
905
|
The CSV uses `buyer_period_ref`, not raw buyer account identifiers.
|
|
899
906
|
The CSV keeps the `rounding_delta_minor` column for schema stability, but usage
|
|
900
|
-
rows report `0
|
|
901
|
-
|
|
907
|
+
rows report `0`. If a batch-level `rounding_delta_minor` appears in historical
|
|
908
|
+
or internal records, do not add it to buyer debit and do not allocate it to
|
|
909
|
+
provider revenue.
|
|
902
910
|
|
|
903
911
|
Micro / Nano amount fields are decimal minor-unit strings. In JavaScript, do
|
|
904
912
|
not aggregate them with `number`; parse them with a decimal library. In Python,
|
|
@@ -950,14 +958,17 @@ Returns the prepared-transaction payload object.
|
|
|
950
958
|
Returns the bare HMAC-SHA256 hex digest over `"<timestamp>.<body>"`. This is the
|
|
951
959
|
primitive `buildWebhookSignatureHeader` / `verifyWebhookSignature` use. In
|
|
952
960
|
TypeScript `options` is `{ timestamp: number }`; in Python `timestamp` is a
|
|
953
|
-
keyword-only `int`. `body` may be raw bytes, a string, or a JSON object
|
|
961
|
+
keyword-only `int`. `body` may be raw bytes, a string, or a JSON object when you
|
|
962
|
+
are building a test signature. Production webhook verification must use the
|
|
963
|
+
exact raw request body.
|
|
954
964
|
|
|
955
965
|
### `buildWebhookSignatureHeader(secret, body, options)` / `build_webhook_signature_header(secret, body, *, timestamp=None)`
|
|
956
966
|
|
|
957
967
|
Returns a `t=<timestamp>,v1=<signature>` header string. Mainly for tests /
|
|
958
968
|
mocking inbound webhooks. In TypeScript `options` is an optional
|
|
959
969
|
`{ timestamp?: number }` (defaults to now); in Python `timestamp` is a
|
|
960
|
-
keyword-only optional `int`.
|
|
970
|
+
keyword-only optional `int`. This helper accepts JSON objects for tests; the
|
|
971
|
+
verification helpers below do not.
|
|
961
972
|
|
|
962
973
|
### `verifyWebhookSignature(secret, body, signature_header, options)` / `verify_webhook_signature(secret, body, signature_header, *, tolerance_seconds=300, now=None)`
|
|
963
974
|
|
|
@@ -966,7 +977,9 @@ Verifies the `Siglume-Signature` header against the raw `body`. Throws
|
|
|
966
977
|
the timestamp is outside tolerance or the signature does not match. In TypeScript
|
|
967
978
|
`options` is `{ tolerance_seconds?, now? }`; in Python those are keyword-only
|
|
968
979
|
(`tolerance_seconds` defaults to `DEFAULT_WEBHOOK_TOLERANCE_SECONDS` = 300).
|
|
969
|
-
Returns `{ timestamp, signature }`.
|
|
980
|
+
Returns `{ timestamp, signature }`. Pass the exact raw request body bytes or raw
|
|
981
|
+
body string captured by your web framework. Passing a parsed JSON object is
|
|
982
|
+
rejected because re-stringifying changes the signed bytes.
|
|
970
983
|
|
|
971
984
|
### `parseDirectRequestPaymentWebhookEvent(payload)` / `parse_direct_request_payment_webhook_event(payload)`
|
|
972
985
|
|
|
@@ -1029,7 +1042,8 @@ return `kind: "unknown"` with a machine-readable `reason`.
|
|
|
1029
1042
|
|
|
1030
1043
|
Verifies the signature and parses the event in one call. Returns
|
|
1031
1044
|
`{ event, verification }` (TS) / `{"event": ..., "verification": ...}` (Py). Same
|
|
1032
|
-
options shape as `verifyWebhookSignature` (keyword-only in Python).
|
|
1045
|
+
options shape as `verifyWebhookSignature` (keyword-only in Python). The `body`
|
|
1046
|
+
argument is raw bytes or a raw body string only; do not pass parsed JSON.
|
|
1033
1047
|
|
|
1034
1048
|
Webhook-verification trio (typical inbound webhook handler):
|
|
1035
1049
|
|
|
@@ -1058,6 +1072,45 @@ event = verified["event"]
|
|
|
1058
1072
|
# or equivalent fail-closed field checks before marking an order paid or fulfilled.
|
|
1059
1073
|
```
|
|
1060
1074
|
|
|
1075
|
+
Express example:
|
|
1076
|
+
|
|
1077
|
+
```ts
|
|
1078
|
+
app.post("/siglume/webhook", express.raw({ type: "application/json" }), async (req, res) => {
|
|
1079
|
+
const { event } = await verifyDirectRequestPaymentWebhook(
|
|
1080
|
+
process.env.SIGLUME_WEBHOOK_SECRET!,
|
|
1081
|
+
req.body,
|
|
1082
|
+
req.header("siglume-signature") ?? "",
|
|
1083
|
+
);
|
|
1084
|
+
res.json({ received: event.id });
|
|
1085
|
+
});
|
|
1086
|
+
```
|
|
1087
|
+
|
|
1088
|
+
FastAPI example:
|
|
1089
|
+
|
|
1090
|
+
```py
|
|
1091
|
+
@app.post("/siglume/webhook")
|
|
1092
|
+
async def siglume_webhook(request: Request):
|
|
1093
|
+
raw_body = await request.body()
|
|
1094
|
+
verified = verify_direct_request_payment_webhook(
|
|
1095
|
+
os.environ["SIGLUME_WEBHOOK_SECRET"],
|
|
1096
|
+
raw_body,
|
|
1097
|
+
request.headers.get("siglume-signature", ""),
|
|
1098
|
+
)
|
|
1099
|
+
return {"received": verified["event"]["id"]}
|
|
1100
|
+
```
|
|
1101
|
+
|
|
1102
|
+
Django example:
|
|
1103
|
+
|
|
1104
|
+
```py
|
|
1105
|
+
def siglume_webhook(request):
|
|
1106
|
+
verified = verify_direct_request_payment_webhook(
|
|
1107
|
+
os.environ["SIGLUME_WEBHOOK_SECRET"],
|
|
1108
|
+
request.body,
|
|
1109
|
+
request.headers.get("Siglume-Signature", ""),
|
|
1110
|
+
)
|
|
1111
|
+
return JsonResponse({"received": verified["event"]["id"]})
|
|
1112
|
+
```
|
|
1113
|
+
|
|
1061
1114
|
## Exported Constants
|
|
1062
1115
|
|
|
1063
1116
|
Both packages export these importable constants:
|
|
@@ -91,38 +91,34 @@ open period. It can report `wallet_balance_checked: false` or
|
|
|
91
91
|
`allowance_checked: false`; in that case it is guidance, not a final on-chain
|
|
92
92
|
guarantee.
|
|
93
93
|
|
|
94
|
-
##
|
|
94
|
+
## Seller-borne Micro / Nano Amounts
|
|
95
95
|
|
|
96
96
|
Micro / Nano usage rows keep provider price and protocol fee values as decimal
|
|
97
97
|
minor-unit amounts. This allows Nano fees such as JPY 0.2 per SDRP Tx to be
|
|
98
98
|
accounted without rounding every accepted payment.
|
|
99
99
|
|
|
100
|
-
|
|
100
|
+
The buyer is charged only the provider-visible usage amount. Micro / Nano
|
|
101
|
+
protocol fees are seller-borne and are deducted from provider receivable:
|
|
101
102
|
|
|
102
103
|
```text
|
|
103
|
-
|
|
104
|
+
provider_gross_amount_minor = sum(provider price minor units for accepted metered rows)
|
|
105
|
+
provider_usage_amount_minor = provider_gross_amount_minor # legacy alias
|
|
106
|
+
gross_buyer_debit_minor = provider_gross_amount_minor # legacy alias
|
|
107
|
+
buyer_debit_minor = provider_gross_amount_minor
|
|
104
108
|
protocol_fee_minor = sum(Micro/Nano fixed protocol fee minor units for accepted metered rows)
|
|
105
|
-
provider_receivable_minor =
|
|
106
|
-
|
|
107
|
-
buyer_debit_minor = ceil(gross_buyer_debit_minor)
|
|
108
|
-
rounding_delta_minor = buyer_debit_minor - gross_buyer_debit_minor
|
|
109
|
+
provider_receivable_minor = provider_gross_amount_minor - protocol_fee_minor
|
|
110
|
+
rounding_delta_minor = 0 for buyer/provider accounting
|
|
109
111
|
```
|
|
110
112
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
`rounding_delta_minor` belongs to the buyer debit and Siglume's rounding
|
|
121
|
-
adjustment accounting for that batch. It is not provider revenue.
|
|
122
|
-
`protocol_fee_minor` is provider-borne and is not added to the buyer debit.
|
|
123
|
-
Provider reports should use `provider_receivable_minor`,
|
|
124
|
-
`settled_provider_receivable_minor`, `unsettled_provider_receivable_minor`, and
|
|
125
|
-
`past_due_provider_receivable_minor`.
|
|
113
|
+
Example: a JPY 100 Micro usage event has `buyer_debit_minor = 100`,
|
|
114
|
+
`protocol_fee_minor = 2`, and `provider_receivable_minor = 98`.
|
|
115
|
+
|
|
116
|
+
The `rounding_delta_minor` field remains in some statement schemas for
|
|
117
|
+
compatibility. It is not added to `buyer_debit_minor`, not added to
|
|
118
|
+
`provider_gross_amount_minor`, and not deducted again from
|
|
119
|
+
`provider_receivable_minor`. If non-zero in a historical or internal record,
|
|
120
|
+
treat it as a Siglume platform accounting adjustment, not buyer debit or
|
|
121
|
+
provider revenue.
|
|
126
122
|
|
|
127
123
|
Micro / Nano amount fields are decimal minor-unit strings. JavaScript
|
|
128
124
|
integrations should aggregate them with a decimal library, not `number`. Python
|
|
@@ -149,7 +145,9 @@ Buyer usage event amount fields:
|
|
|
149
145
|
|
|
150
146
|
- `provider_usage_amount_minor`: provider price for the usage event
|
|
151
147
|
- `protocol_fee_minor`: provider-borne metered protocol fee
|
|
152
|
-
- `
|
|
148
|
+
- `provider_gross_amount_minor`: provider price before protocol fee
|
|
149
|
+
- `gross_buyer_debit_minor`: legacy alias of `provider_gross_amount_minor`
|
|
150
|
+
- `buyer_debit_minor`: buyer debit; equals `provider_gross_amount_minor`
|
|
153
151
|
- `expected_scheduled_debit_at`: derived schedule for an open period before a
|
|
154
152
|
settlement batch exists
|
|
155
153
|
|
|
@@ -175,8 +173,10 @@ Buyer batch amount fields:
|
|
|
175
173
|
|
|
176
174
|
- `estimated_buyer_debit_minor`: total buyer debit for the batch
|
|
177
175
|
- `provider_usage_amount_minor`: provider usage amount before protocol fee
|
|
178
|
-
- `
|
|
176
|
+
- `provider_gross_amount_minor`: provider gross before protocol fee
|
|
177
|
+
- `gross_buyer_debit_minor`: legacy alias of `provider_gross_amount_minor`
|
|
179
178
|
- `buyer_debit_minor`: amount scheduled for the debit transaction
|
|
179
|
+
- `provider_receivable_minor`: provider gross minus provider-borne protocol fee
|
|
180
180
|
|
|
181
181
|
Past-due batches include:
|
|
182
182
|
|
|
@@ -197,7 +197,7 @@ Threshold-control fields:
|
|
|
197
197
|
- `threshold_reached_at`: set when the fixed amount threshold closed the batch
|
|
198
198
|
- `total_unsettled_exposure_minor`: open plus `notice_pending`, `ready`,
|
|
199
199
|
`submitted`, retrying, and `past_due` provider gross exposure for the same
|
|
200
|
-
buyer / provider / token
|
|
200
|
+
buyer / provider / token / pricing band
|
|
201
201
|
|
|
202
202
|
JPY 10,000 and USD 100.00 are market-specific fixed thresholds, not FX
|
|
203
203
|
conversions of one another.
|
|
@@ -316,7 +316,7 @@ Important batch fields:
|
|
|
316
316
|
| `settlement_trigger` | `amount_threshold` for early threshold close, or `scheduled_close` for weekly/monthly close |
|
|
317
317
|
| `settlement_threshold_minor` | Fixed market threshold for early settlement: JPY `10000` or USD `10000` minor units |
|
|
318
318
|
| `threshold_reached_at` | Timestamp when the fixed threshold closed the batch, otherwise null |
|
|
319
|
-
| `total_unsettled_exposure_minor` | Current open plus notice/ready/submitted/retrying/past-due provider gross exposure for the same buyer / provider / token |
|
|
319
|
+
| `total_unsettled_exposure_minor` | Current open plus notice/ready/submitted/retrying/past-due provider gross exposure for the same buyer / provider / token / pricing band |
|
|
320
320
|
| `expected_scheduled_debit_at` | Expected debit time for an open period before a batch exists |
|
|
321
321
|
| `scheduled_debit_at` | Scheduled debit time after batch creation |
|
|
322
322
|
| `not_before_attempt_at` | Earliest allowed debit attempt; this is the close-plus-3-day gate |
|
|
@@ -324,14 +324,15 @@ Important batch fields:
|
|
|
324
324
|
| `latest_execution_attempt_status` | Latest non-sensitive execution attempt status |
|
|
325
325
|
| `chain_receipt_id` | On-chain receipt id when available |
|
|
326
326
|
| `usage_event_digest` | Digest of usage rows included in the batch |
|
|
327
|
+
| `provider_gross_amount_minor` | Provider gross before provider-borne protocol fee |
|
|
327
328
|
| `provider_usage_amount_minor` | Provider usage amount before protocol fee |
|
|
328
329
|
| `provider_receivable_minor` | Provider amount for the batch after provider-borne protocol fee |
|
|
329
330
|
| `settled_provider_receivable_minor` | Provider receivable that is settled on-chain |
|
|
330
331
|
| `unsettled_provider_receivable_minor` | Provider receivable not yet settled |
|
|
331
332
|
| `past_due_provider_receivable_minor` | Provider receivable blocked on past-due settlement |
|
|
332
|
-
| `gross_buyer_debit_minor` |
|
|
333
|
+
| `gross_buyer_debit_minor` | Legacy alias of provider gross; protocol fee is not added |
|
|
333
334
|
| `protocol_fee_minor` | Micro / Nano protocol fee deducted from provider receivable |
|
|
334
|
-
| `buyer_debit_minor` | Amount scheduled for the buyer debit |
|
|
335
|
+
| `buyer_debit_minor` | Amount scheduled for the buyer debit; equals provider gross |
|
|
335
336
|
| `attempt_count`, `next_attempt_at` | Retry state |
|
|
336
337
|
| `failure_reason_code`, `failure_reason_label`, `failure_reason_help` | Sanitized public failure reason |
|
|
337
338
|
| `support_reference` | Non-secret support reference |
|
|
@@ -350,14 +351,14 @@ curl https://siglume.com/v1/sdrp/metered/provider/settlement-batches/<batch-id>/
|
|
|
350
351
|
The CSV contains exactly these columns:
|
|
351
352
|
|
|
352
353
|
```text
|
|
353
|
-
metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end,listing_id,capability_key,operation_key,currency,token_symbol,provider_usage_amount_minor,provider_receivable_minor,protocol_fee_minor,gross_buyer_debit_minor,rounding_delta_minor,buyer_debit_minor,status,settlement_batch_id,buyer_period_ref
|
|
354
|
+
metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end,listing_id,capability_key,operation_key,currency,token_symbol,provider_gross_amount_minor,provider_usage_amount_minor,provider_receivable_minor,protocol_fee_minor,gross_buyer_debit_minor,rounding_delta_minor,buyer_debit_minor,status,settlement_batch_id,buyer_period_ref
|
|
354
355
|
```
|
|
355
356
|
|
|
356
357
|
The CSV uses `buyer_period_ref`, not `buyer_user_id`.
|
|
357
358
|
`rounding_delta_minor` is present for a stable usage-event schema, but per-row
|
|
358
|
-
values are `0`.
|
|
359
|
-
|
|
360
|
-
|
|
359
|
+
values are `0`. If a batch-level `rounding_delta_minor` appears in historical or
|
|
360
|
+
internal records, do not add it to buyer debit and do not allocate it to provider
|
|
361
|
+
revenue.
|
|
361
362
|
|
|
362
363
|
## Notifications
|
|
363
364
|
|
package/docs/pricing.md
CHANGED
|
@@ -151,8 +151,8 @@ confirmed payment turns into money in your settlement wallet.
|
|
|
151
151
|
the affected batch is treated as past due. Siglume currently retries every 6
|
|
152
152
|
hours for up to 28 automatic attempts. After that, the batch remains past due
|
|
153
153
|
and requires manual resolution before another attempt.
|
|
154
|
-
- While the same buyer / provider / token has total unsettled
|
|
155
|
-
above the fixed threshold, new Micro/Nano usage is paused with the
|
|
154
|
+
- While the same buyer / provider / token / pricing band has total unsettled
|
|
155
|
+
exposure at or above the fixed threshold, new Micro/Nano usage is paused with the
|
|
156
156
|
machine-readable error `METERED_SETTLEMENT_PAST_DUE`; the provider API is not
|
|
157
157
|
called. Exposure includes open usage plus `notice_pending`, `ready`,
|
|
158
158
|
`submitted`, retrying, and `past_due` batches, and remains paused while
|
|
@@ -167,7 +167,7 @@ confirmed payment turns into money in your settlement wallet.
|
|
|
167
167
|
|
|
168
168
|
Micro and Nano run a budget check before the buyer's paid request is fulfilled:
|
|
169
169
|
|
|
170
|
-
- A buyer's wallet budget reservation is consumed at the **gross
|
|
170
|
+
- A buyer's wallet budget reservation is consumed at the **provider gross
|
|
171
171
|
amount** (your usage price, before any provider-borne protocol fee) from
|
|
172
172
|
acceptance until settlement confirms. This
|
|
173
173
|
is a reservation against Siglume spending limits; it does not lock, escrow,
|
|
@@ -185,51 +185,43 @@ Micro and Nano run a budget check before the buyer's paid request is fulfilled:
|
|
|
185
185
|
### What is fixed vs platform-managed
|
|
186
186
|
|
|
187
187
|
The cadence fields are fixed: **Micro is weekly, Nano is monthly**. In both
|
|
188
|
-
bands, Siglume can close a buyer/
|
|
189
|
-
10,000 or USD 100.00.
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
188
|
+
bands, Siglume can close a buyer / provider / token / pricing-band batch early
|
|
189
|
+
once provider gross reaches JPY 10,000 or USD 100.00. These are fixed
|
|
190
|
+
market-specific thresholds, not FX conversions of one another. A payment is
|
|
191
|
+
final only after its on-chain settlement confirms. Micro and Nano are automatic
|
|
192
|
+
amount bands, not customer-selected options. The account-assigned period
|
|
193
|
+
boundaries, roughly 3-day pre-debit notice window, early settlement threshold,
|
|
194
|
+
and current retry policy above are the public behavior as of 2026-06-19. Treat
|
|
195
|
+
the platform's statement status, `not_before_attempt_at`, Standard `fee_bps`,
|
|
196
|
+
and Micro / Nano statement amount fields as authoritative rather than
|
|
197
|
+
hard-coding local revenue recognition.
|
|
198
|
+
|
|
199
|
+
## Micro / Nano Seller-borne Amounts
|
|
198
200
|
|
|
199
201
|
Micro / Nano fees are stored internally as decimal minor-unit values so
|
|
200
|
-
sub-yen and sub-cent Nano fees are not silently rounded per accepted SDRP Tx.
|
|
201
|
-
|
|
202
|
+
sub-yen and sub-cent Nano fees are not silently rounded per accepted SDRP Tx.
|
|
203
|
+
The buyer is charged only the provider-visible usage amount; the protocol fee is
|
|
204
|
+
not added to the buyer debit:
|
|
202
205
|
|
|
203
206
|
```text
|
|
204
|
-
|
|
207
|
+
provider_gross_amount_minor = sum(provider price minor units for accepted metered rows)
|
|
208
|
+
provider_usage_amount_minor = provider_gross_amount_minor # legacy alias
|
|
209
|
+
gross_buyer_debit_minor = provider_gross_amount_minor # legacy alias
|
|
210
|
+
buyer_debit_minor = provider_gross_amount_minor
|
|
205
211
|
protocol_fee_minor = sum(Micro/Nano fixed protocol fee minor units for accepted metered rows)
|
|
206
|
-
provider_receivable_minor =
|
|
207
|
-
|
|
208
|
-
buyer_debit_minor = ceil(gross_buyer_debit_minor)
|
|
209
|
-
rounding_delta_minor = buyer_debit_minor - gross_buyer_debit_minor
|
|
212
|
+
provider_receivable_minor = provider_gross_amount_minor - protocol_fee_minor
|
|
213
|
+
rounding_delta_minor = 0 for buyer/provider accounting
|
|
210
214
|
```
|
|
211
215
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
revenue
|
|
221
|
-
`provider_receivable_minor`, `settled_provider_receivable_minor`,
|
|
222
|
-
`unsettled_provider_receivable_minor`, and
|
|
223
|
-
`past_due_provider_receivable_minor`, not with `buyer_debit_minor`.
|
|
224
|
-
|
|
225
|
-
For low-count Nano batches, the integer ceiling can make the effective buyer
|
|
226
|
-
rounded debit per SDRP Tx higher than the decimal provider usage amount. The
|
|
227
|
-
decimal protocol fee remains visible as `protocol_fee_minor` and is deducted
|
|
228
|
-
from provider receivable; the difference created by integer-token settlement is
|
|
229
|
-
visible as `rounding_delta_minor` on the batch. Each settlement batch can add a
|
|
230
|
-
positive rounding adjustment of less than 1 token minor unit. If a buyer uses
|
|
231
|
-
many providers / payees in one period, that adjustment can occur once per
|
|
232
|
-
settlement batch. JavaScript integrations should not sum Micro / Nano minor
|
|
216
|
+
Example: a JPY 100 Micro usage event has buyer debit JPY 100, protocol fee JPY
|
|
217
|
+
2, and provider receivable JPY 98.
|
|
218
|
+
|
|
219
|
+
The `rounding_delta_minor` field is retained in some schemas for compatibility.
|
|
220
|
+
It is not added to `buyer_debit_minor`, not added to
|
|
221
|
+
`provider_gross_amount_minor`, and not deducted again from
|
|
222
|
+
`provider_receivable_minor`. If non-zero in a historical or internal record,
|
|
223
|
+
treat it as a Siglume platform accounting adjustment, not buyer debit or
|
|
224
|
+
provider revenue. JavaScript integrations should not sum Micro / Nano minor
|
|
233
225
|
amounts with `number`; use a decimal library. Python integrations should use
|
|
234
226
|
`Decimal`.
|
|
235
227
|
|