Quickstart

Get started with AutopayOS by accepting your first agent payment. This guide walks you through the complete flow: requesting permission, verifying a cart, and executing a payment.

Before you begin

  1. Sign up for an AutopayOS account
  2. Get your API key from the Dashboard
  3. Install the SDK for your language

1. Install the SDK

<tabs> <tab title="TypeScript">
Bash
npm install @autopayos/sdk
# or
pnpm add @autopayos/sdk
# or
yarn add @autopayos/sdk
</tab> <tab title="Python">
Bash
pip install autopayos
</tab> <tab title="cURL">

No installation needed. Use your API key in the Authorization header.

</tab> </tabs>

2. Initialize the client

<tabs> <tab title="TypeScript">
TypeScript
import { AutopayosClient } from '@autopayos/sdk';

const client = new AutopayosClient({
  baseUrl: 'https://api.autopayos.com',
  apiKey: 'ak_live_your_api_key',
});
</tab> <tab title="Python">
Python
from autopayos import AutopayosClient

client = AutopayosClient(
    base_url="https://api.autopayos.com",
    api_key="ak_live_your_api_key"
)
</tab> <tab title="cURL">
Bash
# Set your API key as an environment variable
export AUTOPAYOS_API_KEY="ak_live_your_api_key"
</tab> </tabs>

3. Request permission (Intent)

Before an agent can make a purchase, it must request permission by creating an Intent Mandate. This checks the request against your configured policy.

<tabs> <tab title="TypeScript">
TypeScript
const permission = await client.requestPermission({
  agentDid: 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK',
  principalDid: 'did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH',
  amount: 50.00,
  currency: 'USD',
  merchantDomain: 'amazon.com',
});

if (!permission.allowed) {
  console.error('Permission denied:', permission.reasonCodes);
  // Handle denial: AMOUNT_OVER_CAP, MERCHANT_NOT_ALLOWED, etc.
  return;
}

console.log('Intent approved!', permission.intentVc);
</tab> <tab title="Python">
Python
permission = client.request_permission(
    agent_did="did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    principal_did="did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
    amount=50.00,
    currency="USD",
    merchant_domain="amazon.com"
)

if not permission.allowed:
    print(f"Permission denied: {permission.reason_codes}")
    return

print(f"Intent approved! {permission.intent_vc}")
</tab> <tab title="cURL">
Bash
curl https://api.autopayos.com/ap2/intents \
  -H "Authorization: Bearer $AUTOPAYOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentDid": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "principalDid": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
    "request": {
      "maxAmount": 50.00,
      "currency": "USD",
      "vendorHints": {
        "domain": "amazon.com"
      }
    }
  }'

Response:

JSON
{
  "allowed": true,
  "intentVc": {
    "id": "urn:uuid:intent_abc123",
    "type": ["VerifiableCredential", "IntentMandate"],
    "credentialSubject": {
      "mandateId": "intent_abc123",
      "agentDid": "did:key:z6Mk...",
      "maxAmount": 50.00,
      "currency": "USD"
    }
  },
  "attestation": { ... }
}
</tab> </tabs>

4. Verify the cart

Once the agent has a cart from the merchant, verify it against the intent and policy.

<tabs> <tab title="TypeScript">
TypeScript
const verification = await client.verifyCart({
  intentVc: permission.intentVc,
  cartVc: merchantCartVc, // Cart VC from the merchant
});

if (!verification.allowed) {
  console.error('Cart rejected:', verification.reasonCodes);
  return;
}

console.log('Cart verified!');
console.log('Payment rail:', verification.railDecision.rail);
console.log('Approval token:', verification.approvalToken);
</tab> <tab title="Python">
Python
verification = client.verify_cart(
    intent_vc=permission.intent_vc,
    cart_vc=merchant_cart_vc  # Cart VC from the merchant
)

if not verification.allowed:
    print(f"Cart rejected: {verification.reason_codes}")
    return

