Integration and API Spec

Integration and API Spec

Subscription and Recurring Billing

HubSpot is the subscriber data source for Agent 1 (Billing Cycle Agent) and the status-update sink for Agent 2 (Failed Payment Recovery Agent). The automation reads contact and deal records to build the billing list and writes billing-status properties back after each payment outcome.

// Input to Agent 1
GET /crm/v3/objects/contacts?filterGroups=[{subscription_status=active}]
  Returns: contact_id, email, firstname, lastname, subscription_tier,
           mrr_amount, billing_cycle_day, stripe_customer_id

// Output from Agent 2
PATCH /crm/v3/objects/contacts/{contact_id}
  Body: { last_payment_status, last_payment_date, subscription_status }

Xero is used by Agent 1 (Billing Cycle Agent) to create invoices and by Agent 3 (Reconciliation and Notification Agent) to mark invoices as paid and flag unmatched items for human review.

// Input to Agent 1 (invoice creation)
POST /api.xro/2.0/Invoices
  Body per subscriber: { Type: ACCREC, Contact: { ContactID },
    LineItems: [{ Description, Quantity: 1, UnitAmount: mrr_amount,
    AccountCode, TaxType }], InvoiceStatus: AUTHORISED,
    DueDate: billing_cycle_day + 7 days, Reference: stripe_payment_intent_id }

// Output from Agent 3 (mark as paid)
POST /api.xro/2.0/Payments
  Body: { Invoice: { InvoiceID }, Account: { Code: XERO_BANK_ACCOUNT_CODE },
    Date: payment_date, Amount: amount_paid }

Stripe is used by Agent 1 to trigger payment charges, by Agent 2 to detect failures and schedule retries, and by Agent 3 to confirm successful payments for reconciliation. Stripe is the event source for both the failure and success branches of the automation.

// Input to Agent 1 (charge subscriber)
POST /v1/payment_intents
  Body: { amount: mrr_amount_cents, currency: 'usd',
    customer: stripe_customer_id, payment_method: default_payment_method,
    confirm: true, metadata: { xero_invoice_id, hubspot_contact_id } }

// Inbound webhook to Agent 2 (failure event)
POST {platform_inbound_url}/stripe/webhook
  Stripe-Signature header validated against STRIPE_WEBHOOK_SIGNING_SECRET
  Event type: payment_intent.payment_failed
  Payload fields used: id, customer, amount, last_payment_error.message,
    metadata.xero_invoice_id, metadata.hubspot_contact_id

// Inbound webhook to Agent 3 (success event)
  Event type: payment_intent.succeeded
  Payload fields used: id, customer, amount, created,
    metadata.xero_invoice_id, metadata.hubspot_contact_id

Gmail is used by Agent 2 (Failed Payment Recovery Agent) to send payment-failure notifications and by Agent 3 (Reconciliation and Notification Agent) to send invoice confirmation emails to successful payers. All emails use pre-approved templates stored in the credential or configuration store.

// Output from Agent 2 (failed payment email)
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
  Body (base64-encoded RFC 2822): To: subscriber_email,
    From: GMAIL_SENDER_ADDRESS, Subject: 'Action required: payment failed',
    Body: TEMPLATE_PAYMENT_FAILED rendered with { first_name, invoice_amount,
    card_update_url }

// Output from Agent 3 (confirmation email)
  Subject: 'Payment confirmed - your invoice is attached',
  Body: TEMPLATE_PAYMENT_CONFIRMED rendered with { first_name,
    invoice_amount, invoice_pdf_url }

Slack is used exclusively by Agent 3 (Reconciliation and Notification Agent) to post a billing run summary to the designated finance channel at the end of each billing cycle. This is the only outbound message; Slack sends no inbound events to the automation.

// Output from Agent 3
POST https://slack.com/api/chat.postMessage
  Headers: Authorization: Bearer SLACK_BOT_TOKEN
  Body: { channel: SLACK_FINANCE_CHANNEL_ID, blocks: [
    { type: 'header', text: 'Billing Run Summary - {billing_period}' },
    { type: 'section', fields: [
      { text: 'Invoices raised: {total_invoices}' },
      { text: 'Collected: ${total_collected}' },
      { text: 'Failed: {failed_count}' },
      { text: 'Retries scheduled: {retry_count}' },
      { text: 'Unmatched items: {unmatched_count}' } ] } ] }

// Credential store contents (all entries encrypted at rest)
// Do NOT hardcode any of these values in workflow steps

// HubSpot
HUBSPOT_API_TOKEN            = <private app token>
HUBSPOT_PORTAL_ID            = <portal numeric ID>

// Xero
XERO_CLIENT_ID               = <OAuth app client ID>
XERO_CLIENT_SECRET           = <OAuth app client secret>
XERO_REFRESH_TOKEN           = <OAuth refresh token, auto-rotated>
XERO_TENANT_ID               = <Xero organisation tenant ID>
XERO_ACCOUNT_CODE_MONTHLY    = <e.g. 200>
XERO_ACCOUNT_CODE_ANNUAL     = <e.g. 201>
XERO_TAX_TYPE                = <e.g. TAX001>
XERO_BRANDING_THEME_ID       = <invoice template UUID>
XERO_BANK_ACCOUNT_CODE       = <reconciliation bank account code>

// Stripe
STRIPE_SECRET_KEY            = <restricted key, PaymentIntents + Charges>
STRIPE_WEBHOOK_SIGNING_SECRET = <whsec_...>
STRIPE_RETRY_DELAY_HOURS     = 72
STRIPE_CUSTOMER_PORTAL_URL   = <https://billing.stripe.com/p/login/...>

// Gmail
GMAIL_OAUTH_CLIENT_ID        = <Google OAuth client ID>
GMAIL_OAUTH_CLIENT_SECRET    = <Google OAuth client secret>
GMAIL_OAUTH_REFRESH_TOKEN    = <OAuth refresh token>
GMAIL_SENDER_ADDRESS         = <billing@yourdomain.com>
TEMPLATE_PAYMENT_FAILED      = <key referencing email template store>
TEMPLATE_PAYMENT_CONFIRMED   = <key referencing email template store>

// Slack
SLACK_BOT_TOKEN              = <xoxb-...>
SLACK_FINANCE_CHANNEL_ID     = <C0XXXXXXXXX>
SLACK_BILLING_SUMMARY_TEMPLATE = <key referencing Block Kit template store>