Pre-authorization risk check

Run your own risk rules on a card payment before Breeze authorizes it.

The pre-authorization risk check lets you apply your own risk rules to a card payment before it is authorized. Breeze sends your endpoint the payment's card metadata, and your response decides whether the payment proceeds, is declined, or goes through 3D Secure.

Because the decision is made before authorization, a payment you decline places no hold on the customer's card, and you do not need to refund it afterwards. For example, you can decline cards issued outside the countries you serve.

Before you start

  • Configure a webhook secret in the Breeze dashboard. Breeze signs every request with it, and does not call your endpoint if no secret is configured.
  • Supported payments: card payments made on a Breeze payment page — new cards, saved cards, Apple Pay, and Google Pay. Payments made through the Direct Payment API are not sent to your endpoint.

1. Set your endpoint on the payment page

Pass preAuthRiskUrl when you create a payment page. Each payment page carries its own URL, so you can use different endpoints for different flows.

curl -X POST 'https://api.breeze.cash/v1/payment_pages' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "lineItems": [{ "productId": "prd_123abc456", "quantity": 1 }],
    "clientReferenceId": "order-0001",
    "successReturnUrl": "https://example.com/success",
    "failReturnUrl": "https://example.com/fail",
    "preAuthRiskUrl": "https://risk.example.com/breeze/pre-auth"
  }'

The create and retrieve payment page responses return the preAuthRiskUrl you set.

2. Receive the request

For each payment attempt, Breeze sends one POST request with a JSON body to your endpoint.

FieldTypeDescription
pageIdstringThe payment page ID (page_...).
paymentIdstringThe payment ID (py_...). Unique per payment attempt — use it to deduplicate.
clientReferenceIdstringThe clientReferenceId you set on the payment page. Omitted if you did not set one.
amountintegerAmount in minor units, e.g. 5000 for $50.00.
currencystringISO 4217 currency code, e.g. USD.
walletTypestring | nullapplepay or googlepay for a wallet payment; null for a card entered or saved on the payment page.
tokenFormatstringFor wallet payments: dpan (device token) or fpan (the card number). Omitted when it cannot be determined.
card.binstringThe first 6 or 8 digits of the card number.
card.last4stringThe last 4 digits of the card number.
card.expiryMonthstringTwo-digit expiry month, 01–12.
card.expiryYearstringFour-digit expiry year.
card.schemestringCard scheme, e.g. VISA.
card.issuerstringName of the issuing bank.
card.issuerCountrystringISO 3166-1 alpha-2 country code of the issuing bank, e.g. US.
card.cardTypestringCREDIT or DEBIT.
card.firstNamestringCardholder first name.
card.lastNamestringCardholder last name.
signaturestringRequest signature. See Verify the signature.

Every card field is sent when Breeze has it and omitted otherwise, so do not treat any of them as required. Breeze never sends the full card number, the CVV, the billing address, or the customer's email.

{
  "pageId": "page_8d78100e18bc825f",
  "paymentId": "py_2f1c9a7e5b3d4e60",
  "clientReferenceId": "order-0001",
  "amount": 5000,
  "currency": "USD",
  "walletType": null,
  "card": {
    "bin": "424242",
    "last4": "4242",
    "expiryMonth": "01",
    "expiryYear": "2030",
    "scheme": "VISA",
    "issuer": "Example Bank",
    "issuerCountry": "US",
    "cardType": "CREDIT",
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "signature": "fP0n8m...="
}

3. Verify the signature

Verify every request before acting on it. The signature uses the same HMAC-SHA256 scheme and webhook secret as webhook signatures, with one difference: it covers the whole request body except signature, rather than a data object.

  1. Remove the signature field from the request body.
  2. Sort the remaining keys alphabetically, including the keys inside card, and stringify the result as JSON with no whitespace.
  3. Compute the HMAC-SHA256 of that string with your webhook secret and Base64-encode it.
  4. Compare the result with signature using a constant-time comparison.
import stringify from "json-stable-stringify";
import { createHmac, timingSafeEqual } from "crypto";

app.post("/breeze/pre-auth", (request, response) => {
  // Your webhook secret from dashboard.breeze.cash
  const webhookSecret = process.env.BREEZE_WEBHOOK_SECRET;

  const { signature, ...payload } = request.body;
  const expectedSignature = createHmac("sha256", webhookSecret)
    .update(stringify(payload))
    .digest("base64");

  const received = Buffer.from(signature ?? "", "utf8");
  const expected = Buffer.from(expectedSignature, "utf8");
  if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
    return response.status(400).send();
  }

  // Apply your own rules, e.g. an allowlist of issuing countries.
  const allowedCountries = ["US", "CA", "GB"];
  const decision = allowedCountries.includes(payload.card.issuerCountry) ? "accept" : "decline";

  return response.status(200).json({ decision });
});

4. Respond with a decision

Respond with HTTP 200 (any 2xx status is accepted) and a JSON body containing decision:

{ "decision": "decline" }
decisionEffect
acceptThe payment continues through Breeze's checks as normal.
declineThe payment is declined before authorization. No authorization is attempted.
require_3dsThe payment continues, and the customer must complete 3D Secure even if Breeze would otherwise have skipped it.
no_decisionYou have no opinion. Breeze decides on its own, the same as accept.

Additional fields in the response are ignored. Keep the response body under 1,500 characters.

How Breeze combines your decision with its own

Your decision can only make a payment stricter, never more permissive:

  • If Breeze's own risk checks decline the payment, it is declined, even if you respond accept.
  • require_3ds can turn 3D Secure on. Nothing you return can turn 3D Secure off.

What a declined payment looks like

A payment you decline fails with the error code RISK_MERCHANT_DECLINE. You see it in payment attempts and payment webhooks. The customer sees Breeze's generic decline message and is not told which check declined them. See the Error Reference.

Timeouts and failures

The check never blocks a payment because your endpoint is unavailable. Breeze ignores your response and continues on its own decision — the same as no_decision — when:

  • Your endpoint does not respond within 3 seconds.
  • It returns a non-2xx status, or a redirect (Breeze does not follow redirects).
  • The response body is not valid JSON, is over the size limit, or does not contain a valid decision.
  • The connection fails.

Breeze calls your endpoint once per payment attempt and does not retry. Your endpoint's response time adds directly to checkout time, so keep it well under the timeout.



Did this page help you?