Asset Transfers

An asset transfer is an asynchronous exchange of an asset or an amount to a recipient.

A recipient is an existing Centrapay user or someone who can create an account to claim the asset transfer by verifying their phone number or email.

After an asset transfer is completed the recipientAlias, lastSentTo and message fields are scrubbed to avoid storing PII.

Asset Transfer Model

Attributes

id
string
The unique identifier.
status
string
The status of the Asset Transfer. See Asset Transfer lifecycle for possible values.
value
bignumber
Amount to send. Required for money transfers. Units depend on the asset type.
assetId
string
Id of a discrete asset to transfer or wallet asset to draw from.
assetType
string
The Asset Type being transferred.
assetCollectionId
stringexperimental
The Token Collection id being transferred.
description
string
Shows up in transaction history against the transfer. 200 character limit.
message
string
Shows up in transaction history against the transfer. 100 character limit.
lastSentTo
string
The phone number or email address of the last recipient.
senderAlias
string
Phone number, email or handle of sender and who receives a request for asset transfer
senderName
string
Human readable name for the sender. 30 character limit.
recipientAccountId
string
The Centrapay Account id of the recipient.
senderAccountId
string
The Centrapay Account id of the sender.
claimedByAccountId
string
The Centrapay Account that claimed the Asset Transfer.
recipientAlias
string
Phone number, email or handle of receiver and who make a request for asset transfer
createdAt
timestamp
When the Asset Transfer was created.
updatedAt
timestamp
When the Asset Transfer was updated.
suppressNotification
boolean
Suppress notifications from Centrapay (SMS/Email).
url
string
A URL where the asset can be claimed if a recipient is not supplied.
claimType
stringexperimental
'multi' if the asset transfer can be claimed by multiple users, 'single' if it can only be claimed by one user.
valueConfig
objectexperimental
The configuration of the value of the asset being transferred for each claim.
claimConditions
arrayexperimental
Array of claim conditions that must be met to successfully claim the asset transfer.
remainingValue
stringexperimental
The remaining value of the asset that has not been claimed.
expiresAt
timestamp
The time that the asset transfer will expire.
loyaltyProgramId
string
The ID of the Loyalty Program associated with this asset transfer.

Asset Transfer lifecycle

Asset Transfer goes through different lifecycle stages.

Asset Transfer Lifecycle

State	Description
created	Asset transfer successfully created
sent	Asset transfer notification (sms, email) was sent to a new user
expired	Asset transfer expired as new user didn't create his account and claimed the asset. This is very short lived state
returned	Asset transfer expired and was returned to original owner
claimed	Asset transfer was successfully completed
cancelled	Asset transfer was cancelled.

Create an Asset Transfer

Transfer an asset to a recipient. Some assets can be transfered only in whole (eg tokens) while others can be transfered only in part (eg money).

Some assets can be transferred without supplying a recipient. A url field will be returned in these cases. The url will link to a page to claim the asset.

Attributes

assetId
stringrequired
Id of a discrete asset to transfer or wallet asset to draw from.
recipientAlias
string
Phone number, email or handle of receiver.
description
string
Shows up in transaction history against the transfer. 200 character limit.
message
string
Shows up in transaction history against the transfer. 100 character limit.
value
bignumber
Amount to send. Required for money transfers. Units depend on the asset type.
senderName
string
Human readable name for the sender. 30 character limit.
suppressNotification
boolean
Suppress notifications from Centrapay (SMS/Email).
expiresAt
timestamp
The time that the asset transfer will expire.
claimType
stringexperimental
'multi' if the asset transfer can be claimed by multiple users, 'single' if it can only be claimed by one user. Defaults to 'single'.
valueConfig
objectexperimental
The configuration of the value of the asset being transferred for each claim. Required if claimType is multi. The value must be less than or equal to the total value of the asset transfer.
claimConditions
arrayexperimental
Array of claim conditions that must be met to successfully claim the asset transfer.
loyaltyProgramId
string
The ID of the Loyalty Program to associate with this asset transfer.

Errors

INSUFFICIENT_WALLET_BALANCE
403
The value of the asset-transfer exceeds the balance on the wallet asset.
QUOTA_EXCEEDED
403
The transfer exceeds one or more spend quota limits. See Quota Error Response.
ASSET_NOT_ACTIVE
403
The asset is not active and cannot be transferred.
RECIPIENT_MISSING
403
The asset must be transferred with a recipient supplied.
INVALID_ASSET_TYPE
403
The asset's type does not support transfers.
LOYALTY_PROGRAM_NOT_FOUND
403
The loyalty program does not exist.

