payment

The payment noun — identity, lifecycle, events, and every capability as an anchored section: 18 capabilities, 0 live, 18 sandbox, 0 declared.

payment is one of the estate's 317 automotive nouns — a job a car needs done. It carries 18 capabilities: 0 live, 18 sandbox, 0 declared · doors payments.vin · aggregator.vin.

Identity


Noun	`payment`
Pillar	Commerce (facets: 2 data · 4 services · 12 commerce)
Capabilities	18 — 0 live · 18 sandbox · 0 declared
Entities	`Payment`
Doors	`aggregator.vin` · `payments.vin`
SDK	`Vin.payment.*` from `apis.vin`
Address	`/catalog/payment#{action}` — the anchor IS the wire name minus `payment.`

Payment — PaymentFSM: 7 states, 7 transitions — Initiated · Authorized · Settled · Split · Refunded · ChargedBack · Reconciled. Each transition is a past-tense event on the record.

Events

The vocabulary this noun can append to the record — 23 past-tense, versioned event types, each linked to the capability that emits it:

Fee.assessed@1 — emitted by chargeback
Ledger.posted@1 — emitted by settle
Payment.achOriginated@1 — emitted by ach
Payment.authorized@1 — emitted by authorize · settle
Payment.captured@1 — emitted by capture
Payment.chargedBack@1 — emitted by chargeback
Payment.checkProcessed@1 — emitted by check
Payment.deposited@1 — emitted by rdc
Payment.disputeEvidenced@1 — emitted by disputeEvidence
Payment.failed@1 — emitted by ach · authorize · capture · chargeback · check · nsf · rdc · refund · settle · wire
Payment.nsfFlagged@1 — emitted by chargeback
Payment.nsfHandled@1 — emitted by nsf
Payment.paid@1 — emitted by settle
Payment.rdcCaptured@1 — emitted by rdc
Payment.receiptIssued@1 — emitted by receipt
Payment.reconciled@1 — emitted by reconcile
Payment.refunded@1 — emitted by refund · settle
Payment.represented@1 — emitted by representment
Payment.settled@1 — emitted by rdc · settle
Payment.split@1 — emitted by split
Payment.wired@1 — emitted by wire
PaymentMethod.tokenized@1 — emitted by tokenize
Payout.remitted@1 — emitted by settle

Discover & read

check

payment.check · POST /payments/check · gate offer · sandbox · answers PaymentCheck@1

Field	Type	Required	Notes
`vin`	`string`	no	—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

Emits — Payment.checkProcessed@1 · Payment.failed@1.

the SDK — payment.check

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.check({"vin":"JM1NDAD7XR0604689"})

POST /payments/check

curl -X POST https://apis.vin/payments/check \
  -H 'content-type: application/json' \
  -d '{"vin":"JM1NDAD7XR0604689"}'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-17T12:42:15.097Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentCheck@1",
  "value": {
    "method": "check",
    "settlement": {
      "$type": "Settlement",
      "$id": "settlement_pi_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "amount": {
        "amount": "50000",
        "currency": "USD"
      },
      "status": "settled",
      "payeeRef": "payee-sandbox",
      "settledAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "pi_1"
      },
      "ledgerRef": "ledgerentry_pi_1"
    }
  },
  "evidence": {
    "method": "check",
    "settlement": {
      "$type": "Settlement",
      "$id": "settlement_pi_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "amount": {
        "amount": "50000",
        "currency": "USD"
      },
      "status": "settled",
      "payeeRef": "payee-sandbox",
      "settledAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "pi_1"
      },
      "ledgerRef": "ledgerentry_pi_1"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "settlement-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

Quote & price

fee

payment.fee · GET /payments/fee · gate key · sandbox · answers PaymentFee@1

Field	Type	Required	Notes
`vin`	`string`	no	—

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

the SDK — payment.fee

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.fee({"vin":"JM1NDAD7XR0604689"})

GET /payments/fee

