Loyalty point payment properties

When the Custom Currency webhook executes, it sends a JSON request body to the payment gateway.

The request body contains information about the order, the method of payment, and the type of transaction being initiated. The gateway processes the request and returns a JSON response body that contains information about the results of the transaction, including whether the transaction succeeded.

The set of properties in the request and response bodies, including the subobjects, vary depending on the type of transaction. For loyalty point gateways, there are four transaction types supported: authorize, void, refund, and balance inquiry.

Loyalty point payment request properties

This section describes the top-level properties and the properties of subobjects sent in the JSON request body of the Custom Currency webhook for loyalty point transactions. Note that if the includeOrderInWebhookPayload property in the gateway extension's config.json file is set to true, the order is also included in the request (except for balance inquiry requests, which do not have an associated order). See Order Submit webhook for information about the order properties.

Top-level properties

The following table describes the top-level properties that Oracle Commerce sends in the webhook request.

Property	Description
transactionType	A code indicating the type of transaction. This must be one of the following numeric values: `0100 (authorize) 0110 (void) 0400 (refund) 0600 (balance inquiry)`
channel	The area of the system where the payment-processing request originated. Valid values are: `storefront agent review`
orderId	The ID of the order associated with the transaction
currencyCode	The custom currency code used for the loyalty program. See Create a custom currency for loyalty points for information about this value.
locale	The shopper’s locale, taken from the order. If no locale is set, the default locale from the storefront is used.
customProperties	Additional key/value pairs to be sent to the payment provider
paymentId	The ID of the internal payment group
transactionId	The unique ID of the transaction. Consists of the order ID, the payment ID, and the transaction timestamp (in milliseconds), separated by hyphens.
transactionTimestamp	The timestamp of the transaction, expressed as an ISO 8601 value in the following format: `yyyy-MM-dd'T'HH:mm:ssZ`
paymentMethod	The payment method. For loyalty points, the value is `loyaltyPoints`.
amount	For authorize, void, and refund transactions, the number of loyalty points, expressed as a positive 12-digit number.
retryPaymentCount	The number of times payment has been retried for the order
siteURL	The URL of the site on which the order is placed
siteId	The ID of the site on which the order is placed
gatewayId	The ID of the payment gateway
gatewaySettings	Key/value pairs of properties that configure the payment gateway

profile properties

The following table describes the properties of the profile object included in the request. These values are associated with the shopper purchasing the order.

Property	Description
id	The Commerce ID of the shopper profile
phoneNumber	The phone number from the shopper profile
email	The email address from the shopper profile

profileDetails properties

The following table describes the properties of the profileDetails object in the request. These values are associated with the customer purchasing the order.

Property	Description
id	The ID of the customer profile
lastName	The last name of the customer profile
firstName	The first name of the customer profile
middleName	The middle name of the customer profile
email	The email address from the customer profile
taxExempt	Indicates whether the customer tax-exempt status; either `true` or `false`
taxExemptionCode	For a customer with tax-exempt status, the exemption code
profileType	The type of profile; either `b2c_user` or `b2b_user`
receiveEmail	Indicates whether the customer agrees to receive email; either `yes` or `no`
registrationDate	The timestamp of when the profile was created, expressed as an ISO 8601 value in the following format: `yyyy-MM-dd'T'HH:mm:ssZ`
lastPasswordUpdate	The timestamp of when the password for the profile was last updated, expressed as an ISO 8601 value in the following format: `yyyy-MM-dd'T'HH:mm:ssZ`

loyaltyDetails properties

The following table describes the properties of the loyaltyDetails objects sent in an authorization request or balance inquiry. These values are retrieved from the shopper’s profile.

Property	Description
programName	The name of the loyalty program
programId	The ID for the loyal program
membershipId	The shopper’s membership ID in the loyalty program
status	The shopper’s status in the loyalty program. Valid values are: `RequestForEnrollment Enrolled RequestForUnenrollment Unenrolled Failed`

referenceInfos properties

The following table describes the properties of the referenceInfos objects sent in a void request or refund request. The values of these properties are taken from the original authorization transaction so the merchant can map the void or refund to it.

Property	Description
amount	The number of loyalty points used in the original transaction, expressed as a positive 12-digit number.
currencyCode	The custom currency code used for the loyalty program
locale	The shopper’s locale from the original transaction
merchantTransactionId	The transaction reference ID from the merchant
hostTransactionId	The transaction reference ID from the payment gateway

