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

2
interface/api.yaml
View File

@@ -89,8 +89,6 @@ paths:
$ref: ./api/payments/quote.yaml
/payments/multiquote/{organizations_ref}:
$ref: ./api/payments/multiquote.yaml
/payments/immediate/{organizations_ref}:
$ref: ./api/payments/immediate.yaml
/payments/by-quote/{organizations_ref}:
$ref: ./api/payments/by_quote.yaml
/payments/by-multiquote/{organizations_ref}:

3
interface/api/accounts/bodies/auth.yaml
View File

@@ -1,12 +1,14 @@
components:
requestBodies:
LoginBody:
description: JSON credentials payload for standard login.
required: true
content:
application/json:
schema:
$ref: ../request/auth.yaml#/components/schemas/LoginRequest
ApiLoginBody:
description: JSON credentials payload for API client login.
required: true
content:
application/json:
@@ -14,6 +16,7 @@ components:
$ref: ../request/auth.yaml#/components/schemas/ApiLoginRequest
RefreshTokenBody:
description: JSON payload containing session and refresh token data.
required: true
content:
application/json:

1
interface/api/accounts/request/auth.yaml
View File

@@ -11,6 +11,7 @@ components:
description: Client identifier bound to refresh token lifecycle and client policy checks.
deviceId:
type: string
description: Device/server identifier associated with the client session.
login:
$ref: ../../../models/auth/login_data.yaml#/components/schemas/LoginData

13
interface/api/accounts/response/auth.yaml
View File

@@ -1,6 +1,7 @@
components:
schemas:
AccountAuthData:
description: Authentication response containing account profile and access token.
type: object
additionalProperties: false
required:
@@ -8,11 +9,14 @@ components:
- account
properties:
accessToken:
description: Access token used for authenticated requests.
$ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
account:
description: Authenticated account data.
$ref: ../../../models/account/account.yaml#/components/schemas/AccountData
LoginData:
description: Full login response including access and refresh tokens.
type: object
additionalProperties: false
required:
@@ -21,13 +25,17 @@ components:
- refreshToken
properties:
accessToken:
description: Access token used for authenticated requests.
$ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
account:
description: Authenticated account data.
$ref: ../../../models/account/account.yaml#/components/schemas/AccountData
refreshToken:
description: Refresh token used to obtain a new access token.
$ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
PendingLoginData:
description: Pending login response requiring additional verification.
type: object
additionalProperties: false
required:
@@ -36,14 +44,19 @@ components:
- target
properties:
account:
description: Interim authentication payload prepared for verification completion.
type: object
additionalProperties: false
properties:
accessToken:
description: Temporary access token issued before verification is completed.
$ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
account:
description: Account data associated with the pending login flow.
$ref: ../../../models/account/account.yaml#/components/schemas/AccountData
pendingToken:
description: Token proving the pending verification session.
$ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
target:
description: Verification target destination (for example email or phone).
type: string

2
interface/api/callbacks/bodies/callback.yaml
View File

@@ -1,9 +1,9 @@
components:
requestBodies:
CallbackBody:
description: JSON body containing callback endpoint configuration.
required: true
content:
application/json:
schema:
$ref: ../request/callback.yaml#/components/schemas/CallbackRequest

4
interface/api/callbacks/request/callback.yaml
View File

@@ -1,5 +1,5 @@
components:
schemas:
CallbackRequest:
$ref: ../../../models/callback/callback.yaml#/components/schemas/Callback
description: Request payload used to create or update a callback configuration.
$ref: ../../../models/callback/callback.yaml#/components/schemas/CallbackContent

5
interface/api/callbacks/response/callback.yaml
View File

@@ -1,6 +1,7 @@
components:
schemas:
CallbacksAuthData:
description: Authenticated response payload containing callback configurations.
type: object
additionalProperties: false
required:
@@ -8,12 +9,14 @@ components:
- callbacks
properties:
accessToken:
description: Refreshed access token to be used in subsequent API calls.
$ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
callbacks:
description: Collection of callbacks configured for the authenticated scope.
type: array
items:
$ref: ../../../models/callback/callback.yaml#/components/schemas/Callback
generatedSigningSecret:
description: Newly generated signing secret when secret rotation is requested.
type: string
nullable: true

