Go to home page
Docs

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 to draw from.

  • assetType

    string

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

Asset Transfer lifecycle

Asset Transfer goes through different lifecycle stages.

Asset Transfer Lifecycle

StateDescription
requestedAsset transfer successfully requested
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-transfer-requests

Request an Asset Transfer experimental

Request a transfer of an asset from a sender to the recipient.

Attributes

  • recipientAlias

    string required

    Contact information, such as phone number, email, or handle, for the individual requesting asset transfer. Currently supports bank account number only.

  • senderAccountId

    string required

    The account id of the sender who receives the request from recipientAlias.

  • assetType

    string required

    The type of asset being transferred. Currently, supports only quartz.nzd assets

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

  • suppressNotification

    boolean

    Suppress notifications from Centrapay (SMS/Email).

Errors

  • SENDER_NOT_FOUND

    403

    The requests must include a valid sender alias.

  • INVALID_ASSET_TYPE

    403

    The asset’s type does not support transfers.

Request
curl -X POST \
 https://service.centrapay.com/api/asset-transfer-requests \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "recipientAlias": "12-1234-1234567-123",
 "senderAccountId": "9EDxUT91TMsUjoqoQeBuLQ",
 "value": "1000",
 "assetType": "quartz.nzd.test"
}
'
Response
{
  "id": "M7Kn2stAxNa6ri7h",
  "recipientAlias": "12-1234-1234567-123",
  "status": "requested",
  "assetType": "quartz.nzd.main",
  "description": "request payment",
  "senderAccountId": "9EDxUT91TMsUjoqoQeBuLQ",
  "createdAt": "2024-03-01T23:56:21.514Z",
  "createdBy": "crn:userId:1234",
  "suppressNotifications": false,
  "value": "1000",
  "message": "Payment request"
}
POST /api/asset-transfer-requests/{assetTransferId}/accept

Accept an Asset Transfer Request experimental

Attributes

  • assetId

    string required

    Id of the asset to pay the asset transfer request with. Only valid for quartz.nzd assets

  • senderName

    string required

    Human readable name for the sender. 30 character limit.

  • value

    bignumber

    Amount to send. Required if not defined in the request; forbidden if it was.

Errors

  • ASSET_TRANSFER_REQUEST_EXPIRED

    403

    The asset transfer request has already expired

  • ASSET_TRANSFER_REQUEST_ACCEPTED

    403

    The asset transfer request has already been accepted

  • BANK_ACCOUNT_BALANCE_INSUFFICIENT

    403

    The bank account the asset is for does not have enough balance for the transfer

  • QUOTA_EXCEEDED

    403

    The asset transfer would exceed the provided assets quotas

  • ASSET_NOT_ACTIVE

    403

    The asset is not active.

  • INVALID_ASSET_TYPE

    403

    The asset’s type does not match the request.

  • VALUE_NOT_DEFINED

    403

    The value of the asset transfer was not defined in either the initial request or the acceptance

  • VALUE_ALREADY_DEFINED

    403

    The value of the asset transfer was defined in both the initial request and the acceptance

Request
curl -X POST \
 https://service.centrapay.com/api/asset-transfer-requests/M7Kn2stAxNa6ri7h/accept \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "assetId": "YGRo6TYYSxH3js7",
 "value": "1000",
 "senderName": "Jane Doe"
}
'
Response
{
  "assetTransferId": "M7Kn2stAxNa6ri7h",
  "status": "accepted",
  "type": "asset-transfer:accepted",
  "createdAt": "2020-05-02T01:03:37.222Z",
  "createdBy": "sdasd98199dadas",
  "assetId": "YGRo6TYYSxH3js7",
  "senderName": "Jane Doe",
  "value": "1000"
}
POST /api/asset-transfers

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

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.

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

Request
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": "centrapay.token.main",
  "description": "Centrapay Token",
  "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}

Get an Asset Transfer

Request
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": "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 /api/asset-transfers/{assetTransferId}/summary

Get Asset Transfer Summary

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

Request
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

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.

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

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.

Request
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

Cancel an Asset Transfer

Errors

  • INVALID_ASSET_TRANSFER_STATUS

    403

    The asset transfer status is invalid and cannot be cancelled.

Request
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
}