Burn Interface (PayWithPoints)

The possibility to make (partial) payments with earned points is a common feature in Loyalty programs. In this chapter, we will explain how to implement this payment method using Convercus API.

Getting current Account Balance

Before payments with points can be made, it is necessary to get the current account balance. There are two ways to get the balance.

The following request will respond the current amount of points on a certain account:

curl --location --request GET '{{api_url}}/accounts/{{accountId}}/balance' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'id-type: {{idType}}' \
--header 'Content-Type: application/json' \

whereas the following request (note the difference in the url) will respond the value of those points in Euro as amount.

curl --location --request GET '{{api_url}}/accounts/{{accountId}}/balance/EUR' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'id-type: {{idType}}' \
--header 'Content-Type: application/json' \
The ladder option offers a shortcut for payment implementation as the (possibly not static) calculation of the account balances financial value is already performed by the Convercus System.
The used variables in the requests are the following

PayWithPoints-Transaction

Like all API-bookings, paying with points is also handled via account-transaction. Analogously, the following request has to be sent to burn points by paying with them:

curl --location --request POST '{{api_url}}/accounts/{{accountId}}/transactions' \
--header 'Authorization: {{jwt_token}}' \
--header 'interaction-id: {{interactionId}}' \
--header 'id-type: {{idType}}' \
--header 'Content-Type: application/json' \
--data-raw '{{body}}'

where again

PAYWITHPOINTSTRANSACTION-Body

The minimal set of body information about payments with points is the following

{
"transactionType": "PAYWITHPOINTSTRANSACTION",
"amount": 5.00
}

with the following mandatory attributes

Once again, the minimal setup is only providing the minimal functionality (i.e. burn the amount of points that’s worth the amout you want to pay with).

The following example will give a maximal set of PayWithPoints information. The relevant fields for your implementation depend on the system and program setup and need to be coordinated with the program manager.

{
"transactionType": "PAYWITHPOINTSTRANSACTION",
"reason": "Paying with Points",
"transactionTime": "2020-04-30T10:50:00+02:00",
"valueTime": "2020-04-30T10:50:00+02:00",
"externalId": "UniqueBonID",
"amount": 5.00,
"currencyCode": "EUR",
"linkedTransaction": {
"linkType": "EXTERNALID",
"linkValue": "bon_id_123456"
}
}

The following attributes may be used (if not stated otherwise, every attribute may only be used once):

Note, that the basic setup is similar to the EARN-case above. However, the usage of lineItems and tenderItems is not meaningful here.

Connection between EARN and BURN transactions

It is very important to note, that receipts where a (partial) payment is made with points requires two transaction requests - one for the payments with points (BURN) and one for the bon as a whole (EARN). If payments are tracked in the EARN-bon, make sure to add the correct amount of the PAYWITHPOINTSTRANSACTION to the bon, e.g. add

"tenderItems": [
{
"sequenceNumber": 3,
"tenderType": "Loyalty",
"tenderId": "PayWithPoints",
"amount": 10.00,
"currencyCode": "EUR",
"taxRate": 19.00
},
...
]