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.
After an asset transfer is completed the recipientAlias, lastSentTo and message fields are scrubbed to avoid storing PII.
Contents
- Asset Transfer lifecycle
- Create an Asset Transfer
- Get an Asset Transfer
- Resolve claimable assets EXPERIMENTAL
- List Asset Transfers EXPERIMENTAL
Asset Transfer lifecycle
Asset Transfer goes through different lifecycle stages.
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 |
Create an Asset Transfer
Transfer an asset to a recipient. Some assets can be transfered only in whole (eg giftcards or tokens) while others can be transfered only in part (eg money).
POST /
Whole asset transfer
curl -X POST https://service.centrapay.com/api/asset-transfers \
-H "X-Api-Key: $api_key" \
-H "Content-Type: application/json" \
-d '{
"assetId": "YGRo6TYYSxH3js7",
"recipientAlias": "+642212312"
}'
Partial asset transfer
curl -X POST https://service.centrapay.com/api/asset-transfers \
-H "X-Api-Key: $api_key" \
-H "Content-Type: application/json" \
-d '{
"assetId": "sai2Pai7ohgongo",
"value": "6000",
"recipientAlias": "+642212312"
}'
Required Fields
Parameter | Type | Description |
---|---|---|
assetId | String | Id of a discrete asset to transfer or wallet to draw from. |
recipientAlias | String | Phone number, email or handle of receiver. |
Optional Parameters
Parameter | Type | Description |
---|---|---|
description | String | Shows up in transaction history against the transfer. 200 character limit. |
message | String | A message which shows up in the SMS of the receiver. 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. |
senderAlias | String | Phone number, email or handle of sender to return asset to. See (★) note below. |
suppressNotifications | Boolean | Suppress notifications from Centrapay (SMS/Email). |
★ Only provide a senderAlias value if you are invoking asset transfer with api key. In case that recipient doesn’t claim asset in 2 weeks or asset was sent to an invalid Alias (wrong phone number etc) we will use senderAlias to return the asset. If asset cannot be returned to a sender it will be returned to asset owner.
Example response payload
{
"id": "M7Kn2stAxNa6ri7h",
"status": "created",
"value": "1000",
"assetId": "YGRo6TYYSxH3js7",
"assetType": "epay.nzd.main",
"description": "$60 Giftcard",
"message": "Happy birthday",
"senderName": "My Cafe",
"recipientAccountId": "9EDxUT91TMsUjoqoQeBuLQ",
"claimedByAccountId": "9EDxUT91TMsUjoqoQeBuLQ",
"recipientAlias": "+64212312345",
"createdAt": "2020-05-01T12:30:00.000Z",
"updatedAt": "2020-05-02T01:03:37.222Z",
"suppressNotifications": false
}
The above example has $10 left on a $60 dollar giftcard at the time of transfer.
Error Responses
Status | Code | Description |
---|---|---|
403 | INSUFFICIENT_ | The value of the asset-transfer exceeds the balance on the wallet |
403 | QUOTA_ | The transfer exceeds one or more spend quota limits. See Quota Error Response. |
Get an Asset Transfer
GET /
curl https://service.centrapay.com/api/asset-transfers/M7Kn2stAxNa6ri7h \
-H "X-Api-Key: $api_key"
Example response payload (In-progress money transfer)
{
"id": "M7Kn2stAxNa6ri7h",
"status": "sent",
"value": "6000",
"assetId": "sai2Pai7ohgongo",
"assetType": "centrapay.nzd.main",
"message": "Happy birthday",
"senderName": "My Cafe",
"lastSentTo": "+64212312345",
"senderAccountId": "aBc932S9182qwCDqwer",
"recipientAccountId": "oS3Xom2au3Ooy9aihai",
"claimedByAccountId": "9EDxUT91TMsUjoqoQeBuLQ",
"recipientAlias": "+64212312345",
"createdAt": "2020-05-01T12:30:00.000Z",
"updatedAt": "2020-05-02T01:03:37.222Z",
"suppressNotifications": false
}
Example response payload (completed giftcard transfer)
{
"id": "M7Kn2stAxNa6ri7h",
"status": "claimed",
"value": "6000",
"assetId": "YGRo6TYYSxH3js7",
"assetType": "epay.nzd.main",
"description": "$60 Giftcard",
"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
}
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.
POST /
curl -X POST https://service.centrapay.com/api/me/resolve-claimable-assets \
-H "X-Api-Key: $api_key"
Example response payload
{
}
List Asset Transfers EXPERIMENTAL
Returns a paginated list of Asset Transfers.
GET /
List asset transfers received
curl -G https://service.centrapay.com/api/asset-transfers \
-H "X-Api-Key: $api_key" \
-d recipientAccountId=oS3Xom2au3Ooy9aihai
List asset transfers sent
curl -G https://service.centrapay.com/api/asset-transfers \
-H "X-Api-Key: $api_key" \
-d senderAccountId=aBc932S9182qwCDqwer
Example response payload
{
"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
}
]
}