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.
| Field | Type | Description |
|---|---|---|
pageId | string | The payment page ID (page_...). |
paymentId | string | The payment ID (py_...). Unique per payment attempt — use it to deduplicate. |
clientReferenceId | string | The clientReferenceId you set on the payment page. Omitted if you did not set one. |
amount | integer | Amount in minor units, e.g. 5000 for $50.00. |
currency | string | ISO 4217 currency code, e.g. USD. |
walletType | string | null | applepay or googlepay for a wallet payment; null for a card entered or saved on the payment page. |
tokenFormat | string | For wallet payments: dpan (device token) or fpan (the card number). Omitted when it cannot be determined. |
card.bin | string | The first 6 or 8 digits of the card number. |
card.last4 | string | The last 4 digits of the card number. |
card.expiryMonth | string | Two-digit expiry month, 01–12. |
card.expiryYear | string | Four-digit expiry year. |
card.scheme | string | Card scheme, e.g. VISA. |
card.issuer | string | Name of the issuing bank. |
card.issuerCountry | string | ISO 3166-1 alpha-2 country code of the issuing bank, e.g. US. |
card.cardType | string | CREDIT or DEBIT. |
card.firstName | string | Cardholder first name. |
card.lastName | string | Cardholder last name. |
signature | string | Request 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.
- Remove the
signaturefield from the request body. - Sort the remaining keys alphabetically, including the keys inside
card, and stringify the result as JSON with no whitespace. - Compute the HMAC-SHA256 of that string with your webhook secret and Base64-encode it.
- Compare the result with
signatureusing 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" }decision | Effect |
|---|---|
accept | The payment continues through Breeze's checks as normal. |
decline | The payment is declined before authorization. No authorization is attempted. |
require_3ds | The payment continues, and the customer must complete 3D Secure even if Breeze would otherwise have skipped it. |
no_decision | You 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_3dscan 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-
2xxstatus, 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.
Updated 1 day ago