Cash payment properties
When the Generic Payment webhook executes, it sends a JSON request body to the payment gateway.
The request body contains an authorization request that contains information about
the order and about the method of payment. The gateway processes the request and
returns a JSON response body that contains information about the transaction,
including whether the transaction succeeded. 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. See Order Submit webhook for information about the order properties.
Cash payment request properties
This section describes the top-level properties and the properties of subobjects sent in the JSON request body for cash transactions.
Top-level properties
The following table describes the top-level properties that Oracle Commerce sends in the webhook request.
| Property | Description |
|---|---|
referenceNumber |
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. |
transactionType |
For a cash payment gateway, this must be one of the following strings:
|
transactionTimestamp |
The timestamp of the transaction, expressed as an ISO 8601 value in the following format:
|
channel |
The area of the system where the payment-processing request originated. Valid values are:
|
paymentMethod |
For a cash payment gateway, the value must be cash |
orderId |
The ID of the order associated with the payment |
amount |
The amount to be authorized, as a positive, 12-digit number that is expressed in base currency. For example, $125.75 is represented as 000000012575.
|
currencyCode |
The ISO 4217 currency code |
locale |
The shopper’s locale, taken from the order. If no locale is set, the default locale from the storefront is used. |
retryPaymentCount |
The number of times payment has been retried for the order |
siteURL |
The URL of the site on which the order was placed |
siteId |
The ID of the site on which the order was placed |
gatewayId |
The ID of the payment gateway |
profile properties
The following table describes the properties of the profile object in the request. These values are associated with the customer purchasing the order.
| Property | Description |
|---|---|
| id | The ID of the customer profile. |
| phoneNumber | The phone number from the customer profile. |
| The email address from the customer 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:
|
Sample authorization request
The following is an example of an authorization request sent by the Generic Payment webhook to a cash payment gateway:
{
"transactionId": "o30446-pg30417-1458555741310",
"currencyCode": "USD",
"referenceNumber": "pg30417",
"locale": "en",
"gatewaySettings": {
"paymentMethodTypes": "cash",
"filteredFields": ["paymentMethodTypes"]
},
"amount": ""000000122526",",
"transactionType": "CASH REQUEST",
"transactionTimestamp": "2019-10-21T10:22:21+0000",
"channel": "storefront",
"orderId": "o30446",
"paymentMethod": "cash",
"retryPaymentCount": 0,
"siteURL": "https://www.example.com",
"siteId": "siteUS",
"gatewayId": "gatewayDemo",
"profile": {
"id": "110454",
"phoneNumber": "617-555-1977",
"email": "tshopper@example.com"
}
"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",
}
}Cash payment response properties
This section describes the top-level properties and the properties of subobjects that should be returned in the JSON response body for cash transactions.
Top-level properties
The following table describes the top-level properties that Oracle Commerce expects in the webhook response.
| Property | Description |
|---|---|
referenceNumber |
The ID of the internal payment group. Must match the value from the request. |
transactionId |
The unique ID of the transaction. Consists of the order ID, the payment ID, and the transaction timestamp (in milliseconds), separated by hyphens. |
transactionType |
For a cash payment gateway, this must be one of the following strings:
|
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. |
hostTimeStamp |
The timestamp of the transaction in the gateway (in milliseconds). |
merchantTransactionTimestamp |
The timestamp of the transaction from the merchant (in milliseconds). |
paymentMethod |
For a cash payment gateway, the value must be cash.
|
orderId |
The ID of the order associated with the payment. Must match the value from the request. |
amount |
The actual amount collected from the shopper. This may differ from the amount in the request. The value of this property is a positive, 12-digit number that is expressed in base currency. For example, $125.75 is represented as |
currencyCode |
The ISO 4217 currency code. This is expected to match the value in 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. |
additionalProperties |
Key/value pairs for additional properties sent by the merchant. |
authorizationResponse properties
The following table describes the properties of the authorizationResponse object in the response. The values of these properties indicate whether the transaction was authorized successfully.
| Property | Description |
|---|---|
responseCode |
For a cash payment gateway, this must be one of the following values:
|
responseDescription |
Information from the payment gateway about the response. |
responseReason |
Information about why the authorization succeeded or failed. |
authorizationCode |
The authorization code from the payment provider. |
hostTransactionId |
The transaction reference ID from the payment gateway. |
merchantTransactionId |
The transaction reference ID from the merchant. |
token |
The payment token used by the payment provider. |
Sample authorization response
The following is an example of an authorization response sent to the Generic Payment webhook by a cash payment gateway:
{
"orderId": "o30446",
"currencyCode": "USD",
"transactionId": "o30446-pg30417-1458555741310",
"referenceNumber": "pg30417",
"amount": "000000122526",
"transactionType": "CASH REQUEST",
"hostTimestamp": "1447807667046",
"transactionTimestamp": "2019-10-21T10:22:21+0000",
"merchantTransactionTimestamp": "1447807667046"
"paymentMethod": "cash",
"siteId": "siteUS",
"gatewayId": "gatewayDemo",
"authorizationResponse": {
"responseCode": "1000",
"responseReason": "1001",
"responseDescription": "1002",
"authorizationCode": "s001",
"hostTransactionId": "h001"
},
"additionalProperties": {
"sampleProperty1": "An additional property whose value will be stored."
}
}