billingAddress properties

The following table describes the properties of the billingAddress object in an authorization request. The billing address is the address of the shopper to whom the order is charged.

Property	Description
lastName	The last name of the shopper
postalCode	The postal code in the address (for example, the zip code in the United States)
phoneNumber	The phone number associated with the address
email	The email address associated with the address
state	The state in the address
address1	The first line of the address. Typically the street and number
address2	The second line of the address. Included as an empty string in the JSON data if no value exists in the order
firstName	The first name of the shopper
city	The city in the address
country	The country in the address

shippingAddress properties

The following table describes the properties of the shippingAddress object in an authorization or balance inquiry request. The shipping address is the address of the person (not necessarily the shopper) receiving the order.

Property	Description
lastName	The last name of the order recipient
postalCode	The postal code in the address (for example, the zip code in the United States)
phoneNumber	The phone number associated with the address
email	The email address associated with the address
state	The state in the address
address1	The first line of the address. Typically the street and number.
address2	The second line of the address. Included as an empty string in the JSON data if no value exists in the order.
firstName	The first name of the order recipient
city	The city in the address
country	The country in the address

Sample balance inquiry request

The following is an example of a loyalty point balance inquiry request:

{
  "loyaltyDetails": [
    {
      "programName": "programForFlyer",
      "membershipId": "member0002",
      "programId": "prg10002",
      "status": "Enrolled"
    },
    {
      "programName": "programForYoungster",
      "membershipId": "member0001",
      "programId": "prg10001",
      "status": "Enrolled"
    }
  ],
  "orderId": "o30417",
  "profile": {
    "phoneNumber": "1234512345",
    "id": "110072",
    "email": "john@example.com"
  },
  "channel": "storefront",
  "locale": "en",
  "transactionId": "o30417-pg30418-1504691722253",
  "transactionTimestamp": "2017-09-06T09:55:22+0000",
  "transactionType": "0600",
  "customProperties": {
    "cust-prop2": "cust-prop2",
    "cust-prop1": "cust-prop1"
  },
  "paymentId": "pg30418",
  "gatewaySettings": {
    "paymentMethodTypes": "loyaltyPoints"
  },
  "paymentMethod": "loyaltyPoints",
  "shippingAddress": {
    "lastName": "Niel",
    "country": "US",
    "firstName": "John",
    "phoneNumber": "1234512345",
    "address2": null,
    "city": "Cambridge",
    "address1": "1 Main St",
    "postalCode": "02142",
    "state": "MA",
    "email": "john@example.com"
  },
  "siteId": "siteUS",
  "currencyCode": "PTS",
  "gatewayId": "demoLoyaltyPointsPaymentGateway"
}

Sample authorization request

The following is an example of a loyalty point authorization request:

{
  "loyaltyDetails": [
    {
      "programName": "programForYoungster",
      "membershipId": "member0001",
      "programId": "prg10001",
      "status": "Enrolled"
    },
    {
      "programName": "programForFlyer",
      "membershipId": "member0002",
      "programId": "prg10002",
      "status": "Enrolled"
    }
  ],
  "amount": "000000000200",
  "orderId": "o30417",
  "profile": {
    "phoneNumber": "1234512345",
    "id": "110072",
    "email": "john@example.com"
  },
  "profileDetails": {
    "id": "110072",
    "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",
   }
  "channel": "storefront",
  "locale": "en",
  "siteURL": "https://www.example.com",
  "retryPaymentCount": 0,
  "transactionId": "o30417-pg30415-1504691268818",
  "transactionTimestamp": "2019-12-06T09:47:48+0000",
  "transactionType": "0100",
  "customProperties": {
    "cust-prop2": "cust-prop2",
    "cust-prop1": "cust-prop1"
  },
  "paymentId": "pg30415",
  "gatewaySettings": {
    "paymentMethodTypes": "loyaltyPoints"
  },
  "paymentMethod": "loyaltyPoints",
  "shippingAddress": {
    "lastName": "Niel",
    "country": "US",
    "firstName": "John",
    "phoneNumber": "1234512345",
    "address2": null,
    "city": "Cambridge",
    "address1": "1 Main St",
    "postalCode": "02142",
    "state": "MA",
    "email": "john@example.com"
  },
  "siteId": "siteUS",
  "billingAddress": {
    "country": "US",
    "lastName": "John",
    "firstName": "Niel",
    "phoneNumber": "9000054321",
    "city": "San Francisco",
    "address1": "1 Elm St",
    "postalCode": "91333",
    "state": "CA",
    "email": "john.niel@gmail.com"
  },
  "currencyCode": "PTS",
  "gatewayId": "demoLoyaltyPointsPaymentGateway"
}

