Ubyx Platform Settlement AsyncAPI 1.0-beta documentation

Ubyx Platform Settlement AsyncAPI 1.0-beta

Proprietary
Terms of service
application/cloudevents+json
External Docs
Ubyx Platform Team
platform@ubyx.xyz
ID: urn:ubyx:asyncapi:settlement:v1.0-beta

AsyncAPI specification for Ubyx Platform Settlement asynchronous events. This document describes the event-driven architecture and event messaging for clearing transaction events between the Settlement Platform and external systems.

CloudEvents Format

All events published by Ubyx Platform follow the CloudEvents v1.0 specification. Events are wrapped in a CloudEvent envelope with standardized metadata.

Important: Events use structured mode CloudEvents binding for Message Broker:

The full CloudEvent (including all mandatory attributes and business data) is placed in the message value (body) as a single JSON object.

This mode simplifies integration for consumers that are not yet prepared to handle CloudEvents attributes in message headers.

Subject Correlation Best Practice

Recommended approach for subject field:

For initial requests (conversion-request): Use any partner-defined correlation ID
For response actions (approvals, rejections): Use the workflowId from the corresponding Ubyx outbound event

Example Flow:

1. Partner sends: conversion-request with subject: "partner-conversion-request-001"
2. Ubyx responds: conversion.created with subject: "notification-conversion-created-request-conversion-123e4567"
3. Partner responds: issuer-approval with subject: "notification-conversion-created-request-conversion-123e4567"

This creates perfect event correlation and simplifies debugging across both systems.

Schema Versioning (URN Format)

Event schemas are identified using URN (Uniform Resource Name) format: urn:ubyx:clearing:schema:{version}

Version	Status	Description
1.0-beta	Current	MVP/Early adopter version
1.0	Planned	Stable production version (post-validation)

#Clearing
#Outbound
#Inbound

Servers

broker-sandbox.ubyx-platform.com:9092kafka-securesandbox
Sandbox Broker Server
Security:
X509:
Mutual TLS required for all Broker servers - Ubyx Platform

security.protocol:SSL
broker.ubyx-platform.com:9092kafka-secureproduction
Production Broker Server
Security:
X509:
Mutual TLS required for all Broker servers - Ubyx Platform

security.protocol:SSL

Operations

SUB ubyx.outbound
Stream of clearing transaction events emitted by the platform. This topic is partitioned by institutionId to guarantee ordering.

Consumer Configuration:

group.id: Use your institutionId (UUID)

client.id: Use your institutionId (UUID)

topic: ubyx.outbound

Runtime Safety: Validate that message.data.institutionId matches your ID.

Event Types (December 2025 - Hierarchical Format):

ubyx.clearing.conversion.created - New conversion initiated

ubyx.clearing.conversion.completed - Conversion successfully completed

ubyx.clearing.conversion.failed - Conversion failed or rejected

ubyx.clearing.settlement.approved - Settlement approved by all parties

ubyx.clearing.settlement.confirmed - Settlement confirmed by settlers
Receive clearing status updates
Consumes real-time CloudEvents regarding transaction lifecycle changes (Created, Approved, Rejected). Use Case: Keep local partner systems synchronized with the Settlement Platform state.

Operation IDconsumeOutboundEvents
Available only on servers:
- sandbox
- production
object
topic
ubyx.outbound
partitions
96
replicas
3
object
tuple<string, ...optional<any>>
1 item:
delete
retention.ms
604800000
object
groupId
${institutionId}
clientId
${institutionId}
- #Clearing
- #Outbound
Accepts the following message:
Clearing Transaction CloudEventoutbound:clearing-cloudevent
Generic envelope for all outbound clearing events.
application/cloudevents+json
Message IDoutbound:clearing-cloudevent
object
Full CloudEvent v1.0 envelope (structured mode)

specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
source
required
string
subject
string
Correlation ID for event tracking. Best Practice: For response actions, use the workflowId from the corresponding Ubyx outbound event.

time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Business payload for clearing transaction events (Updated December 2025).

transactionId
required
string
Unique identifier for the clearing transaction (simplified from clearingTransactionId)

Examples values:
"request-conversion-123e4567-e89b-12d3-a456-426614174000"
institutionId
required
string
format: uuid
Institution ID that this event is relevant to

workflowId
required
string
Temporal workflow ID that generated this event

transactionType
required
string
Allowed values:
"CONVERSION"
"REDEMPTION"
"MINTING"
"ERROR"
eventType
required
string
Specific business event type that occurred

Examples values:
"CONVERSION_CREATED"
"CONVERSION_COMPLETED"
"SETTLEMENT_APPROVED"
status
required
string
High-level transaction status for SSE notification alignment

Allowed values:
"INITIATED"
"PROCESSING"
"COMPLETED"
"FAILED"
"CONFIRMED"
eventSource
required
string
Source system that generated the event data

Examples values:
"canton-ledger"
transactionTimestamp
required
string
format: date-time
Timestamp when the business transaction occurred (UTC)

