Send transaction data to a payment gateway

When payment transaction data is sent to a payment provider by the Generic Payment webhook, the provider processes the payment and returns data about the transaction.

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. The set of properties differs depending on the payment method and the type of transaction. For example, the following is a sample payload for a gift card authorization request:

{
   "transactionType": "0100",
   "currencyCode": "USD",
   "locale": "en",
   "customProperties": { },
   "channel": "storefront",
   "siteId": "siteUS",
   "siteURL": "https://www.example.com",
   "orderId": "o50415",
   "paymentRequests": [
      {
         "transactionId": "o50415-pg50417-1464958982609",
         "paymentId": "pg50417",
         "customProperties": { },
         "gatewaySettings": {
            "paymentMethodTypes":"physicalGiftCard"
         },
         "cardDetails":{
            "giftCardNumber": "12393678",
            "giftCardPin": ""
         },
         "amount":"000000002499",
         "billingAddress": { },
         "transactionTimestamp": "2019-12-03T13:03:02+0000",
         "referenceInfos": { },
         "shippingAddress": { },
         "paymentMethod": "physicalGiftCard",
         "gatewayId": "demoGiftCardGateway",
      }
   ],
   "profile": {
      "id": "120002",
      "phoneNumber": "1234512345",
      "email": "[e-mail]"
   }
   "profileDetails": {
       "id": "120002",
       "lastName": "Shopper",
       "firstName": "Test",
       "taxExempt": false,
       "profileType": "b2c_user",
       "receiveEmail": "no",
       "registrationDate": "2019-10-15T06:50:51.000Z",
       "lastPasswordUpdate": "2019-10-15T06:50:51.000Z",
   }
}

The request and response payload properties for the payment methods Commerce supports are described in detail in Extending Oracle Commerce.

Send custom properties

Depending on the payment method and the provider you integrate with, there may be additional payment data that you need to send. If so, you can include this data in the POST /ccstore/v1/orders/current/submit endpoint 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"
  }
],
...

The custom properties from the endpoint 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 also 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. In addition, the webhook can return a customPaymentProperties object that specifies a list of the properties in the additionalProperties object that should be returned to the storefront in the endpoint response. 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",
...