curl 'https://apis.vin/payments/fee?vin=JM1NDAD7XR0604689'

receipt · executed 2026-08-17T12:42:15.097Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentFee@1",
  "value": {
    "method": "card",
    "amount": {
      "amount": "500.00",
      "currency": "USD"
    },
    "fee": {
      "amount": "14.80",
      "currency": "USD"
    },
    "net": {
      "amount": "485.20",
      "currency": "USD"
    }
  },
  "evidence": {
    "method": "card",
    "amount": {
      "amount": "500.00",
      "currency": "USD"
    },
    "fee": {
      "amount": "14.80",
      "currency": "USD"
    },
    "net": {
      "amount": "485.20",
      "currency": "USD"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "settlement-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

Pay & settle

capture

payment.capture · POST /payments/capture · gate offer · sandbox · answers PaymentCapture@1

Field	Type	Required	Notes
`vin`	`string`	no	—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Payment.captured@1 · Payment.failed@1.

the SDK — payment.capture

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.capture({"vin":"JM1NDAD7XR0604689"})

POST /payments/capture

curl -X POST https://apis.vin/payments/capture \
  -H 'content-type: application/json' \
  -d '{"vin":"JM1NDAD7XR0604689"}'

receipt · executed 2026-08-17T12:42:15.097Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentCapture@1",
  "value": {
    "settlement": {
      "$type": "Settlement",
      "$id": "settlement_pi_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "amount": {
        "amount": "50000",
        "currency": "USD"
      },
      "status": "settled",
      "payeeRef": "payee-sandbox",
      "settledAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "pi_1"
      },
      "ledgerRef": "ledgerentry_pi_1"
    }
  },
  "evidence": {
    "settlement": {
      "$type": "Settlement",
      "$id": "settlement_pi_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "amount": {
        "amount": "50000",
        "currency": "USD"
      },
      "status": "settled",
      "payeeRef": "payee-sandbox",
      "settledAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "pi_1"
      },
      "ledgerRef": "ledgerentry_pi_1"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "settlement-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

settle

payment.settle · POST /payments/settle · gate offer · sandbox · answers Payment@1

Field	Type	Required	Notes
`amount_total`	`integer`	yes	THE ONE integer-cents exception (kept). All other estate money is decimal strings.
`method`	`string`	no	one of `ach`, `card`, `wire`, `check`, `rdc`
`subject`	`string`	no	—
`payTo`	`string`	no	abstract payee ref
`authority`	`string`	no	—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Delegated calls require a typed Mandate — { ceiling, perAction, expires, tripwires }; the ceiling is a field, not a conversation.

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Ledger.posted@1 · Payment.authorized@1 · Payment.failed@1 · Payment.paid@1 · Payment.refunded@1 · Payment.settled@1 · Payout.remitted@1.

the SDK — payment.settle

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.settle({"amount_total":0})

POST /payments/settle

curl -X POST https://apis.vin/payments/settle \
  -H 'content-type: application/json' \
  -d '{"amount_total":0}'

receipt · executed 2026-08-16T14:50:09.963Z · HTTP 200

