422

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.

Back to all problem details