Assets API such as Giftcards or Tokens can be issued by a Centrapay Account. They can then be sent to another Centrapay account using one of the methods described below.
Sending Assets
You can send Assets such as Tokens and Giftcards by calling our Create Asset Transfers API endpoint.
For any asset transfer that is not claimed within 2 weeks, the sent asset will be returned to the sender.
Sending to Alias
Provide the recipient’s phone number or email in the recipientAlias
field when creating the asset transfer.
The recipient will be notified via the provided channel.
Use the recipient’s phone number for the recipientAlias
field
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"
}'
Use the recipient’s email for the recipientAlias
field.
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": "john.doe@centrapay.com"
}'
Sending via Link
If a recipientAlias
isn’t provided when creating the asset transfer, a link will be returned in the url
field, which can then be shared via whichever channel you prefer.
Clicking on the link will open a page to view and claim the 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"
}'
{
"id": "EL49tYKmAAkp2njVMs39mrP",
"status": "created",
"assetId": "YGRo6TYYSxH3js7",
"assetType": "centrapay.token.main",
"senderAccountId": "6ZfBR4jls3nR2mpFJQJ6Qg",
"createdAt": "2023-11-20T05:01:31.634Z",
"updatedAt": "2023-11-20T05:01:31.634Z",
"suppressNotifications": false,
"url": "https://app.centrapay.com/transfer/EL49tYKmAAkp2njVMs39mrP"
}
Loading Giftcards
You can load Giftcards by calling our External Assets API endpoint. You will need to use the giftcard number for the externalId
field. The pin
, the issuer
and the type
need to be on hand too.
If your asset type is not included on the list, contact integrations@centrapay.com.
Example: Bulk distribution of Giftcards
Sometimes you might want to load and distribute Giftcards to a large number of recipients. This requires some scripting, but this is not hard. We can do this with:
- A CSV to manage Giftcards to load
- A script to load and send Giftcards
Here’s an example of the CSV named input.csv
:
recipientAlias,cardNumber,pin,message
+64221231234,23403321042,1111,Hello Bob! Here's your giftcard
+64221231235,23403321042,1111,Hello Alice! Here's your giftcard
+64221231236,23403321042,1111,Hello Eve! Here's your giftcard
Phone numbers must start with +64
Here’s an example of the script to parse the CSV and send Giftcards. To run this, you will need:
- Node JS in your environment
- A copy of Axios for HTTP requests
- An API Key API to call our APIs
- Your Account id API for the initial load of each Giftcard
#!/usr/bin/env node
const apiKey = 'api123'; // FIXME
const accountId = 'acc123'; // FIXME
const inputFile = './input.csv';
const type = 'epay.nzd.main';
const category = 'giftcard';
const issuer = 'ezipay';
const baseUrl = 'https://service.centrapay.com';
const axios = require('axios');
const fs = require('fs');
const sleep = require('util').promisify(setTimeout);
// calls axios and return parsed body, sleep and retry if we get 429
async function requestWithRetry(args) {
let response;
try {
response = await axios.request(args);
} catch(err) {
if (err.response.status != 429) {
throw(err);
}
const retrySeconds = Number(err.response.headers['retry-after']) + 1;
await sleep(retrySeconds * 1000);
response = await axios.request(args);
}
return response.data;
}
// loads and sends giftcard to a phone number
async function sendGiftcard({ recipientAlias, cardNumber, pin, message }) {
const asset = await requestWithRetry({
method: 'POST',
url: `${baseUrl}/api/external-assets`,
data: { accountId, pin, category, issuer, type, externalId: cardNumber },
headers: {
'Content-Type': 'application/json',
'X-Api-Key': apiKey,
},
});
const assetTransfer = await requestWithRetry({
method: 'POST',
url: `${baseUrl}/api/asset-transfers`,
data: { recipientAlias, message, assetId: asset.id },
headers: {
'Content-Type': 'application/json',
'X-Api-Key': apiKey,
},
});
return `Sent ${cardNumber} to ${recipientAlias} with assetTransferId ${assetTransfer.id}`;
}
// takes a CSV and returns a list of objects where headings are the keys
function parseCsv(input) {
const lines = String(input).split('\n').filter(line => line.length);
const [headings, ...rows] = lines.map(row => row.split(',').map(cell => cell.trim()));
const objectList = rows.map(values => {
const outRow = {};
for (const [i, heading] of Object.entries(headings)) {
outRow[heading] = values[i]
}
return outRow;
});
return objectList;
}
// loads from input.csv and sends giftcards to people
async function run() {
const start = new Date();
const data = await fs.promises.readFile(inputFile);
const csv = parseCsv(data);
for (const row of csv) {
const msg = await sendGiftcard(row);
console.log(msg);
}
const duration = new Date() - start;
return `Done in ${duration / 1000} seconds`;
}
// entry into the script
run()
.then(console.log)
.catch(console.error);