Client Postbacks

Client postbacks allow your application to receive real-time notifications when payment transactions are processed through PayConnect. When a transaction completes or is refunded, PayConnect sends an HTTP POST to your configured endpoint.

How It Works

1. A payment is processed through a payment processor
2. The processor sends a postback to PayConnect
3. PayConnect forwards the transaction data to your configured postback URL
4. Your endpoint processes the data and returns a 2xx response

Configuration

Client postbacks are configured per company. A company admin can set them in the PayConnect portal under Settings → Organization → API Configuration (Edit, then Save changes):

Setting	Description
Status	Active to send postbacks, Inactive to stop them
Postback URL	The HTTPS endpoint that will receive transaction data. Required while postbacks are active
Postback API Key	The credential sent in the Authorization header for authentication
Authorization Scheme	How the key is presented in the Authorization header: Api-Key (default) or Bearer. See Authentication.

The key is masked in the portal. To change it, enter the new key and save; to remove it, set Status to Inactive first. If you need help, email [email protected].

Payload Format

PayConnect sends a JSON payload containing transaction details:

{
  "transaction_id": "6789abc...",
  "order_id": "INV-2025-001",
  "status": "completed",
  "transaction_amount": 50,
  "action": "sale",
  "type_id": 20,
  "line_items": [],
  "info": {
    "subscription_id": "sub_xyz789"
  },
  "customFields": {
    "mlsnumber": "12345"
  }
}

Fields

Field	Type	Description
transaction_id	string	Unique transaction identifier
order_id	string	Your order/invoice reference ID
status	string	Transaction status
transaction_amount	number	Amount in dollars (e.g., 50 = $50.00)
action	string	Transaction action (e.g., sale, refund, auth)
type_id	number	Transaction type identifier
line_items	array | null	Line item details, if applicable
info	object | null	Additional info; includes subscription_id for subscription transactions
customFields	object | null	Client-defined custom field values inherited from the paying invoice (and, for subscription transactions, from the subscription). null when none were set. Keys are your configured custom field keys.

Authentication

Each postback request includes your configured key in the Authorization header, prefixed with your configured authorization scheme.

With the default Api-Key scheme:

Authorization: Api-Key YOUR_POSTBACK_KEY

With the Bearer scheme, for receivers that expect a standard bearer token:

Authorization: Bearer YOUR_POSTBACK_KEY

If your endpoint expects a bearer token, set Authorization Scheme to Bearer on the API Configuration page. Existing integrations keep the Api-Key scheme until someone changes it.

If no key is configured, the postback is sent without an Authorization header.

A CorrelationId header is also included for request tracing.

Transaction Sources

Postbacks are sent for transactions originating from:

Source	Description
Hosted Payment Page	Payments made through a PayConnect hosted payment page
Subscription Run	Automated recurring subscription charges
Integration	Transactions initiated via API integration
Payform	Payments submitted through embedded payforms
Manual Payment	Check or cash payments recorded against an invoice in PayConnect
Refund	Refunds of a previous transaction

Refunds

A refund postback reuses the original transaction's transaction_id and carries "action": "refund" and "type_id": 30, so you can match it to the sale it reverses. transaction_amount is a positive amount.

Endpoint Requirements

Your postback endpoint must:

• Accept POST requests with Content-Type: application/json
• Return a 2xx status code to acknowledge receipt
• Be accessible via HTTPS

Example Receiver (Node.js)

const express = require("express");
const app = express();

app.use(express.json());

app.post("/postbacks/payconnect", (req, res) => {
  const auth = req.headers["authorization"];

  // Verify the postback key. Use "Bearer YOUR_POSTBACK_KEY" if your
  // authorization scheme is set to Bearer.
  if (auth !== "Api-Key YOUR_POSTBACK_KEY") {
    return res.status(401).json({ error: "Unauthorized" });
  }

  const { transaction_id, order_id, status, transaction_amount } = req.body;

  console.log(`Transaction ${transaction_id}: ${status} - $${transaction_amount}`);

  // Process the transaction data (update order status, etc.)

  res.status(200).json({ received: true });
});

app.listen(3000);

Retry Behavior

If your endpoint does not return a 2xx response, PayConnect retries delivery via an SQS queue:

• Up to 4 delivery attempts (maxReceiveCount 4) before the message is moved to a dead letter queue
• Messages are retained in the main queue for 24 hours
• Failed messages are retained in the dead letter queue for 4 days

Each postback attempt is logged with the attempt count, status, and any error details. Contact support to replay failed postback messages.

Best Practices

1. Return 200 quickly — process postback data asynchronously to avoid timeouts
2. Verify the key — check the Authorization header matches your configured scheme and postback key
3. Handle duplicates — use the transaction_id and CorrelationId to deduplicate in case of retries. A sale and its refund share a transaction_id, so include action in your dedup key
4. Log all postbacks — keep a record of incoming postbacks for debugging and reconciliation