Loyalty point payment response properties

This section describes the top-level properties and the properties of subobjects that should be returned in the response body of the Custom Currency webhook for loyalty point transactions.

Top-level properties

The following table describes the top-level properties that Oracle Commerce expects in the webhook response.

Property	Description
transactionType	A code indicating the type of transaction. This must be one of the following numeric values, and is expected to match the value in the request: `0100 (authorization) 0110 (void) 0400 (refund) 0600 (balance inquiry)`
currencyCode	The custom currency code used for the loyalty program. This is expected to match the value in the request.
locale	The shopper’s locale. This is expected to match the value in the request.
channel	The area of the system where the payment-processing request originated. This is expected to match the value in the request.
orderId	The ID of the order associated with the payment. This is expected to match the value in the request.
paymentId	The ID of the internal payment group. Must match the value from the request.
paymentMethod	The payment method. Must match the value from the request. For loyalty points, the value is `loyaltyPoints`.
transactionId	The unique ID of the transaction. Consists of the order ID, the payment ID, and the transaction timestamp (in milliseconds), separated by hyphens. Must match the value from the request.
amount	The number of loyalty points used in the transaction, expressed as a positive 12-digit number.
transactionTimestamp	The timestamp of the transaction in Oracle Commerce, expressed as an ISO 8601 value in the following format: `yyyy-MM-dd'T'HH:mm:ssZ` Must match the value from the request.
siteId	The ID of the site on which the order was placed. Must match the value from the request.
gatewayId	The ID of the payment gateway. Must match the value from the request.

authorizationResponse, voidResponse, creditResponse, and inquireBalanceResponse properties

The following table describes the properties of the authorizationResponse, voidResponse, creditResponse, or inquireBalanceResponse object in the webhook response. Only one of these objects is included in each response (the object corresponding to the transaction type; for example, a voidResponse object for a void transaction). All of these object types require the same set of properties. The values of these properties indicate the results of the transaction.

Property	Description
responseCode	The decision from the payment provider as interpreted by the merchant. The acceptable values depend on the transaction type. For an authorization request, the code must be one of the following values: `1000 (success) 4000 (sale complete) 9000 (decline)` For a void request, the code must be one of the following values: `2000 (success) 8000 (decline)` For a credit (refund) request, the code must be one of the following values: `3000 (success) 7000 (decline)` For a balance inquiry, the code must be one of the following values: `5000 (success) 6000 (decline)`
responseDescription	Information from the payment gateway about the response
responseReason	Information about why the transaction succeeded or failed
hostTransactionId	The transaction reference ID from the payment gateway
merchantTransactionId	The transaction reference ID from the merchant
merchantTransactionTimeStamp	The timestamp of the transaction from the merchant (in milliseconds)
hostTransactionTimeStamp	The timestamp of the transaction from the gateway (in milliseconds)
additionalProperties	Key/value pairs for additional properties sent by the merchant. (For an `authorizationResponse` object, we recommend including the `programId`, `programName`, and `membershipId` properties, so they can be included in any subsequent void or refund webhook requests.)
customPaymentProperties	A list of the properties from the `additionalProperties` map that should be returned to the storefront

loyaltyPrograms properties

The following table describes the properties of the objects in the loyaltyPrograms array of an inquireBalanceResponse object.

Property	Description
membershipType	The category or level of the membership; for example, silver, gold, or platinum
pointsBalance	The number of points available
pointsType	The type of points. This should match the currencyCode value described in Create a custom currency for loyalty points.
additionalProperties	Key/value pairs for additional properties sent by the merchant for this program type

loyaltyPointDetails properties

The following table describes the properties of the objects in the loyaltyPointDetails array of a loyaltyPrograms object of an inquireBalanceResponse object.

Property	Description
programName	The name of the loyalty program
programId	The ID of the loyalty program
membershipId	The shopper’s ID in the loyalty program
additionalProperties	Key/value pairs for additional properties sent by the merchant for this point type
status	The status of the shopper in the loyalty program. Valid values are: `RequestForEnrollment Enrolled RequestForUnenrollment Unenrolled Failed`