2
interface/api/callbacks/rotate_secret.yaml
View File

@@ -1,7 +1,7 @@
post:
tags: [Callbacks]
summary: Rotate callback signing secret
description: Generates and stores a new HMAC secret for the callback in Vault and returns it once.
description: Generates and stores a new HMAC secret for the callback and returns it once.
operationId: callbacksRotateSecret
security:
- bearerAuth: []

3
interface/api/organizations/response/organization.yaml
View File

@@ -1,6 +1,7 @@
components:
schemas:
OrganizationsAuthData:
description: Authenticated response payload containing organizations.
type: object
additionalProperties: false
required:
@@ -8,8 +9,10 @@ components:
- organizations
properties:
accessToken:
description: Refreshed access token to be used in subsequent API calls.
$ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
organizations:
description: Collection of organizations available to the authenticated account.
type: array
items:
$ref: ../../../models/organization/organization.yaml#/components/schemas/Organization

2
interface/api/parameters/callbacks_ref.yaml
View File

@@ -4,7 +4,7 @@ components:
name: callbacks_ref
in: path
required: true
description: Callback subscription reference (Mongo ObjectId, 24 hex chars).
description: Callback subscription reference, 24 hex chars.
schema:
$ref: ../../models/objectid.yaml#/components/schemas/ObjectId

2
interface/api/parameters/org_ref.yaml
View File

@@ -4,6 +4,6 @@ components:
name: org_ref
in: path
required: true
description: Organization reference in BFF route format (Mongo ObjectId, 24 hex chars).
description: Organization reference in BFF route format, 24 hex chars.
schema:
$ref: ../../models/objectid.yaml#/components/schemas/ObjectId

2
interface/api/parameters/payment_methods_ref.yaml
View File

@@ -4,6 +4,6 @@ components:
name: payment_methods_ref
in: path
required: true
description: Payment method reference (Mongo ObjectId, 24 hex chars).
description: Payment method reference, 24 hex chars.
schema:
$ref: ../../models/objectid.yaml#/components/schemas/ObjectId

2
interface/api/parameters/recipients_ref.yaml
View File

@@ -4,6 +4,6 @@ components:
name: recipients_ref
in: path
required: true
description: Recipient reference (Mongo ObjectId, 24 hex chars).
description: Recipient reference, 24 hex chars.
schema:
$ref: ../../models/objectid.yaml#/components/schemas/ObjectId

1
interface/api/payment_methods/bodies/payment_method.yaml
View File

@@ -1,6 +1,7 @@
components:
requestBodies:
PaymentMethodBody:
description: JSON body containing a payment method definition.
required: true
content:
application/json:

1
interface/api/payment_methods/request/payment_method.yaml
View File

@@ -1,4 +1,5 @@
components:
schemas:
PaymentMethodRequest:
description: Request payload used to create or update a payment method.
$ref: ../../../models/payment_method/payment_method.yaml#/components/schemas/PaymentMethod

3
interface/api/payment_methods/response/payment_method.yaml
View File

@@ -1,6 +1,7 @@
components:
schemas:
Payment MethodsAuthData:
description: Authenticated response payload containing payment methods.
type: object
additionalProperties: false
required:
@@ -8,8 +9,10 @@ components:
- payment_methods
properties:
accessToken:
description: Refreshed access token to be used in subsequent API calls.
$ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
payment_methods:
description: Collection of payment methods available to the authenticated account.
type: array
items:
$ref: ../../../models/payment_method/payment_method.yaml#/components/schemas/PaymentMethod

4
interface/api/payments/bodies/payment.yaml
View File

