@conto_finance/sdk 0.4.0 or later. A standard agent SDK key has the transactions:read and payments:approve scopes these calls need. See authentication.
Request and use a credential
Callconto.connectedCards.list() for card IDs and active mandates. Pass the card and mandate IDs to draw() with a saved 8–128 character idempotency key. A draw requests a credential. Amounts are USD cents: 2500 means $25.00.
completeAuthorizedCheckout is your application’s function. It must use the authorized merchant and checkout origin, enforce the purchase amount, and prevent duplicate checkout. Never persist credentials or expose them in prompts, tool results, logs, traces, or screenshots.
Check a purchase first
Before you ask the cardholder to authorize a purchase, you can check it against the agent’s card limits and policies. The check reserves nothing, creates no authorization, and returns no credential.decision is APPROVED, DENIED, or REQUIRES_APPROVAL, and reasons explains a denial. Send the store details the authorization will record. All merchant fields are optional: name, providerMerchantId, categoryCode (four-digit MCC), countryCode (two-letter code), and checkoutOrigin (HTTPS).
The draw rechecks current limits and policies against the verified authorization; a successful preview does not authorize checkout.
Decisions and retries
Credentials are returned only once. The SDK does not automatically retry
draw(), and reusing a key cannot retrieve a lost credential. Do not generate a new key to recover an uncertain result. A failed checkout does not return the amount to the verified authorization, even after the hold on the agent’s limits is released.
If the card provider refuses to issue a credential, the draw returns DENIED with the reason. Nothing was charged, the hold is released, and a single-purchase authorization stays usable, so you can retry with a new idempotency key.
acknowledgeDelivery() is safe to retry for the same request. It records receipt of the credential, not payment settlement. Keep the request ID and non-sensitive order references, and confirm the purchase against the merchant receipt and card activity. Contact support if the outcome remains unclear.
Purpose and task
A draw takes two optional fields, indraw() and in the request body:
purpose: why the agent wants this purchase, up to 500 characters. People reviewing the draw see it, and it stays on the purchase record. Text that looks like a card number or a labeled secret is refused with 400.taskRequestId: an approved task, for a shared budget that requires one.
DENIED with no credential, the reason in reasons, and a code in reasonCodes. A test card draw returns reasonCodes too. Common codes:
See budget errors for more.
Get the task approved before you draw. A draw a budget refuses keeps its single-purchase authorization, unless another purchase takes the last of the budget at that same moment. Then the next try needs a new one.
Report the outcome
The draw’s amount stays held against the agent’s limits until Conto knows what happened. After checkout, callreportOutcome():
USED at the full amount closes the draw. NOT_USED, or a smaller amount, goes under Needs attention on the agent’s Funding tab with your report shown. A person checks the card’s activity and confirms, and only then is the rest of the hold released. An unused credential is shown there once it expires. The result has closed and reviewRequired so your agent knows which happened.
reportOutcome() is safe to retry with the same report. A different second report returns 409. If the agent reports nothing, the draw also goes under Needs attention an hour after its credential expires.
Test cards
A test card works on every plan and uses the same agent key and scopes. Draws go through the agent’s limits, your policies, and human review like a live card, and the same retry rules apply. The differences:- Test cards have their own endpoints. A live card or authorization ID is not found there, and a test ID is not found on the live endpoints.
- An approved draw returns
testCredential, an opaque token that starts withctc_test_, instead of card fields. It is returned once. Handle it like a live credential: keep it out of prompts, tool results, and logs. - The purchase completes at Conto’s test checkout, the only place the token works. Checkout returns a receipt with
environment: "test",simulated: true, andsettlementMode: "test". Retrying checkout with the same draw and token returns the same receipt withreplayed: true. - Test purchases are simulated. No card is charged and no funds move.
merchants lists each test merchant’s catalog. Leave out items to buy one line for the authorized amount. An order above the authorized amount, or an item the merchant does not sell, is declined with 409 and leaves the credential usable until it expires. A credential expires 15 minutes after it is issued.
HTTP endpoints
Test cards:
Use bearer authentication. On a draw, all
merchant fields are optional: merchantName, merchantId, merchantCategory (four-digit MCC), and merchantCountry (two- or three-letter code). Any field you send must match the verified mandate exactly, or the request fails with 400. amountMinor cannot exceed the mandate amount.