Sample balance inquiry response

The following is an example of a response to a loyalty point balance inquiry request:

{
  "transactionType": "0600",
  "orderId": "o30417",
  "paymentId": "pg30418",
  "channel": "storefront",
  "paymentMethod": "loyaltyPoints",
  "siteId": "siteUS",
  "locale": "en",
  "inquireBalanceResponse": {
    "hostTransactionTimestamp": "1504691722267",
    "responseReason": "inquireBalanceResponseReason",
    "customPaymentProperties": [
      "cust-prop2",
      "cust-prop1"
    ],
    "responseDescription": "inquireBalanceResponseDescription",
    "loyaltyPrograms": [
      {
        "loyaltyPointDetails": [
          {
            "membershipType": "blue",
            "pointsBalance": "2000",
            "pointsType": "bluePoints",
            "additionalProperties": {
              "propertyName1": "value1",
              "propertyName2": "value2"
            }
          },
          {
            "membershipType": "red",
            "pointsBalance": "6000",
            "pointsType": "redPoints",
            "additionalProperties": {
              "propertyName4": "value4",
              "propertyName3": "value3"
            }
          },
          {
            "membershipType": "standard",
            "pointsBalance": "6000",
            "pointsType": "PTS",
            "additionalProperties": {
              "propertyName6": "value6",
              "propertyName5": "value5"
            }
          }
        ],
        "programName": "programForYoungster",
        "membershipId": "member0001",
        "additionalProperties": {
          "validTill": "2029-11-26T15:57:55.631Z",
          "validFrom": "2017-07-14T15:57:55.631Z"
        },
        "programId": "prg10001"
      },
      {
        "loyaltyPointDetails": [
          {
            "membershipType": "silver",
            "pointsBalance": "2000",
            "pointsType": "rewardPoints",
            "additionalProperties": {
              "propertyName7": "value7",
              "propertyName8": "value8"
            }
          },
          {
            "membershipType": "gold",
            "pointsBalance": "6000",
            "pointsType": "skyMiles",
            "additionalProperties": {
              "propertyName10": "value10",
              "propertyName9": "value9"
            }
          }
        ],
        "programName": "programForFlyer",
        "membershipId": "member0002",
        "additionalProperties": {
          "validTill": "2030-12-26T15:57:55.631Z",
          "validFrom": "2017-06-14T15:57:55.631Z"
        },
        "programId": "prg10002"
      }
    ],
    "merchantTransactionId": "MERCH-TX-1504691722267",
    "hostTransactionId": "HOST-TX-1504691722267",
    "additionalProperties": {
      "cust-prop2": "cust-prop2",
      "cust-prop1": "cust-prop1",
    },
    "responseCode": "5000",
    "merchantTransactionTimestamp": "1504691722267"
  },
  "currencyCode": "PTS",
  "transactionId": "o30417-pg30418-1504691722253",
  "transactionTimestamp": "2017-09-06T09:55:22+0000",
  "gatewayId": "demoLoyaltyPointsPaymentGateway"
}

Sample authorization response

The following is an example of a response to a loyalty point authorization request:

{
  "amount": "000000000200",
  "orderId": "o30417",
  "channel": "storefront",
  "authorizationResponse": {
    "hostTransactionTimestamp": "1504691269627",
    "responseReason": "authResponseReason",
    "customPaymentProperties": [
      "programName",
      "membershipId",
      "programId"
    ],
    "responseDescription": "authResponseDescription",
    "merchantTransactionId": "MERCH-TX-1504691269627",
    "hostTransactionId": "HOST-TX-1504691269627",
    "additionalProperties": {
      "programName": "programForFlyer",
      "membershipId": "member0002",
      "programId": "prg10002"
    },
    "responseCode": "1000",
    "merchantTransactionTimestamp": "1504691269627"
  },
  "locale": "en",
  "transactionId": "o30417-pg30415-1504691268818",
  "transactionTimestamp": "2017-09-06T09:47:48+0000",
  "transactionType": "0100",
  "paymentId": "pg30415",
  "paymentMethod": "loyaltyPoints",
  "siteId": "siteUS",
  "currencyCode": "PTS",
  "gatewayId": "demoLoyaltyPointsPaymentGateway"
}