Send custom properties to a payment gateway
When payment transaction data is sent to a payment provider by the Generic Payment webhook, the provider processes the payment information and returns information about the transaction.
This section applies to Open Storefront Framework (OSF) and Storefront Classic.
The webhook sends out a predefined set of properties in the request, and expects to receive another predefined set of properties back in the response. For some providers, however, you may need to send additional data in the request, and the provider may include additional data in the response. This section describes how you can send and receive additional data that is not included in the predefined properties.
Include custom properties in the REST call
Depending on the payment provider you integrate with, there may be additional
payment data that you want to send. If so, you can include this data in the
createOrder
REST request. Each payments
object in the
request can include a customProperties
subobject that you can use to send
additional data as key/value pairs. For example:
...
"payments": [
{
"endYear": 2018,
"cardTypeName": "Visa",
"nameOnCard": "Fred Smith",
"customProperties": {
"monthlyCharge": "$77",
"numberOfPayments": "12"
},
"cardCVV": "123",
"type": "card",
"cardType": "visa",
"endMonth": "02",
"cardNumber": "4055011111111111"
}
],
...
Send custom properties in the webhook request
The custom properties from the REST request are then included in the customProperties
object in the webhook call to the payment provider. For example:
{
"transactionId": "o60412-pg60411-1465342612829",
"currencyCode": "USD",
"paymentId": "pg60411",
"siteId": "siteUS",
"locale": "en",
"customProperties": {
"monthlyCharge": "$77",
"numberOfPayments": "12"
},
"gatewaySettings": [{
"paymentMethodTypes": "card",
"filteredFields": ["paymentMethodTypes"]
}],
"amount": "000000007700",
"transactionType": "0100",
...
Note that for gift card payments, in addition to the top-level customProperties
object, each paymentRequests
object also has a customProperties
object. See Integrate with a Gift Card Payment Gateway for more information.
Return custom properties in the webhook response
The webhook can return custom properties from the payment provider as an additionalProperties
object in the response. This data is saved with the payment group for the order. The webhook can also return a customPaymentProperties
object that specifies a list of the properties in the additionalProperties
object that should be returned to the storefront in the response to the original createOrder
request. For example:
{
"orderId": "o60412",
"paymentId": "pg60411",
"siteId": "siteUS",
"merchantTransactionId": "324a5107-8fe5-4dd7-aa1f-8b7e2e0ec8df",
"hostTransactionId": "o60412-pg60411-1465342612829",
"transactionTimestamp": "2016-06-07T23:36:52+0000",
"hostTimestamp": "2016-06-07T23:36:52+0000",
"transactionType": "0100",
"additionalProperties": {
"interestRate": "0.05",
"remainingPayments": "5",
"latePayment": false,
},
"customPaymentProperties": ["remainingPayments", "latePayment"],
"amount": "000000007700",
"currencyCode": "USD",
...