Collect — money in

req = atoa.payment.collect(
    amount={"amount": 45.00},    # pounds, not pence (45.00 = £45); GBP default
    order_id="order-1099",       # your own reference
)

print(req.payment_url)           # hand over the link
print(req.qr_code_url)           # or the QR

settled = atoa.payment.await_settled(req.payment_request_id)
print(settled.status)            # COMPLETED

const req = await atoa.payment.collect({
  amount: { amount: 45.00 },     // pounds, not pence (45.00 = £45); GBP default
  orderId: "order-1099",         // your own reference
});

console.log(req.paymentUrl);     // hand over the link
console.log(req.qrCodeUrl);      // or the QR

const settled = await atoa.payment.awaitSettled(req.paymentRequestId);
console.log(settled.status);     // COMPLETED

customer = atoa.customer.create(
    full_name="Ada Lovelace",
    email="[email protected]",      # email or phone required
)

contract = atoa.contract.create(
    type="COLLECT",
    name="Monthly membership",
    atoa_customer_id=customer.id,
    limits={
        "max_per_payment": 50.00,
        "period_limits": [{"amount": 100.00, "period": "MONTH"}],
        "valid_to": "2026-12-31T23:59:59Z",
    },
)

print(contract.authorization_url)                # customer links a method + approves the caps here
atoa.contract.await_active(contract.contract_id)          # → ACTIVE

charge = atoa.payment.collect(
    contract_id=contract.contract_id,
    atoa_customer_id=customer.id,
    amount={"amount": 20.00},
    order_id="membership-jan",
)
# charge.next_action — the customer approves before it settles (next section)

const customer = await atoa.customer.create({
  fullName: "Ada Lovelace",
  email: "[email protected]",       // email or phone required
});

const contract = await atoa.contract.create({
  type: "COLLECT",
  name: "Monthly membership",
  atoaCustomerId: customer.id,
  limits: {
    maxPerPayment: 50.00,
    periodLimits: [{ amount: 100.00, period: "MONTH" }],
    validTo: "2026-12-31T23:59:59Z",
  },
});

console.log(contract.authorizationUrl);          // customer links a method + approves the caps here
await atoa.contract.awaitActive(contract.contractId);    // → ACTIVE

const charge = await atoa.payment.collect({
  contractId: contract.contractId,
  atoaCustomerId: customer.id,
  amount: { amount: 20.00 },
  orderId: "membership-jan",
});
// charge.nextAction — the customer approves before it settles (next section)

usage = atoa.contract.get(contract.contract_id).usage or []
month = next((u for u in usage if u.period == "MONTH"), None)
print(month.remaining)           # what is left this window; over-cap charges fail LIMIT_EXCEEDED

const { usage } = await atoa.contract.get(contract.contractId);
const month = usage?.find((u) => u.period === "MONTH");
console.log(month?.remaining);   // what is left this window; over-cap charges fail LIMIT_EXCEEDED

contract = atoa.contract.create(
    type="COLLECT",
    name="Gym membership",
    atoa_customer_id=customer.id,
    limits={
        "max_per_payment": 50.00,
        "period_limits": [{"amount": 50.00, "period": "MONTH"}],
        "valid_to": "2027-01-31T23:59:59Z",
    },
    initial_charge={
        "amount": 25.00,             # ≥ £1 and ≤ max_per_payment
        "order_id": "joining-1001",  # your reference (≤ 50 chars)
        "notes": "Joining fee",      # optional (≤ 30 chars)
    },
)

# One approval at contract.authorization_url activates the contract AND takes the charge.
atoa.contract.await_active(contract.contract_id)
first = atoa.contract.get(contract.contract_id).initial_charge
print(first.status)                  # AWAITING_APPROVAL → PENDING → COMPLETED | FAILED

const contract = await atoa.contract.create({
  type: "COLLECT",
  name: "Gym membership",
  atoaCustomerId: customer.id,
  limits: {
    maxPerPayment: 50.00,
    periodLimits: [{ amount: 50.00, period: "MONTH" }],
    validTo: "2027-01-31T23:59:59Z",
  },
  initialCharge: {
    amount: 25.00,             // ≥ £1 and ≤ maxPerPayment
    orderId: "joining-1001",   // your reference (≤ 50 chars)
    notes: "Joining fee",      // optional (≤ 30 chars)
  },
});

// One approval at contract.authorizationUrl activates the contract AND takes the charge.
await atoa.contract.awaitActive(contract.contractId);
const { initialCharge } = await atoa.contract.get(contract.contractId);
console.log(initialCharge?.status);  // AWAITING_APPROVAL → PENDING → COMPLETED | FAILED

share_with_customer(charge.next_action.approval_url)   # your own delivery — email, push, …
decision = atoa.payment.await_decision(charge.next_action.approval_id)
print(decision.status)                                  # APPROVED / DECLINED / EXPIRED

settled = atoa.payment.await_settled(charge.payment_request_id)
print(settled.status)                                   # COMPLETED

shareWithCustomer(charge.nextAction.approvalUrl);    // your own delivery — email, push, …
const decision = await atoa.payment.awaitDecision(charge.nextAction.approvalId);
console.log(decision.status);                        // APPROVED / DECLINED / EXPIRED

const settled = await atoa.payment.awaitSettled(charge.paymentRequestId);
console.log(settled.status);                         // COMPLETED

refund = atoa.payment.refund(
    req.payment_request_id,
    amount={"amount": 10.00},       # omit for a full refund
    reason="Damaged item",
)
print(refund.status, refund.refund_amount)

atoa.payment.list_refunds(req.payment_request_id)       # all refunds on this payment

const refund = await atoa.payment.refund(req.paymentRequestId, {
  amount: { amount: 10.00 },      // omit for a full refund
  reason: "Damaged item",
});
console.log(refund.status, refund.refundAmount.amount);

await atoa.payment.listRefunds(req.paymentRequestId);   // all refunds on this payment