v1

latestOpenAPI 3.1.02026-08-047829.9 KB

Request a payment credential

Request a single-use virtual card to execute a specific purchase against an active mandate. Allowance automatically validates the request against the mandate rules — amount, merchant, merchant category, and time period. No human approval is needed at this step; the human already approved the mandate.

If validation passes, a virtual card (PAN, expiry, CVV) is returned. The agent uses these details at merchant checkout like a normal card number. The card is single-use, amount-capped, and short-lived — safety comes from these constraints, not from hiding credentials.

For cadence: "once" mandates, the mandate automatically moves to exhausted status after the first virtual card is issued.

post/mandates/{id}/credential-requests

Path parameters

idstring required

Headers

Idempotency-Keystring

Client-generated unique key. Same key returns the same response without re-executing the operation. Always set this on credential requests.

Request body

amountinteger required

Requested amount in minor currency units (cents). Example: 47231 = $472.31. Never use floats.

currencystring required
merchantstring required

Name of the merchant where the purchase will be made.

merchant_category_codestring

4-digit ISO 18245 MCC for the merchant.

contextstring required

Human-readable explanation of why this purchase is being made. Appears in the owner's transaction log. Be specific — this is the audit trail.

idempotency_keystring

Always set this. Prevents duplicate credential issuance on retries.

metadataobject

Response

Credential request processed. Check validation.passed for the outcome.

idstring required

Unique credential request ID.

mandate_idstring required
amountinteger required

Requested amount in minor currency units.

currencystring required
merchantstring required
merchant_category_codestring
contextstring
idempotency_keystring
metadataobject
status'approved' | 'denied' | 'expired' required

approved = token issued, proceed with purchase. denied = mandate rules not satisfied, do not proceed. expired = mandate expired before this request was evaluated.

created_atstring date-time required