Skip to content

Gateway Receipt v1

Source schema: doc/schemas/gateway-receipt.v1.schema.json

Machine-readable schema for a signed fiat-to-credit or credit-to-fiat crossing performed by a trusted prepaid gateway node. The signed surface uses orbiplex-gateway-receipt-v1\x00 || deterministic_cbor(payload_without_signature).

Governing Basis

Project Lineage

Requirements

Stories

Fields

Field Required Shape Description
schema/v yes const: 1 Schema version.
receipt/id yes string Stable identifier of the gateway receipt.
gateway/node-id yes string Trusted gateway node that performed the external settlement crossing.
direction yes enum: inbound, outbound Direction of value crossing the protocol boundary. inbound credits a local account, outbound debits it for payout.
external/amount yes number Gross amount observed on the external payment rail before any explicit ingress fee is applied.
external/currency yes string External settlement currency or tender symbol.
internal/amount yes integer Net amount credited or debited to account/id in internal minor units. For ORC, the value uses ORC minor units with fixed scale 2.
internal/currency yes const: ORC Internal settlement unit used by the supervised ledger in MVP. ORC uses fixed decimal scale 2.
account/id yes string Local supervised account affected by the gateway event.
ts yes string Timestamp when the gateway event was committed for audit.
external/payment-ref yes string Gateway-side payment reference such as a PSP transaction id or bank transfer reference.
gateway-policy/ref yes string Gateway policy under which this boundary crossing was executed.
fee/external-amount no number Explicit fee amount deducted from the gross external amount.
fee/rate no number Fee rate applied to the gross external amount.
fee/destination-account-id no string Ledger account that received the internal fee portion, typically the community-pool.
net/external-amount no number External amount remaining after explicit fee deduction.
rate/applied no number Applied conversion rate from one external unit into internal minor units. For ORC, one unit of this rate equals one ORC minor unit at fixed scale 2.
internal/fee-amount no integer Internal minor-unit amount credited to the fee destination account. For ORC, the value uses ORC minor units with fixed scale 2.
external/provider no string Payment service provider or banking rail label used by the gateway.
exchange-policy/ref no string Optional reference to the gateway-side pricing or exchange policy in force for this event.
notes no string Optional human-readable notes.
signature yes ref: #/$defs/signature Gateway node signature over the receipt payload.
policy_annotations no object

Definitions

Definition Shape Description
signature object

Conditional Rules

Rule 1

When:

{
  "properties": {
    "direction": {
      "const": "inbound"
    }
  },
  "required": [
    "direction"
  ]
}

Then:

{
  "required": [
    "fee/external-amount",
    "fee/rate",
    "fee/destination-account-id",
    "net/external-amount",
    "rate/applied",
    "internal/fee-amount"
  ]
}

Rule 2

When:

{
  "properties": {
    "direction": {
      "const": "outbound"
    }
  },
  "required": [
    "direction"
  ]
}

Then:

{
  "required": [
    "gateway-policy/ref"
  ]
}

Field Semantics

schema/v

  • Required: yes
  • Shape: const: 1

Schema version.

receipt/id

  • Required: yes
  • Shape: string

Stable identifier of the gateway receipt.

gateway/node-id

  • Required: yes
  • Shape: string

Trusted gateway node that performed the external settlement crossing.

direction

  • Required: yes
  • Shape: enum: inbound, outbound

Direction of value crossing the protocol boundary. inbound credits a local account, outbound debits it for payout.

external/amount

  • Required: yes
  • Shape: number

Gross amount observed on the external payment rail before any explicit ingress fee is applied.

external/currency

  • Required: yes
  • Shape: string

External settlement currency or tender symbol.

internal/amount

  • Required: yes
  • Shape: integer

Net amount credited or debited to account/id in internal minor units. For ORC, the value uses ORC minor units with fixed scale 2.

internal/currency

  • Required: yes
  • Shape: const: ORC

Internal settlement unit used by the supervised ledger in MVP. ORC uses fixed decimal scale 2.

account/id

  • Required: yes
  • Shape: string

Local supervised account affected by the gateway event.

ts

  • Required: yes
  • Shape: string

Timestamp when the gateway event was committed for audit.

external/payment-ref

  • Required: yes
  • Shape: string

Gateway-side payment reference such as a PSP transaction id or bank transfer reference.

gateway-policy/ref

  • Required: yes
  • Shape: string

Gateway policy under which this boundary crossing was executed.

fee/external-amount

  • Required: no
  • Shape: number

Explicit fee amount deducted from the gross external amount.

fee/rate

  • Required: no
  • Shape: number

Fee rate applied to the gross external amount.

fee/destination-account-id

  • Required: no
  • Shape: string

Ledger account that received the internal fee portion, typically the community-pool.

net/external-amount

  • Required: no
  • Shape: number

External amount remaining after explicit fee deduction.

rate/applied

  • Required: no
  • Shape: number

Applied conversion rate from one external unit into internal minor units. For ORC, one unit of this rate equals one ORC minor unit at fixed scale 2.

internal/fee-amount

  • Required: no
  • Shape: integer

Internal minor-unit amount credited to the fee destination account. For ORC, the value uses ORC minor units with fixed scale 2.

external/provider

  • Required: no
  • Shape: string

Payment service provider or banking rail label used by the gateway.

exchange-policy/ref

  • Required: no
  • Shape: string

Optional reference to the gateway-side pricing or exchange policy in force for this event.

notes

  • Required: no
  • Shape: string

Optional human-readable notes.

signature

  • Required: yes
  • Shape: ref: #/$defs/signature

Gateway node signature over the receipt payload.

policy_annotations

  • Required: no
  • Shape: object

Definition Semantics

$defs.signature

  • Shape: object