Developer documentation

Callback handler

Last updated:

The callback handler is a URL on your server that UnitPay calls when a payment changes state. It is the source of truth for whether a payment succeeded — never deliver goods or credit a balance based on the customer's browser redirect alone. Configure the URL in the merchant cabinet under Settings → Project → Payment handler URL.

Endpoint requirements

  • HTTPS only. Plain HTTP is rejected by the cabinet validator.
  • A registered domain name; raw IP addresses and embedded credentials are not accepted.
  • The handler domain does not need to match your website domain. https://api.example.com/unitpay/callback is fine.
  • Respond within 10 seconds. Long-running work (fulfilment, emails) belongs in a background job, not in the response path.

Methods you must handle

methodWhen it is sentYour job
checkBefore the customer is asked for payment details.Verify the order exists, the amount and currency match, and the customer is allowed to pay. Do not deliver yet.
payAfter UnitPay confirms a successful charge.Mark the order as paid in your system; deliver the goods or credit the balance.
preauthWhen funds are authorised but not captured yet.Reserve inventory if relevant; do not deliver until pay arrives.
errorAn error happened on the gateway side. May be followed by a successful pay.Log it; do not treat the order as failed unless no pay arrives within the payment window.

check is disabled by default for new projects. Enable it from the cabinet only after your handler is verified to handle it correctly — rejecting check rejects the payment.

Request shape

UnitPay sends a GET request. Parameters arrive as query-string fields (or form-encoded body). Common fields:

ParameterDescription
methodOne of check, pay, preauth, error.
params[unitpayId]UnitPay's unique payment identifier. Persist it on first sight; use it as the idempotency key.
params[projectId]Your project ID. Reject any callback for an unexpected project ID.
params[account]The customer or order identifier you passed to initPayment.
params[orderSum]Amount of the original order in major currency units. Compare against your stored order.
params[orderCurrency]ISO 4217 currency code of the original order.
params[payerSum]Amount actually charged to the customer (after FX, fees).
params[payerCurrency]Currency the customer was charged in.
params[date]Payment timestamp in YYYY-MM-DD HH:MM:SS WIB.
params[test]1 for test-mode, 0 for live payments.
params[signature]Request signature. Verify before trusting any other parameter.

Signature verification

Verify the signature first. Reject the request with HTTP 200 and an error message if it does not match — do not log the secret key.

  1. Take all keys under params except sign and signature.
  2. Sort those keys alphabetically.
  3. Build a string by concatenating, in order: method, then each sorted parameter value, then your project secret key. Use the literal four-character delimiter {up} between every part.
  4. Hash the string with SHA-256 and lowercase the hex digest.
  5. Compare against params[signature] using a constant-time comparison.

Reference implementation in Node.js:

import { createHash } from "node:crypto";
import { timingSafeEqual } from "node:crypto";

function verifyUnitpaySignature(method, params, secretKey) {
  const sortedKeys = Object.keys(params)
    .filter((k) => k !== "sign" && k !== "signature")
    .sort();
  const sortedValues = sortedKeys.map((k) => String(params[k]));
  const payload = [method, ...sortedValues, secretKey].join("{up}");
  const expected = createHash("sha256").update(payload).digest("hex");
  const received = String(params.signature || "");
  if (expected.length !== received.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

Expected response

Always reply with HTTP 200 and a JSON body. The shape tells UnitPay whether to advance the payment.

OutcomeBody
Accept the request — payment may proceed (or has been processed).{"result": {"message": "Request processed successfully."}}
Reject the request — payment must not proceed.{"error": {"message": "Order not found."}}

The error.message string is shown to the customer on the payment form, so write it as customer-facing copy. Do not include internal IDs, stack traces, or PII.

Idempotency

UnitPay may retry a callback if the network drops or your handler returns 5xx. Treat params[unitpayId] as the idempotency key:

  • If the same unitpayId arrives twice with the same method, return the response you returned the first time. Do not deliver again, do not credit again.
  • If the customer retries a failed payment, UnitPay issues a new unitpayId. The previous unitpayId stays in your system as failed.

Funds are credited to your project balance based on UnitPay's record, not on the response your handler returned. If a delivery fails on your side after pay succeeded, retry from your background job — you do not need UnitPay to resend the callback.

What not to do

  • Do not deliver during preauth — funds are not yet captured.
  • Do not whitelist by IP only. UnitPay's outbound IPs may change; signature verification is the binding check.
  • Do not log the secret key, the full callback URL with secrets in query strings, or the raw signature next to the verification result.
  • Do not return HTTP 200 with an error body for transient failures (database down, queue full). Return 5xx so UnitPay retries.
  • Do not skip check validation when it is enabled — an accepted check commits you to honour the eventual pay.

Operational notes

  • If no handler URL is configured, callbacks are not sent and payments are auto-approved without your validation. Always set the URL before going live.
  • Failed pay callbacks (handler returned an error) leave the payment in Not completed status. Resolve the underlying issue, then retry from Statistics → Payment details in the cabinet.

Next steps