Batch Files vs APIs: Which Integration Is Right for You?

South African banks and payment providers generally support two integration styles for collections and payouts: real-time APIs and host-to-host batch files. Both can carry the same payment instructions, such as DebiCheck mandates, EFT debit orders and credit payouts, but they differ in latency, operating model and the skills needed to run them.

Most banks publish both an API specification and a file specification for the same streams, so this is a genuine architectural choice rather than a forced one.

How does a batch file integration work?

In a host-to-host model, you exchange structured files with the bank or provider over a secure channel such as SFTP or Connect:Direct. Files follow a fixed-format or ISO 20022 layout defined in the bank's specification document.

A typical cycle looks like this:

1. You generate a file of instructions with a unique file name or sequence number and unique references per record.
2. You transmit it before the submission cut-off for the processing cycle.
3. The bank returns an acknowledgement file confirming the file was received and passed structural validation, or rejecting it with reasons.
4. Response files follow on the processing cycle, reporting per-instruction outcomes.
5. Unpaid files arrive over subsequent days for collections that are returned.

Missing a cut-off moves the whole file to the next cycle, so cut-off times and value dates drive the operating rhythm.

How does an API integration work?

With an API, your system submits instructions individually or in small batches over HTTPS, authenticated as described in API authentication and signatures. Validation results come back immediately in the response, and asynchronous outcomes, such as DebiCheck authentication results and collection unpaids, are delivered through webhooks and callbacks or status queries.

Batch files vs APIs: side-by-side

When are batch files the better fit?

• You submit large, predictable runs, for example monthly premium collections across hundreds of thousands of policies.
• Your outcomes are naturally cyclical and next-day results are acceptable.
• Your organisation already operates file-based bank integrations and has the scheduling, monitoring and support processes in place.

When are APIs the better fit?

• You need real-time DebiCheck mandate authentication while the customer is on the phone or in your app.
• Instructions are created continuously rather than in periodic runs.
• You want immediate validation feedback instead of discovering errors in a response file the next day.
• Lower latency matters for customer experience or downstream automation.

Can you use both?

Yes, and larger collectors often do: APIs for real-time mandate authentication and ad-hoc instructions, files for bulk collection runs. The DebiCheck-specific view of this decision is covered in API vs host-to-host for DebiCheck.

Whichever channel you use, the same disciplines apply: unique references per instruction, duplicate protection at file and record level, structured handling of reason codes and daily reconciliation of outcomes.

Back to the Payment Operations hub.