Skip to main content

Integration overview

To offer Expense Management, you connect your core ledger to it in both directions. Every connection is a public HTTPS API. You don't need a private network link, and neither side registers callback URLs.

Prerequisites​

  • A card program with Open Fabric Issuing. Expense Management issues virtual cards on your card program, so you need an active card program. See Card programs. If your cards are processed by another issuer processor, talk to your Open Fabric contact.
  • Authorization and Clearing mode. Your core ledger receives card authorizations, reversal notifications, clearing files and settlement files from your issuer processor. With Open Fabric Issuing, this is Authorization and Clearing mode. See Authorization and Clearing.
  • An Open Fabric API client for your core ledger, with the exp.bank (expense.bank) scope, listed under Expense Management in the portal. You can use the API client you already have for Open Fabric. An admin on your Open Fabric portal account adds the scope. See Authentication.
  • Expense Management enabled on your Open Fabric account. Open Fabric sets this up during onboarding, together with your market (currency, QR standard, locale and time zone) and default branding.

What you build​

DirectionWhatRequiredPage
You → Expense ManagementAuthorization check: ask before you approve a card or QR payment on a business's funding accountYes, for card paymentsAuthorization checks
You → Expense ManagementAccount events: report holds, debits, credits, payouts, fees and declines on the funding accountsYesAccount events
Expense Management → youAccount lookup: account holder, masked number and live balanceYesCore ledger APIs
Expense Management → youQR payments: pay a merchant from a QR code scanned in the appIf you offer QR paymentsCore ledger APIs
Expense Management → youPayouts: reimbursements and supplier payments from the funding accountIf you offer reimbursements or bill payCore ledger APIs
Expense Management → youAccount event list: fill a gap in the event sequenceOptionalCore ledger APIs

What Expense Management handles​

  • Policy evaluation. Spend policies, limits across card, QR and claims, budgets, approved exceptions and your platform-wide card limits.
  • Your card limits on the card itself. With Open Fabric Issuing, your platform-wide blocked categories and card limits are also set as a spend control ruleset on every card. They still apply if a payment is never checked with Expense Management.
  • Card issuing. Expense Management creates virtual cards on your card program when a business admin issues one. Each card is linked to the business's funding account in your ledger.
  • Everything the business uses. The native iOS and Android apps, the business dashboard and the admin console, plus notifications, receipts, approvals and accounting exports. You don't build a user interface.

How a card payment flows​

We recommend this order inside your core ledger:

  1. Your issuer processor's spend controls run before the authorization reaches you. With Open Fabric Issuing, this is your card's spend control ruleset.
  2. Your own checks: available funds, fraud, account status.
  3. Expense Management's authorization check. Decline if it answers decline.
  4. Hold or debit the funding account.
  5. Post an account event that carries the check_id of the check.
Expense Management advises, you decide

Expense Management never approves or declines a payment on your behalf. If its check times out, fails or is rate-limited, you apply your own stand-in decision. Expense Management then reconciles the payment from your account events. An out-of-policy payment is flagged for the business to review, but never reversed.

Authenticating your calls​

Your calls to Expense Management use an OAuth 2.0 access token from your Open Fabric API client:

curl --request POST \
--url https://auth.openfabric.co/oauth2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials \
--data client_id=YOUR_CLIENT_ID \
--data client_secret=YOUR_CLIENT_SECRET

If you request specific scopes, include exp.bank. Send the token as Authorization: Bearer <token>. The token identifies your organization, so no request carries an account or client ID.

Calls from Expense Management to your core ledger APIs use a credential that you issue: an OAuth 2.0 client-credentials token, an API key or mutual TLS. Expense Management stores it encrypted. You can allow-list Expense Management's outbound IP addresses, which we share during onboarding.

Base URLs​

You receive the Expense Management API base URL for each environment during onboarding. You tell us your core ledger API base URL for each environment.

EnvironmentUse
SandboxIntegration testing, demos and user acceptance testing
ProductionLive businesses

Identifiers you'll see​

IdentifierOwned byMeaning
account_refYouThe business's funding account in your ledger. You enter it when you onboard the business.
business_refExpense ManagementThe business. With Open Fabric Issuing, set on each card as tenant_customer_ref.
card_refExpense ManagementThe card. With Open Fabric Issuing, set on each card as tenant_token_ref.
of_transaction_id, of_static_token_idOpen Fabric IssuingThe card payment and the card, as the issuer processor sends them in the authorization.
check_id, event_idYouYour IDs for a check and for an account event. Both make the call idempotent.
expense_mgmt_refExpense ManagementA QR payment (qrp_…) or payout (pay_…) that Expense Management started.

Data rules​

  • Never send a full card number (PAN), CVV or full account number. Card details stay with the issuer processor. Use the last 4 digits at most, and mask counterparty account numbers.
  • Amounts are decimal strings with an ISO 4217 currency code, for example {"amount": "280.00", "currency": "SGD"}.
  • Unknown fields are ignored, so you can send more than a schema asks for.

Next steps​

  1. Authorization checks
  2. Account events
  3. Core ledger APIs
  4. Testing and go-live