Transferring Assets

Assets such as Tokens can be transferred between Centrapay accounts by creating an Asset Transfer or by requesting an Asset Transfer.

Transfers occur between a sender and a receiver where:

• The sender refers to the account that initially holds the assets before the Asset Transfer is executed.
• The recipient refers to the account that receives the assets after the Asset Transfer is completed.
• The integrator’s server can optionally send a notification to either party to enhance the transfer experience.

Requesting an Asset Transfer

When a recipient requests an Asset Transfer from another Centrapay account, the sender must accept the request in order for the assets to be transferred.

    sequenceDiagram
autonumber

participant Recipient
participant Centrapay
participant Integrator's Server
participant Sender

Recipient->>Centrapay: Create an Asset Transfer Request
Integrator's Server->>Sender: Send notification

alt
Sender->>Centrapay: Accept asset transfer request
else
Note over Centrapay: Asset Transfer request expires
end

Sender->>Recipient: Transfer assets
  

1. The recipient requests an Asset Transfer

   • recipientAlias is an alias for the Centrapay account that creates request. This field accepts the recipient’s bank account number.

   • senderAccountId is an ID of the Centrapay account that receives the request.

     curl -X POST https://service.centrapay.com/api/asset-transfer-requests \
       -H "X-Api-Key: <TOKEN>" \
       -H "Content-Type: application/json" \
       -d '{
           "recipientAlias": "12-1234-1234567-123",
           "senderAccountId": "9EDxUT91TMsUjoqoQeBuLQ",
           "value": "1000",
           "assetType": "quartz.nzd.test"
           }'

2. The integrator’s server optionally sends a notification to the sender to prompt them to accept the request.

3. The sender accepts the Asset Transfer Request. If the sender does not accept the request within 14 days, the request will expire.

   • senderName is the name of sender who sends the assets. It is displayed to the recipient in their activity history.

     curl -X POST https://service.centrapay.com/api/asset-transfer-requests/{assetTransferId}/accept \
       -H "X-Api-Key: <TOKEN>" \
       -H "Content-Type: application/json" \
       -d '
         {
           "assetId": "YGRo6TYYSxH3js7",
           "value": "1000",
           "senderName": "Jane Doe"
         }'

4. The requested assets are transferred from the sender to the recipient.

Sending Assets

When a sender initiates an Asset Transfer from Centrapay account, the recipient must claim the transfer to receive the assets.

    sequenceDiagram
autonumber

participant Sender
participant Centrapay
participant Recipient

Sender->>Centrapay: Create an Asset Transfer
Sender->>Recipient: Share asset transfer URL

alt
	Recipient->>Centrapay: Claim asset transfer
else
	Note over Centrapay: Asset Transfer expires
	Centrapay->>Sender: Asset Transfer returned to Sender
end

Note over Centrapay: Transfer asset
  

1. The sender creates an Asset Transfer

   The recipientAlias field can be set to recipient’s phone number, email or bank account number. If a recipientAlias isn’t provided, a shareable URL will be returned in the url field.

   curl -X POST https://service.centrapay.com/api/asset-transfers \
     -H "X-Api-Key: <TOKEN>" \
     -H "Content-Type: application/json" \
     -d '
       {
         "assetId": "YGRo6TYYSxH3js7"
       }'

   {
     "id": "EL49tYKmAAkp2njVMs39mrP",
     "status": "created",
     "assetId": "YGRo6TYYSxH3js7",
     "assetType": "centrapay.token.main",
     "senderAccountId": "6ZfBR4jls3nR2mpFJQJ6Qg",
     "createdAt": "2023-11-20T05:01:31.634Z",
     "updatedAt": "2023-11-20T05:01:31.634Z",
     "suppressNotifications": false,
     "url": "https://app.centrapay.com/transfer/EL49tYKmAAkp2njVMs39mrP"
   }

2. The sender shares the Asset Transfer URL with the recipient. The URL is returned when the Asset Transfer is created.

3. The recipient claims the Asset Transfer by visiting the Asset Transfer URL. If the recipient does not claim the asset transfer within 14 days, the asset transfer will expire.

   • If the recipient does not have a Centrapay account, integrators should call the Resolve Claimable Assets endpoint to allocate the assets they have received once their account is created.

4. Expired asset transfer is returned to the sender. Assets are returned to the sender if they are not claimed within 14 days.