{"_id":"59a45d2bd12e81000f842f09","category":{"_id":"59a45d2bd12e81000f842ef0","version":"59a45d2bd12e81000f842ee2","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-03T20:45:01.593Z","from_sync":false,"order":13,"slug":"topics","title":"Guides & Tools"},"parentDoc":null,"user":"560d5913af97231900938124","project":"57336fd5a6a9c40e00e13a0b","version":{"_id":"59a45d2bd12e81000f842ee2","project":"57336fd5a6a9c40e00e13a0b","__v":1,"createdAt":"2017-08-28T18:12:59.168Z","releaseDate":"2017-08-28T18:12:59.168Z","categories":["59a45d2bd12e81000f842ee3","59a45d2bd12e81000f842ee4","59a45d2bd12e81000f842ee5","59a45d2bd12e81000f842ee6","59a45d2bd12e81000f842ee7","59a45d2bd12e81000f842ee8","59a45d2bd12e81000f842ee9","59a45d2bd12e81000f842eea","59a45d2bd12e81000f842eeb","59a45d2bd12e81000f842eec","59a45d2bd12e81000f842eed","59a45d2bd12e81000f842eee","59a45d2bd12e81000f842eef","59a45d2bd12e81000f842ef0","59a45d2bd12e81000f842ef1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":false,"codename":"3.22.1","version_clean":"8976.0.0-JSON","version":"8976-JSON"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-10-06T17:27:35.463Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":110,"body":"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. \n\nSee:\n  * [How to use metadata](#section-how-to-use-metadata)\n  * [Example: Shipping and tax info](#section-example-shipping-and-tax-info)\n  * [Example: Product info](#section-example-product-info)\n\n##How to use metadata\nThe 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`.\n\nEach 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. \tYou can also include a description of up to 40 characters to provide more details about the data. For more information, see [metadata](doc:meta-data). \n\nThe 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. \n\n##Example: Shipping and tax info\nUsing 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.\n\nFor example, you might have an order for a total amount of $200 dollars, which includes:\n  * $150 for the product that was ordered\n  * $20 for state tax\n  * $20 for city tax\n  * $10 for shipping\n\nYou 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 200,\\n    \\\"recurringTransaction\\\": \\\"ECOMMERCE\\\",\\n    \\\"cardHolderInfo\\\": {\\n        \\\"firstName\\\": \\\"test first name\\\",\\n        \\\"lastName\\\": \\\"test last name\\\"\\n    },\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"creditCard\\\": {\\n        \\\"expirationYear\\\": 2016,\\n        \\\"cardType\\\": \\\"VISA\\\",\\n        \\\"securityCode\\\": 111,\\n        \\\"expirationMonth\\\": \\\"07\\\",\\n        \\\"cardNumber\\\": 4012000033330026\\n    },\\n    \\\"cardTransactionType\\\": \\\"AUTH_ONLY\\\",\\n    \\\"transactionMetaData\\\": {\\\"metaData\\\": [\\n        {\\n            \\\"metaValue\\\": 20,\\n            \\\"metaKey\\\": \\\"stateTaxAmount\\\",\\n            \\\"metaDescription\\\": \\\"State Tax Amount\\\"\\n        },\\n        {\\n            \\\"metaValue\\\": 20,\\n            \\\"metaKey\\\": \\\"cityTaxAmount\\\",\\n            \\\"metaDescription\\\": \\\"City Tax Amount\\\"\\n        },\\n        {\\n            \\\"metaValue\\\": 10,\\n            \\\"metaKey\\\": \\\"shippingAmount\\\",\\n            \\\"metaDescription\\\": \\\"Shipping Amount\\\"\\n        }\\n    ]}\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Auth Only request with metadata for tax and shipping\"\n    },\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 200,\\n    \\\"recurringTransaction\\\": \\\"ECOMMERCE\\\",\\n    \\\"processingInfo\\\": {\\n        \\\"avsResponseCodeAddress\\\": \\\"U\\\",\\n        \\\"processingStatus\\\": \\\"success\\\",\\n        \\\"cvvResponseCode\\\": \\\"MA\\\",\\n        \\\"avsResponseCodeName\\\": \\\"U\\\",\\n        \\\"avsResponseCodeZip\\\": \\\"U\\\"\\n    },\\n    \\\"cardHolderInfo\\\": {\\n        \\\"firstName\\\": \\\"test first name\\\",\\n        \\\"lastName\\\": \\\"test last name\\\"\\n    },\\n    \\\"avsResponseCode\\\": \\\"G\\\",\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"creditCard\\\": {\\n        \\\"cardLastFourDigits\\\": \\\"0026\\\",\\n        \\\"cardSubType\\\": \\\"CREDIT\\\",\\n        \\\"cardType\\\": \\\"VISA\\\"\\n    },\\n    \\\"cardTransactionType\\\": \\\"AUTH_ONLY\\\",\\n    \\\"transactionMetaData\\\": {\\\"metaData\\\": [\\n        {\\n            \\\"metaValue\\\": 20,\\n            \\\"metaKey\\\": \\\"stateTaxAmount\\\",\\n            \\\"metaDescription\\\": \\\"State Tax Amount\\\"\\n        },\\n        {\\n            \\\"metaValue\\\": 20,\\n            \\\"metaKey\\\": \\\"cityTaxAmount\\\",\\n            \\\"metaDescription\\\": \\\"City Tax Amount\\\"\\n        },\\n        {\\n            \\\"metaValue\\\": 10,\\n            \\\"metaKey\\\": \\\"shippingAmount\\\",\\n            \\\"metaDescription\\\": \\\"Shipping Amount\\\"\\n        }\\n    ]},\\n    \\\"transactionId\\\": 38497126\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Auth Only response with transaction ID and metadata for tax and shipping\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n##Example: Product info\nYou 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. See the example request and response below. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 20,\\n    \\\"recurringTransaction\\\": \\\"ECOMMERCE\\\",\\n    \\\"cardHolderInfo\\\": {\\n        \\\"firstName\\\": \\\"test first name\\\",\\n        \\\"lastName\\\": \\\"test last name\\\"\\n    },\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"creditCard\\\": {\\n        \\\"expirationYear\\\": 2016,\\n        \\\"cardType\\\": \\\"VISA\\\",\\n        \\\"securityCode\\\": 111,\\n        \\\"expirationMonth\\\": \\\"07\\\",\\n        \\\"cardNumber\\\": 4012000033330026\\n    },\\n    \\\"cardTransactionType\\\": \\\"AUTH_ONLY\\\",\\n    \\\"transactionMetaData\\\": {\\\"metaData\\\": [\\n        {\\n            \\\"metaValue\\\": \\\"tshirt\\\",\\n            \\\"metaKey\\\": \\\"type\\\",\\n            \\\"metaDescription\\\": \\\"item type\\\"\\n        },\\n        {\\n            \\\"metaValue\\\": \\\"m\\\",\\n            \\\"metaKey\\\": \\\"size\\\",\\n            \\\"metaDescription\\\": \\\"size info - s/m/l/xl\\\"\\n        },\\n        {\\n            \\\"metaValue\\\": \\\"blue\\\",\\n            \\\"metaKey\\\": \\\"color\\\",\\n            \\\"metaDescription\\\": \\\"item color\\\"\\n        }\\n    ]}\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Auth Only request with metadata for product info\"\n    },\n    {\n      \"code\": \"{\\n    \\\"amount\\\": 20,\\n    \\\"recurringTransaction\\\": \\\"ECOMMERCE\\\",\\n    \\\"processingInfo\\\": {\\n        \\\"avsResponseCodeAddress\\\": \\\"U\\\",\\n        \\\"processingStatus\\\": \\\"success\\\",\\n        \\\"cvvResponseCode\\\": \\\"MA\\\",\\n        \\\"avsResponseCodeName\\\": \\\"U\\\",\\n        \\\"avsResponseCodeZip\\\": \\\"U\\\"\\n    },\\n    \\\"cardHolderInfo\\\": {\\n        \\\"firstName\\\": \\\"test first name\\\",\\n        \\\"lastName\\\": \\\"test last name\\\"\\n    },\\n    \\\"avsResponseCode\\\": \\\"G\\\",\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"creditCard\\\": {\\n        \\\"cardLastFourDigits\\\": \\\"0026\\\",\\n        \\\"cardSubType\\\": \\\"CREDIT\\\",\\n        \\\"cardType\\\": \\\"VISA\\\"\\n    },\\n    \\\"cardTransactionType\\\": \\\"AUTH_ONLY\\\",\\n    \\\"transactionMetaData\\\": {\\\"metaData\\\": [\\n        {\\n            \\\"metaValue\\\": \\\"tshirt\\\",\\n            \\\"metaKey\\\": \\\"type\\\",\\n            \\\"metaDescription\\\": \\\"short-sleeve t-shirt\\\"\\n        },\\n        {\\n            \\\"metaValue\\\": \\\"m\\\",\\n            \\\"metaKey\\\": \\\"size\\\",\\n            \\\"metaDescription\\\": \\\"size info - s/m/l/xl\\\"\\n        },\\n        {\\n            \\\"metaValue\\\": \\\"blue\\\",\\n            \\\"metaKey\\\": \\\"color\\\",\\n            \\\"metaDescription\\\": \\\"item color\\\"\\n        }\\n    ]},\\n    \\\"transactionId\\\": 12345678\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Auth Only response with transaction ID and metadata for product info\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"metadata","type":"basic","title":"Metadata Guide"}

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,
    "recurringTransaction": "ECOMMERCE",
    "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,
    "recurringTransaction": "ECOMMERCE",
    "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. See the example request and response below.

{
    "amount": 20,
    "recurringTransaction": "ECOMMERCE",
    "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,
    "recurringTransaction": "ECOMMERCE",
    "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
}