Skip to main content

Authorization checks

Before you approve a card or QR payment on a business's funding account, ask Expense Management whether the payment is within the business's policy. Expense Management answers approve, decline or not_applicable. You make the final decision, place the hold and post the account event.

Endpoint: POST {expense_api_base_url}/v1/spend/bank_integration/authorization_checks

See the Create authorization check API in our API reference for the full schema.

When to call it​

PaymentWhenkindstage
Card pre-authorizationOn the issuer processor's authorization requestcardpre_auth
Card final authorizationOn the issuer processor's authorization requestcardfinal_auth
Incremental pre-authorizationOn the incremental authorization request. Set related_check_id to the original check and amount to the increase onlycardincremental
QR payment started in your own appBefore you pay the merchantqrqr_payment
QR payment started in the Expense Management appOptional. You receive the decision that was already taken when the employee confirmedqrqr_payment
note

For an incremental check, amount (and original_amount, if set) is the increase only, not the new total. Expense Management adds it to the check in related_check_id. For example, if the original check was for 280.00 SGD and the merchant raises the authorization by 50.00 SGD to 330.00 SGD, send amount 50.00 SGD. Sending the new total counts the original amount twice and can decline a payment that is within the employee's policy.

Call it after your own checks (funds, fraud, account status) and before you place the hold. See How a card payment flows.

What Expense Management checks​

  • The employee's and the business's status, and the card's status.
  • Your platform-wide blocked categories and card limits.
  • The employee's spend policy: allowed, capped and blocked categories, per-payment, daily and monthly limits, and countries.
  • The employee's totals across card, QR and claims, so the same limits apply to every way they spend.
  • The department or vendor budget. Budgets are hard limits.
  • Any exception or temporary limit raise the employee has been approved for.

An approve counts toward the employee's totals right away, as a reservation. The reservation becomes the expense when you post an account event with the same check_id. It is released when you post a declined event, or after 15 minutes if no event arrives.

The request​

{
"check_id": "CHK-20261104-000123",
"kind": "card",
"stage": "pre_auth",
"related_check_id": null,
"account_ref": "acc_7f3e",
"amount": { "amount": "280.00", "currency": "SGD" },
"original_amount": null,
"payer": {
"business_ref": "biz_01jbty0z0tfcz9mg0x5gxmmqv2",
"card_ref": "card_01jbty0z0tfcz9mg0x5gxmmqv4",
"bank_account_ref": null
},
"merchant": { "name": "Marina Bay Hotel", "mcc": "7011", "country": "SG", "city": "Singapore" },
"card": {
"of_transaction_id": "9f1c2d3e-4b5a-6789-8abc-def012345678",
"of_static_token_id": null,
"network": "visa",
"entry_mode": "ecommerce",
"policy_result": null
},
"qr": null,
"requested_at": "2026-11-04T09:15:00Z"
}
FieldWhat to send
check_idYour unique ID for this check. A repeat returns the stored decision.
account_refThe funding account in your ledger.
amountThe amount you would hold or debit, in the account's currency.
original_amountThe amount in the transaction's currency, when it differs from the account's.
payer.business_refThe business. On a card payment with Open Fabric Issuing, this is the card's tenant_customer_ref from the authorization.
payer.card_refThe card's tenant_token_ref. If you don't have it, send card.of_static_token_id instead and Expense Management finds the card.
payer.bank_account_refFor a QR payment from your own banking app: your reference for the paying employee. Your staff set it per employee in the admin console.
merchantThe merchant name, plus MCC, country and city when you have them.
cardFor kind: card. The issuer processor's transaction_id as of_transaction_id, and optionally its spend control result in policy_result.
qrFor kind: qr. The QR standard (for example sgqr), and expense_mgmt_ref if the payment was started in the Expense Management app.

The response​

{
"check_id": "CHK-20261104-000123",
"decision": "decline",
"reason_code": "merchant_category_blocked",
"appealable": true,
"decided_at": "2026-11-04T09:15:00.120Z"
}
decisionMeaningWhat you do
approveWithin policyContinue with your approval
declineOutside policyDecline the payment. Post a declined account event with decline.source: expense_mgmt
not_applicableExpense Management doesn't manage this account, card or employee (for example a card you issued outside Expense Management)Decide on your own. Expense Management records nothing

When appealable is true, the employee sees Ask for approval in the app. If an approver agrees, the employee gets a one-off, time-boxed exception, and the retried payment is approved.

Decline reasons​

The app shows the employee a plain-words message for each code.

reason_codeMeaningAppealable
merchant_category_blockedThe spend policy blocks this categoryYes
over_transaction_limitOver the policy's per-payment limitYes
over_period_limitOver the daily or monthly limit across card, QR and claimsYes
allowance_expiredAn approved exception was used up or expiredYes
category_blocked_by_bankYou block this category for every businessNo
over_bank_limitOver your platform-wide card limitNo
over_budgetOver the department or vendor budgetNo
country_not_allowed, currency_not_allowedThe policy doesn't allow this country or currencyNo
merchant_not_allowedA vendor card used at another merchantNo
no_policy_assignedThe employee has no spend policyNo
card_frozen, card_cancelled, card_not_activeThe card can't be usedNo
membership_inactive, vendor_inactiveThe employee or vendor is no longer activeNo

On not_applicable, the code is unknown_payer, unknown_account or unknown_card. These codes are for you only and are never shown to an employee.

Treat any code you don't recognize as a decline.

Timeouts and stand-in​

  • Deadline: wait at most 1 second for an answer. The target is under 300 ms at p99.
  • On a timeout, a 5xx or a 429, apply your own stand-in decision. Expense Management doesn't set or enforce your stand-in.
  • A payment approved without an answered check is still recorded from your account events. Expense Management evaluates it after the fact. If it is out of policy, the expense is flagged and sent to the business's approvers for review. It is never reversed.

Errors​

StatusMeaningRetry
400The request doesn't match the schemaNo
401, 403Missing or invalid token, or the exp.bank scope is missingNo. Fix the credential
409check_id reused with a different amount, account or payerNo
429, 503Rate-limited or temporarily unavailableNo. Apply your stand-in

Recommendations​

  • Check every card payment on a funding account linked to Expense Management. Without the check, policy is applied only after the payment.
  • Keep the issuer processor's IDs from the authorization (transaction_id, tenant_token_ref, tenant_customer_ref, the static token ID). You send them on the check and on every later account event.
  • Use one check_id per authorization message. An incremental authorization is a new check that points to the original one.