Go to home page
Docs

Guides

Loading and Sending Assets

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

Request
POST/api/asset-transfers
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.

Request
POST/api/asset-transfers
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"
  }'

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.

Request
POST/api/asset-transfers
curl -X POST https://service.centrapay.com/api/asset-transfers \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "assetId": "YGRo6TYYSxH3js7"
  }'
Response
{
  "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:

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

Example
#!/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);