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

State	Description
requested	Asset transfer successfully requested
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.

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.

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"
}
'

{
  "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"
}

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

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"
}
'

{
  "assetTransferId": "M7Kn2stAxNa6ri7h",
  "status": "accepted",
  "type": "asset-transfer:accepted",
  "createdAt": "2020-05-02T01:03:37.222Z",
  "createdBy": "sdasd98199dadas",
  "assetId": "YGRo6TYYSxH3js7",
  "senderName": "Jane Doe",
  "value": "1000"
}

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.

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"
}
'

{
  "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 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"
}

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.

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

description

message

lastSentTo

senderAlias

senderName

recipientAccountId

senderAccountId

claimedByAccountId

recipientAlias

createdAt

updatedAt

suppressNotification

url

Asset Transfer lifecycle

Request an Asset Transfer experimental

Attributes

recipientAlias

senderAccountId

assetType

description

message

suppressNotification

Errors

SENDER_NOT_FOUND

INVALID_ASSET_TYPE

Accept an Asset Transfer Request experimental

Attributes

assetId

senderName

value

Errors

ASSET_TRANSFER_REQUEST_EXPIRED

ASSET_TRANSFER_REQUEST_ACCEPTED

BANK_ACCOUNT_BALANCE_INSUFFICIENT

QUOTA_EXCEEDED

ASSET_NOT_ACTIVE

INVALID_ASSET_TYPE

VALUE_NOT_DEFINED

VALUE_ALREADY_DEFINED

Create an Asset Transfer

Attributes

assetId

recipientAlias

description

message

value

senderName

suppressNotification

Errors

INSUFFICIENT_WALLET_BALANCE

QUOTA_EXCEEDED

ASSET_NOT_ACTIVE

RECIPIENT_MISSING

INVALID_ASSET_TYPE

Get an Asset Transfer

Get Asset Transfer Summary

Claim Asset Transfer experimental

Errors

ASSET_TRANSFER_INVALID_RECIPIENT

ASSET_TRANSFER_INVALID_STATUS

Resolve Claimable Assets experimental

List Asset Transfers experimental

Attributes

recipientAccountId

senderAccountId

Cancel an Asset Transfer

Errors

INVALID_ASSET_TRANSFER_STATUS