curl -X POST https://service.centrapay.com/api/asset-transfers \
-H 'content-type: application/json' \
-H 'x-api-key: <TOKEN>' \
-d '{
  "assetId": "YGRo6TYYSxH3js7",
  "value": "1000",
  "message": "Happy birthday",
  "senderName": "My Cafe",
  "claimType": "multi",
  "valueConfig": {
    "type": "flat",
    "params": {
      "amount": "100"
    }
  },
  "claimConditions": [
    {
      "type": "frequency",
      "params": {
        "period": "lifetime",
        "limit": "1"
      }
    }
  ],
  "expiresAt": "2020-05-03T01:03:37.222Z",
  "loyaltyProgramId": "WRhAxxWpTKb5U7pXyxQjjY"
}'

{
  "id": "M7Kn2stAxNa6ri7h",
  "status": "created",
  "value": "1000",
  "assetId": "YGRo6TYYSxH3js7",
  "assetType": "centrapay.ledger.main",
  "assetCollectionId": "c_Xv990BzkgfoDS7bBls50pd",
  "description": "Centrapay Ledger",
  "message": "Happy birthday",
  "senderName": "My Cafe",
  "createdAt": "2020-05-01T12:30:00.000Z",
  "updatedAt": "2020-05-02T01:03:37.222Z",
  "suppressNotifications": false,
  "claimType": "multi",
  "expiresAt": "2020-05-03T01:03:37.222Z",
  "valueConfig": {
    "type": "flat",
    "params": {
      "amount": "100"
    }
  },
  "claimConditions": [
    {
      "type": "frequency",
      "params": {
        "period": "lifetime",
        "limit": "1"
      }
    }
  ],
  "remainingValue": "1000",
  "loyaltyProgramId": "WRhAxxWpTKb5U7pXyxQjjY"
}

Get an Asset Transfer

curl -X GET https://service.centrapay.com/api/asset-transfers/M7Kn2stAxNa6ri7h \
-H 'x-api-key: <TOKEN>'

{
  "id": "M7Kn2stAxNa6ri7h",
  "status": "claimed",
  "value": "6000",
  "assetId": "YGRo6TYYSxH3js7",
  "assetType": "centrapay.token.main",
  "description": "Centrapay Token",
  "message": "Happy birthday",
  "senderName": "My Cafe",
  "recipientAccountId": "9EDxUT91TMsUjoqoQeBuLQ",
  "claimedByAccountId": "9EDxUT91TMsUjoqoQeBuLQ",
  "recipientAlias": "+64******2345",
  "createdAt": "2020-05-01T12:30:00.000Z",
  "updatedAt": "2020-05-02T01:03:37.222Z",
  "suppressNotifications": false
}

Get Asset Transfer Summary

curl -X GET https://service.centrapay.com/api/asset-transfers/M7Kn2stAxNa6ri7h/summary

{
  "id": "M7Kn2stAxNa6ri7h",
  "status": "created",
  "assetId": "YGRo6TYYSxH3js7",
  "message": "Happy birthday",
  "senderName": "My Cafe",
  "createdAt": "2020-05-01T12:30:00.000Z",
  "url": "https://app.centrapay.com/transfer/M7Kn2stAxNa6ri7h",
  "assetCollectionId": "c_Xv990BzkgfoDS7bBls50pd"
}

Claim Asset Transfer experimental

Claim the asset transfer for the caller's authorised account.

Errors

ASSET_TRANSFER_INVALID_RECIPIENT
403
The asset transfer already has a recipient defined through the recipientAlias field and cannot be claimed with this API.
ASSET_TRANSFER_INVALID_STATUS
403
The asset transfer is not in a sent status and hence cannot be claimed.
ASSET_TRANSFER_CLAIM_CONDITIONS_NOT_MET
403
The claim has failed because one or more of the claim conditions were not met.

curl -X POST https://service.centrapay.com/api/asset-transfers/M7Kn2stAxNa6ri7h/claim \
-H 'x-api-key: <TOKEN>'

