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: `yyyy-MM-dd'T'HH:mm:ssZ`
`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: `storefront` `agent` `preview`
`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: `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 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: `yyyy-MM-dd'T'HH:mm:ssZ` 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: `1000` (success) `9000` (decline)
`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"
}