This document provides a comprehensive guide for API integrators on how to manage redemption orders using our API. The guide covers the complete lifecycle of a redemption order from retrieval to token burning.

📘

Prerequisites:

To complete this use case, you will need to authenticate your request(s). You can generate your token by following these steps:

• Make sure to leverage an existing account, e.g. Agent, Owner, etc.
• Sign into your Servicing portal to disable your 2FA.
• Navigate to the "Getting API access" page to generate the required JWT, thanks to your credentials.
• Add the JWT to the header of your request.

Order Status Flow

The following diagram illustrates the possible status transitions for a redemption order:

• Initiated: The initial state when an investor creates a redemption order
• Pending_To_Accept: The order is waiting for acceptance
• Pending: The order has been accepted but no price has been set
• Pending_Payment: The price has been set, and payment is awaited
• Payment_Sent: Payment has been confirmed and tokens are ready to be burned
• Burn_Pending: The burn transaction has been initiated but not yet confirmed on the blockchain
• Redeemed: Tokens have been successfully burned, completing the redemption
• Canceled: The order has been canceled at any stage before burning

Complete Open-ended Redemption Order Workflow

 Step 1 - Retrieve redemption information

This endpoint allows you to retrieve information about available redemption options for a specific token.

GET /tokens/{tokenId}/redemptions

 Step 2 - Retrieve all redemption order(s)

This endpoint allows you to retrieve all redemption orders associated with a specific redemption.

GET /redemptions/{redemptionId}/orders

Step 3 - Create an open-ended redemption order on behalf of an investor

This endpoint creates a new order with "Initiated" status, beginning the redemption workflow.

POST api/redemptions/{redemptionId}/orders

Step 4 - Accept order

Use this endpoint to accept redemption orders, which will set their status to "Pending".

POST /redemptions/{redemptionId}/orders/accept

 Step 5 - Sign and Submit the Accept Transaction

This endpoint includes a taskId that is returned in the response from the accept endpoint. You should include this same taskId when calling the transaction logging endpoint.

Logging the transaction is essential to reconcile on-chain and off-chain flows. Since the user handles blockchain interactions on their own, we use the taskId to:

• Identify the workflow uniquely.
• Maintain a consistent link between off-chain logic and on-chain activity.
• Ensure traceability and reliability in our subscription/order system.

Steps to Complete the Accept:

1. Sign the transaction payload with your private key
2. Broadcast, on your end, the signed transaction to the blockchain
3. Log the transaction hash:

POST /redemptions/{redemptionId}/orders/actions/{redemptionOrdersActionId}/transactions

Step 6 - Set price

Use this endpoint to set the price for redemption orders, which will update their status to "Pending_Payment".

POST /redemptions/{redemptionId}/orders/set-price

 Step 7 - Retrieve the redemption order info

This endpoint allows you to retrieve detailed information about a specific redemption order.

GET /redemptions/{redemptionId}/orders/{orderId}

 Step 8 - Confirm payment

Use this endpoint when you need to confirm that payment has been sent to the investor, changing the order status to "Payment_Sent".

This endpoint should be used when:

• You have completed the payment process through your financial systems
• You want to prepare orders for the final token burning step
• You have verified payments have been sent for all included orders

POST /redemptions/{redemptionId}/orders/confirm-payment

 Step 9 - Burn token(s)

Use this endpoint to initiate the token burning process, which will set the order status to "Burn_Pending" and then "Redeemed".

Burning is only available when:

• Orders are in Payment_Sent status
• You have appropriate permissions to manage the token and orders

POST /redemptions/{redemptionId}/orders/burn

 Step 10 - Sign and Submit the Burn Transaction

If burned, the recipient signs and processes the approval transaction following the same process as in Step 4.

Cancellation Flow

This section provides a detailed step-by-step guide for canceling redemption orders at different stages in their lifecycle. Investors can also cancel redemptions, depending on the current status of the order.

 Step 1: Determine Order Eligibility for Cancellation

Before proceeding with cancellation, verify that the order is in a cancellable state:

• Orders in Pending status: Can be canceled
• Orders in Pending_Payment status: Can be canceled
• Orders in Payment_Sent status: Can be canceled (though financial reconciliation may be needed)
• Orders in Burn_Pending or Redeemed status: Cannot be canceled

 Step 2: Retrieve Current Order Information

Use this endpoint to fetch the current order details to confirm its status:

GET api/redemptions/{redemptionId}/orders/{orderId}

Or use this endpoint to retrieve multiple orders at once:

GET api/redemptions/{redemptionId}/orders

Step 3: Cancel Orders

This endpoint allows you to cancel orders:

POST api/redemptions/{redemptionId}/orders/actions/cancel

 Step 4: Sign and Submit the Cancel Transaction

If canceled, the recipient signs and processes the approval transaction following the same process as in Step 4 of Complete Open-ended Redemption Order Workflow.

 Step 5: Verify Cancellation Result

Use this endpoint after sending the cancellation request, verify that the orders have been successfully canceled:

GET api/redemptions/{redemptionId}/orders/{orderId}

The response should show the order status as Canceled.