processingCompletedAt
string
format: date-time
Timestamp when transaction processing was completed (UTC), null if still in progress

object
Contains only contract-specific information, cleaned of system-added fields.

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
key
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).

Examples
#1 Example - ConversionCreated
New conversion created
{ "specversion": "1.0", "id": "550e8400-e29b-41d4-a716-446655440000", "type": "ubyx.clearing.conversion.created", "source": "ubyx-platform-settlement", "time": "2024-12-16T10:30:00Z", "datacontenttype": "application/json", "dataschema": "urn:ubyx:clearing:schema:1.0-beta", "subject": "notification-conversion-created-request-conversion-123e4567", "data": { "transactionId": "request-conversion-123e4567-e89b-12d3-a456-426614174000", "institutionId": "123e4567-e89b-12d3-a456-426614174000", "workflowId": "notification-conversion-created-request-conversion-123e4567", "transactionType": "CONVERSION", "eventType": "CONVERSION_CREATED", "status": "INITIATED", "eventSource": "canton-ledger", "transactionTimestamp": "2024-12-16T10:30:00Z", "processingCompletedAt": null, "ledgerEventData": { "conversionId": "request-conversion-123e4567-e89b-12d3-a456-426614174000", "receivingInstitutionId": "123e4567-e89b-12d3-a456-426614174000", "issuerId": "ef0b3459-ce00-4c01-bcbe-3cb8a57b2706", "assetId": "RLUSD", "quantity": 1000, "currency": "USD", "createdAt": "2024-12-16T10:29:58Z" } } }
PUB ubyx.inbound
Ingestion channel for clearing transaction actions from external partners.

Producer Configuration:

client.id: Use your institutionId (UUID)

topic: ubyx.inbound

Message Key (Partition Key): MANDATORY use the institutionId (UUID) as the message key.
This guarantees ordering per institution and even load distribution across partitions.

Events must follow CloudEvents v1.0 specification in structured mode.
Publish clearing actions
Sends business actions (approvals, requests, confirmations) to the Settlement Platform. Each event type triggers specific workflow transitions.

Operation IDsendInboundEvents
Available only on servers:
- sandbox
- production
object
topic
ubyx.inbound
partitions
96
replicas
3
object
tuple<string, ...optional<any>>
1 item:
delete
retention.ms
604800000
object
clientId
${institutionId}
- #Clearing
- #Inbound
Accepts one of the following messages:
- #0Conversion Request Eventinbound:conversion-request
  New conversion request received from partner institution
  application/cloudevents+json
  Message IDinbound:conversion-request
  object
  specversion
  required
  string
  Const:"1.0"
  id
  required
  string
  format: uuid
  type
  required
  string
  Const:"ubyx.clearing.conversion.conversion-request"
  source
  required
  string
  subject
  string
  time
  string
  format: date-time
  datacontenttype
  string
  Const:"application/json"
  dataschema
  string
  format: uri
  object
  Payload for conversion request events
  
  required
  object
  conversionType
  string
  Allowed values:
  "REDEMPTION"
  "MINTING"
  receivingInstitutionId
  required
  string
  must match: \S<= 50 characters
  issuerId
  required
  string
  must match: \S<= 50 characters
  cashSettlerId
  required
  string
  must match: \S<= 50 characters
  assetSettlerId
  required
  string
  must match: \S<= 50 characters
  required
  object
  accountId
  required
  string
  must match: \S<= 255 characters
  walletAddress
  required
  string
  must match: \S<= 255 characters
  Additional properties are allowed.
  required
  object
  fullName
  required
  string
  must match: \S<= 255 characters
  address
  required
  string
  must match: \S<= 500 characters
  Additional properties are allowed.
  startingCurrency
  required
  string
  must match: ^[A-Z]{3}$
  settlementCurrency
  required
  string
  must match: ^[A-Z]{3}$
  assetId
  required
  string
  must match: \S<= 20 characters
  quantity
  required
  number
  must match: ^\d{1,15}([.]\d{1,8})?$>= 0.01
  depositId
  required
  string
  must match: \S<= 255 characters
  chainId
  required
  string
  must match: \S<= 255 characters
  ticker
  required
  string
  must match: \S<= 255 characters
  Additional properties are allowed.
  Additional properties are allowed.
  Additional properties are allowed.
  object
  key
  string
  format: uuid
  Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
  
  Examples
  #1 Example - RedemptionRequest
  Token redemption to fiat currency
  { "specversion": "1.0", "id": "550e8400-e29b-41d4-a716-446655440001", "type": "ubyx.clearing.conversion.conversion-request", "source": "https://bank-a.clearing.example.com", "subject": "partner-batch-001", "time": "2024-12-12T10:30:00Z", "datacontenttype": "application/json", "dataschema": "urn:ubyx:clearing:schema:1.0-beta", "data": { "conversionRequest": { "conversionType": "REDEMPTION", "receivingInstitutionID": "inst-bank-a", "issuerID": "issuer-001", "cashSettlerID": "settler-cash-001", "assetSettlerID": "settler-asset-001", "assetID": "USDC", "quantity": 10000, "currency": "USD", "ownerMeta": { "fullName": "John Doe", "address": "123 Main Street, New York, NY 10001" }, "RIaccountNumber": "US12345678901234" } } }
