The Payment Module API enables automated creation, execution, scheduling, and monitoring of payments for new or existing transaction agreements.

It supports both Biz Core-managed and partner-managed (just-in-time) scheduling, allowing integrators to choose the model that best fits their platform and operational requirements.

---

High-Level Integration Flow

flowchart TD
    Start([Create transaction agreement<br/>without source]) --> Choice{Scheduling<br/>strategy?}

    Choice -->|Biz Core-managed| BCM1[Schedule all<br/>transactions immediately]
    Choice -->|Partner-managed| PM1

    BCM1 --> BCM2[Customer provides<br/>payment method]
    PM1[Customer provides<br/>payment method]

    BCM2 --> Pay{Payment type?}
    PM1 --> Pay

    Pay -->|Direct Debit| Sign[Customer signs<br/>DDA]
    Pay -->|Card| Skip[Source authorised on<br/>card details submission]

    Sign --> Exec
    Skip --> Exec

    Exec{Execution model}
    Exec -->|Biz Core-managed| AutoExec[Biz Core executes<br/>on schedule]
    Exec -->|Partner-managed| AdHoc[Partner executes<br/>ad-hoc via API]

    AutoExec --> Track[Track transaction<br/>status]
    AdHoc --> Track

    Track --> DD{Direct Debit?}
    DD -->|Yes| Late[Monitor late rejections<br/>for at least 7 days]
    DD -->|No| End([Complete])
    Late --> End

    style Start fill:#e6f1fb,stroke:#185fa5,color:#0c447c
    style End fill:#eaf3de,stroke:#3b6d11,color:#173404
    style Choice stroke-dasharray: 5 5
    style Pay stroke-dasharray: 5 5
    style Exec stroke-dasharray: 5 5
    style DD stroke-dasharray: 5 5

⚠️ Important: Direct Debit transactions can be reversed by the financial institution after completion. You must monitor for late rejections for at least 7 days after execution.

---

What the Payments Module Supports

• Creation of transaction agreements between customers and merchants.
• Secure capture and update of payment sources (bank account or card).
• Scheduling of once-off and recurring transactions within agreements.
• Ad-hoc execution of transactions without scheduling.
• Transaction status synchronisation via API polling (pull) or webhooks (push).
• Deferred outcome handling — clearing, disputes, and late rejections.

---

Scheduling Strategy

This is a key design decision and directly affects how the agreement appears in Biz Core. Choose your strategy before going live, as switching mid-agreement requires cleanup of scheduled transactions.

Option 1 — Biz Core-managed schedule

• All scheduled transactions are created immediately after agreement creation.
• The agreement in Biz Core shows the full payment schedule, recurring transaction definitions, and individual scheduled payments.

Recommended when:

• Payment plans are fixed at agreement creation.
• You want Biz Core to fully represent the repayment schedule.

Option 2 — Partner-managed schedule

• Your platform manages the schedule internally.
• Biz Core only reflects the agreement terms and executed transactions — no scheduled transactions are visible on the agreement.

Why most partners choose this:

• Customers frequently change payment frequency or dates.
• Catch-up and additional payments are common.
• Declines and retries require custom logic.
• Eliminates ongoing resync of scheduled transactions between systems.

Comparison

---

Authentication

The Payment Module uses HAWK authentication — see Getting Started for implementation details, API key generation, and library recommendations.

---

Integration Guide

Step 1 — Create a Transaction Agreement (Without Source)

Call Create New Agreement Without Source to create the agreement and customer record. The response returns identifiers and a Source Creation URL for collecting payment details.

Outcome:

• Agreement created.
• Customer created or associated.
• Agreement identifiers returned to your platform.
• Source Creation URL generated.

---

Step 2 — Schedule Transactions (Biz Core-managed only)

Skip this step if you are using a partner-managed schedule.

If Biz Core will manage the payment schedule, call Schedule Transactions immediately after creating the agreement to schedule all once-off and recurring transactions.

Notes:

• Scheduled transactions appear on the agreement record.
• Recurring schedules generate individual future transactions.
• Scheduled transaction details become visible on the DDA document and on the agreement page in the Biz Core portal.

---

Step 3 — Customer Provides Payment Method Details

Present the Source Creation URL returned in Step 1 to the customer via:

• Redirect
• Iframe embed
• Secure link

Biz Core securely collects and stores the payment method.

ℹ️ Note: If the customer chooses to pay by card, the separate Direct Debit Authority (DDA) signing process in Step 4 is not required.

---

Step 4 — Customer Signs the Agreement (Direct Debit only)

Once bank account details have been provided, the customer is automatically redirected to a signing page to authorise the DDA.

After signing:

• The agreement becomes fully authorised.
• Scheduled transactions (if any) are locked in.
• Payments can now be executed.

---

Step 5 — Execute Payments

Option A — Biz Core-managed schedule

Payments are executed automatically by Biz Core on their scheduled dates. No additional API calls are required.

Option B — Partner-managed (ad-hoc execution)

Call Execute Transaction to run a single transaction immediately against an existing agreement, based on your internal schedule.

---

Step 6 — Track Transaction Status

Track progress and outcomes either by polling the status endpoints or by subscribing to webhooks (recommended for production):

• Polling — call Get Transactions Statuses for a specific set of transactions, or Get Transactions Statuses by Date to retrieve all transactions in a date range.
• Webhooks — receive push notifications for individual transaction status changes (including decline reason codes) via the Transaction Status Change webhook.

Transaction Statuses

---

Step 7 — Monitor Late Rejections (Direct Debit only)

Even after a transaction is marked Complete, it may later be reversed by the financial institution. Call Get Late Rejections to retrieve transactions that were reversed after completion.

Best practice:

• Poll daily.
• Monitor for at least 7 days after execution.

---

Agreement Statuses

---

Additional Endpoints

These endpoints support secondary workflows such as agreement signing, payment source updates, and reconciliation. They are not required for the basic happy-path integration but are commonly used in production.

---

Error Handling

Refer to Getting Started — Error Handling for the standard HTTP status codes returned across all Payment Module endpoints. Module-specific error details (e.g. validation failures on agreement creation, late rejection responses) are documented on the relevant API reference pages.

---

Integration Checklist

Before going live:

• Scheduling strategy chosen (Biz Core-managed or partner-managed) and documented.
• Webhook endpoint configured for transaction status changes.
• Late rejection polling scheduled (daily, ≥ 7 days after execution).
• Idempotency handling implemented for webhook payloads.
• Error handling and retry logic implemented for execution and source-update endpoints.
• UAT testing completed for both Direct Debit and card payment flows.
• Customer-facing source update flow (if applicable) tested end-to-end.