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

3
interface/models/account/account.yaml
View File

@@ -1,12 +1,15 @@
components:
schemas:
AccountData:
description: Extended account payload including visibility-specific metadata.
allOf:
- $ref: ./account_public.yaml#/components/schemas/AccountPublic
- type: object
description: Account attributes that are not part of the public profile.
additionalProperties: false
required:
- isAnonymous
properties:
isAnonymous:
description: Indicates whether the account is marked as anonymous.
type: boolean

7
interface/models/account/account_public.yaml
View File

@@ -1,10 +1,12 @@
components:
schemas:
AccountPublic:
description: Public account profile data exposed in API responses.
allOf:
- $ref: ../storable.yaml#/components/schemas/Storable
- $ref: ../common/describable.yaml#/components/schemas/Describable
- type: object
description: Account-specific public attributes.
additionalProperties: false
required:
- login
@@ -13,14 +15,19 @@ components:
- isArchived
properties:
login:
description: Account login identifier represented as an email address.
type: string
format: email
locale:
description: Preferred locale used for account-facing content.
type: string
lastName:
description: Account holder last name.
type: string
avatarUrl:
description: Optional URL of the account avatar image.
type: string
nullable: true
isArchived:
description: Indicates whether the account is archived and inactive.
type: boolean

3
interface/models/auth/client_refresh_token.yaml
View File

@@ -1,12 +1,15 @@
components:
schemas:
ClientRefreshToken:
description: Refresh token bound to a specific client and device session.
allOf:
- $ref: ./session_identifier.yaml#/components/schemas/SessionIdentifier
- type: object
description: Refresh-token payload associated with the session identifier.
additionalProperties: false
required:
- token
properties:
token:
description: Long-lived token used to obtain a new access token.
type: string

4
interface/models/auth/login_data.yaml
View File

@@ -1,6 +1,7 @@
components:
schemas:
LoginData:
description: Credentials and optional locale used during user sign-in.
type: object
additionalProperties: false
required:
@@ -8,10 +9,13 @@ components:
- password
properties:
login:
description: User login identifier, represented as an email address.
type: string
format: email
password:
description: User password submitted for authentication.
type: string
format: password
locale:
description: Optional locale preference provided at login time.
type: string

3
interface/models/auth/session_identifier.yaml
View File

@@ -1,6 +1,7 @@
components:
schemas:
SessionIdentifier:
description: Identifies an authentication session by client and device.
type: object
additionalProperties: false
required:
@@ -8,6 +9,8 @@ components:
- deviceId
properties:
clientId:
description: Client application identifier associated with the session.
type: string
deviceId:
description: Device/server identifier associated with the client session.
type: string

3
interface/models/auth/token_data.yaml
View File

@@ -1,6 +1,7 @@
components:
schemas:
TokenData:
description: Authentication token payload with expiration metadata.
type: object
additionalProperties: false
required:
@@ -8,7 +9,9 @@ components:
- expiration
properties:
token:
description: Issued authentication token value.
type: string
expiration:
description: RFC 3339 timestamp when the token expires.
type: string
format: date-time

54
interface/models/callback/callback.yaml
View File

