Postbacks

It is important to make sure that your client system can appropriately update itself to the result of a payment to help keep the systems in sync. After processing a payment through Hosted or Embedded Checkouts, PaymentExpress needs to relay the fact that this payment occurred to your client systems.

The most real-time way to accomplish this task is through the use of a postback (sometimes referred to as a "webhook") - an HTTP request that is sent from PaymentExpress to your own system after a transaction has been processed. These postbacks are sent in real-time immediately after a payment is processed, to communicate the completion and details of the transaction to your system. If your system exposes an API endpoint which conforms with the request and response format outlined below, PaymentExpress can easily be configured to send these real-time postbacks to your system.

Ensuring Postback Success

Postback transmission is not a "fire and forget" process for PaymentExpress. Postbacks require an acknowledgement of success from your system to ensure that the systems stay in sync. In the event that a postback fails in a non-permanent manner (documented below), PaymentExpress will queue the postback for a retry - attempting the same postback again after a delay. The amount of time of the delay and the number of retries to be completed before a postback is considered a failure is configurable based on the environment.

Postback success rates are incredibly high on the first attempt, and the majority of postback failures are quickly rectified through the retry process. They are a highly reliable way to ensure that PaymentExpress and your system stay in sync and up-to-date. However, for the extremely rare occurrence that there is a sync issue between PaymentExpress and your system, we also provide for the usage of daily Reconciliation Files.

Postback Request Format

A standard postback is an HTTP POST request to a URL of the client's choosing containing JSON encoded data about the transaction. The URL to which the postback is sent is configured by the client, as explained in "Configuring Postbacks" below. The standard base fields of a postback are below:

• timestamp - An RFC3339 formatted timestamp indicating the time that the transaction was processed.
• paymentId - The unique identifier for this payment in the PaymentExpress system.
• clientTransactionId - The unique identifier for this transaction as provided by the client during cart handoff in the clientTransactionId field, to assist in locating the items to be paid in the client system.
• primaryAmount - The amount that the customer was charged for this transaction, excluding any applicable transaction fees. This is the amount that will make its way to your bank account and matches the amount that was transmitted at cart creation.
• feeAmount - The amount that the customer was charged as a fee for processing this transaction, in addition to the primary amount which is remitted to the payee.
• tenderType - The tender type (CreditCard, eCheck, Paypal, etc) used to complete the transaction.

There are other fields about the transaction which can be included in the postback request, especially including any fields which were transmitted in the meta sections of the cart creation request.

📘

Currency Fields

Note that fields returning a currency amount (eg primaryAmount and feeAmount) will be sent as strings with at least 1 digit followed by a decimal and 2 more digits to denote cents.

Example Postback Request

Below is an example postback request that your system could receive from PaymentExpress:

{
  "timestamp": "2021-04-21T08:34:32",
  "clientTransactionId": "F45E063E-063B-FC1B-AAA2-FA35803C7D5F",
  "paymentId": "F6039302747",
  "tenderType": "MSCD",
  "primaryAmount": "64.88",
  "feeAmount": "1.95"
}

Postback Response Format

A postback is considered to have been successfully processed by the client system when the client system returns an HTTP 200 response with a JSON body with one of the successful statuses. In the event that the postback returns a non-200 HTTP response code, provides an invalid response, or provides a valid response that indicates a non-permanent postback error in the client system, the postback will be considered a failure and follow the retry mechanism mentioned above.

The format of the expected response is below, with one required field, as well as optional fields to help with debugging communication between the systems.

• status (Required) - String field with 4 valid values:
  • Updated - The basic success case. Tells PaymentExpress that the client system was successfully updated by the postback.
  • Dupe - A case where the client system recognizes this request as a duplicate of another request already processed. This is also a success case.
  • Error - A potentially transient error condition in the system of record, such as a DB access issue, etc, that prevents the requested postback from being processed successfully. Likely result is a retry from the postback system. Client system is encouraged to set the errorMessage field to communicate the context of the failure.
  • PermanentError - An error condition noted in the client system which will permanently prevent the update of this record. This response will request a prevention/stoppage of any retry process.
• errorMessage - An optional field we request that you set in any error response status, indicating the source of the error.
• meta - On optional JSON object allowing for the client system to provide debugging information about this postback transaction. Some potential valuable fields:
  • system - Name of the node processing the request
  • requestTime - The clock time this request was received by the processing system. (Preferably RFC3399)
  • totalTime - The time in seconds and nanoseconds this request took to process by the processing system.

Example Postback Success Response

{
  "status": "Updated"
}

Example Postback Failure Response

{
  "status": "Error",
  "errorMessage": "There was a failure communicating with the database."
}

Configuring Postbacks

For both In Person and Online Payments, the Cart Handoff request allows for the client system to specify the URL to which a postback is to be sent at the conclusion of that exact transaction (in the request.resultUrls.postback parameter). For more details about the Cart Handoff request and the postback URL in that request, please see the OTC Cart Handoff or Online Cart Handoff requests in our API reference.

🚧

Access Requests Necessary

To ensure that PaymentExpress postbacks can reach your postback destination, we will need to know what systems will be answering these requests to permit access to them.

Please make sure you let us know of any changes to your postback destination so we will have time to make any needed changes to permit access.