AI agents can finally accept payments.

import { VoicePay } from '@voicepay/sdk';

const voicepay = new VoicePay('vp_live_your_api_key');

// Called by your voice agent when the conversation reaches checkout.
export async function handlePayment(call) {
  const session = await voicepay.payments.create({
    amount: 14999,               // cents
    currency: 'usd',
    call_id: call.id,            // your provider's call id
    merchant_id: 'mch_bs_main',  // which gateway account settles this
    description: 'Teeth cleaning appointment',
    metadata: {
      customer_name: call.caller.name,
      appointment_date: '2026-08-06',
    },
  });

  // Capture runs field by field on the caller's own leg.
  // Your agent is muted from the keypad tones for the whole sequence.
  for (const field of session.required) {
    // -> 'card_number' | 'expiry' | 'cvc' | 'postal_code'
    await session.capture(field);
  }

  const payment = await session.complete({
    idempotency_key: `${call.id}:charge:1`,
  });

  if (payment.status === 'succeeded') {
    await call.say(
      `Payment of $${payment.amount / 100} confirmed. You're all set!`
    );
  }

  return payment;
}

from voicepay import VoicePay

voicepay = VoicePay("vp_live_your_api_key")


async def handle_payment(call):
    session = await voicepay.payments.create(
        amount=14999,                # cents
        currency="usd",
        call_id=call.id,             # your provider's call id
        merchant_id="mch_bs_main",   # which gateway account settles this
        description="Teeth cleaning appointment",
        metadata={
            "customer_name": call.caller.name,
            "appointment_date": "2026-08-06",
        },
    )

    # 'card_number', 'expiry', 'cvc', 'postal_code' — the connector
    # decides which fields are required; iterate whatever it asks for.
    for field in session.required:
        await session.capture(field, timeout=30)

    payment = await session.complete(
        idempotency_key=f"{call.id}:charge:1",
    )

    if payment.status == "succeeded":
        await call.say(
            f"Payment of ${payment.amount / 100:.2f} confirmed. You're all set!"
        )

    return payment

# 1. Open a capture session on the live call
curl https://api.voicepay.dev/v1/payments/sessions \
  -H "Authorization: Bearer vp_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 14999,
    "currency": "usd",
    "call_id": "call_a1b2c3d4",
    "merchant_id": "mch_bs_main",
    "description": "Teeth cleaning appointment",
    "capture_method": "dtmf_secure"
  }'
# -> { "id": "pay_3M2n9Rx4", "status": "requires_capture",
#      "required": ["card_number", "expiry", "cvc", "postal_code"] }

# 2. Capture one field. Blocks until the caller finishes it.
curl https://api.voicepay.dev/v1/payments/pay_3M2n9Rx4/capture \
  -H "Authorization: Bearer vp_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "field": "card_number", "timeout": 30 }'
# -> { "field": "card_number", "status": "captured", "masked": "•••• 4242" }

# 3. Charge. This is the only call that reaches the gateway.
curl https://api.voicepay.dev/v1/payments/pay_3M2n9Rx4/complete \
  -H "Authorization: Bearer vp_live_your_api_key" \
  -H "Idempotency-Key: call_a1b2c3d4:charge:1"
# -> { "id": "pay_3M2n9Rx4", "status": "succeeded", "amount": 14999,
#      "card": { "brand": "visa", "last4": "4242" },
#      "receipt_url": "https://pay.voicepay.dev/r/3M2n9Rx4" }

{
  "tools": [
    {
      "name": "start_payment",
      "description": "Open a secure card capture on the caller's line. Call this once the customer has agreed to pay.",
      "url": "https://api.voicepay.dev/v1/retell/payments/start",
      "parameters": {
        "amount": { "type": "number", "description": "Amount in cents" },
        "description": { "type": "string" }
      }
    },
    {
      "name": "capture_field",
      "description": "Collect one field from the keypad. Call in order: card_number, expiry, cvc, postal_code. Returns when the customer has finished entering it.",
      "url": "https://api.voicepay.dev/v1/retell/payments/capture",
      "parameters": {
        "field": {
          "type": "string",
          "enum": ["card_number", "expiry", "cvc", "postal_code"]
        }
      }
    },
    {
      "name": "complete_payment",
      "description": "Submit the card for authorization and return the result.",
      "url": "https://api.voicepay.dev/v1/retell/payments/complete"
    }
  ],
  "auth": { "type": "bearer", "token": "vp_live_your_api_key" }
}

No backend required. Paste three tools into your Retell or VAPI agent, point your number at VoicePay, and your agent can take money.