{
  "id": "M7Kn2stAxNa6ri7h",
  "status": "claimed",
  "value": "6000",
  "assetId": "YGRo6TYYSxH3js7",
  "description": "$60 Giftcard",
  "message": "Happy birthday",
  "senderName": "My Cafe",
  "senderAccountId": "aBc932S9182qwCDqwer",
  "recipientAccountId": "9EDxUT91TMsUjoqoQeBuLQ",
  "claimedByAccountId": "9EDxUT91TMsUjoqoQeBuLQ",
  "createdAt": "2020-05-01T12:30:00.000Z",
  "updatedAt": "2020-05-02T01:03:37.222Z",
  "suppressNotifications": false
}

Resolve Claimable Assets experimental

When you send another centrapay user cash or assets, they're automatically assigned to them. However, if they're not signed up yet then these assets are not immediately assigned.

If unclaimed, asset transfers are returned after 2 weeks.

New accounts should call this endpoint to allocate assets that you've been sent.

curl -X POST https://service.centrapay.com/api/me/resolve-claimable-assets \
-H 'x-api-key: <TOKEN>'

{}

List Asset Transfers experimental

Returns a paginated list of Asset Transfers.

Attributes

recipientAccountId
string
The Centrapay Account id of the recipient.
senderAccountId
string
The Centrapay Account id of the sender.

curl -X GET 'https://service.centrapay.com/api/asset-transfers?recipientAccountId=oS3Xom2au3Ooy9aihai' \
-H 'x-api-key: <TOKEN>'

{
  "items": [
    {
      "id": "M7Kn2stAxNa6ri7h",
      "status": "created",
      "value": "6000",
      "assetId": "YGRo6TYYSxH3js7",
      "description": "$60 Giftcard",
      "message": "Happy birthday",
      "senderName": "My Cafe",
      "senderAccountId": "aBc932S9182qwCDqwer",
      "recipientAccountId": "9EDxUT91TMsUjoqoQeBuLQ",
      "claimedByAccountId": "9EDxUT91TMsUjoqoQeBuLQ",
      "recipientAlias": "+64*****2345",
      "createdAt": "2020-05-01T12:30:00.000Z",
      "updatedAt": "2020-05-02T01:03:37.222Z",
      "suppressNotifications": false
    }
  ]
}

Cancel an Asset Transfer

Errors

INVALID_ASSET_TRANSFER_STATUS
403
The asset transfer status is invalid and cannot be cancelled.

curl -X POST https://service.centrapay.com/api/asset-transfers/M7Kn2stAxNa6ri7h/cancel \
-H 'x-api-key: <TOKEN>'

{
  "id": "M7Kn2stAxNa6ri7h",
  "status": "cancelled",
  "assetId": "YGRo6TYYSxH3js7",
  "value": "6000",
  "description": "$60 Giftcard",
  "message": "Happy birthday",
  "senderName": "My Cafe",
  "senderAccountId": "aBc932S9182qwCDqwer",
  "recipientAccountId": "9EDxUT91TMsUjoqoQeBuLQ",
  "recipientAlias": "+64*****2345",
  "createdAt": "2020-05-01T12:30:00.000Z",
  "updatedAt": "2020-05-02T01:03:37.222Z",
  "suppressNotifications": false
}

Asset Transfer Model

Attributes

id

status

value

assetId

assetType

assetCollectionId

description

message

lastSentTo

senderAlias

senderName

recipientAccountId

senderAccountId

claimedByAccountId

recipientAlias

createdAt

updatedAt

suppressNotification

url

claimType

valueConfig

claimConditions

remainingValue

expiresAt

loyaltyProgramId

Asset Transfer lifecycle

Create an Asset Transfer

Attributes

assetId

recipientAlias

description

message

value

senderName

suppressNotification

expiresAt

claimType

valueConfig

claimConditions

loyaltyProgramId

Errors

INSUFFICIENT_WALLET_BALANCE

QUOTA_EXCEEDED

ASSET_NOT_ACTIVE

RECIPIENT_MISSING

INVALID_ASSET_TYPE

LOYALTY_PROGRAM_NOT_FOUND

Get an Asset Transfer

Get Asset Transfer Summary

Claim Asset Transfer experimental

Errors

ASSET_TRANSFER_INVALID_RECIPIENT

ASSET_TRANSFER_INVALID_STATUS

ASSET_TRANSFER_CLAIM_CONDITIONS_NOT_MET

Resolve Claimable Assets experimental

List Asset Transfers experimental

Attributes

recipientAccountId

senderAccountId

Cancel an Asset Transfer

Errors

INVALID_ASSET_TRANSFER_STATUS