print(f"Cart verified!")
print(f"Payment rail: {verification.rail_decision['rail']}")
print(f"Approval token: {verification.approval_token}")
</tab> <tab title="cURL">
Bash
curl https://api.autopayos.com/ap2/carts/validate \
  -H "Authorization: Bearer $AUTOPAYOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intentVc": { ... },
    "cartVc": {
      "type": ["VerifiableCredential", "CartMandate"],
      "credentialSubject": {
        "merchant": "amazon.com",
        "items": [
          { "name": "USB-C Cable", "price": 12.99, "quantity": 2 }
        ],
        "total": 25.98,
        "currency": "USD"
      }
    }
  }'

Response:

JSON
{
  "allowed": true,
  "approvalToken": "apt_xyz789...",
  "railDecision": {
    "rail": "STRIPE",
    "reason": "Optimal for merchant capabilities",
    "expiresAt": "2025-12-17T10:05:00Z"
  }
}
</tab> </tabs>

5. Execute the payment

With the approval token, execute the payment to receive a Payment Mandate.

<tabs> <tab title="TypeScript">
TypeScript
const payment = await client.executePayment({
  approvalToken: verification.approvalToken,
});

console.log('Payment authorized!');
console.log('Mandate ID:', payment.pmVc.credentialSubject.mandateId);
</tab> <tab title="Python">
Python
payment = client.execute_payment(
    approval_token=verification.approval_token
)

print(f"Payment authorized!")
print(f"Mandate ID: {payment.pm_vc['credentialSubject']['mandateId']}")
</tab> <tab title="cURL">
Bash
curl https://api.autopayos.com/ap2/payments/mandate \
  -H "Authorization: Bearer $AUTOPAYOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "approvalToken": "apt_xyz789..."
  }'

Response:

JSON
{
  "pmVc": {
    "type": ["VerifiableCredential", "PaymentMandate"],
    "credentialSubject": {
      "mandateId": "pm_abc123",
      "amount": 25.98,
      "currency": "USD",
      "expiresAt": "2025-12-17T10:10:00Z"
    },
    "proof": {
      "type": "Ed25519Signature2020",
      "jws": "eyJhbGciOiJFZERTQSJ9..."
    }
  }
}
</tab> </tabs>

Complete example

Here's the full flow in one script:

TypeScript
import { AutopayosClient } from '@autopayos/sdk';

async function makePurchase() {
  const client = new AutopayosClient({
    baseUrl: 'https://api.autopayos.com',
    apiKey: process.env.AUTOPAYOS_API_KEY,
  });

  // Step 1: Request permission
  const permission = await client.requestPermission({
    agentDid: 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK',
    principalDid: 'did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH',
    amount: 50.00,
    currency: 'USD',
    merchantDomain: 'amazon.com',
  });

  if (!permission.allowed) {
    throw new Error(`Permission denied: ${permission.reasonCodes?.join(', ')}`);
  }

  // Step 2: Get cart from merchant (simulated)
  const cartVc = await getCartFromMerchant('amazon.com', [
    { name: 'USB-C Cable', price: 12.99, quantity: 2 }
  ]);

  // Step 3: Verify cart
  const verification = await client.verifyCart({
    intentVc: permission.intentVc,
    cartVc: cartVc,
  });

  if (!verification.allowed) {
    throw new Error(`Cart rejected: ${verification.reasonCodes?.join(', ')}`);
  }

  // Step 4: Execute payment
  const payment = await client.executePayment({
    approvalToken: verification.approvalToken,
  });

  console.log('Payment complete!');
  console.log('Mandate ID:', payment.pmVc.credentialSubject.mandateId);
  
  return payment;
}

makePurchase();

What's next?

Now that you've completed your first payment flow:

Test mode

Use the sandbox environment for testing:

TypeScript
const client = new AutopayosClient({
  baseUrl: 'https://sandbox-api.autopayos.com',
  apiKey: 'ak_test_your_test_key',
});

See the Testing guide for test DIDs, demo endpoints, and sandbox features.