Credit card payment properties
When the Credit Card Payment webhook executes, it sends a JSON request body to the payment gateway.
This section applies to Open Storefront Framework (OSF) and Storefront Classic.
The request body contains a 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.
The set of properties in the request and response bodies, including the subobjects,
vary depending on the type of transaction. For credit card gateways, there are three
transaction types supported: authorization
, void
,
and refund
.
Credit card payment request properties
This section describes the top-level properties and the properties of subobjects
sent in the JSON request body of the Credit Card Payment webhook. 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.
Top-level properties
The following table describes the top-level properties that Oracle Commerce sends in the webhook request.
Property | Description |
---|---|
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. |
transactionType |
A code indicating the type of transaction. For the Credit Card Payment webhook, this must be one of the following numeric values:
|
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 | The payment method. For the Credit Card Payment webhook, the value must be
card .
|
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. |
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 |
retryPaymentCount | The number of times payment has been retried for the order |
auxiliaryProperties
The following table describes the properties of the
auxiliaryProperties
object in the request.
Property | Description |
---|---|
authenticationMethod | Either guest (for an
anonymous shopper) or local (for a
logged-in shopper)
|
shopperAccountPaymentAccountFirstUseDate |
The timestamp of when the card used for payment was saved, expressed as an ISO 8601 value in the following format:
|
cardDetails
properties
The following table describes the properties of the cardDetails
object in a credit card payment request. The values of these properties are used to authorize the payment.
Property | Description |
---|---|
expirationMonth | A two-digit number indicating the month the credit card expires (for example, 07 for July) |
expirationYear | A four-digit number indicating the year the credit card expires (for example, 2019) |
cvv | The three-digit or four-digit security code verifying the credit card |
number | The credit card number |
type |
The credit card type. Valid values are:
|
holderName | The complete name of the holder of the credit card |
billingAddress
properties
The following table describes the properties of the billingAddress
object in the request. The billing address is the address of the customer to whom the order is charged.
Property | Description |
---|---|
lastName | The last name of the customer |
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 customer |
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 the request. The shipping address is the address of the person (not necessarily a customer) 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 |
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. Note that for account-based
commerce shoppers, this object may also include
parentOrganization
, currentOrganization
,
and secondaryOrganizations
subobjects.
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 Credit Card Payment webhook to a payment gateway:
{
"transactionId": "o30446-pg30417-1458555741310",
"currencyCode": "USD",
"paymentId": "pg30417",
"locale": "en",
"siteURL": "https://www.example.com",
"gatewaySettings": {
"paymentMethodTypes": "card",
"filteredFields": ["paymentMethodTypes"]
},
"cardDetails": {
"expirationMonth": "02",
"expirationYear": "2022",
"cvv": "234",
"number": "4111111111111111",
"type": "visa",
"holderName": "Test Shopper"
},
"amount": ""000000122526",
"transactionType": "0100",
"transactionTimestamp": "2019-11-21T10:22:21+0000",
"siteId": "siteUS",
"billingAddress": {
"lastName": "Shopper",
"postalCode": "01242",
"phoneNumber": "617-555-1977",
"email": "tshopper@example.com",
"state": "MA",
"address1": "1 Main Street",
"address2": "",
"firstName": "Test",
"city": "Cambridge",
"country": "US"
},
"channel": "storefront",
"shippingAddress": {
"lastName": "Shopper",
"postalCode": "01242",
"phoneNumber": "617-555-1977",
"email": "tshopper@example.com",
"state": "MA",
"address1": "1 Main Street",
"address2": "",
"firstName": "Test",
"city": "Cambridge",
"country": "US"
},
"orderId": "o30446",
"paymentMethod": "card",
"gatewayId": "gatewayDemo",
"profile": {
"id": "110454",
"phoneNumber": "617-555-1977",
"email": "tshopper@example.com"
},
"profileDetails": {
"id": "110454",
"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"
}
"retryPaymentCount": 0,
"auxiliaryProperties": {
"authenticationMethod": "local",
"shopperAccountPaymentAccountFirstUseDate": "2019-10-17T06:14:06.004Z"
},
}
Credit card payment response properties
This section describes the top-level properties and the properties of subobjects that should be returned in the JSON response body of the Credit Card Payment webhook.
Top-level properties
The following table describes the top-level properties that Oracle Commerce expects in the webhook response.
Property | Description |
---|---|
paymentId | 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 |
A code indicating the type of transaction. For the Credit Card Payment webhook, this must be one of the following numeric values:
Must match the value from the request. |
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. |
hostTransactionTimeStamp | The timestamp of the transaction from the gateway (in milliseconds). |
paymentMethod | The payment method. For the Credit Card Payment webhook, the value must be
card .
|
orderId | The ID of the order associated with the payment. Must match the value from the request. |
amount |
The amount authorized. This must match the exact amount requested. Any other amount will cause an error, as Oracle Commerce does not support partial authorizations for credit card payments. 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. |
gatewayId | The ID of the payment gateway. 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. |
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 |
The authorization decision from the payment provider as interpreted by the merchant. For the Credit Card Payment webhook, 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 Credit Card Payment webhook by a payment gateway:
{
"orderId": "o30446",
"currencyCode": "USD",
"transactionId": "o30446-pg30417-1458555741310",
"paymentId": "pg30417",
"amount": "000000122526",
"transactionType": "0100",
"hostTransactionTimestamp": "1447807667046",
"transactionTimestamp": "2019-11-21T10:22:21+0000",
"paymentMethod": "card",
"gatewayId": "gatewayDemo",
"siteId": "siteUS",
"authorizationResponse": {
"responseCode": "1000",
"responseReason": "1001",
"responseDescription": "1002",
"authorizationCode": "s001",
"hostTransactionId": "h001"
},
"additionalProperties": {
"sampleProperty1": "An additional property whose value will be stored."
}
}