@@ -1,6 +1,7 @@
components:
requestBodies:
QuotePaymentBody:
description: JSON payload used to request a quote for one payment intent.
required: true
content:
application/json:
@@ -8,6 +9,7 @@ components:
$ref: ../request/payment.yaml#/components/schemas/QuotePaymentRequest
QuotePaymentsBody:
description: JSON payload used to request quotes for multiple payment intents.
required: true
content:
application/json:
@@ -15,6 +17,7 @@ components:
$ref: ../request/payment.yaml#/components/schemas/QuotePaymentsRequest
InitiatePaymentBody:
description: JSON payload used to initiate a single payment.
required: true
content:
application/json:
@@ -22,6 +25,7 @@ components:
$ref: ../request/payment.yaml#/components/schemas/InitiatePaymentRequest
InitiatePaymentsBody:
description: JSON payload used to initiate multiple payments from a quote reference.
required: true
content:
application/json:

18
interface/api/payments/request/payment.yaml
View File

@@ -1,33 +1,41 @@
components:
schemas:
PaymentBase:
description: Base fields shared by payment initiation request payloads.
type: object
additionalProperties: false
required:
- idempotencyKey
properties:
idempotencyKey:
description: Client-supplied key used to safely deduplicate requests.
type: string
metadata:
description: Optional request metadata forwarded through payment processing.
type: object
additionalProperties:
type: string
QuotePaymentRequest:
description: Request payload to quote a single payment intent.
type: object
additionalProperties: false
required:
- intent
properties:
idempotencyKey:
description: Idempotency key used when persisting quote context.
type: string
metadata:
description: Optional metadata associated with the quote request.
type: object
additionalProperties:
type: string
intent:
description: Payment intent to be priced.
$ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentIntent
previewOnly:
description: If true, returns a preview quote without requiring idempotency.
type: boolean
allOf:
- if:
@@ -45,23 +53,28 @@ components:
- idempotencyKey
QuotePaymentsRequest:
description: Request payload to quote multiple payment intents in a single call.
type: object
additionalProperties: false
required:
- intents
properties:
idempotencyKey:
description: Idempotency key used when persisting batch quote context.
type: string
metadata:
description: Optional metadata associated with the quote request.
type: object
additionalProperties:
type: string
intents:
description: List of payment intents to be priced.
type: array
minItems: 1
items:
$ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentIntent
previewOnly:
description: If true, returns preview quotes without requiring idempotency.
type: boolean
allOf:
- if:
@@ -79,6 +92,7 @@ components:
- idempotencyKey
InitiatePaymentRequest:
description: Request payload to initiate a single payment.
allOf:
- $ref: ./payment.yaml#/components/schemas/PaymentBase
- type: object
@@ -88,11 +102,14 @@ components:
- required: [quoteRef]
properties:
intent:
description: Payment intent to execute directly.
$ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentIntent
quoteRef:
description: Reference to a previously generated quote to execute.
type: string
InitiatePaymentsRequest:
description: Request payload to initiate multiple payments from a multi-quote reference.
allOf:
- $ref: ./payment.yaml#/components/schemas/PaymentBase
- type: object
@@ -101,4 +118,5 @@ components:
- quoteRef
properties:
quoteRef:
description: Reference to a previously generated multi-quote.
type: string

17
interface/api/payments/response/payment.yaml
View File

