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).

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",
...