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:
|
channel |
The area of the system where the payment-processing request originated. Valid values are:
|
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:
|
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 |
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 |
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:
|
lastPasswordUpdate |
The timestamp of when the password for the profile was last updated, expressed as an ISO 8601 value in the following format:
|
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:
|
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 |
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 |
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:
|
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:
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:
For a void request, the code must be one of the following values:
For a credit (refund) request, the code must be one of the following values:
For a balance inquiry, the code must be one of the following values:
|
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:
|
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"
}