- #1Issuer Approval Eventinbound:issuer-approval
  Issuer approved the conversion request
  application/cloudevents+json
  Message IDinbound:issuer-approval
  object
  specversion
  required
  string
  Const:"1.0"
  id
  required
  string
  format: uuid
  type
  required
  string
  Const:"ubyx.clearing.conversion.issuer-approval"
  source
  required
  string
  subject
  string
  time
  string
  format: date-time
  datacontenttype
  string
  Const:"application/json"
  dataschema
  string
  format: uri
  object
  Payload for issuer approval events
  
  conversionId
  required
  string
  ID of the conversion being approved
  
  institutionId
  required
  string
  format: uuid
  walletAddress
  string
  accountNumber
  string
  Additional properties are allowed.
  Additional properties are allowed.
  object
  key
  string
  format: uuid
  Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
  
  Examples
  #1 Example - IssuerApprovalExample
  Issuer approves a redemption conversion
  { "specversion": "1.0", "id": "550e8400-e29b-41d4-a716-446655440003", "type": "ubyx.clearing.conversion.issuer-approval", "source": "https://issuer-bank.clearing.example.com", "subject": "notification-conversion-created-request-conversion-123e4567", "time": "2024-12-12T10:45:00Z", "datacontenttype": "application/json", "dataschema": "urn:ubyx:clearing:schema:1.0-beta", "data": { "conversionId": "request-conversion-123e4567", "institutionId": "123e4567-e89b-12d3-a456-426614174001", "walletAddress": "0x742d35Cc6634C0532925a3b8D4C9db96590c6C87", "accountNumber": "US12345678901234" } }
- #2Issuer Reject Eventinbound:issuer-reject
  Issuer rejected the conversion request
  application/cloudevents+json
  Message IDinbound:issuer-reject
  object
  specversion
  required
  string
  Const:"1.0"
  id
  required
  string
  format: uuid
  type
  required
  string
  Const:"ubyx.clearing.conversion.issuer-reject"
  source
  required
  string
  subject
  string
  time
  string
  format: date-time
  datacontenttype
  string
  Const:"application/json"
  dataschema
  string
  format: uri
  object
  Payload for issuer reject events
  
  conversionId
  required
  string
  institutionId
  required
  string
  format: uuid
  reason
  required
  string
  Reason for rejection
  
  Additional properties are allowed.
  Additional properties are allowed.
  object
  key
  string
  format: uuid
  Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
  
  Examples
  #1 Example - IssuerRejectExample
  Issuer rejects conversion due to compliance issue
  { "specversion": "1.0", "id": "550e8400-e29b-41d4-a716-446655440004", "type": "ubyx.clearing.conversion.issuer-reject", "source": "https://issuer-bank.clearing.example.com", "subject": "notification-conversion-created-request-conversion-123e4567", "time": "2024-12-12T10:45:00Z", "datacontenttype": "application/json", "dataschema": "urn:ubyx:clearing:schema:1.0-beta", "data": { "conversionId": "request-conversion-123e4567", "institutionId": "123e4567-e89b-12d3-a456-426614174001", "reason": "Compliance check failed - KYC documentation incomplete" } }
- #3Asset Settler Approval Eventinbound:asset-settler-approval
  Asset settler approved the settlement
  application/cloudevents+json
  Message IDinbound:asset-settler-approval
  object
  specversion
  required
  string
  Const:"1.0"
  id
  required
  string
  format: uuid
  type
  required
  string
  Const:"ubyx.clearing.conversion.asset-settler-approval"
  source
  required
  string
  subject
  string
  time
  string
  format: date-time
  datacontenttype
  string
  Const:"application/json"
  dataschema
  string
  format: uri
  object
  Payload for settler approval events (asset/cash)
  
  conversionId
  required
  string
  institutionId
  required
  string
  format: uuid
  Additional properties are allowed.
  Additional properties are allowed.
  object
  key
  string
  format: uuid
  Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
  
  Examples
  #1 Example - AssetSettlerApprovalExample
  Asset settler approves the token transfer
  { "specversion": "1.0", "id": "550e8400-e29b-41d4-a716-446655440005", "type": "ubyx.clearing.conversion.asset-settler-approval", "source": "https://asset-settler.clearing.example.com", "subject": "notification-conversion-created-request-conversion-123e4567", "time": "2024-12-12T11:00:00Z", "datacontenttype": "application/json", "dataschema": "urn:ubyx:clearing:schema:1.0-beta", "data": { "conversionId": "request-conversion-123e4567", "institutionId": "123e4567-e89b-12d3-a456-426614174002" } }
