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
string experimental

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
string experimental

'multi' if the asset transfer can be claimed by multiple users, 'single' if it can only be claimed by one user.
valueConfig
object experimental

The configuration of the value of the asset being transferred for each claim.
claimConditions
array experimental

Array of claim conditions that must be met to successfully claim the asset transfer.
remainingValue
string experimental

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
string required

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
string experimental

'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
object experimental

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
array experimental

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