@@ -1,67 +1,89 @@
components:
schemas:
CallbackRetryPolicy:
CallbackBackoff:
description: Backoff window used between callback retry attempts.
type: object
additionalProperties: false
required:
- minDelayMs
- maxDelayMs
properties:
minDelayMs:
description: Minimum delay in milliseconds before scheduling a retry attempt.
type: integer
minimum: 1
maxDelayMs:
description: Maximum delay in milliseconds before scheduling a retry attempt.
type: integer
minimum: 1
CallbackRetryPolicy:
description: Retry and delivery behavior for callback requests.
type: object
additionalProperties: false
required:
- backoff
- signingMode
- maxAttempts
- requestTimeoutMs
properties:
minDelayMs:
type: integer
minimum: 1
maxDelayMs:
type: integer
minimum: 1
backoff:
description: Delay boundaries used to compute retry backoff between attempts.
$ref: '#/components/schemas/CallbackBackoff'
signingMode:
description: Request-signing strategy applied when dispatching callback payloads.
type: string
enum:
- none
- hmac_sha256
secretRef:
type: string
nullable: true
headers:
description: Additional HTTP headers included with every callback request.
type: object
additionalProperties:
type: string
maxAttempts:
description: Maximum number of delivery attempts before marking dispatch as failed.
type: integer
minimum: 1
requestTimeoutMs:
description: Per-request timeout in milliseconds for callback HTTP calls.
type: integer
minimum: 1
Callback:
CallbackContent:
description: Callback endpoint configuration and delivery parameters.
allOf:
- $ref: ../permission_bound.yaml#/components/schemas/PermissionBound
- $ref: ../common/describable.yaml#/components/schemas/Describable
- type: object
additionalProperties: false
required:
- clientId
- status
- url
- eventTypes
- retryPolicy
properties:
clientId:
type: string
status:
description: Operational state controlling whether callback delivery is enabled.
type: string
enum:
- active
- disabled
url:
description: Absolute HTTPS endpoint URL that receives callback events.
type: string
format: uri
eventTypes:
description: Event type names that trigger callback delivery to this endpoint.
type: array
items:
type: string
retryPolicy:
description: Retry and timeout parameters used when dispatching callback events.
$ref: '#/components/schemas/CallbackRetryPolicy'
Callback:
description: Stored callback configuration bound to an organization permission scope.
allOf:
- $ref: ../permission_bound.yaml#/components/schemas/PermissionBound
- $ref: ../common/describable.yaml#/components/schemas/Describable
- $ref: '#/components/schemas/CallbackContent'

3
interface/models/common/describable.yaml
View File

@@ -1,13 +1,16 @@
components:
schemas:
Describable:
description: Common naming metadata for user-defined entities.
type: object
additionalProperties: false
required:
- name
properties:
name:
description: Human-readable name of the entity.
type: string
description:
description: Optional free-form description of the entity.
type: string
nullable: true

2
interface/models/common/money.yaml
View File

@@ -1,6 +1,7 @@
components:
schemas:
Money:
description: Monetary value represented by a decimal amount and ISO currency code.
type: object
additionalProperties: false
required:
@@ -12,5 +13,6 @@ components:
description: Decimal string amount.
example: '125.50'
currency:
description: ISO 4217 currency code for the provided amount.
type: string
example: USD

2
interface/models/common/pagination.yaml
View File

@@ -1,8 +1,10 @@
components:
schemas:
CursorPageResponse:
description: Cursor-based pagination metadata returned with list responses.
type: object
additionalProperties: false
properties:
next_cursor:
description: Opaque cursor to request the next page; omitted when no more items exist.
type: string

2
interface/models/objectid.yaml
View File

@@ -1,7 +1,9 @@
components:
schemas:
ObjectId:
description: Object identifier represented as a 24-character hexadecimal string.
type: string
format: objectid
pattern: '^[a-fA-F0-9]{24}$'
examples:
- 64f85f5f4c7dbf7cfb8f3f10

3
interface/models/organization/organization.yaml
View File

@@ -7,11 +7,8 @@ components:
- type: object
additionalProperties: false
required:
- tenantRef
- timeZone
properties:
tenantRef:
$ref: ../objectid.yaml#/components/schemas/ObjectId
timeZone:
type: string
logoUrl:

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

5
interface/models/permission_bound.yaml
View File

@@ -1,9 +1,11 @@
components:
schemas:
PermissionBound:
description: Association between an organization and a permission, including archival state.
allOf:
- $ref: ./storable.yaml#/components/schemas/Storable
- type: object
description: Permission binding details scoped to an organization.
additionalProperties: false
required:
- organizationRef
@@ -11,8 +13,11 @@ components:
- isArchived
properties:
organizationRef:
description: Identifier of the organization that owns this permission binding.
$ref: ./objectid.yaml#/components/schemas/ObjectId
permissionRef:
description: Identifier of the permission granted to the organization.
$ref: ./objectid.yaml#/components/schemas/ObjectId
isArchived:
description: Indicates whether this object is archived and inactive.
type: boolean

4
interface/models/storable.yaml
View File

@@ -1,6 +1,7 @@
components:
schemas:
Storable:
description: Common persistence metadata included on stored entities.
type: object
additionalProperties: false
required:
@@ -9,10 +10,13 @@ components:
- updatedAt
properties:
id:
description: Unique identifier assigned to the stored entity.
$ref: ./objectid.yaml#/components/schemas/ObjectId
createdAt:
description: RFC 3339 timestamp indicating when the entity was created.
type: string
format: date-time
updatedAt:
description: RFC 3339 timestamp indicating the most recent entity update.
type: string
format: date-time