- #4Cash Settler Approval Eventinbound:cash-settler-approval
  Cash settler approved the settlement
  application/cloudevents+json
  Message IDinbound:cash-settler-approval
  object
  specversion
  required
  string
  Const:"1.0"
  id
  required
  string
  format: uuid
  type
  required
  string
  Const:"ubyx.clearing.conversion.cash-settler-approval"
  source
  required
  string
  subject
  string
  time
  string
  format: date-time
  datacontenttype
  string
  Const:"application/json"
  dataschema
  string
  format: uri
  object
  Payload for settler approval events (asset/cash)
  
  conversionId
  required
  string
  institutionId
  required
  string
  format: uuid
  Additional properties are allowed.
  Additional properties are allowed.
  object
  key
  string
  format: uuid
  Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
  
  Examples
  #1 Example - CashSettlerApprovalExample
  Cash settler approves the fiat transfer
  { "specversion": "1.0", "id": "550e8400-e29b-41d4-a716-446655440006", "type": "ubyx.clearing.conversion.cash-settler-approval", "source": "https://cash-settler.clearing.example.com", "subject": "notification-conversion-created-request-conversion-123e4567", "time": "2024-12-12T11:05:00Z", "datacontenttype": "application/json", "dataschema": "urn:ubyx:clearing:schema:1.0-beta", "data": { "conversionId": "request-conversion-123e4567" } }
- #5Asset Settler Confirm Eventinbound:asset-settler-confirm
  Asset Settler confirmed the settlement completion
  application/cloudevents+json
  Message IDinbound:asset-settler-confirm
  object
  specversion
  required
  string
  Const:"1.0"
  id
  required
  string
  format: uuid
  type
  required
  string
  Const:"ubyx.clearing.conversion.settler-confirm"
  source
  required
  string
  subject
  string
  time
  string
  format: date-time
  datacontenttype
  string
  Const:"application/json"
  dataschema
  string
  format: uri
  object
  Payload for settler confirm events
  
  conversionId
  required
  string
  institutionId
  required
  string
  format: uuid
  Additional properties are allowed.
  Additional properties are allowed.
  object
  key
  string
  format: uuid
  Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
  
  Examples
  #1 Example - AssetSettlerConfirmExample
  Asset Settler confirms successful settlement
  { "specversion": "1.0", "id": "550e8400-e29b-41d4-a716-446655440007", "type": "ubyx.clearing.conversion.asset-settler-confirm", "source": "https://asset-settler.clearing.example.com", "subject": "notification-conversion-created-request-conversion-123e4567", "time": "2024-12-12T11:30:00Z", "datacontenttype": "application/json", "dataschema": "urn:ubyx:clearing:schema:1.0-beta", "data": { "conversionId": "request-conversion-123e4567" } }
- #6Cash Settler Confirm Eventinbound:cash-settler-confirm
  Cash Settler confirmed the settlement completion
  application/cloudevents+json
  Message IDinbound:cash-settler-confirm
  object
  specversion
  required
  string
  Const:"1.0"
  id
  required
  string
  format: uuid
  type
  required
  string
  Const:"ubyx.clearing.conversion.settler-confirm"
  source
  required
  string
  subject
  string
  time
  string
  format: date-time
  datacontenttype
  string
  Const:"application/json"
  dataschema
  string
  format: uri
  object
  Payload for settler confirm events
  
  conversionId
  required
  string
  institutionId
  required
  string
  format: uuid
  Additional properties are allowed.
  Additional properties are allowed.
  object
  key
  string
  format: uuid
  Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
  
  Examples
  #1 Example - CashSettlerConfirmExample
  Cash Settler confirms successful settlement
  { "specversion": "1.0", "id": "550e8400-e29b-41d4-a716-446655440008", "type": "ubyx.clearing.conversion.cash-settler-confirm", "source": "https://cash-settler.clearing.example.com", "subject": "notification-conversion-created-request-conversion-123e4567", "time": "2024-12-12T11:35:00Z", "datacontenttype": "application/json", "dataschema": "urn:ubyx:clearing:schema:1.0-beta", "data": { "conversionId": "request-conversion-123e4567", "institutionId": "123e4567-e89b-12d3-a456-426614174005" } }
- #7Asset Settler Reject Confirm Eventinbound:asset-settler-reject-confirm
  Asset Settler rejected at confirmation stage
  application/cloudevents+json
  Message IDinbound:asset-settler-reject-confirm
  object
  specversion
  required
  string
  Const:"1.0"
  id
  required
  string
  format: uuid
  type
  required
  string
  source
  required
  string
  subject
  string
  time
  string
  format: date-time
  datacontenttype
  string
  Const:"application/json"
  dataschema
  string
  format: uri
  object
  Payload for settler reject events
  
  conversionId
  required
  string
  institutionId
  required
  string
  format: uuid
  reason
  required
  string
  Reason for rejection
  
  Additional properties are allowed.
  Additional properties are allowed.
  object
  key
  string
  format: uuid
  Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
  
  Examples
  { "specversion": "1.0", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "type": "string", "source": "string", "subject": "string", "time": "2019-08-24T14:15:22Z", "datacontenttype": "application/json", "dataschema": "http://example.com", "data": { "conversionId": "string", "institutionId": "cdae5c01-a629-4362-be56-52101ec22a49", "reason": "string" } }
  
  This example has been generated automatically.