{
  "type": "OK",
  "answers": "Payment@1",
  "value": {
    "vin": "1HGCM82633A004352",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    },
    "payer": {
      "name": "Ava Good",
      "castRow": "super-prime",
      "creditTier": "super-prime"
    }
  },
  "evidence": {
    "vin": "1HGCM82633A004352",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    },
    "payer": {
      "name": "Ava Good",
      "castRow": "super-prime",
      "creditTier": "super-prime"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "cashier-window-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

reconcile

payment.reconcile · POST /payments/reconcile · gate offer · sandbox · answers PaymentReconcile@1

Field	Type	Required	Notes
`vin`	`string`	no	—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Payment.reconciled@1.

the SDK — payment.reconcile

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.reconcile({"vin":"JM1NDAD7XR0604689"})

POST /payments/reconcile

curl -X POST https://apis.vin/payments/reconcile \
  -H 'content-type: application/json' \
  -d '{"vin":"JM1NDAD7XR0604689"}'

receipt · executed 2026-08-17T12:42:15.098Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentReconcile@1",
  "value": {
    "intentRef": "intent_1",
    "ledger": [
      {
        "$id": "ledgerentry_pi_1",
        "$type": "LedgerEntry",
        "actionRef": "action_intent_1_pi_1",
        "debits": [
          {
            "accountRef": "settlement-clearing",
            "amount": {
              "amount": "50000",
              "currency": "USD"
            }
          }
        ],
        "credits": [
          {
            "accountRef": "payable:payee-sandbox",
            "amount": {
              "amount": "50000",
              "currency": "USD"
            }
          }
        ],
        "memo": "settlement JM1NDAD7XR0604689",
        "postedAt": "2026-08-10T00:00:00.000Z"
      }
    ]
  },
  "evidence": {
    "intentRef": "intent_1",
    "ledger": [
      {
        "$id": "ledgerentry_pi_1",
        "$type": "LedgerEntry",
        "actionRef": "action_intent_1_pi_1",
        "debits": [
          {
            "accountRef": "settlement-clearing",
            "amount": {
              "amount": "50000",
              "currency": "USD"
            }
          }
        ],
        "credits": [
          {
            "accountRef": "payable:payee-sandbox",
            "amount": {
              "amount": "50000",
              "currency": "USD"
            }
          }
        ],
        "memo": "settlement JM1NDAD7XR0604689",
        "postedAt": "2026-08-10T00:00:00.000Z"
      }
    ]
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "settlement-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

refund

payment.refund · POST /payments/refund · gate offer · sandbox · answers PaymentRefund@1

Field	Type	Required	Notes
`vin`	`string`	no	—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Payment.failed@1 · Payment.refunded@1.

the SDK — payment.refund

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.refund({"vin":"JM1NDAD7XR0604689"})

POST /payments/refund

curl -X POST https://apis.vin/payments/refund \
  -H 'content-type: application/json' \
  -d '{"vin":"JM1NDAD7XR0604689"}'

receipt · executed 2026-08-17T12:42:15.098Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentRefund@1",
  "value": {
    "refund": {
      "$type": "Refund",
      "$id": "refund_re_1",
      "settlementRef": "settlement_pi_1",
      "amount": {
        "amount": "50000",
        "currency": "USD"
      },
      "refundedAt": "2026-08-10T00:00:00.000Z",
      "ledgerRef": "ledgerentry_re_1",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "re_1"
      }
    }
  },
  "evidence": {
    "refund": {
      "$type": "Refund",
      "$id": "refund_re_1",
      "settlementRef": "settlement_pi_1",
      "amount": {
        "amount": "50000",
        "currency": "USD"
      },
      "refundedAt": "2026-08-10T00:00:00.000Z",
      "ledgerRef": "ledgerentry_re_1",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "re_1"
      }
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "settlement-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

chargeback

payment.chargeback · POST /payments/chargeback · gate key · sandbox · answers Chargeback@1

Field	Type	Required	Notes
`subject`	`string`	yes	—
`kind`	`string`	no	one of `chargeback`, `nsf`, `return`
`reasonCode`	`string`	no	—

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Fee.assessed@1 · Payment.chargedBack@1 · Payment.failed@1 · Payment.nsfFlagged@1.

the SDK — payment.chargeback

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.chargeback({"subject":"subject"})

POST /payments/chargeback

curl -X POST https://apis.vin/payments/chargeback \
  -H 'content-type: application/json' \
  -d '{"subject":"subject"}'

receipt · executed 2026-08-16T14:50:09.961Z · HTTP 200

{
  "type": "OK",
  "answers": "Chargeback@1",
  "value": {
    "vin": "1HGCM82633A004352",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    }
  },
  "evidence": {
    "vin": "1HGCM82633A004352",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "cashier-window-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

Fulfill & operate

split

payment.split · POST /payments/split · gate key · sandbox · answers PaymentSplit@1

No input — this capability takes no request body.

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Payment.split@1.

the SDK — payment.split

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.split()

POST /payments/split

curl -X POST https://apis.vin/payments/split \
  -H 'content-type: application/json' \
  -d '{}'

receipt · executed 2026-08-16T14:50:09.963Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentSplit@1",
  "value": {
    "settlement": {
      "$type": "Settlement",
      "$id": "settlement_pi_1",
      "intentRef": "intent_1",
      "reference": "magic-clear",
      "amount": {
        "amount": "100000",
        "currency": "USD"
      },
      "status": "settled",
      "payeeRef": "payee-sandbox",
      "settledAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "pi_1"
      },
      "ledgerRef": "ledgerentry_pi_1"
    },
    "legs": [
      {
        "payeeRef": "payee-sandbox",
        "amount": {
          "amount": "700.00",
          "currency": "USD"
        }
      },
      {
        "payeeRef": "payee-secondary-sandbox",
        "amount": {
          "amount": "300.00",
          "currency": "USD"
        }
      }
    ]
  },
  "evidence": {
    "settlement": {
      "$type": "Settlement",
      "$id": "settlement_pi_1",
      "intentRef": "intent_1",
      "reference": "magic-clear",
      "amount": {
        "amount": "100000",
        "currency": "USD"
      },
      "status": "settled",
      "payeeRef": "payee-sandbox",
      "settledAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "pi_1"
      },
      "ledgerRef": "ledgerentry_pi_1"
    },
    "legs": [
      {
        "payeeRef": "payee-sandbox",
        "amount": {
          "amount": "700.00",
          "currency": "USD"
        }
      },
      {
        "payeeRef": "payee-secondary-sandbox",
        "amount": {
          "amount": "300.00",
          "currency": "USD"
        }
      }
    ]
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "settlement-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

Authorize & resolve

authorize

payment.authorize · POST /payments/authorize · gate offer · sandbox · answers PaymentAuthorize@1

Field	Type	Required	Notes
`vin`	`string`	no	—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Payment.authorized@1 · Payment.failed@1.

the SDK — payment.authorize

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.authorize({"vin":"JM1NDAD7XR0604689"})

POST /payments/authorize

curl -X POST https://apis.vin/payments/authorize \
  -H 'content-type: application/json' \
  -d '{"vin":"JM1NDAD7XR0604689"}'

receipt · executed 2026-08-17T12:42:15.097Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentAuthorize@1",
  "value": {
    "offer": {
      "$type": "X402Offer",
      "status": 402,
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "amount": {
        "amount": "50000",
        "currency": "USD"
      },
      "payTo": "https://checkout.settlement-rail.sandbox/intent_1",
      "expiresAt": "2026-08-10T00:15:00.000Z",
      "accepts": [
        "card",
        "ach"
      ],
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      }
    }
  },
  "evidence": {
    "offer": {
      "$type": "X402Offer",
      "status": 402,
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "amount": {
        "amount": "50000",
        "currency": "USD"
      },
      "payTo": "https://checkout.settlement-rail.sandbox/intent_1",
      "expiresAt": "2026-08-10T00:15:00.000Z",
      "accepts": [
        "card",
        "ach"
      ],
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      }
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "settlement-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

More actions

ach

payment.ach · POST /payments/ach · gate offer · sandbox · answers PaymentAch@1

Field	Type	Required	Notes
`vin`	`string`	no	—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Payment.achOriginated@1 · Payment.failed@1.

the SDK — payment.ach

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.ach({"vin":"JM1NDAD7XR0604689"})

POST /payments/ach

curl -X POST https://apis.vin/payments/ach \
  -H 'content-type: application/json' \
  -d '{"vin":"JM1NDAD7XR0604689"}'

receipt · executed 2026-08-17T12:42:15.097Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentAch@1",
  "value": {
    "checkout": {
      "$type": "CheckoutSession",
      "$id": "checkoutsession_cs_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "url": "https://checkout.settlement-rail.sandbox/cs_1",
      "status": "complete",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "cs_1"
      }
    },
    "settlement": {
      "$type": "Settlement",
      "$id": "settlement_pi_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "amount": {
        "amount": "50000",
        "currency": "USD"
      },
      "status": "settled",
      "payeeRef": "payee-sandbox",
      "settledAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "pi_1"
      },
      "ledgerRef": "ledgerentry_pi_1"
    }
  },
  "evidence": {
    "checkout": {
      "$type": "CheckoutSession",
      "$id": "checkoutsession_cs_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "url": "https://checkout.settlement-rail.sandbox/cs_1",
      "status": "complete",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "cs_1"
      }
    },
    "settlement": {
      "$type": "Settlement",
      "$id": "settlement_pi_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "amount": {
        "amount": "50000",
        "currency": "USD"
      },
      "status": "settled",
      "payeeRef": "payee-sandbox",
      "settledAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "pi_1"
      },
      "ledgerRef": "ledgerentry_pi_1"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "settlement-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

