@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(). Each entry in cards has a cardId and the active mandates (verified authorizations) the agent can use. Pass cardId and a mandate id to draw(). A credential request is called a draw. Use a stable 8–128 character idempotency key per draw. Amounts are in 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).
A preview is a check, not a decision on the purchase. Limits, spend, and policies can change before the draw. The draw decides again, using the store details on the verified authorization.
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.
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 Connected Cards 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.