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 Cloud 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 Cloud, 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"
}

Copyright © 1997, 2017 Oracle and/or its affiliates. All rights reserved. Legal Notices