Economicopayments.process
Record an existing payment and its evidenced provider processing fee, with gross/net reconciliation. Does not process or initiate a payment; fee taxes and cross-currency fees are unsupported.
What it does
Records a payment and its evidenced processor fee that already occurred; does not process or initiate a payment. Atomically record an independent payment and its priced provider service fee, with explicit gross/net reconciliation. Net is measured in the primary payment direction and can be negative if an incoming payment costs more to process than its gross amount. The account names its provider agreement; rail selects the service right. Evidence proves processing usage; ordinary right evaluation bills and recognizes the fee, then payments settle it separately.
Use the same idempotency key to retry. feeFacts carries integer facts the processor reported for this payment that its price declares, such as an international or converted amount for a card surcharge; grossAmount always comes from the payment. Provider fee taxes and cross-currency fees are not yet supported.
Before you send it
An authorized OAuth connection may call it, including a headless client. Effective membership, application grant and token permissions still apply. Describe payments.process through GET /v1/catalog/commands/{name} before acting.
This command does not accept source_document_id in its envelope. Any input evidence requirements remain as documented below.
Inputs
Put these fields inside the envelope’s input object. The outer envelope names the command, a stable idempotency_key and effective_at; request and recovery rules explain those separately. Use exact minor-unit integer strings for monetary fields. Take existing IDs from prior reads or command results; choose a new identity only where the command asks for one.
Required means required within its containing object; an optional parent can be omitted.
| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
payment | object | Yes | |
payment.exchangeRate | object | No | An evidenced exchange rate (1 base = numerator/denominator quote), e.g. from a bank statement. It overrides the shared rate store for this command; omit it to use the store. |
payment.exchangeRate.base | string | Yes | Pattern: "^[A-Z]{3}$". |
payment.exchangeRate.quote | string | Yes | Pattern: "^[A-Z]{3}$". |
payment.exchangeRate.date | string | Yes | Format: date. |
payment.exchangeRate.numerator | string | Yes | Pattern: "^[1-9][0-9]*$". |
payment.exchangeRate.denominator | string | Yes | Pattern: "^[1-9][0-9]*$". |
payment.exchangeRate.evidence | array | Yes | Items: object. Minimum items: 1. |
payment.exchangeRate.evidence[].kind | string | Yes | Choose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other". |
payment.exchangeRate.evidence[].ref | string | Yes | Minimum length: 1. |
payment.exchangeRate.evidence[].signer | string | No | |
payment.refundsFundingClaim | object | No | |
payment.refundsFundingClaim.claimId | string | Yes | Minimum length: 1. |
payment.refundsFundingClaim.component | object | Yes | |
payment.refundsFundingClaim.component.originLedgerId | string | Yes | Minimum length: 1. |
payment.refundsFundingClaim.component.accountCode | integer | Yes | |
payment.financialAccountId | string | Yes | Minimum length: 1. |
payment.direction | string | Yes | Choose "in", "out". |
payment.amount | string | Yes | Pattern: "^[1-9][0-9]*$". |
payment.currency | string | Yes | ISO currency, or a CAIP-19 token for a company-owned wallet; amount is in that unit’s exact minor units. Minimum length: 1. |
payment.partyId | string | Yes | Minimum length: 1. |
payment.effectiveAt | string | Yes | Format: date-time. |
payment.sourceFactId | string | Yes | Minimum length: 1. |
payment.evidence | array | Yes | Items: object. Minimum items: 1. |
payment.evidence[].kind | string | Yes | Choose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other". |
payment.evidence[].ref | string | Yes | Minimum length: 1. |
payment.evidence[].signer | string | No | Minimum length: 1. |
payment.allocations | array | Yes | Items: object. Minimum items: 0. Maximum items: 100. |
payment.allocations[].claimId | string | Yes | Minimum length: 1. |
payment.allocations[].amount | string | Yes | Pattern: "^[1-9][0-9]*$". |
payment.allocations[].cashAmount | string | No | Pattern: "^[1-9][0-9]*$". |
payment.allocations[].component | object | Yes | |
payment.allocations[].component.originLedgerId | string | Yes | Minimum length: 1. |
payment.allocations[].component.accountCode | integer | Yes | |
rail | string | Yes | Choose "ach", "ach_same_day", "fedwire", "rtp", "sepa", "sepa_instant", "swift", "onchain", "internal", "card". |
netAmount | string | Yes | Pattern: "^(0|-?[1-9][0-9]*)$". |
feeFacts | object | No | |
evidence | array | Yes | Items: object. Minimum items: 1. Maximum items: 20. |
evidence[].kind | string | Yes | Choose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other". |
evidence[].ref | string | Yes | Minimum length: 1. |
evidence[].signer | string | No | Minimum length: 1. |
After acceptance
When the command emits events, its documented effects and receipt are recorded in the command transaction. The response returns commandId, replayed, the command-specific result below and emitted events with their IDs and CIDs. A command is not automatically a cash movement or revenue recognition: use the behavior above to determine what this command records.
Inspect result and the affected records or reports before continuing. Save returned identifiers for later calls. Fetch GET /v1/commands/{id} with commandId to recover the accepted receipt; retry the same intent with the same idempotency key if the response was lost. Some commands can succeed with events: [] and return a transient result and commandId without persisting a receipt. A lookup of that ID can return null; retain the returned result and verify the affected record. Retrying can re-evaluate the current state rather than replay a stored result. A domain no_change is a separate success outcome with no persisted receipt.
Result fields
Required means required within its containing object; an optional parent can be omitted.
| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
payment | object | Yes | |
grossAmount | string | Yes | |
netAmount | string | Yes | |
fee | object | Yes |
All commands · Operation and errors · Reusable schemas
Keep credentials out of prompts; rehearse writes only in a disposable sandbox.
Exact request schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"const": "payments.process"
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"payment",
"rail",
"netAmount",
"evidence"
],
"properties": {
"payment": {
"type": "object",
"additionalProperties": false,
"required": [
"financialAccountId",
"direction",
"amount",
"currency",
"partyId",
"effectiveAt",
"sourceFactId",
"evidence",
"allocations"
],
"properties": {
"exchangeRate": {
"type": "object",
"additionalProperties": false,
"required": [
"base",
"quote",
"date",
"numerator",
"denominator",
"evidence"
],
"description": "An evidenced exchange rate (1 base = numerator/denominator quote), e.g. from a bank statement. It overrides the shared rate store for this command; omit it to use the store.",
"properties": {
"base": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quote": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"date": {
"type": "string",
"format": "date"
},
"numerator": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"denominator": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"evidence": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string"
}
}
}
}
}
},
"refundsFundingClaim": {
"type": "object",
"additionalProperties": false,
"properties": {
"claimId": {
"type": "string",
"minLength": 1
},
"component": {
"type": "object",
"additionalProperties": false,
"required": [
"originLedgerId",
"accountCode"
],
"properties": {
"originLedgerId": {
"type": "string",
"minLength": 1
},
"accountCode": {
"type": "integer"
}
}
}
},
"required": [
"claimId",
"component"
]
},
"financialAccountId": {
"type": "string",
"minLength": 1
},
"direction": {
"enum": [
"in",
"out"
]
},
"amount": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"currency": {
"type": "string",
"minLength": 1,
"description": "ISO currency, or a CAIP-19 token for a company-owned wallet; amount is in that unit's exact minor units."
},
"partyId": {
"type": "string",
"minLength": 1
},
"effectiveAt": {
"type": "string",
"format": "date-time"
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"evidence": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
},
"required": [
"kind",
"ref"
],
"additionalProperties": false
}
},
"allocations": {
"type": "array",
"minItems": 0,
"maxItems": 100,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"claimId",
"component",
"amount"
],
"properties": {
"claimId": {
"type": "string",
"minLength": 1
},
"amount": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"cashAmount": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"component": {
"type": "object",
"additionalProperties": false,
"required": [
"originLedgerId",
"accountCode"
],
"properties": {
"originLedgerId": {
"type": "string",
"minLength": 1
},
"accountCode": {
"type": "integer"
}
}
}
}
}
}
}
},
"rail": {
"enum": [
"ach",
"ach_same_day",
"fedwire",
"rtp",
"sepa",
"sepa_instant",
"swift",
"onchain",
"internal",
"card"
]
},
"netAmount": {
"type": "string",
"pattern": "^(0|-?[1-9][0-9]*)$"
},
"feeFacts": {
"type": "object",
"maxProperties": 20,
"additionalProperties": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
}
},
"evidence": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"required": [
"kind",
"ref"
],
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
}
}
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"effective_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"required": [
"name",
"input",
"idempotency_key",
"effective_at"
],
"additionalProperties": false
}Accepted command receipt
{
"type": "object",
"required": [
"commandId",
"replayed",
"result",
"events"
],
"properties": {
"commandId": {
"type": "string"
},
"replayed": {
"type": "boolean"
},
"imported": {
"const": true,
"description": "The command's events are history from before the business joined Economico, recorded as an import: free of monthly events."
},
"result": {
"type": "object",
"required": [
"payment",
"grossAmount",
"netAmount",
"fee"
],
"properties": {
"payment": {
"type": "object"
},
"grossAmount": {
"type": "string"
},
"netAmount": {
"type": "string"
},
"fee": {
"type": "object"
}
}
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"cid": {
"type": "string"
}
}
}
}
}
}