disputeEvidence

payment.disputeEvidence · POST /payments/dispute-evidence · gate key · sandbox · answers PaymentDisputeEvidence@1

No input — this capability takes no request body.

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Payment.disputeEvidenced@1.

the SDK — payment.disputeEvidence

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.disputeEvidence()

POST /payments/dispute-evidence

curl -X POST https://apis.vin/payments/dispute-evidence \
  -H 'content-type: application/json' \
  -d '{}'

receipt · executed 2026-08-16T14:50:09.962Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentDisputeEvidence@1",
  "value": {
    "vin": "1HGCM82633A004352",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    }
  },
  "evidence": {
    "vin": "1HGCM82633A004352",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "cashier-window-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

method

payment.method · GET /payments/method · gate none · sandbox · answers PaymentMethod@1

Field	Type	Required	Notes
`vin`	`string`	no	—

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

the SDK — payment.method

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.method({"vin":"JM1NDAD7XR0604689"})

GET /payments/method

curl 'https://apis.vin/payments/method?vin=JM1NDAD7XR0604689'

receipt · executed 2026-08-17T12:42:15.097Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentMethod@1",
  "value": {
    "methods": [
      "card",
      "ach",
      "wire",
      "check"
    ],
    "default": "card"
  },
  "evidence": {
    "methods": [
      "card",
      "ach",
      "wire",
      "check"
    ],
    "default": "card"
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "settlement-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

nsf

payment.nsf · POST /payments/nsf · gate offer · sandbox · answers PaymentNsf@1

Field	Type	Required	Notes
`vin`	`string`	no	—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Payment.failed@1 · Payment.nsfHandled@1.

the SDK — payment.nsf

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.nsf({"vin":"JM1NDAD7XR0604689"})

POST /payments/nsf

curl -X POST https://apis.vin/payments/nsf \
  -H 'content-type: application/json' \
  -d '{"vin":"JM1NDAD7XR0604689"}'

receipt · executed 2026-08-17T12:42:15.098Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentNsf@1",
  "value": {
    "vin": "JM1NDAD7XR0604689",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    },
    "nsf": {
      "status": "no-axis-posted",
      "basis": "no-world-nsf-axis"
    }
  },
  "evidence": {
    "vin": "JM1NDAD7XR0604689",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    },
    "nsf": {
      "status": "no-axis-posted",
      "basis": "no-world-nsf-axis"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "cashier-window-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

rdc

payment.rdc · POST /payments/rdc · gate offer · sandbox · answers RemoteDeposit@1

Field	Type	Required	Notes
`instrument`	`object`	yes	—
`subject`	`string`	no	—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Delegated calls require a typed Mandate — { ceiling, perAction, expires, tripwires }; the ceiling is a field, not a conversation.

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Payment.deposited@1 · Payment.failed@1 · Payment.rdcCaptured@1 · Payment.settled@1.

the SDK — payment.rdc

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.rdc({"instrument":{}})

POST /payments/rdc

curl -X POST https://apis.vin/payments/rdc \
  -H 'content-type: application/json' \
  -d '{"instrument":{}}'

receipt · executed 2026-08-16T14:50:09.962Z · HTTP 200

{
  "type": "OK",
  "answers": "RemoteDeposit@1",
  "value": {
    "vin": "1HGCM82633A004352",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    },
    "payer": {
      "name": "Ava Good",
      "castRow": "super-prime",
      "creditTier": "super-prime"
    }
  },
  "evidence": {
    "vin": "1HGCM82633A004352",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    },
    "payer": {
      "name": "Ava Good",
      "castRow": "super-prime",
      "creditTier": "super-prime"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "cashier-window-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

receipt

payment.receipt · POST /payments/receipt · gate offer · sandbox · answers PaymentReceipt@1

Field	Type	Required	Notes
`vin`	`string`	no	—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Payment.receiptIssued@1.

the SDK — payment.receipt

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.receipt({"vin":"JM1NDAD7XR0604689"})

POST /payments/receipt

curl -X POST https://apis.vin/payments/receipt \
  -H 'content-type: application/json' \
  -d '{"vin":"JM1NDAD7XR0604689"}'

receipt · executed 2026-08-17T12:42:15.098Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentReceipt@1",
  "value": {
    "receipt": {
      "$type": "Settlement",
      "$id": "settlement_pi_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "amount": {
        "amount": "50000",
        "currency": "USD"
      },
      "status": "settled",
      "payeeRef": "payee-sandbox",
      "settledAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "pi_1"
      },
      "ledgerRef": "ledgerentry_pi_1"
    }
  },
  "evidence": {
    "receipt": {
      "$type": "Settlement",
      "$id": "settlement_pi_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "amount": {
        "amount": "50000",
        "currency": "USD"
      },
      "status": "settled",
      "payeeRef": "payee-sandbox",
      "settledAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "pi_1"
      },
      "ledgerRef": "ledgerentry_pi_1"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "settlement-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

representment

payment.representment · POST /payments/representment · gate key · sandbox · answers PaymentRepresentment@1

No input — this capability takes no request body.

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Payment.represented@1.

the SDK — payment.representment

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.representment()

POST /payments/representment

curl -X POST https://apis.vin/payments/representment \
  -H 'content-type: application/json' \
  -d '{}'

receipt · executed 2026-08-16T14:50:09.963Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentRepresentment@1",
  "value": {
    "vin": "1HGCM82633A004352",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    }
  },
  "evidence": {
    "vin": "1HGCM82633A004352",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "cashier-window-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

tokenize

payment.tokenize · POST /payments/tokenize · gate key · sandbox · answers PaymentMethod@1

Field	Type	Required	Notes
`method`	`string`	yes	one of `ach`, `card`, `wire`
`party`	`string`	no	—

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — PaymentMethod.tokenized@1.

the SDK — payment.tokenize

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.tokenize({"method":"ach"})

POST /payments/tokenize

curl -X POST https://apis.vin/payments/tokenize \
  -H 'content-type: application/json' \
  -d '{"method":"ach"}'

receipt · executed 2026-08-16T14:50:09.963Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentMethod@1",
  "value": {
    "vin": "1HGCM82633A004352",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    },
    "token": {
      "id": "TOK-c7307896",
      "method": "ach",
      "holderId": "ID-11f17424",
      "status": "tokenized"
    },
    "payer": {
      "name": "Ava Good",
      "castRow": "super-prime",
      "creditTier": "super-prime"
    }
  },
  "evidence": {
    "vin": "1HGCM82633A004352",
    "noun": "payment",
    "asOf": "2026-08-10",
    "payment": {
      "status": "no-payment-story-on-file"
    },
    "token": {
      "id": "TOK-c7307896",
      "method": "ach",
      "holderId": "ID-11f17424",
      "status": "tokenized"
    },
    "payer": {
      "name": "Ava Good",
      "castRow": "super-prime",
      "creditTier": "super-prime"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "cashier-window-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

wire

payment.wire · POST /payments/wire · gate offer · sandbox · answers PaymentWire@1

Field	Type	Required	Notes
`vin`	`string`	no	—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — payments.vin serves this noun on its two routes: / (the landing) · /JM1NDAD7XR0604689 (the VIN lens).

Emits — Payment.failed@1 · Payment.wired@1.

the SDK — payment.wire

import { payment } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await payment.wire({"vin":"JM1NDAD7XR0604689"})

POST /payments/wire

curl -X POST https://apis.vin/payments/wire \
  -H 'content-type: application/json' \
  -d '{"vin":"JM1NDAD7XR0604689"}'

receipt · executed 2026-08-17T12:42:15.106Z · HTTP 200

{
  "type": "OK",
  "answers": "PaymentWire@1",
  "value": {
    "checkout": {
      "$type": "CheckoutSession",
      "$id": "checkoutsession_cs_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "url": "https://checkout.settlement-rail.sandbox/cs_1",
      "status": "complete",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "cs_1"
      }
    },
    "settlement": {
      "$type": "Settlement",
      "$id": "settlement_pi_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "amount": {
        "amount": "2500000",
        "currency": "USD"
      },
      "status": "settled",
      "payeeRef": "payee-sandbox",
      "settledAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "pi_1"
      },
      "ledgerRef": "ledgerentry_pi_1"
    }
  },
  "evidence": {
    "checkout": {
      "$type": "CheckoutSession",
      "$id": "checkoutsession_cs_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "url": "https://checkout.settlement-rail.sandbox/cs_1",
      "status": "complete",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "cs_1"
      }
    },
    "settlement": {
      "$type": "Settlement",
      "$id": "settlement_pi_1",
      "intentRef": "intent_1",
      "reference": "JM1NDAD7XR0604689",
      "amount": {
        "amount": "2500000",
        "currency": "USD"
      },
      "status": "settled",
      "payeeRef": "payee-sandbox",
      "settledAt": "2026-08-10T00:00:00.000Z",
      "provenance": {
        "environment": "sandbox",
        "simulated": true,
        "provider": "settlement-rail"
      },
      "providerData": {
        "externalId": "pi_1"
      },
      "ledgerRef": "ledgerentry_pi_1"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "settlement-rail-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

Data model

The record shape behind this noun — one entity, each property an evidence field. See the whole estate model on the data model page.

Schema

Property	Type	Notes
`id`	`id`	pay_
`subjectId`	`ref→Deal\|Invoice`	—
`amountTotal`	`money`	—
`method`	`enum`	ach\|card\|wire\|check\|rdc
`payToId`	`ref→Party`	—
`authority`	`ref→Mandate`	—
`direction`	`enum`	pay\|payout\|refund
`status`	`PaymentFSM`	—
`receipts`	`Receipt[]`	—
`reconciledAt`	`datetime`	—

Relationships

From	To	Cardinality	As
`deal`	`payment`	`1:0..*`	`settled`
`invoice`	`payment`	`1:0..*`	`paid by`
`payment`	`moneyInstrument`	`1:0..1`	`via`

Modeled

The noun drawn out — its record shape, its lifecycle, and how it is exercised end to end. 3 diagrams, rendered from the estate model.

Payment · Class model

Payment · State machine

Payment · Sequence

Generated from the catalog. Every capability, answer, gate, and entity on this page is a rendered descriptor — it cannot drift from the wire.

payment

Identity

Lifecycle

Events

Discover & read

check

Quote & price

fee

Pay & settle

capture

settle

reconcile

refund

chargeback

Fulfill & operate

split

Authorize & resolve

authorize

More actions

ach

disputeEvidence

method

nsf

rdc

receipt

representment

tokenize

wire

Data model

Payment

Modeled

On this page