API problem detail
A payment method is required
Description
An approval ($Verify or $VerifyAndSend, granular or bundled) was refused because
DirecFunds could not confirm a chargeable billing payment method for the company: no card or bank account was
saved, the card expired, the method was removed or blocked, or the saved method is not a card or US bank
account (a Stripe Link wallet is not accepted). The response is Problem Details with
errorCode BILLING_PAYMENT_METHOD_REQUIRED and a detail (also in
message) that names the problem. Nothing was verified, billed, or moved.
This refusal happens only where billing payment-method enforcement is enabled. GET /Onboarding/Readiness does not include it, so
disbursementsEnabled: true can still be followed by this refusal.
The same errorCode is also returned when the billing check itself is briefly unavailable. In that
case the detail ends with "Try again later; no new billable work was started." and the company's
payment method may be fine.
Response errorCode: BILLING_PAYMENT_METHOD_REQUIRED.
Experience API error bodies also carry errorCode, resolution, and
traceId. Branch on errorCode, not on title or
detail; see fields on every error.
How to resolve
If the detail says to try again later, nothing needs to change: wait a minute and repeat the
call with a new X-Idempotency-Key.
Otherwise ask a company administrator to add or update a card or bank account under
Billing → Payment method in the DirecFunds portal, then repeat the call with a
new X-Idempotency-Key. Approval reads the billing status live, so a newly saved method is seen
on the next attempt. Payments that were already approved are not affected.