- #8Cash Settler Reject Confirm Eventinbound:cash-settler-reject-confirm
  Cash Settler rejected at confirmation stage
  application/cloudevents+json
  Message IDinbound:cash-settler-reject-confirm
  object
  specversion
  required
  string
  Const:"1.0"
  id
  required
  string
  format: uuid
  type
  required
  string
  source
  required
  string
  subject
  string
  time
  string
  format: date-time
  datacontenttype
  string
  Const:"application/json"
  dataschema
  string
  format: uri
  object
  Payload for settler reject events
  
  conversionId
  required
  string
  institutionId
  required
  string
  format: uuid
  reason
  required
  string
  Reason for rejection
  
  Additional properties are allowed.
  Additional properties are allowed.
  object
  key
  string
  format: uuid
  Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
  
  Examples
  { "specversion": "1.0", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "type": "string", "source": "string", "subject": "string", "time": "2019-08-24T14:15:22Z", "datacontenttype": "application/json", "dataschema": "http://example.com", "data": { "conversionId": "string", "institutionId": "cdae5c01-a629-4362-be56-52101ec22a49", "reason": "string" } }
  
  This example has been generated automatically.
- #9Asset Settler Reject Approve Eventinbound:asset-settler-reject-approve
  Asset Settler rejected at approval stage
  application/cloudevents+json
  Message IDinbound:asset-settler-reject-approve
  object
  specversion
  required
  string
  Const:"1.0"
  id
  required
  string
  format: uuid
  type
  required
  string
  source
  required
  string
  subject
  string
  time
  string
  format: date-time
  datacontenttype
  string
  Const:"application/json"
  dataschema
  string
  format: uri
  object
  Payload for settler reject events
  
  conversionId
  required
  string
  institutionId
  required
  string
  format: uuid
  reason
  required
  string
  Reason for rejection
  
  Additional properties are allowed.
  Additional properties are allowed.
  object
  key
  string
  format: uuid
  Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
  
  Examples
  { "specversion": "1.0", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "type": "string", "source": "string", "subject": "string", "time": "2019-08-24T14:15:22Z", "datacontenttype": "application/json", "dataschema": "http://example.com", "data": { "conversionId": "string", "institutionId": "cdae5c01-a629-4362-be56-52101ec22a49", "reason": "string" } }
  
  This example has been generated automatically.
- #10Cash Settler Reject Approve Eventinbound:cash-settler-reject-approve
  Cash Settler rejected at approval stage
  application/cloudevents+json
  Message IDinbound:cash-settler-reject-approve
  object
  specversion
  required
  string
  Const:"1.0"
  id
  required
  string
  format: uuid
  type
  required
  string
  source
  required
  string
  subject
  string
  time
  string
  format: date-time
  datacontenttype
  string
  Const:"application/json"
  dataschema
  string
  format: uri
  object
  Payload for settler reject events
  
  conversionId
  required
  string
  institutionId
  required
  string
  format: uuid
  reason
  required
  string
  Reason for rejection
  
  Additional properties are allowed.
  Additional properties are allowed.
  object
  key
  string
  format: uuid
  Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
  
  Examples
  { "specversion": "1.0", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "type": "string", "source": "string", "subject": "string", "time": "2019-08-24T14:15:22Z", "datacontenttype": "application/json", "dataschema": "http://example.com", "data": { "conversionId": "string", "institutionId": "cdae5c01-a629-4362-be56-52101ec22a49", "reason": "string" } }
  
  This example has been generated automatically.

Messages

#1Clearing Transaction CloudEventoutbound:clearing-cloudevent
Generic envelope for all outbound clearing events.
- application/cloudevents+json
Message IDoutbound:clearing-cloudevent
object
Full CloudEvent v1.0 envelope (structured mode)

specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
source
required
string
subject
string
Correlation ID for event tracking. Best Practice: For response actions, use the workflowId from the corresponding Ubyx outbound event.

time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Business payload for clearing transaction events (Updated December 2025).

transactionId
required
string
Unique identifier for the clearing transaction (simplified from clearingTransactionId)

Examples values:
"request-conversion-123e4567-e89b-12d3-a456-426614174000"
institutionId
required
string
format: uuid
Institution ID that this event is relevant to

workflowId
required
string
Temporal workflow ID that generated this event

transactionType
required
string
Allowed values:
"CONVERSION"
"REDEMPTION"
"MINTING"
"ERROR"
eventType
required
string
Specific business event type that occurred

