The Payment API enables you to associate any data you wish to any type of transaction by using the flexible metadata property in your requests. This elegant approach to handling key business data allows you to create fields that append key information to a payment, such as product info, customer info, key dates, shipping and tax, or more. By using metadata, you can store the info that is most useful for your business and build the reporting needed.
See:
How to use metadata
The metadata functionality with our Payment API enables you to directly attach key-value pairs to your transactions, and the details of the metadata will be associated with the transactionId. You can then store the metadata fields in your own local database using a reference to the transactionId.
Each request can contain up to 20 keys, with key names up to 40 characters long and values up to 500 characters long, providing excellent flexibility to use the metadata fields as you see fit. You can also include a description of up to 40 characters to provide more details about the data. For more information, see metadata.
The metadata specified in the API request is stored at BlueSnap and returned in the API response. However, your metadata is not used by BlueSnap (for example to process transactions), and it will not be displayed to shoppers unless you choose to show it.
Example: Shipping and tax info
Using metadata to handle shipping and tax records is one great use case. As you expand your business and sell in more locations, you are constantly faced with how to handle VAT/Tax and shipping details. The metadata functionality allows you to attach this extra information as part of the transaction.
For example, you might have an order for a total amount of $200 dollars, which includes:
- $150 for the product that was ordered
- $20 for state tax
- $20 for city tax
- $10 for shipping
You would send $200 in the amount property in the request, and then specify the different tax and shipping amounts in the transactionMetaData object. This information will be returned to you along with the transaction ID in the response, so you can easily mark the correct amounts for the product, tax, and shipping in your internal system. This is shown in the sample request and response below.
{
"amount": 200,
"cardHolderInfo": {
"firstName": "test first name",
"lastName": "test last name"
},
"currency": "USD",
"creditCard": {
"expirationYear": 2016,
"cardType": "VISA",
"securityCode": 111,
"expirationMonth": "07",
"cardNumber": 4012000033330026
},
"cardTransactionType": "AUTH_ONLY",
"transactionMetaData": {"metaData": [
{
"metaValue": 20,
"metaKey": "stateTaxAmount",
"metaDescription": "State Tax Amount"
},
{
"metaValue": 20,
"metaKey": "cityTaxAmount",
"metaDescription": "City Tax Amount"
},
{
"metaValue": 10,
"metaKey": "shippingAmount",
"metaDescription": "Shipping Amount"
}
]}
}
{
"amount": 200,
"processingInfo": {
"avsResponseCodeAddress": "U",
"processingStatus": "success",
"cvvResponseCode": "MA",
"avsResponseCodeName": "U",
"avsResponseCodeZip": "U"
},
"cardHolderInfo": {
"firstName": "test first name",
"lastName": "test last name"
},
"avsResponseCode": "G",
"currency": "USD",
"creditCard": {
"cardLastFourDigits": "0026",
"cardSubType": "CREDIT",
"cardType": "VISA"
},
"cardTransactionType": "AUTH_ONLY",
"transactionMetaData": {"metaData": [
{
"metaValue": 20,
"metaKey": "stateTaxAmount",
"metaDescription": "State Tax Amount"
},
{
"metaValue": 20,
"metaKey": "cityTaxAmount",
"metaDescription": "City Tax Amount"
},
{
"metaValue": 10,
"metaKey": "shippingAmount",
"metaDescription": "Shipping Amount"
}
]},
"transactionId": 38497126
}
Example: Product info
You can use metadata to transmit information about the products ordered. For example, if the order is for a medium sized blue t-shirt, you can easily associate this information to the transaction by sending it in the transactionMetaData object. Another use case for the transactionMetaData object is using it to include a product's name in your API request. Passing the product name using API parameters will also ensure that you are able to add the product name to your invoices. Add the transactionMetaData object to your request, enter "product name" as the metaKey, enter your product name as the metaValue, and be sure to include the isVisible parameter with a value of "Y". See example requests below.
{
"amount": 20,
"cardHolderInfo": {
"firstName": "test first name",
"lastName": "test last name"
},
"currency": "USD",
"creditCard": {
"expirationYear": 2016,
"cardType": "VISA",
"securityCode": 111,
"expirationMonth": "07",
"cardNumber": 4012000033330026
},
"cardTransactionType": "AUTH_ONLY",
"transactionMetaData": {"metaData": [
{
"metaValue": "tshirt",
"metaKey": "type",
"metaDescription": "item type"
},
{
"metaValue": "m",
"metaKey": "size",
"metaDescription": "size info - s/m/l/xl"
},
{
"metaValue": "blue",
"metaKey": "color",
"metaDescription": "item color"
}
]}
}
{
"amount": 20,
"processingInfo": {
"avsResponseCodeAddress": "U",
"processingStatus": "success",
"cvvResponseCode": "MA",
"avsResponseCodeName": "U",
"avsResponseCodeZip": "U"
},
"cardHolderInfo": {
"firstName": "test first name",
"lastName": "test last name"
},
"avsResponseCode": "G",
"currency": "USD",
"creditCard": {
"cardLastFourDigits": "0026",
"cardSubType": "CREDIT",
"cardType": "VISA"
},
"cardTransactionType": "AUTH_ONLY",
"transactionMetaData": {"metaData": [
{
"metaValue": "tshirt",
"metaKey": "type",
"metaDescription": "short-sleeve t-shirt"
},
{
"metaValue": "m",
"metaKey": "size",
"metaDescription": "size info - s/m/l/xl"
},
{
"metaValue": "blue",
"metaKey": "color",
"metaDescription": "item color"
}
]},
"transactionId": 12345678
}