880 lines
34 KiB
YAML
880 lines
34 KiB
YAML
components:
|
|
schemas:
|
|
Asset:
|
|
description: Blockchain asset identifier used for on-chain transfers.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
chain:
|
|
description: Chain/network where the asset exists.
|
|
$ref: ../../external/chain_network.yaml#/components/schemas/ChainNetwork
|
|
token_symbol:
|
|
description: Symbol of the token on the selected chain.
|
|
type: string
|
|
contract_address:
|
|
description: Smart-contract address for tokenized assets.
|
|
type: string
|
|
|
|
ExternalChainAsset:
|
|
description: Blockchain asset identifier used for external-chain endpoints. `token_symbol` is required by current quote/initiate logic; `chain` remains optional.
|
|
required:
|
|
- token_symbol
|
|
allOf:
|
|
- $ref: ./payment.yaml#/components/schemas/Asset
|
|
|
|
LedgerEndpoint:
|
|
description: |
|
|
Internal ledger-based endpoint used as payment source or destination.
|
|
Current request handling accepts exactly one of `account_ref` or `account_code`.
|
|
`ledger_account_ref` is accepted as a legacy alias for `account_ref`.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
account_ref:
|
|
description: Reference of the primary ledger account.
|
|
type: string
|
|
ledger_account_ref:
|
|
description: Legacy alias for `account_ref`.
|
|
deprecated: true
|
|
type: string
|
|
account_code:
|
|
description: Account code of the primary ledger account.
|
|
type: string
|
|
contra_account_ref:
|
|
description: Optional contra ledger account reference for balancing entries.
|
|
type: string
|
|
contra_account_code:
|
|
description: Optional contra ledger account code for balancing entries.
|
|
type: string
|
|
|
|
PaymentMethodEndpoint:
|
|
description: Stored payment method selector. Sent with endpoint type `paymentMethod` and `data.ref`.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- ref
|
|
properties:
|
|
ref:
|
|
description: Stored payment method reference.
|
|
type: string
|
|
|
|
AccountEndpoint:
|
|
description: Account-owned main payment method selector. Sent with endpoint type `account` and `data.ref`.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- ref
|
|
properties:
|
|
ref:
|
|
description: Account reference whose main payment method should be used.
|
|
type: string
|
|
|
|
RecipientEndpoint:
|
|
description: Recipient-owned main payment method selector. Sent with endpoint type `recipient` and `data.ref`.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- ref
|
|
properties:
|
|
ref:
|
|
description: Recipient reference whose main payment method should be used.
|
|
type: string
|
|
|
|
ManagedWalletEndpoint:
|
|
description: Endpoint referencing a managed wallet within the platform.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- ref
|
|
properties:
|
|
ref:
|
|
description: Reference of the managed wallet.
|
|
type: string
|
|
asset:
|
|
description: Asset details for the managed wallet transfer.
|
|
$ref: ./payment.yaml#/components/schemas/Asset
|
|
|
|
ExternalChainEndpoint:
|
|
description: Endpoint representing an external blockchain address.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- asset
|
|
- address
|
|
properties:
|
|
asset:
|
|
description: Asset to be transferred to or from the external address.
|
|
$ref: ./payment.yaml#/components/schemas/ExternalChainAsset
|
|
address:
|
|
description: Target blockchain address.
|
|
type: string
|
|
memo:
|
|
description: Optional destination memo or tag required by some chains.
|
|
type: string
|
|
|
|
CardEndpoint:
|
|
description: |
|
|
Raw card payout endpoint.
|
|
Current quotation logic only requires `pan`; `exp_month` and `exp_year` are accepted but optional while pricing.
|
|
Raw-card payment execution requires `pan`, `exp_month`, and `exp_year`.
|
|
That execution rule also applies when a payment is later created from `quoteRef`, because the quoted endpoint snapshot is reused.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- pan
|
|
properties:
|
|
pan:
|
|
description: Primary account number of the card. Required for both quotation and raw-card payment execution.
|
|
type: string
|
|
firstName:
|
|
description: Optional cardholder first name hint. Current quote and execution logic do not require it.
|
|
type: string
|
|
lastName:
|
|
description: Optional cardholder last name hint. Current quote and execution logic do not require it.
|
|
type: string
|
|
exp_month:
|
|
description: Card expiration month. Optional for quotation, but required for raw-card payment execution, including payments executed later from `quoteRef`.
|
|
type: integer
|
|
format: int32
|
|
minimum: 0
|
|
exp_year:
|
|
description: Card expiration year. Optional for quotation, but required for raw-card payment execution, including payments executed later from `quoteRef`.
|
|
type: integer
|
|
format: int32
|
|
minimum: 0
|
|
country:
|
|
description: Optional card country hint. Current quote and execution logic do not require it.
|
|
type: string
|
|
|
|
CardTokenEndpoint:
|
|
description: |
|
|
Tokenized card payout endpoint used instead of raw PAN details.
|
|
Current quotation and payment-execution logic require only `token`.
|
|
`masked_pan` remains optional and is mainly used for display, auditing, and provider-specific context.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- token
|
|
properties:
|
|
token:
|
|
description: Provider-issued card token. Required for both quotation and tokenized-card payment execution.
|
|
type: string
|
|
masked_pan:
|
|
description: Optional masked PAN representation for display and auditing. Current quote and execution logic do not require it.
|
|
type: string
|
|
|
|
BankAccountEndpoint:
|
|
description: |
|
|
Russian domestic bank-account payout endpoint.
|
|
The recipient name is grouped under `recipient` with `first_name`
|
|
and `last_name`.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- recipient
|
|
- kpp
|
|
- bankName
|
|
- bik
|
|
- accountNumber
|
|
- correspondentAccount
|
|
properties:
|
|
recipient:
|
|
description: Legal recipient name for the bank-account payout.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- first_name
|
|
- last_name
|
|
properties:
|
|
first_name:
|
|
description: Recipient first name.
|
|
type: string
|
|
last_name:
|
|
description: Recipient last name.
|
|
type: string
|
|
inn:
|
|
description: Optional Russian INN tax identifier for the recipient. If present, it must be valid. Bank payout execution uses this value before falling back to the customer or saved owner tax identifier.
|
|
type: string
|
|
kpp:
|
|
description: Russian KPP tax registration reason code.
|
|
type: string
|
|
bankName:
|
|
description: Recipient bank name.
|
|
type: string
|
|
bik:
|
|
description: 9-digit Russian bank identification code.
|
|
type: string
|
|
accountNumber:
|
|
description: 20-digit Russian bank account number.
|
|
type: string
|
|
correspondentAccount:
|
|
description: 20-digit correspondent account number.
|
|
type: string
|
|
example:
|
|
recipient:
|
|
first_name: Ivan
|
|
last_name: Ivanov
|
|
inn: '7707083893'
|
|
kpp: '770701001'
|
|
bankName: Test Bank
|
|
bik: '044525225'
|
|
accountNumber: '40702810900000000001'
|
|
correspondentAccount: '30101810400000000225'
|
|
|
|
IBANEndpoint:
|
|
description: International bank-account payout endpoint.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- iban
|
|
- accountHolder
|
|
properties:
|
|
iban:
|
|
type: string
|
|
accountHolder:
|
|
type: string
|
|
bic:
|
|
type: string
|
|
bankName:
|
|
type: string
|
|
|
|
Endpoint:
|
|
description: |
|
|
Polymorphic payment endpoint definition. Every endpoint is expressed with the same
|
|
`type` plus `data` shape. Stored references are typed endpoints too: a stored payment
|
|
method uses `type: paymentMethod`, a recipient main method uses `type: recipient`, and
|
|
an account main method uses `type: account`, each with a `ref` inside `data`.
|
|
Flat top-level selector fields (`paymentMethodRef`, `recipientRef`, `accountRef`) are
|
|
not accepted; the request handler rejects them.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- type
|
|
- data
|
|
properties:
|
|
type:
|
|
description: Endpoint type determining the shape of the `data` field.
|
|
$ref: ../../external/endpoint_type.yaml#/components/schemas/EndpointType
|
|
data:
|
|
description: Endpoint payload corresponding to the selected endpoint type. For raw `card` payloads, `pan` is always required and expiry becomes required once the intent is executed.
|
|
anyOf:
|
|
- $ref: ./payment.yaml#/components/schemas/PaymentMethodEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/AccountEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/RecipientEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/LedgerEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/ManagedWalletEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/ExternalChainEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/CardEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/CardTokenEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/BankAccountEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/IBANEndpoint
|
|
metadata:
|
|
description: Optional key-value metadata attached to the endpoint.
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
|
|
PaymentResponseEndpoint:
|
|
description: |
|
|
Endpoint snapshot attached to a persisted payment. Uses the same `type` plus `data`
|
|
shape as request endpoints. Stored-reference snapshots are emitted as typed endpoints
|
|
(`paymentMethod`, `account`, or `recipient`) with a `ref` inside `data`.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- type
|
|
- data
|
|
properties:
|
|
type:
|
|
description: Endpoint type for the endpoint snapshot.
|
|
$ref: ../../external/endpoint_type.yaml#/components/schemas/EndpointType
|
|
data:
|
|
description: Endpoint payload snapshot; shape depends on `type`.
|
|
anyOf:
|
|
- $ref: ./payment.yaml#/components/schemas/PaymentMethodEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/AccountEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/RecipientEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/LedgerEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/ManagedWalletEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/ExternalChainEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/CardEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/CardTokenEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/BankAccountEndpoint
|
|
- $ref: ./payment.yaml#/components/schemas/IBANEndpoint
|
|
|
|
Customer:
|
|
description: Customer identity and address attributes for compliance and routing.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
id:
|
|
description: External or internal customer identifier.
|
|
type: string
|
|
first_name:
|
|
description: Customer first name.
|
|
type: string
|
|
middle_name:
|
|
description: Customer middle name.
|
|
type: string
|
|
last_name:
|
|
description: Customer last name.
|
|
type: string
|
|
ip:
|
|
description: Source IP address associated with the payment request.
|
|
type: string
|
|
zip:
|
|
description: Postal or ZIP code.
|
|
type: string
|
|
country:
|
|
description: Country code of customer residence or billing address.
|
|
type: string
|
|
state:
|
|
description: State or region.
|
|
type: string
|
|
city:
|
|
description: City name.
|
|
type: string
|
|
address:
|
|
description: Street address line.
|
|
type: string
|
|
tax_identifier:
|
|
description: Customer tax identifier. Russian bank-account payouts interpret this value as INN.
|
|
type: string
|
|
|
|
CurrencyPair:
|
|
description: Foreign-exchange currency pair.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- base
|
|
- quote
|
|
properties:
|
|
base:
|
|
description: Base currency code.
|
|
type: string
|
|
quote:
|
|
description: Quote currency code.
|
|
type: string
|
|
|
|
FxIntent:
|
|
description: FX execution preferences associated with a payment.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- pair
|
|
- side
|
|
properties:
|
|
pair:
|
|
description: Currency pair for FX conversion.
|
|
$ref: ./payment.yaml#/components/schemas/CurrencyPair
|
|
side:
|
|
description: Side of the FX trade intent.
|
|
$ref: ../../external/fx_side.yaml#/components/schemas/FxSide
|
|
firm:
|
|
description: Whether a firm quote is required.
|
|
type: boolean
|
|
ttl_ms:
|
|
description: Desired quote time-to-live in milliseconds.
|
|
type: integer
|
|
format: int64
|
|
preferred_provider:
|
|
description: Preferred FX liquidity provider identifier.
|
|
type: string
|
|
max_age_ms:
|
|
description: Maximum accepted quote age in milliseconds.
|
|
type: integer
|
|
format: int32
|
|
|
|
PaymentIntent:
|
|
description: Requested payment execution parameters before processing. For raw `card` destinations, quotation accepts missing expiry but payment execution requires `exp_month` and `exp_year`.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- kind
|
|
- source
|
|
- destination
|
|
- amount
|
|
properties:
|
|
kind:
|
|
description: High-level payment kind that drives orchestration behavior.
|
|
$ref: ../../external/payment_kind.yaml#/components/schemas/PaymentKind
|
|
source:
|
|
description: Source endpoint from which funds are debited.
|
|
$ref: ./payment.yaml#/components/schemas/Endpoint
|
|
destination:
|
|
description: Destination endpoint to which funds are credited. If `type=card`, `exp_month` and `exp_year` are optional while quoting but required when the payment is executed.
|
|
$ref: ./payment.yaml#/components/schemas/Endpoint
|
|
amount:
|
|
description: Requested payment amount.
|
|
$ref: ../common/money.yaml#/components/schemas/Money
|
|
fx:
|
|
description: Optional FX preferences when conversion is needed.
|
|
$ref: ./payment.yaml#/components/schemas/FxIntent
|
|
settlement_mode:
|
|
description: Settlement strategy for the transfer.
|
|
$ref: ../../external/settlement_mode.yaml#/components/schemas/SettlementMode
|
|
fee_treatment:
|
|
description: How fees should be applied to source/destination amounts.
|
|
type: string
|
|
enum:
|
|
- unspecified
|
|
- add_to_source
|
|
- deduct_from_destination
|
|
attributes:
|
|
description: Additional key-value attributes used by downstream processors.
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
comment:
|
|
description: Optional free-form comment attached to the payment intent.
|
|
type: string
|
|
customer:
|
|
description: Optional customer information attached to the payment intent.
|
|
$ref: ./payment.yaml#/components/schemas/Customer
|
|
|
|
FeeLine:
|
|
description: Single fee component included in a payment quote.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
ledgerAccountRef:
|
|
description: Ledger account reference receiving or charging this fee.
|
|
type: string
|
|
amount:
|
|
description: Monetary amount of the fee line.
|
|
$ref: ../common/money.yaml#/components/schemas/Money
|
|
lineType:
|
|
description: Fee line classification.
|
|
type: string
|
|
side:
|
|
description: Indicates whether the fee applies on debit or credit side.
|
|
type: string
|
|
meta:
|
|
description: Optional metadata for fee calculation traceability.
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
|
|
QuoteFees:
|
|
description: Collection of fee lines for a quoted payment.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
lines:
|
|
description: List of individual quoted fee lines.
|
|
type: array
|
|
items:
|
|
$ref: ./payment.yaml#/components/schemas/FeeLine
|
|
|
|
QuoteAmounts:
|
|
description: Amount breakdown returned with a payment quote.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
sourcePrincipal:
|
|
description: Principal amount debited from the source before fees.
|
|
$ref: ../common/money.yaml#/components/schemas/Money
|
|
sourceDebitTotal:
|
|
description: Total amount debited from the source including adjustments.
|
|
$ref: ../common/money.yaml#/components/schemas/Money
|
|
destinationSettlement:
|
|
description: Net amount expected to settle at the destination.
|
|
$ref: ../common/money.yaml#/components/schemas/Money
|
|
|
|
FxQuote:
|
|
description: FX quote details used to price converted payment amounts.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
quoteRef:
|
|
description: Identifier of the FX quote.
|
|
type: string
|
|
baseCurrency:
|
|
description: Base currency of the quote pair.
|
|
type: string
|
|
quoteCurrency:
|
|
description: Quote currency of the quote pair.
|
|
type: string
|
|
side:
|
|
description: FX side used for pricing.
|
|
type: string
|
|
price:
|
|
description: Quoted FX price as a decimal string.
|
|
type: string
|
|
baseAmount:
|
|
description: Base currency amount covered by this quote.
|
|
$ref: ../common/money.yaml#/components/schemas/Money
|
|
quoteAmount:
|
|
description: Quote currency amount corresponding to the base amount.
|
|
$ref: ../common/money.yaml#/components/schemas/Money
|
|
expiresAtUnixMs:
|
|
description: Quote expiration timestamp in Unix milliseconds.
|
|
type: integer
|
|
format: int64
|
|
pricedAtUnixMs:
|
|
description: Quote pricing timestamp in Unix milliseconds.
|
|
type: integer
|
|
format: int64
|
|
provider:
|
|
description: Provider that supplied the FX quote.
|
|
type: string
|
|
rateRef:
|
|
description: Provider-specific rate reference identifier.
|
|
type: string
|
|
firm:
|
|
description: Indicates whether the FX quote is firm.
|
|
type: boolean
|
|
|
|
FxRateCalculation:
|
|
description: Exchange-rate calculation used by an FX quote.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- requestedPair
|
|
- requestedSide
|
|
- pathKind
|
|
- marketRate
|
|
- effectiveRate
|
|
- overrideScope
|
|
- specialRateApplied
|
|
- legs
|
|
properties:
|
|
requestedPair:
|
|
description: Requested currency pair for the FX quote.
|
|
$ref: ./payment.yaml#/components/schemas/CurrencyPair
|
|
requestedSide:
|
|
description: FX side interpreted against the requested pair.
|
|
$ref: ../../external/fx_side.yaml#/components/schemas/FxSide
|
|
pathKind:
|
|
description: Whether the applied rate was obtained from a direct pair or a cross-rate path.
|
|
type: string
|
|
enum:
|
|
- direct
|
|
- cross
|
|
marketRate:
|
|
description: Market-path rate before quote-level overrides, as a decimal string.
|
|
type: string
|
|
effectiveRate:
|
|
description: Final rate applied to the quote after leg-level or whole-rate overrides, as a decimal string.
|
|
type: string
|
|
overrideScope:
|
|
description: Location of the rate override. `none` means no special rate was applied.
|
|
type: string
|
|
enum:
|
|
- none
|
|
- leg
|
|
- total
|
|
specialRateApplied:
|
|
description: Derived convenience flag equal to `overrideScope != none`.
|
|
type: boolean
|
|
overrideRef:
|
|
description: Opaque support/audit reference for whole-rate overrides. Clients must not parse it.
|
|
type: string
|
|
asOfUnixMs:
|
|
description: Calculation/path decision timestamp in Unix milliseconds.
|
|
type: integer
|
|
format: int64
|
|
legs:
|
|
description: Resolved market path legs used to obtain the rate.
|
|
type: array
|
|
items:
|
|
$ref: ./payment.yaml#/components/schemas/FxRateCalculationLeg
|
|
|
|
FxRateCalculationLeg:
|
|
description: One market-path leg used in an FX quote rate calculation.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- pair
|
|
- sourcePair
|
|
- invertedFromSource
|
|
- marketRate
|
|
- effectiveRate
|
|
- overrideApplied
|
|
properties:
|
|
pair:
|
|
description: Oriented pair multiplied in path order.
|
|
$ref: ./payment.yaml#/components/schemas/CurrencyPair
|
|
sourcePair:
|
|
description: Stored/provider pair before orientation adjustments.
|
|
$ref: ./payment.yaml#/components/schemas/CurrencyPair
|
|
invertedFromSource:
|
|
description: Whether the source pair was inverted to produce this oriented leg.
|
|
type: boolean
|
|
marketRate:
|
|
description: Market executable rate for this leg, as a decimal string.
|
|
type: string
|
|
effectiveRate:
|
|
description: Effective rate for this leg after leg-level override, as a decimal string.
|
|
type: string
|
|
provider:
|
|
description: Rate provider identifier.
|
|
type: string
|
|
rateRef:
|
|
description: Opaque support/audit reference for the source rate. Clients must not parse it.
|
|
type: string
|
|
asOfUnixMs:
|
|
description: Source rate timestamp for this leg in Unix milliseconds.
|
|
type: integer
|
|
format: int64
|
|
overrideApplied:
|
|
description: Whether a leg-level override was applied to this leg.
|
|
type: boolean
|
|
overrideRef:
|
|
description: Opaque support/audit reference for the leg-level override. Clients must not parse it.
|
|
type: string
|
|
|
|
SpecialRateInfo:
|
|
description: Indicates whether quotation pricing policy applied a non-market FX rate to the quote.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- applied
|
|
properties:
|
|
applied:
|
|
description: Derived from `fxRateCalculation.overrideScope != none` when `fxRateCalculation` is present.
|
|
type: boolean
|
|
|
|
PaymentQuote:
|
|
description: Pricing result for a specific payment intent.
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- executable
|
|
- state
|
|
properties:
|
|
quoteRef:
|
|
description: Unique identifier of the payment quote.
|
|
type: string
|
|
intentRef:
|
|
description: Reference to the payment intent used for quoting.
|
|
type: string
|
|
state:
|
|
description: Backend quotation execution state. `executable` means the quote can be submitted for execution. `blocked`, `indicative`, `expired`, and `unspecified` must not be executed as-is.
|
|
type: string
|
|
enum:
|
|
- unspecified
|
|
- indicative
|
|
- executable
|
|
- blocked
|
|
- expired
|
|
executable:
|
|
description: Explicit execution flag. `false` means the quote must not be sent to `/payments/by-quote` or `/payments/by-multiquote`.
|
|
type: boolean
|
|
blockReason:
|
|
description: Reason the quote is not executable when `state` is `blocked`. Omitted for executable, indicative, and expired quotes.
|
|
type: string
|
|
enum:
|
|
- route_unavailable
|
|
- limit_blocked
|
|
- risk_blocked
|
|
- insufficient_liquidity
|
|
- price_stale
|
|
- amount_too_small
|
|
- amount_too_large
|
|
amounts:
|
|
description: Amount breakdown for source and destination values.
|
|
$ref: ./payment.yaml#/components/schemas/QuoteAmounts
|
|
fees:
|
|
description: Fee breakdown included in the quote.
|
|
$ref: ./payment.yaml#/components/schemas/QuoteFees
|
|
fxQuote:
|
|
description: Associated FX quote when conversion is part of the payment.
|
|
$ref: ./payment.yaml#/components/schemas/FxQuote
|
|
fxRateCalculation:
|
|
description: Explanation of how the FX quote rate was obtained.
|
|
$ref: ./payment.yaml#/components/schemas/FxRateCalculation
|
|
specialRate:
|
|
description: Indicates whether quotation pricing policy applied a special FX rate while pricing this quote.
|
|
$ref: ./payment.yaml#/components/schemas/SpecialRateInfo
|
|
|
|
PaymentFailureCode:
|
|
description: |
|
|
Broad machine-readable category for a payment or operation that reports a failure
|
|
condition. This field is a public category, not the orchestration service's
|
|
canonical failure code. A card payout terminated after a definitive AML denial
|
|
uses `failure_restriction`; its canonical orchestration code is `card.aml_denied`.
|
|
|
|
The enumeration is closed and safe to use for failure handling after checking the
|
|
payment state. The state remains the lifecycle authority: `failure_restriction`
|
|
can accompany non-terminal `needs_attention` while manual review or additional
|
|
checks are pending. `failure_policy` is reserved and is not currently returned by
|
|
the API; policy blocks are reported as `failure_restriction`.
|
|
|
|
The published cause-to-category-to-reason list is at
|
|
https://app.sendico.io/docs/en/payment-failures/
|
|
type: string
|
|
enum:
|
|
- failure_unspecified
|
|
- failure_balance
|
|
- failure_ledger
|
|
- failure_fx
|
|
- failure_chain
|
|
- failure_fees
|
|
- failure_policy
|
|
- failure_validation
|
|
- failure_restriction
|
|
example: failure_restriction
|
|
|
|
PaymentFailureReason:
|
|
description: |
|
|
Stable lowercase machine-readable reason token intended for client handling. A
|
|
card payout terminated after a definitive AML denial uses `aml_denied`. Detailed
|
|
AML evidence, including the matched blacklist reason, and raw gateway, provider,
|
|
or RPC messages are not exposed here.
|
|
|
|
Unlike `failureCode`, this token set is open: compliance policy reason codes and
|
|
provider-derived reasons can add values without a contract change. Treat unknown
|
|
tokens as the category-level failure and keep a fallback message.
|
|
|
|
Default reasons per category: `insufficient_funds`; `ledger_operation_failed`,
|
|
`ledger_operation_cancelled`, `ledger_access_violation`,
|
|
`ledger_validation_failed`; `fee_fx_conversion_failed`; `fee_posting_failed`;
|
|
`gateway_execution_failed`, `gateway_execution_rejected`, `gateway_execution_cancelled`,
|
|
`gateway_transfer_failed`, `gateway_transfer_cancelled`, `card_payout_failed`,
|
|
`card_payout_cancelled`, `provider_declined`, `provider_limit`,
|
|
`provider_unavailable`, `provider_status_unknown`, `provider_unknown`,
|
|
`velocity_limit_exceeded`, `limits_rejected`; `validation_failed`,
|
|
`quote_precision_identity_missing`, `quote_precision_asset_identity_mismatch`,
|
|
`quote_precision_asset_scale_missing`, `quote_precision_amount_scale_exceeded`,
|
|
`card_validation_failed`, `card_scheme_unsupported`, `card_expired`,
|
|
`amount_below_minimum`, `amount_above_maximum`, `duplicate_transaction`,
|
|
`currency_unsupported`; `card_scheme_disabled`, `aml_denied`, `policy_blocked`,
|
|
`review_required`, `more_checks_required`, `risk_restricted`,
|
|
`operation_restricted`, `card_product_unsupported`; `assessment_failed`;
|
|
`failure_unspecified` for an unclassified cause.
|
|
|
|
Additional currently known override reasons are `do_not_honor`, `invalid_card`,
|
|
`invalid_card_number`, `invalid_cardholder_name`, `cardholder_name_mismatch`,
|
|
`card_details_invalid`, `card_expiry_required`, `invalid_amount`,
|
|
`provider_cancelled`, `disabled_card_scheme`,
|
|
`unsupported_gateway_card_scheme`, and `recipient_tax_identifier_required`.
|
|
Structured bank validation can add normalized reasons ending in `_required` or
|
|
`_invalid`; compliance policy reason codes are also an open set.
|
|
|
|
The published cause-to-category-to-reason list, including the additional
|
|
provider, submit-validation, and bank-validation tokens, is at
|
|
https://app.sendico.io/docs/en/payment-failures/
|
|
type: string
|
|
pattern: '^[a-z0-9_]+$'
|
|
example: aml_denied
|
|
|
|
PaymentOperation:
|
|
description: |
|
|
Execution step record captured during payment processing. For a card payout
|
|
terminated by AML screening, `failureCode` is `failure_restriction` and
|
|
`failureReason` is `aml_denied`.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
stepRef:
|
|
description: Identifier of the orchestration step.
|
|
type: string
|
|
code:
|
|
description: Operation code representing the executed action.
|
|
type: string
|
|
state:
|
|
description: Current state of the operation.
|
|
type: string
|
|
label:
|
|
description: Human-readable operation label.
|
|
type: string
|
|
comment:
|
|
description: Optional comment attached to the execution step.
|
|
type: string
|
|
money:
|
|
description: Planned and executed monetary snapshots for the operation.
|
|
$ref: ./payment.yaml#/components/schemas/PaymentOperationMoney
|
|
operationRef:
|
|
description: External operation reference identifier reported by the gateway.
|
|
type: string
|
|
gateway:
|
|
description: Gateway microservice type handling the operation.
|
|
type: string
|
|
failureCode:
|
|
$ref: ./payment.yaml#/components/schemas/PaymentFailureCode
|
|
failureReason:
|
|
$ref: ./payment.yaml#/components/schemas/PaymentFailureReason
|
|
startedAt:
|
|
description: RFC 3339 timestamp when execution of the operation started.
|
|
type: string
|
|
format: date-time
|
|
completedAt:
|
|
description: RFC 3339 timestamp when execution of the operation completed.
|
|
type: string
|
|
format: date-time
|
|
|
|
PaymentOperationMoney:
|
|
description: Planned and executed monetary snapshots associated with the operation.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
planned:
|
|
description: Monetary values planned for the operation before execution.
|
|
$ref: ./payment.yaml#/components/schemas/PaymentOperationMoneySnapshot
|
|
executed:
|
|
description: Monetary values observed after the operation was executed.
|
|
$ref: ./payment.yaml#/components/schemas/PaymentOperationMoneySnapshot
|
|
|
|
PaymentOperationMoneySnapshot:
|
|
description: Monetary snapshot containing base and converted amounts for an operation state.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
amount:
|
|
description: Primary money amount associated with the operation snapshot.
|
|
$ref: ../common/money.yaml#/components/schemas/Money
|
|
convertedAmount:
|
|
description: Secondary amount for conversion operations in the same snapshot.
|
|
$ref: ../common/money.yaml#/components/schemas/Money
|
|
|
|
Payment:
|
|
description: |
|
|
Persisted payment aggregate with status, quote, and operation history. A definitive
|
|
card-payout AML denial terminates the payment in the failed state and is reported as
|
|
`failureCode: failure_restriction` with `failureReason: aml_denied` at both payment
|
|
and failed-operation level.
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
paymentRef:
|
|
description: Unique payment reference identifier.
|
|
type: string
|
|
state:
|
|
description: Current lifecycle state of the payment.
|
|
$ref: ../../external/payment_state.yaml#/components/schemas/PaymentState
|
|
comment:
|
|
description: Optional comment copied from the original payment intent.
|
|
type: string
|
|
source:
|
|
description: Source endpoint snapshot captured from intent.
|
|
$ref: ./payment.yaml#/components/schemas/PaymentResponseEndpoint
|
|
destination:
|
|
description: Destination endpoint snapshot captured from intent.
|
|
$ref: ./payment.yaml#/components/schemas/PaymentResponseEndpoint
|
|
failureCode:
|
|
$ref: ./payment.yaml#/components/schemas/PaymentFailureCode
|
|
failureReason:
|
|
$ref: ./payment.yaml#/components/schemas/PaymentFailureReason
|
|
operations:
|
|
description: Chronological list of operations executed for this payment.
|
|
type: array
|
|
items:
|
|
$ref: ./payment.yaml#/components/schemas/PaymentOperation
|
|
lastQuote:
|
|
description: Most recent payment quote used or generated for the payment.
|
|
$ref: ./payment.yaml#/components/schemas/PaymentQuote
|
|
createdAt:
|
|
description: RFC 3339 timestamp when the payment was created.
|
|
type: string
|
|
format: date-time
|
|
completedAt:
|
|
description: RFC 3339 timestamp when the payment reached a terminal state. Omitted while the payment is still in progress.
|
|
type: string
|
|
format: date-time
|
|
meta:
|
|
description: Additional metadata captured for the payment.
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|