Examples values:
"CONVERSION_CREATED"
"CONVERSION_COMPLETED"
"SETTLEMENT_APPROVED"
status
required
string
High-level transaction status for SSE notification alignment

Allowed values:
"INITIATED"
"PROCESSING"
"COMPLETED"
"FAILED"
"CONFIRMED"
eventSource
required
string
Source system that generated the event data

Examples values:
"canton-ledger"
transactionTimestamp
required
string
format: date-time
Timestamp when the business transaction occurred (UTC)

processingCompletedAt
string
format: date-time
Timestamp when transaction processing was completed (UTC), null if still in progress

object
Contains only contract-specific information, cleaned of system-added fields.

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
key
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
#2Conversion Request Eventinbound:conversion-request
New conversion request received from partner institution
- application/cloudevents+json
Message IDinbound:conversion-request
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
Const:"ubyx.clearing.conversion.conversion-request"
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for conversion request events

required
object
conversionType
string
Allowed values:
"REDEMPTION"
"MINTING"
receivingInstitutionId
required
string
must match: \S<= 50 characters
issuerId
required
string
must match: \S<= 50 characters
cashSettlerId
required
string
must match: \S<= 50 characters
assetSettlerId
required
string
must match: \S<= 50 characters
required
object
accountId
required
string
must match: \S<= 255 characters
walletAddress
required
string
must match: \S<= 255 characters
Additional properties are allowed.
required
object
fullName
required
string
must match: \S<= 255 characters
address
required
string
must match: \S<= 500 characters
Additional properties are allowed.
startingCurrency
required
string
must match: ^[A-Z]{3}$
settlementCurrency
required
string
must match: ^[A-Z]{3}$
assetId
required
string
must match: \S<= 20 characters
quantity
required
number
must match: ^\d{1,15}([.]\d{1,8})?$>= 0.01
depositId
required
string
must match: \S<= 255 characters
chainId
required
string
must match: \S<= 255 characters
ticker
required
string
must match: \S<= 255 characters
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
key
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
#3Issuer Approval Eventinbound:issuer-approval
Issuer approved the conversion request
- application/cloudevents+json
Message IDinbound:issuer-approval
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
Const:"ubyx.clearing.conversion.issuer-approval"
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for issuer approval events

conversionId
required
string
ID of the conversion being approved

institutionId
required
string
format: uuid
walletAddress
string
accountNumber
string
Additional properties are allowed.
Additional properties are allowed.
object
key
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
#4Issuer Reject Eventinbound:issuer-reject
Issuer rejected the conversion request
- application/cloudevents+json
Message IDinbound:issuer-reject
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
Const:"ubyx.clearing.conversion.issuer-reject"
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for issuer reject events

conversionId
required
string
institutionId
required
string
format: uuid
reason
required
string
Reason for rejection

Additional properties are allowed.
Additional properties are allowed.
object
key
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
#5Asset Settler Approval Eventinbound:asset-settler-approval
Asset settler approved the settlement
- application/cloudevents+json
Message IDinbound:asset-settler-approval
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
Const:"ubyx.clearing.conversion.asset-settler-approval"
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for settler approval events (asset/cash)

conversionId
required
string
institutionId
required
string
format: uuid
Additional properties are allowed.
Additional properties are allowed.
object
key
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
#6Cash Settler Approval Eventinbound:cash-settler-approval
Cash settler approved the settlement
- application/cloudevents+json
Message IDinbound:cash-settler-approval
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
Const:"ubyx.clearing.conversion.cash-settler-approval"
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for settler approval events (asset/cash)

conversionId
required
string
institutionId
required
string
format: uuid
Additional properties are allowed.
Additional properties are allowed.
object
key
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
#7Asset Settler Confirm Eventinbound:asset-settler-confirm
Asset Settler confirmed the settlement completion
- application/cloudevents+json
Message IDinbound:asset-settler-confirm
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
Const:"ubyx.clearing.conversion.settler-confirm"
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for settler confirm events

conversionId
required
string
institutionId
required
string
format: uuid
Additional properties are allowed.
Additional properties are allowed.
object
key
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
#8Cash Settler Confirm Eventinbound:cash-settler-confirm
Cash Settler confirmed the settlement completion
- application/cloudevents+json
Message IDinbound:cash-settler-confirm
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
Const:"ubyx.clearing.conversion.settler-confirm"
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for settler confirm events

conversionId
required
string
institutionId
required
string
format: uuid
Additional properties are allowed.
Additional properties are allowed.
object
key
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
#9Asset Settler Reject Confirm Eventinbound:asset-settler-reject-confirm
Asset Settler rejected at confirmation stage
- application/cloudevents+json
Message IDinbound:asset-settler-reject-confirm
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for settler reject events

conversionId
required
string
institutionId
required
string
format: uuid
reason
required
string
Reason for rejection

