1. Extending Oracle Commerce
  2. Create a Credit Card Payment Gateway Integration
  3. Credit card payment properties

Credit card payment properties

When the Credit Card Payment webhook executes, it sends a JSON request body to the payment gateway.

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:

0100 (authorization)
0110 (void)
0400 (refund)
transactionTimestamp

The timestamp of the transaction, expressed as an ISO 8601 value in the following format:

yyyy-MM-dd'T'HH:mm:ssZ
channel

The area of the system where the payment-processing request originated. Valid values are:

storefront
agent
preview
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:

yyyy-MM-dd'T'HH:mm:ssZ

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:

visa
mastercard
amex
discover
diners
jcb
elo
dankort
cartebleue
cartasi
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
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 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
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

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
email 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
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

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:

0100 (authorization)
0110 (void)
0400 (refund)

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:

yyyy-MM-dd'T'HH:mm:ssZ

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 000000012575.

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:

1000 (success)
9000 (decline)
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."
     }
}