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.

Attributes

  • id

    string

    The unique identifier.

  • status

    string

    The status of the Asset Transfer. See Asset Transfer lifecycle for possible values.

  • Amount to send. Required for money transfers. Units depend on the asset type.

  • assetId

    string

    Id of a discrete asset to transfer or wallet to draw from.

  • assetType

    string

    The Asset Type  API  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.

  • 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.

  • 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.


Asset Transfer goes through different lifecycle stages.

Asset Transfer Lifecycle

StateDescription
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.

POST/api/asset-transfers

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).

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

  • 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).

Errors

  • INSUFFICIENT_WALLET_BALANCE

    403

    The value of the asset-transfer exceeds the balance on the wallet.

  • QUOTA_EXCEEDED

    403

    The transfer exceeds one or more spend quota limits. See Quota Error Response  API .

  • 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  API  does not support transfers.

Request
POST/api/asset-transfers
curl -X POST \
 https://service.centrapay.com/api/asset-transfers \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "assetId": "YGRo6TYYSxH3js7",
 "recipientAlias": "+642212312"
}
'
Response
{
  "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
}

GET/api/asset-transfers/{assetTransferId}
Request
GET/api/asset-transfers/M7Kn2stAxNa6ri7h
curl -X GET \
 https://service.centrapay.com/api/asset-transfers/M7Kn2stAxNa6ri7h \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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
}

GET/api/asset-transfers/{assetTransferId}/summary
Request
GET/api/asset-transfers/M7Kn2stAxNa6ri7h/summary
curl -X GET \
 https://service.centrapay.com/api/asset-transfers/M7Kn2stAxNa6ri7h/summary
Response
{
  "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"
}

POST/api/asset-transfers/{assetTransferId}/claim

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.

Request
POST/api/asset-transfers/M7Kn2stAxNa6ri7h/claim
curl -X POST \
 https://service.centrapay.com/api/asset-transfers/M7Kn2stAxNa6ri7h/claim \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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
}

POST/api/me/resolve-claimable-assets

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.

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

GET/api/asset-transfers

Returns a paginated  API  list of Asset Transfers.

Attributes

  • recipientAccountId

    string

    The Centrapay Account id of the recipient.

  • senderAccountId

    string

    The Centrapay Account id of the sender.

Request
GET/api/asset-transfers
curl -X GET \
 'https://service.centrapay.com/api/asset-transfers?recipientAccountId=oS3Xom2au3Ooy9aihai' \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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
    }
  ]
}

POST/api/asset-transfers/{assetTransferId}/cancel

Errors

  • INVALID_ASSET_TRANSFER_STATUS

    403

    The asset transfer status is invalid and cannot be cancelled.

Request
POST/api/asset-transfers/M7Kn2stAxNa6ri7h/cancel
curl -X POST \
 https://service.centrapay.com/api/asset-transfers/M7Kn2stAxNa6ri7h/cancel \
 -H 'x-api-key: <TOKEN>'
Response
{
  "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
}