Additional properties are allowed.
Additional properties are allowed.
object
key
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
#10Cash Settler Reject Confirm Eventinbound:cash-settler-reject-confirm
Cash Settler rejected at confirmation stage
- application/cloudevents+json
Message IDinbound:cash-settler-reject-confirm
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for settler reject events

conversionId
required
string
institutionId
required
string
format: uuid
reason
required
string
Reason for rejection

Additional properties are allowed.
Additional properties are allowed.
object
key
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
#11Asset Settler Reject Approve Eventinbound:asset-settler-reject-approve
Asset Settler rejected at approval stage
- application/cloudevents+json
Message IDinbound:asset-settler-reject-approve
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for settler reject events

conversionId
required
string
institutionId
required
string
format: uuid
reason
required
string
Reason for rejection

Additional properties are allowed.
Additional properties are allowed.
object
key
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
#12Cash Settler Reject Approve Eventinbound:cash-settler-reject-approve
Cash Settler rejected at approval stage
- application/cloudevents+json
Message IDinbound:cash-settler-reject-approve
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for settler reject events

conversionId
required
string
institutionId
required
string
format: uuid
reason
required
string
Reason for rejection

Additional properties are allowed.
Additional properties are allowed.
object
key
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).

Schemas

PartitionKey
string
format: uuid
Partition Key (Mandatory) Must be the institutionId (UUID). Ensures that all events for the same institution land on the same partition, guaranteeing sequential processing order (FIFO).
object
Full CloudEvent v1.0 envelope (structured mode)

specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
source
required
string
subject
string
Correlation ID for event tracking. Best Practice: For response actions, use the workflowId from the corresponding Ubyx outbound event.

time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Business payload for clearing transaction events (Updated December 2025).

transactionId
required
string
Unique identifier for the clearing transaction (simplified from clearingTransactionId)

Examples values:
"request-conversion-123e4567-e89b-12d3-a456-426614174000"
institutionId
required
string
format: uuid
Institution ID that this event is relevant to

workflowId
required
string
Temporal workflow ID that generated this event

transactionType
required
string
Allowed values:
"CONVERSION"
"REDEMPTION"
"MINTING"
"ERROR"
eventType
required
string
Specific business event type that occurred

Examples values:
"CONVERSION_CREATED"
"CONVERSION_COMPLETED"
"SETTLEMENT_APPROVED"
status
required
string
High-level transaction status for SSE notification alignment

Allowed values:
"INITIATED"
"PROCESSING"
"COMPLETED"
"FAILED"
"CONFIRMED"
eventSource
required
string
Source system that generated the event data

Examples values:
"canton-ledger"
transactionTimestamp
required
string
format: date-time
Timestamp when the business transaction occurred (UTC)

processingCompletedAt
string
format: date-time
Timestamp when transaction processing was completed (UTC), null if still in progress

object
Contains only contract-specific information, cleaned of system-added fields.

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
Const:"ubyx.clearing.conversion.conversion-request"
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for conversion request events

required
object
conversionType
string
Allowed values:
"REDEMPTION"
"MINTING"
receivingInstitutionId
required
string
must match: \S<= 50 characters
issuerId
required
string
must match: \S<= 50 characters
cashSettlerId
required
string
must match: \S<= 50 characters
assetSettlerId
required
string
must match: \S<= 50 characters
required
object
accountId
required
string
must match: \S<= 255 characters
walletAddress
required
string
must match: \S<= 255 characters
Additional properties are allowed.
required
object
fullName
required
string
must match: \S<= 255 characters
address
required
string
must match: \S<= 500 characters
Additional properties are allowed.
startingCurrency
required
string
must match: ^[A-Z]{3}$
settlementCurrency
required
string
must match: ^[A-Z]{3}$
assetId
required
string
must match: \S<= 20 characters
quantity
required
number
must match: ^\d{1,15}([.]\d{1,8})?$>= 0.01
depositId
required
string
must match: \S<= 255 characters
chainId
required
string
must match: \S<= 255 characters
ticker
required
string
must match: \S<= 255 characters
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
Const:"ubyx.clearing.conversion.issuer-approval"
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for issuer approval events

conversionId
required
string
ID of the conversion being approved

institutionId
required
string
format: uuid
walletAddress
string
accountNumber
string
Additional properties are allowed.
Additional properties are allowed.
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
Const:"ubyx.clearing.conversion.issuer-reject"
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for issuer reject events

conversionId
required
string
institutionId
required
string
format: uuid
reason
required
string
Reason for rejection

Additional properties are allowed.
Additional properties are allowed.
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
Const:"ubyx.clearing.conversion.asset-settler-approval"
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for settler approval events (asset/cash)

conversionId
required
string
institutionId
required
string
format: uuid
Additional properties are allowed.
Additional properties are allowed.
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
Const:"ubyx.clearing.conversion.cash-settler-approval"
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for settler approval events (asset/cash)

conversionId
required
string
institutionId
required
string
format: uuid
Additional properties are allowed.
Additional properties are allowed.
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
Const:"ubyx.clearing.conversion.settler-confirm"
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for settler confirm events

