Asset Transfers - Centrapay Docs

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

POST/api/asset-transfer-requests

Request an Asset Transfer experimental

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

Attributes

recipientAlias
stringrequired
Contact information, such as phone number, email, or handle, for the individual requesting asset transfer. Currently supports bank account number only.
senderAccountId
stringrequired
The account id of the sender who receives the request from recipientAlias.
assetType
stringrequired
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 API does not support transfers.

Request

POST/api/asset-transfer-requests

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
stringrequired
Id of the asset to pay the asset transfer request with. Only valid for quartz.nzd assets
senderName
stringrequired
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 API 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

POST/api/asset-transfer-requests/M7Kn2stAxNa6ri7h/accept

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

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": "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

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

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

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

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

List Asset Transfers experimental

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

Cancel an Asset Transfer

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
}

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