Transaction Request Body (Earn)
In this chapter, we will explain how to fill the body of transaction requests.
Minimal Transaction Body (Mandatory Fields)
The minimal set of receipt information (containing only mandatory fields) is the following:
{
"transactionType": "EARNTRANSACTION",
"amount": 99.90
}with mandatory attributes
| Attribute | Description |
|---|---|
| transactionType | Type of the transaction. For digital receipt, always use the value EARNTRANSACTION |
| amount | Total amount of the bon. |
Maximal Transaction Body (Optional Fields)
The minimal setup is only providing the minimal functionality (i.e. store purchase-totals and connect them with loyalty-accounts). In order to benefit from a range of modules in the Convercus system, it may be necessary to add optional attributes.
The following example will give a maximal set of receipt information. The relevant fields for your implementation depend on the system and program setup and need to be coordinated with the program manager.
{
"transactionType": "EARNTRANSACTION",
"transactionTime": "2020-04-30T10:50:00+02:00",
"valueTime": "2020-04-30T10:50:00+02:00",
"externalId": "UniqueBonID",
"amount": 99.90,
"currencyCode": "EUR",
"lineItems": \[...],
"tenderItems": \[...],
"linkedTransaction": \{...}
"receiptImageData": "iVBORw0KGgoA...."
"receiptImageUrl": "[https://www..../receit1.png](https://www..../receit1.png)",
"reason": "Thank you for your purchase"
}The following attributes may be used (if not stated otherwise, every attribute may only be used once):
| Attribute | Description | Relevance |
|---|---|---|
| transactionType | Type of the transaction. For digital receipt, also use the value EARNTRANSACTION | Mandatory |
| transactionTime | ISO 8601 datetime, when the transaction was created (i.e. datetime of the receipt). Either give the datetime in UTC (eg. 2020-04-08T10:50:00Z or in local-time with timezone (e.g. 2020-04-08T10:50:00+02:00 for CET with daylight-saving-time or 2020-01-08T10:50:00+01:00CET). | Optional |
| valueTime | ISO 8601 value datetime of the transaction (i.e. the datetime, when the booked transaction-points become active). Note: If this field is missing, the valueTime will be set to the time, when the transaction is processed in Convercus system. Do not fill this field unless you don’t want to have this standard-situation. | Optional |
| externalId | Unique (over the program) Bon-ID. As a security measure (don’t incentivate the same bon twice), reoccuring bons with the same externalID are rejected by the system, so make sure that every bon-id is unique. | Optional |
| amount | Total amount of the bon. Important: This amount should always be the same as the sum of all purchases and returns of the bon. Convercus-system rejects bons, where the amount is less the sum of lineItems. Any deviation should be checked before sending the bon as there may be an error in the bon-structure (e.g. missing positions). | Mandatory |
| taxRate | DEPRECIATED - is now at lineItem level | Depreciated |
| currencyCode | Currency Code (e.g. EUR) of the total amount. | Optional |
| lineItems | List of purchased line items of the bon. This attribute will be explained in more Detail in the respective subchapter. | Optional |
| tenderItems | List of payment items of the bon. This attribute will be explained in more Detail in the respective subchapter. | Optional |
| linkedTransaction | Link to an existing transaction. This attribute will be explained in more Detail in the respective subchapter. | Optional |
| receiptImageData | The image resource encoded as Base64 string. | Optional |
| receiptImageUrl | Optional | |
| reason | This is a freetext, used to display the list of purchases in the Convercus app, and also visible in the Admin Portal. Example: “Thank you for your purchase.” | Optional |
lineItems Attribute
The minimal required set of information for a line-item is the following:
"lineItems": \[
\{
"sequenceNumber": 1,
"type": "SALE",
"itemID": "2758221",
"extendedAmount": 199.80
},
...
]with mandatory attributes:
| Attribute | Description |
|---|---|
| sequenceNumber | Sequence number of the line-item. This value is incremented with every line-item, starting at 1. |
| type | Type of the transaction. The values SALE and RETURN are used to differentiate the processes of purchase and cancellation / return. |
| itemID | This is the unique identifier of the product. Usually this is the article code in an external system (e.g. barcode). Note about Incentivation: On the level of this ID, it is possible to define incentivation rules (i.e. exclusion or multiple points). Thus, the set of IDs for this should be consistent over the whole program. |
| extendedAmount | This is the actual amount, this item was sold for. Accordingly, this value has to incorporate all given discounts. Note: Depending on the type of line-item, one has to keep track of the signs of this amount: SALE-transactions have positive signs, RETURN-transactions have negative signs. |
Like before, the minimal setup is only providing the minimal functionality, which may be extended by adding optional attributes. For example, in order to be able to make special incentivation for certain line-items (e.g. exclusion from incentivation, extra-points), it’s important to provide a detailed and consistent set of information about the product itself.
In the following we will show maximal sets of information, also stressing the difference between SALE- and RETURN-transactions a little more.
Maximal SALE-lineItem
The SALE is most common and most important line-item-type as this is classic purchase line-item. Every purchase, which is printed on the bon should also be added to the lineItem-list.
Note, that Discounts should not produce a line-item for themselves. It is possible to track original pricing in the lineItem-element itself.
The following example will give a maximal set of SALE-line-item-information. The relevant fields for your implementation depend on the system and program setup and need to be coordinated with the program manager.
"lineItems": \[
\{
"sequenceNumber": 1,
"type": "SALE",
"itemID": "2758221",
"merchandiseGroupCode": "1201",
"merchandiseGroupName": "Shoes",
"merchandiseSubGroupCode": "120103",
"merchandiseSubGroupName": "Sneakers",
"brandCode": "10543280-CODE 123",
"description": "Test-Shoe",
"actualSalesUnitPrice": 99.90,
"quantity": 2,
"extendedAmount": 199.80,
"currencyCode": "EUR",
"taxRate": 19.00
}
]The following attributes may be used (if not stated otherwise, every attribute may only be used once):
| Attribute | Description | Relevance |
|---|---|---|
| sequenceNumber | Sequence number of the line-item. This value is incremented with every line-item, starting at 1. | Mandatory |
| type | Type of the transaction. For purchases, the value is SALE. | Mandatory |
| itemID | This is the unique identifier of the product. Usually this is the article code in an external system (e.g. barcode). Note about Incentivation: On the level of this ID, it is possible to define incentivation rules (i.e. exclusion or multiple points). Thus, the set of IDs for this should be consistent over the whole program. | Mandatory |
| merchandiseGroupCode | This is the unique identifier of the product's merchandise group. Note about Incentivation: On the level of the ID, it is possible to define incentivation rules (i.e. exclusion or multiple points). Thus, the set of IDs for this should be consistent over the whole program. | Optional |
| merchandiseGroupName | This is the name of the product’s merchandise group. | Optional |
| merchandiseSubGroupCode | This is the unique identifier of the product's merchandise subgroup. Note about Incentivation: On the level of the ID, it is possible to define incentivation rules (i.e. exclusion or multiple points). Thus, the set of IDs for this should be consistent over the whole program. | Optional |
| merchandiseSubGroupName | This is the name of the product’s merchandise subgroup. | Optional |
| brandCode | This is the unique identifier for the product’s brand. The BrandCode can be used in coupon rules and as a trigger for checkout coupons. | Optional |
| description | This is the name or description of the product. | Optional |
| actualSalesUnitPrice | This is the amount, a single item was sold for. So this value is equal to the regular unit price - all discounts on the level of this product. Note: For SALE-transaction, this value is always positive. | Optional |
| quantity | This is the number of units, that were sold in this line-item. | Optional |
| extendedAmount | This is the actual amount, this item was sold for. Accordingly, this value has to incorporate all given discounts. Note: For SALE-transaction, this value is always positive. | Mandatory |
| currencyCode | Currency Code (e.g. EUR) of the extendedAmount. | Optional |
| taxRate | Percentage of tax applied for this line-item. | Optional |
Maximal Return-lineItem
As it is also pretty common to have negative bookings in a bon, as products may be returned or cancelled altogether. Such line-items may be added as a RETURN-line-item. However, there are a few things, to be minded.
Note about the difference between Cancellation and Returns
The Convercus system does not differentiate between cancellation and return as both do basically the same: They refer to a previous, positive purchase / booking and negate it by adding a negativ purchase / booking.
Thus, all negative bookings (i.e. returns and cancellations) shall be mapped to a RETURN-line-item.
Note about the setup of Return line-items
RETURN-line-items have to have the exact same setup as the corresponding SALE-Line-item had. This secures the same treatment of the return while processing in order to rebook points. Therefore, especially all discounts given to the initial booking have to be added to the RETURN-item as well (so that the price is correct). Furthermore, the same product information has to be given (so that incentivation exclusion and extra-points are handled correctly). Note however, that RETURN-line-amounts have to have negative signs.
The following example will give a maximal set of RETURN-line-item-information. The relevant fields for your implementation depend on the system and program setup and need to be coordinated with the program manager.
"lineItems": [
{
"sequenceNumber": 1,
"type": "RETURN",
"itemID": "2758221",
"merchandiseGroupCode": "1201",
"merchandiseGroupName": "Shoes",
"merchandiseSubGroupCode": "120103",
"merchandiseSubGroupName": "Sneakers",
"brandCode": "10543280-CODE 123",
"description": "Test-Shoe",
"currencyCode": "EUR",
"actualSalesUnitPrice": -99.90,
"quantity": 1,
"extendedAmount": -99.90,
"taxRate": 19.00
}
]The following attributes may be used (if not stated otherwise, every attribute may only be used once):
| Attribute | Description | Relevance |
|---|---|---|
| sequenceNumber | Sequence number of the line-item. This value is incremented with every line-item, starting at 1. | Mandatory |
| type | Type of the transaction. For cancellations and returns, the value is RETURN. | Mandatory |
| itemID | This is the unique identifier of the product. Usually this is the article code in an external system (e.g. barcode). Note about Incentivation: On the level of this ID, it is possible to define incentivation rules (i.e. exclusion or multiple points). Thus, the set of IDs for this should be consistent over the whole program. | Mandatory |
| merchandiseGroupCode | This is the unique identifier of the product's merchandise group. Note about Incentivation: On the level of the ID, it is possible to define incentivation rules (i.e. exclusion or multiple points). Thus, the set of IDs for this should be consistent over the whole program. | Optional |
| merchandiseGroupName | This is the name of the product’s merchandise group. | Optional |
| merchandiseSubGroupCode | This is the unique identifier of the product's merchandise subgroup. Note about Incentivation: On the level of the ID, it is possible to define incentivation rules (i.e. exclusion or multiple points). Thus, the set of IDs for this should be consistent over the whole program. | Optional |
| merchandiseSubGroupName | This is the name of the product’s merchandise subgroup. | Optional |
| brandCode | This is the unique identifier for the product’s brand. The BrandCode can be used in coupon rules and as a trigger for checkout coupons. | Optional |
| description | This is the name or description of the product. | Optional |
| actualSalesUnitPrice | This is the amount, a single item was returned for. So this value is equal to the rebooked regular unit price - all discounts on the level of this product. Note: For RETURN-transaction, this value is always negative. | Optional |
| quantity | This is the number of units, that were returned in this line-item. | Optional |
| extendedAmount | This is the actual amount, this item was returned for. Accordingly, this value has to incorporate all given discounts. Note: For RETURN-transaction, this value is always negative. | Mandatory |
| currencyCode | Currency Code (e.g. EUR) of the extendedAmount. | Optional |
| taxRate | Percentage of tax applied for this line-item. | Optional |
Excluding lineItem from point incentivation
add description here
Blacklisting: lineItems can be excluded from points incentivation by referencing the itemID, merchandiseGroupCode or merchandiseSubGroupCode
tenderItems Attribute
In addition to the purchased articles, it may also be reasonable to document payment-methods - especially, for the tracking of gift-cards and pay-with-points transactions. These payment methods may be added to a list of tenderItems.
Minimal tenderItem
The minimal required set of information for a tender-item is the following:
"tenderItems": [
{
"sequenceNumber": 3,
"amount": 10.00
}
]with mandatory attributes:
| Attribute | Description |
|---|---|
| sequenceNumber | Sequence number of the line-item. This value is incremented with every item. It may start with 1 or continue the line-item sequence numbering. |
| amount | This is the amount, that was paid in the format of the respective payment method. |
Maximal tenderItem
Again, the minimal setup is only providing the minimal functionality, which may be extended by adding optional attributes. For example, it is common to allow multiple payment-methods at the same time, which may be documented.
In the following, we will show maximal set of information, where also multiple payment methods were used. The relevant fields for your implementation depend on the system and program setup and need to be coordinated with the program manager.
"tenderItems": [
{
"sequenceNumber": 3,
"tenderType": "Loyalty",
"tenderId": "PayWithPoints",
"amount": 10.00,
"currencyCode": "EUR",
"taxRate": 19.00
},
{
"sequenceNumber": 4,
"tenderType": "GiftCard",
"tenderId": "Geschenkkarte50",
"amount": 50.00,
"currencyCode": "EUR",
"taxRate": 19.00
},
{
"sequenceNumber": 5,
"tenderType": "Cash",
"tenderId": "Barzahlung",
"amount": 39.90,
"currencyCode": "EUR",
"taxRate": 19.00
}
]The following attributes may be used (if not stated otherwise, every attribute may only be used once):
| Attribute | Description | Relevance |
|---|---|---|
| sequenceNumber | Sequence number of the line-item. This value is incremented with every item. It may start with 1 or continue the line-item sequence numbering. | Mandatory |
| tenderType | This attribute defines the payment method description in the third party system. It should be secured, that these descriptions are consistent. | Optional |
| tenderId | This attribute defines the payment method ID in the third party system. It should be secured, that these IDs are consistent. | Optional |
| amount | This is the amount, that was paid in the format of the respective payment method. | Mandatory |
| currencyCode | Currency Code (e.g. EUR) of the amount. Note: Always use real currencies (or the equivalent of a pseudo-currency in a real currency) here. Example: If a amount of 5,00 EUR was paid with Loyalty points, give the amount of 5,00 EUR (and not the amount of burned points). | Optional |
| taxRate | Percentage of tax applied for this payment method. | Optional |
Note:
Always keep in mind, that the sum of all payment-amounts should get the same value as the bon-total-amount.
linkedTransaction
If a transaction has to be linked to an older transaction (e.g. a return, which is mapped to the original sale), the following attribute can be added:
"linkedTransaction": \{
"linkType": "EXTERNALID",
"linkValue": "bon\_id\_123456"
}with mandatory attributes:
| Attribute | Description |
|---|---|
| linkType | Identifier-Type (corresponding to the linkValue). Available values: TRANSACTIONID Convercus-ID of original transaction e.g. db1234b5-67fd-8912-3c4e-56789ac57595 EXTERNALID Original-ID of the transaction e.g. bon_id_123456 |
| linkValue | Value of the above linkType. |
Maximal Example JSON
Summarising everything, this is an example maximal JSON, with incorporates almost all previous settings (valueTime was omitted as here, the booking is to be expected after processing).
{
"transactionType": "EARNTRANSACTION",
"transactionTime": "2020-04-08T10:50:00+02:00",
"externalId": "UniqueBonID",
"amount": 99.90,
"currencyCode": "EUR",
"reason": "Thank you for your purchase",
"lineItems": [
{
"sequenceNumber": 1,
"type": "SALE",
"itemID": "2758221",
"merchandiseGroupCode": "1201",
"merchandiseGroupName": "Shoes",
"merchandiseSubGroupCode": "120103",
"merchandiseSubGroupName": "Sneakers",
"brandCode": "10543280-CODE 123",
"description": "Test-Shoe",
"actualSalesUnitPrice": 99.90,
"quantity": 2,
"extendedAmount": 199.80,
"currencyCode": "EUR",
"taxRate": 19.00
},
{
"sequenceNumber": 2,
"type": "RETURN",
"itemID": "2758221",
"merchandiseGroupCode": "1201",
"merchandiseGroupName": "Shoes",
"merchandiseSubGroupCode": "120103",
"merchandiseSubGroupName": "Sneakers",
"brandCode": "10543280-CODE 123",
"description": "Test-Shoe",
"actualSalesUnitPrice": -99.90,
"quantity": 1,
"extendedAmount": -99.90,
"currencyCode": "EUR",
"taxRate": 19.00
}
],
"tenderItems": [
{
"sequenceNumber": 3,
"tenderType": "Loyalty",
"tenderId": "PayWithPoints",
"amount": 10.00,
"currencyCode": "EUR",
"taxRate": 19.00
},
{
"sequenceNumber": 4,
"tenderType": "GiftCard",
"tenderId": "Geschenkkarte50",
"amount": 50.00,
"currencyCode": "EUR",
"taxRate": 19.00
},
{
"sequenceNumber": 5,
"tenderType": "Cash",
"tenderId": "Barzahlung",
"amount": 39.90,
"currencyCode": "EUR",
"taxRate": 19.00
}
],
"linkedTransaction": {
"linkType": "EXTERNALID",
"linkValue": "bon_id_123456"
}
"receiptImageData": "iVBORw0KGgoAAAAN.......",
}Updated 2 months ago