Go to home page
Docs

Guides

Transferring Assets

Assets  API  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.

Asset transfer statusDescription
requestedAsset transfer request successfully requested.
acceptedAsset transfer request successfully accepted.
sentThe assets have been sent to the recipient.
claimedThe assets have been received by the recipient.
expiredAsset transfer request expired after 14 days when it is not accepted.

Loading Diagram...

  1. The recipient requests an Asset Transfer  API 

    • 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.
    Request
    POST /api/asset-transfer-requests 
    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  API  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.
    Request
    POST /api/asset-transfer-requests/{assetTransferId}/accept 
    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.

Asset transfer statusDescription
createdAsset transfer successfully created.
sentAsset transfer notification (sms, email) was sent to a new user.
expiredAsset transfer expired as new user didn’t create his account and claimed the asset. This is very short lived state.
returnedAsset transfer expired and was returned to original owner.
claimedAsset transfer was successfully completed.
cancelledAsset transfer was cancelled.

Loading Diagram...

  1. The sender creates an Asset Transfer  API 

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