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/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