tech/sendico
2
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects Releases Wiki Activity

Callbacks service docs updated

Browse Source
This commit is contained in:
Stephan D
2026-03-02 16:27:33 +01:00
parent 17e08ff26f
commit 2be76aa519
77 changed files with 803 additions and 764 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
interface/models/payment/payment.yaml
View File

@@ -1,39 +1,50 @@
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
LedgerEndpoint:
description: Internal ledger-based endpoint used as payment source or destination.
type: object
additionalProperties: false
required:
- ledger_account_ref
properties:
ledger_account_ref:
description: Reference of the primary ledger account.
type: string
contra_ledger_account_ref:
description: Optional contra ledger account reference for balancing entries.
type: string
ManagedWalletEndpoint:
description: Endpoint referencing a managed wallet within the platform.
type: object
additionalProperties: false
required:
- managed_wallet_ref
properties:
managed_wallet_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:
@@ -41,56 +52,72 @@ components:
- address
properties:
asset:
description: Asset to be transferred to or from the external address.
$ref: ./payment.yaml#/components/schemas/Asset
address:
description: Target blockchain address.
type: string
memo:
description: Optional destination memo or tag required by some chains.
type: string
CardEndpoint:
description: Raw card details endpoint used for card-based payment flows.
type: object
additionalProperties: false
required:
- pan
properties:
pan:
description: Primary account number of the card.
type: string
firstName:
description: Cardholder first name.
type: string
lastName:
description: Cardholder last name.
type: string
exp_month:
description: Card expiration month.
type: integer
format: int32
minimum: 0
exp_year:
description: Card expiration year.
type: integer
format: int32
minimum: 0
country:
description: Card issuing country code.
type: string
CardTokenEndpoint:
description: Tokenized card endpoint used instead of raw PAN details.
type: object
additionalProperties: false
required:
- token
properties:
token:
description: Provider-issued card token.
type: string
masked_pan:
description: Masked PAN representation for display and auditing.
type: string
WalletEndpoint:
description: Generic wallet endpoint identified by wallet ID.
type: object
additionalProperties: false
required:
- walletId
properties:
walletId:
description: Unique identifier of the wallet.
type: string
Endpoint:
description: Polymorphic payment endpoint definition.
type: object
additionalProperties: false
required:
@@ -98,8 +125,10 @@ components:
- 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.
oneOf:
- $ref: ./payment.yaml#/components/schemas/LedgerEndpoint
- $ref: ./payment.yaml#/components/schemas/ManagedWalletEndpoint
@@ -108,36 +137,49 @@ components:
- $ref: ./payment.yaml#/components/schemas/CardTokenEndpoint
- $ref: ./payment.yaml#/components/schemas/WalletEndpoint
metadata:
description: Optional key-value metadata attached to the endpoint.
type: object
additionalProperties:
type: string
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
CurrencyPair:
description: Foreign-exchange currency pair.
type: object
additionalProperties: false
required:
@@ -145,11 +187,14 @@ components:
- 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:
@@ -157,21 +202,28 @@ components:
- 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.
type: object
additionalProperties: false
required:
@@ -181,160 +233,219 @@ components:
- 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.
$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
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
PaymentQuote:
description: Pricing result for a specific payment intent.
type: object
additionalProperties: false
properties:
quoteRef:
description: Unique identifier of the payment quote.
type: string
intentRef:
description: Reference to the payment intent used for quoting.
type: string
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
PaymentOperation:
description: Execution step record captured during payment processing.
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
failureCode:
description: Machine-readable failure code when operation fails.
type: string
failureReason:
description: Human-readable failure reason when operation fails.
type: string
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
Payment:
description: Persisted payment aggregate with status, quote, and operation history.
type: object
additionalProperties: false
properties:
paymentRef:
description: Unique payment reference identifier.
type: string
idempotencyKey:
description: Idempotency key used to safely deduplicate create requests.
type: string
state:
description: Current lifecycle state of the payment.
$ref: ../../external/payment_state.yaml#/components/schemas/PaymentState
failureCode:
description: Failure code set when the payment cannot be completed.
type: string
failureReason:
description: Human-readable explanation of the failure.
type: string
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
meta:
description: Additional metadata captured for the payment.
type: object
additionalProperties:
type: string