conversionId
required
string
institutionId
required
string
format: uuid
Additional properties are allowed.
Additional properties are allowed.
object
specversion
required
string
Const:"1.0"
id
required
string
format: uuid
type
required
string
source
required
string
subject
string
time
string
format: date-time
datacontenttype
string
Const:"application/json"
dataschema
string
format: uri
object
Payload for settler reject events

conversionId
required
string
institutionId
required
string
format: uuid
reason
required
string
Reason for rejection

Additional properties are allowed.
Additional properties are allowed.
object
Business payload for clearing transaction events (Updated December 2025).

transactionId
required
string
Unique identifier for the clearing transaction (simplified from clearingTransactionId)

Examples values:
"request-conversion-123e4567-e89b-12d3-a456-426614174000"
institutionId
required
string
format: uuid
Institution ID that this event is relevant to

workflowId
required
string
Temporal workflow ID that generated this event

transactionType
required
string
Allowed values:
"CONVERSION"
"REDEMPTION"
"MINTING"
"ERROR"
eventType
required
string
Specific business event type that occurred

Examples values:
"CONVERSION_CREATED"
"CONVERSION_COMPLETED"
"SETTLEMENT_APPROVED"
status
required
string
High-level transaction status for SSE notification alignment

Allowed values:
"INITIATED"
"PROCESSING"
"COMPLETED"
"FAILED"
"CONFIRMED"
eventSource
required
string
Source system that generated the event data

Examples values:
"canton-ledger"
transactionTimestamp
required
string
format: date-time
Timestamp when the business transaction occurred (UTC)

processingCompletedAt
string
format: date-time
Timestamp when transaction processing was completed (UTC), null if still in progress

object
Contains only contract-specific information, cleaned of system-added fields.

Additional properties are allowed.
Additional properties are allowed.
object
Contains only contract-specific information, cleaned of system-added fields.

Additional properties are allowed.
ClearingTransactionType
string
Allowed values:
"CONVERSION"
"REDEMPTION"
"MINTING"
"ERROR"
ClearingTransactionStatus
string
High-level transaction status for SSE notification alignment

Allowed values:
"INITIATED"
"PROCESSING"
"COMPLETED"
"FAILED"
"CONFIRMED"
object
Payload for conversion request events

required
object
conversionType
string
Allowed values:
"REDEMPTION"
"MINTING"
receivingInstitutionId
required
string
must match: \S<= 50 characters
issuerId
required
string
must match: \S<= 50 characters
cashSettlerId
required
string
must match: \S<= 50 characters
assetSettlerId
required
string
must match: \S<= 50 characters
required
object
accountId
required
string
must match: \S<= 255 characters
walletAddress
required
string
must match: \S<= 255 characters
Additional properties are allowed.
required
object
fullName
required
string
must match: \S<= 255 characters
address
required
string
must match: \S<= 500 characters
Additional properties are allowed.
startingCurrency
required
string
must match: ^[A-Z]{3}$
settlementCurrency
required
string
must match: ^[A-Z]{3}$
assetId
required
string
must match: \S<= 20 characters
quantity
required
number
must match: ^\d{1,15}([.]\d{1,8})?$>= 0.01
depositId
required
string
must match: \S<= 255 characters
chainId
required
string
must match: \S<= 255 characters
ticker
required
string
must match: \S<= 255 characters
Additional properties are allowed.
Additional properties are allowed.
object
Payload for issuer approval events

conversionId
required
string
ID of the conversion being approved

institutionId
required
string
format: uuid
walletAddress
string
accountNumber
string
Additional properties are allowed.
object
Payload for issuer reject events

conversionId
required
string
institutionId
required
string
format: uuid
reason
required
string
Reason for rejection

Additional properties are allowed.
object
Payload for settler approval events (asset/cash)

conversionId
required
string
institutionId
required
string
format: uuid
Additional properties are allowed.
object
Payload for settler confirm events

conversionId
required
string
institutionId
required
string
format: uuid
Additional properties are allowed.
object
Payload for settler reject events

conversionId
required
string
institutionId
required
string
format: uuid
reason
required
string
Reason for rejection

Additional properties are allowed.

Ubyx Platform Settlement AsyncAPI 1.0-beta

CloudEvents Format

Subject Correlation Best Practice

Schema Versioning (URN Format)

Servers

Security:

Security:

Operations

SUB ubyx.outbound

Examples

#1 Example - ConversionCreated

PUB ubyx.inbound

Examples

#1 Example - RedemptionRequest

Examples

#1 Example - IssuerApprovalExample

Examples

#1 Example - IssuerRejectExample

Examples

#1 Example - AssetSettlerApprovalExample

Examples

#1 Example - CashSettlerApprovalExample

Examples

#1 Example - AssetSettlerConfirmExample

Examples

#1 Example - CashSettlerConfirmExample

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

Messages

Schemas