Conto Commerce quickstart

Conto Commerce lets your platform’s agents buy from online stores for your users. Your server starts a purchase from a product URL and a task. Conto shops, checks out and pays with the buyer’s own card, and your user reviews each purchase on a Conto page. Your platform never handles card details. Test mode is open to every organization. A test card pays only Conto’s test stores, so this whole page runs without a real card, a real store or a charge.

1. Create a key

Create an organization API key in Settings > API Keys. The Standard preset covers buyers, setup and purchases. Setting allowed return origins needs org:write, which the Admin preset includes. Keep the key on your server. Purchases with one organization key need an @conto_finance/sdk release that includes admin.purchasing.purchases.

2. Set up a test buyer

Map one of your users to a buyer and send them to Conto’s setup page.

import { ContoAdmin } from '@conto_finance/sdk';

const admin = new ContoAdmin({ orgApiKey: process.env.CONTO_ORG_API_KEY! });

await admin.purchasing.settings.update({ allowedReturnOrigins: ['http://localhost:4100'] });

const buyer = await admin.purchasing.buyers.create({
  externalId: 'test-user-1',
  email: 'buyer@example.com',
});

const link = await admin.purchasing.paymentMethods.createSetupLink({
  buyerId: buyer.id,
  environment: 'test',
  returnUrl: 'http://localhost:4100/',
});
console.log(link.url);

Open link.url in a browser. It works once and expires in 10 minutes. On the page, confirm the spending limits, add the test card and let the agent shop with it. The same externalId returns the same buyer, so reuse it while you test. Each buyer uses one agent in your plan.

3. Buy from a test store

const purchases = admin.purchasing.purchases;

const purchase = await purchases.create(
  {
    buyerId: buyer.id,
    request: {
      url: 'https://supplies.conto-test.invalid/products/notebook-pack',
      task: 'Buy one pack of notebooks with standard shipping',
    },
    maxCost: { amountMinor: 2000, currency: 'USD' },
  },
  { idempotencyKey: `order-${Date.now()}` }
);

for await (const event of purchases.watch(purchase.id)) {
  const { status, requiredAction } = event.data;
  console.log(event.version, status);

  if (requiredAction?.kind === 'buyer_details') {
    await purchases.respond(purchase.id, {
      actionId: requiredAction.id,
      revision: requiredAction.revision,
      fields: {
        name: 'Sample Buyer',
        email: 'buyer@example.com',
        phone: '4155550100',
        address: '1 Market Street',
        city: 'San Francisco',
        region: 'CA',
        postalCode: '94105',
        country: 'US',
      },
    });
  }

  if (requiredAction?.kind === 'purchase_review') {
    const review = await purchases.createActionLink(purchase.id);
    console.log('Open to approve:', review.url);
  }
}

The store asks for delivery details, which your server answers. The buyer then opens the review link, checks the items, total and delivery details, and approves.

4. Read the result

const done = await purchases.get(purchase.id);
console.log(done.status, done.result?.merchantReference);
// succeeded TEST-3BE45BD829

succeeded means the store confirmed the order. paymentEvidence reports authorization, the store’s confirmation and settlement separately.

Go live

Live purchases need Conto to enable them for your organization, a Builder or Enterprise plan, and the buyer’s own card. Until then, live setup links and live purchases are refused with LIVE_NOT_ENABLED. admin.purchasing.capabilities() reports environments.live.available for your organization. Your code does not change for live: create the setup link without environment: 'test' and buy from a real store URL. For events in production, use webhooks instead of holding a stream open.

Build it with a coding agent

Paste this into your coding agent from your app’s repository:

Add Conto Commerce to this app with @conto_finance/sdk and an organization API key from
CONTO_ORG_API_KEY, on the server only. Follow https://conto.finance/docs/guides/commerce-quickstart
and https://conto.finance/docs/sdk/purchases.
1. Map each signed-in user to a buyer with admin.purchasing.buyers.create({ externalId: user.id, email }).
2. Add a "Set up purchasing" button that redirects to a test setup link from
   admin.purchasing.paymentMethods.createSetupLink({ buyerId, environment: 'test', returnUrl }).
3. Start purchases with admin.purchasing.purchases.create({ buyerId, request: { url, task }, maxCost })
   and a stable idempotency key per order.
4. Answer buyer_details actions with the user's saved address, and send the user to
   purchases.createActionLink(id) for review and card verification.
5. Receive events by webhook and verify each with verifyPurchaseWebhook.
Never handle card numbers, and never approve a review on the user's behalf.

Conto Commerce API reference: statuses, actions, events, webhooks, errors and test stores.
MCP tools: the purchase tools for agents that call Conto themselves.

Get started

Integrate

Payments

Conto Commerce

Spending controls

Operate

Conto Pay

Conto Commerce quickstart

1. Create a key

2. Set up a test buyer

3. Buy from a test store

4. Read the result

Go live

Build it with a coding agent

Next

​1. Create a key

​2. Set up a test buyer

​3. Buy from a test store

​4. Read the result

​Go live

​Build it with a coding agent

​Next

1. Create a key

2. Set up a test buyer

3. Buy from a test store

4. Read the result

Go live

Build it with a coding agent

Next