Postbacks

Postbacks are real-time HTTPS messages that PaymentExpress sends to your system immediately after a payment is processed. They keep your records in sync with actual outcomes across your payment solutions. Your endpoint acknowledges each message, allowing PaymentExpress to determine whether to retry or consider the delivery complete.

Overview

A postback is an HTTP POST request from PaymentExpress to a URL you provide. The payload is JSON describing the completed transaction.

Your endpoint must return a small JSON response that signals success or the type of error encountered. Retries occur for non-permanent failures.

Postbacks complement, but do not replace, Reconciliation Files for end-of-day balancing.

How Postbacks Work

1. Payment is successfully processed by PaymentExpress.
2. PaymentExpress posts JSON to your configured URL with key identifiers and amounts.
3. Your endpoint responds with a JSON body indicating the status, as described in the response format below.
4. If the response is non-200, contains invalid JSON, or indicates a transient error, PaymentExpress retries according to the environment configuration.
5. Retries continue until the delivery succeeds or the message is considered failed. PermanentError indicates that the message should not be retried.

Access Control Note

Please let us know which systems will receive postbacks so we can grant access and be notified of any destination changes. We need the hostnames and/or IP addresses for the destinations where postbacks will be sent. Without this notice, postbacks will fail to send.

Configure Where Postbacks Go

You can specify a per-transaction postback URL during cart creation using request.resultUrls.postback. This works for Online, In-Person, and IVR carts.

Postback Request Format

PaymentExpress sends a JSON body with the following base fields. Additional metadata included during cart creation may also be echoed back.

• timestamp: The RFC 3339 time when the transaction was processed.
• clientTransactionId: Your unique ID from the cart handoff.
• paymentId: The unique identifier for the payment in PaymentExpress.
• tenderType: The payment method used, such as CreditCard or eCheck.
• primaryAmount: The amount remitted to you, excluding fees, represented as a string with two decimal places.
• feeAmount: The fee charged to the customer, represented as a string with two decimal places.

Example Request

{
  "timestamp": "2025-10-21T08:34:32Z",
  "clientTransactionId": "F45E063E-063B-FC1B-AAA2-FA35803C7D5F",
  "paymentId": "F6039302747",
  "tenderType": "CreditCard",
  "primaryAmount": "64.88",
  "feeAmount": "1.95"
}

Postback Response Format

Your endpoint must return HTTP 200 with a small JSON body containing a status value.

The status field is required and must be one of the following values:

• Updated: Success; your system saved the update.
• Dupe: You already processed this message. This is still considered successful.
• Error: A transient failure occurred, such as a database issue. PaymentExpress will retry. Include an errorMessage.
• PermanentError: A permanent condition prevents the update. PaymentExpress will not retry.

The errorMessage field is optional and provides context for a non-success status.

Success Example

{
  "status": "Updated"
}

Transient Error Example

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

Note: A postback is considered failed and will be retried if your endpoint returns a non-200 status, invalid JSON, or valid JSON that signals a non-permanent error.

Error Handling Scenarios

Duplicate Delivery

• Symptom: You receive the same paymentId again.
• Action: Safely return Dupe after verifying that you already stored the record.

Temporary Backend Failure

• Symptom: A database connection issue prevents persistence.
• Action: Return Error with an errorMessage so PaymentExpress retries.

Permanent Mismatch

• Symptom: The referenced clientTransactionId does not exist in your system, for example, because it has been purged.
• Action: Return PermanentError to stop retries and open a manual investigation.

Non-200 Response or Invalid JSON

• Symptom: Your service times out or returns HTML.
• Action: Fix the endpoint. PaymentExpress will retry according to the configuration.