Invoice payment properties
When the Generic Payment webhook executes, it sends a JSON request body to the payment gateway.
The request body 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.
Invoice payment request properties
This section describes the top-level properties and the properties of subobjects
sent in the JSON request body of the Generic Payment webhook for invoice 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. See Order Submit webhook for information about the order properties.
Top-level properties
The following table describes the top-level properties that Oracle Commerce Cloud sends in the webhook request.
Property | Description |
---|---|
transactionId |
The unique ID of the transaction. Consists of the order ID, the payment ID, and the transaction time stamp (in milliseconds), separated by hyphens. |
transactionType |
The type of transaction. For an invoice payment gateway, this must be AUTHORIZE .
|
transactionTimestamp |
The timestamp of the transaction, expressed as an ISO 8601 value in the following format:
|
organizationId |
The ID of the organization to be invoiced. |
organizationName |
The name of the organization to be invoiced. |
PONumber |
The purchase order number for the account to be invoiced. |
referenceNumber |
The ID of the internal payment group. |
channel |
The area of the system where the payment-processing request originated. Valid values are:
|
paymentMethod |
The payment method. For an invoice payment gateway, the value must be
invoice .
|
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. |
customProperties |
Additional key/value pairs from the submitted order to be sent to the provider. |
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:
|
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 a purchase order authorization request:
{
"transactionId": "o40426-pg40413-1466678343221",
"currencyCode": "USD",
"organizationName": "ABCD Corp",
"locale": "en",
"siteURL": "https://www.example.com",
"PONumber": "po22222",
"referenceNumber": "pg40413",
"customProperties": { },
"organizationId": "or-300007",
"siteId": "siteUS",
"gatewaySettings": {
"paymentMethodTypes": "invoice",
"filteredFields": [
"paymentMethodTypes"
]
},
"amount": "000000002999",
"transactionType": "AUTHORIZE",
"transactionTimestamp": "2019-12-23T10:39:03+0000",
"channel": "storefront",
"orderId": "o40426",
"paymentMethod": "invoice",
"profile": {
"id": "130000",
"phoneNumber": "2342342345",
"email": "a1@abcdcorp.com"
},
"profileDetails": {
"id": "130000",
"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,
"gatewayId": "invoiceGateway"
}
Invoice 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 Generic Payment webhook for invoice transactions.
Top-level properties
The following table describes the top-level properties that Oracle Commerce expects in the webhook response.
Property | Description |
---|---|
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. |
transactionType |
The type of transaction. For an invoice payment gateway, this must be AUTHORIZE .
|
transactionTimestamp |
The time stamp of the transaction in Oracle Commerce Cloud, expressed as an ISO 8601 value in the following format:
Must match the value from the request. |
organizationId |
The ID of the organization for the account to be invoiced. |
PONumber |
The purchase order number for the account to be invoiced. |
referenceNumber |
The ID of the internal payment group. Must match the value from the request. |
hostTransactionTimeStamp |
The time stamp of the transaction from the gateway. |
merchantTransactionTimestamp |
The time stamp of the transaction from the merchant (in milliseconds). |
paymentMethod |
The payment method. For an invoice payment gateway, the value must be invoice .
|
orderId |
The ID of the order associated with the payment. Must match the value from the request. |
amount |
The amount invoiced. 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. |
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 |
The authorization decision from the payment provider as interpreted by the merchant. For an invoice 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. |
hostTransactionId |
The transaction reference ID from the payment gateway. |
merchantTransactionId |
The transaction reference ID from the merchant. |
Sample authorization response
The following is an example of a response to a purchase order authorization request:
{
"merchantTransactionTimestamp": "1447807667046",
"currencyCode": "USD",
"transactionId": "o40426-pg40413-1466678343221",
"PONumber": "po22222",
"referenceNumber": "pg10415",
"organizationId": "or-300007",
"amount": "000000002999",
"transactionType": "AUTHORIZE",
"siteId": "siteUS",
"authorizationResponse": {
"hostTransactionId": "HOST-TRANSACTION-ID",
"responseCode": "1000",
"responseReason": "1002",
"responseDescription": "Valid PO Number",
"merchantTransactionId": "2016-06-23T10:39:03+0000"
},
"transactionTimestamp": "2016-05-02T12:14:09+0000",
"paymentMethod": "invoice",
"orderId": "o40426",
"gatewayId": "invoiceGateway"
}