@@ -1,6 +1,7 @@
components:
schemas:
PaymentQuoteData:
description: Response payload for a single payment quote.
type: object
additionalProperties: false
required:
@@ -8,13 +9,17 @@ components:
- quote
properties:
accessToken:
description: Refreshed access token to be used in subsequent API calls.
$ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
idempotencyKey:
description: Idempotency key associated with the quote response.
type: string
quote:
description: Generated quote data for the requested payment intent.
$ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentQuote
PaymentQuotesData:
description: Response payload for a batch quote request.
type: object
additionalProperties: false
required:
@@ -22,21 +27,27 @@ components:
- quote
properties:
accessToken:
description: Refreshed access token to be used in subsequent API calls.
$ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
quote:
description: Batch quote summary and quoted items.
type: object
additionalProperties: false
properties:
idempotencyKey:
description: Idempotency key associated with the batch quote response.
type: string
quoteRef:
description: Reference to the generated batch quote.
type: string
items:
description: Collection of quotes for each requested payment intent.
type: array
items:
$ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentQuote
PaymentsData:
description: Response payload containing a list of payments.
type: object
additionalProperties: false
required:
@@ -44,15 +55,19 @@ components:
- payments
properties:
accessToken:
description: Refreshed access token to be used in subsequent API calls.
$ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
payments:
description: Collection of payment records.
type: array
items:
$ref: ../../../models/payment/payment.yaml#/components/schemas/Payment
page:
description: Pagination cursor metadata for payment listing endpoints.
$ref: ../../../models/common/pagination.yaml#/components/schemas/CursorPageResponse
PaymentData:
description: Response payload containing a single payment record.
type: object
additionalProperties: false
required:
@@ -60,6 +75,8 @@ components:
- payment
properties:
accessToken:
description: Refreshed access token to be used in subsequent API calls.
$ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
payment:
description: Requested payment record.
$ref: ../../../models/payment/payment.yaml#/components/schemas/Payment

1
interface/api/recipients/bodies/recipient.yaml
View File

@@ -1,6 +1,7 @@
components:
requestBodies:
RecipientBody:
description: JSON body containing recipient details.
required: true
content:
application/json:

1
interface/api/recipients/request/recipient.yaml
View File

@@ -1,4 +1,5 @@
components:
schemas:
RecipientRequest:
description: Request payload used to create or update a recipient.
$ref: ../../../models/recipient/recipient.yaml#/components/schemas/Recipient

3
interface/api/recipients/response/recipient.yaml
View File

@@ -1,6 +1,7 @@
components:
schemas:
RecipientsAuthData:
description: Authenticated response payload containing recipients.
type: object
additionalProperties: false
required:
@@ -8,8 +9,10 @@ components:
- recipients
properties:
accessToken:
description: Refreshed access token to be used in subsequent API calls.
$ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
recipients:
description: Collection of recipients available to the authenticated account.
type: array
items:
$ref: ../../../models/recipient/recipient.yaml#/components/schemas/Recipient

5
interface/api/response/error.yaml
View File

@@ -1,6 +1,7 @@
components:
schemas:
ApiError:
description: Standard API error envelope with optional debugging details.
type: object
additionalProperties: false
required:
@@ -9,11 +10,15 @@ components:
- source
properties:
code:
description: Application-specific numeric error code.
type: integer
format: int32
error:
description: Human-readable error summary.
type: string
source:
description: Component or subsystem that produced the error.
type: string
details:
description: Optional detailed message providing additional failure context.
type: string

2
interface/api/verification/bodies/verification.yaml
View File

@@ -1,6 +1,7 @@
components:
requestBodies:
VerificationCodeBody:
description: JSON payload used to request a new verification code.
required: true
content:
application/json:
@@ -8,6 +9,7 @@ components:
$ref: ../request/verification.yaml#/components/schemas/VerificationCodeRequest
VerifyCodeBody:
description: JSON payload containing a verification code to validate.
required: true
content:
application/json:

6
interface/api/verification/response/verification.yaml
View File

@@ -1,6 +1,7 @@
components:
schemas:
VerificationResponseData:
description: Response data returned after requesting a verification code.
type: object
additionalProperties: false
required:
@@ -10,17 +11,22 @@ components:
- target
properties:
idempotencyKey:
description: Idempotency key associated with the verification request.
type: string
ttl_seconds:
description: Verification code validity period in seconds.
type: integer
format: int32
cooldown_seconds:
description: Cooldown period before another code can be requested.
type: integer
format: int32
target:
description: Destination where the verification code was sent.
type: string
VerifyResultData:
description: Result payload returned after code verification succeeds.
oneOf:
- $ref: ../../accounts/response/auth.yaml#/components/schemas/LoginData
- $ref: ../../response/response.yaml#/components/schemas/SuccessResultData

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