Tereina Integration Service API (1.0.0)

The Integration Service connects client ERP systems to the Tereina platform. It lets SAP customers plug their procurement and accounts-payable processes into Tereina's global B2B payment infrastructure using ISO 20022 messaging (with a few Tereina-specific extensions, detailed later in these docs) — without building bespoke integrations per bank or payment rail.

At a high level, the API lets ERPs:

• Send payment instructions into Tereina for processing.
• Receive payment status updates and bank statements once Tereina has executed and reconciled those payments.

See Important Concepts in the sidebar for the terminology and flows referenced throughout the rest of this documentation.

Platform-only data-retention SPI (platform service account)

SaaS Provider Integration Interface callbacks invoked by UCL to drive the SAP S/4HANA Cloud integration wave flow.

APIs for customer payment integration and status tracking. This includes endpoints for receiving payment instructions from ERPs and sending payment status updates back to ERPs.

This section introduces the vocabulary used throughout the rest of this documentation — both the Tereina-specific concepts you'll only see on this platform and the industry-standard ISO 20022 message types the service speaks with ERPs. Skim it once; each endpoint below assumes you're comfortable with these terms.

Payload Batch

A payload batch is the unit of transfer between an ERP and the Integration Service. Each batch groups a related set of records (e.g., payment requests, payment statuses, bank statements) and tracks their lifecycle from upload through processing.

Data Block

A data block is a chunk of a payload batch used for transferring large files. When a batch payload exceeds the maximum single-upload size, it is split into multiple data blocks that are uploaded individually and reassembled server-side. The number of data blocks is calculated automatically based on the total payload size and the configured maximum data block size.

Direction (Inbound / Outbound)

Every payload batch has a direction. Inbound batches flow from the ERP into Tereina (e.g., PAIN 001 payment instructions). Outbound batches flow from Tereina to the ERP (e.g., PAIN 002 status reports, CAMT 053 statements) and are pulled by the client on their own cadence.

Payload Object Type

The payload object type identifies what kind of records a batch contains — for example, PAYMENT_REQUEST for inbound payment instructions, or PAYMENT_STATUS and BANK_STATEMENT for outbound files. It is used to filter and route batches at nearly every endpoint below.

PAIN 001 (Customer Credit Transfer Initiation)

PAIN 001 (pain.001.001.09) is an ISO 20022 XML message used by a debtor (payer) to instruct their bank to initiate one or more credit transfers to creditors (payees). In the Integration Service, inbound PAIN 001 files are parsed into PaymentRequest objects — each CdtTrfTxInf element in the XML becomes one payment request. The XML is validated, transformed to JSON, and dispatched to the Payment Request Service for processing.

PAIN 002 (Payment Status Report)

PAIN 002 (pain.002.001.10) is an ISO 20022 XML message used to report the status of previously submitted payment instructions back to the initiating party. In the Integration Service, PAIN 002 files are generated as outbound messages that inform ERP systems whether each original payment request was accepted, rejected, or is pending. Each transaction status references the original EndToEndId and optionally the InstrId from the corresponding PAIN 001 submission.

CAMT 053 (Bank-to-Customer Statement)

CAMT 053 (camt.053.001.08) is an ISO 20022 XML message that provides a detailed end-of-day bank statement. It contains balance information and individual transaction entries for a given account and period. In the Integration Service, CAMT 053 files are generated as outbound messages to deliver bank statement data back to ERP systems.

The following endpoints work together to enable ERP systems to pull outbound batches (e.g., PAIN 002 payment status reports, CAMT 053 bank statements):

1. GET /batch/outbound/pending — Poll for ready batches

Returns all outbound batches in PENDING or PARTIAL_PENDING status that are waiting for client pickup. Optionally filter by payload object type (e.g., PAYMENT_STATUS, BANK_STATEMENT). Use this endpoint to discover which batches are available for transfer.

2. GET /batch/{batchId}/transfer — Download a batch

Retrieves the complete batch payload with all pending items and their transformed data. Only returns batches that are in PENDING status and ready for transfer. The response includes the batch metadata and all individual items with their payloads.

3. POST /batch/{batchId}/confirm-transfer-receipt — Acknowledge receipt

Confirms that the client has successfully received and processed all items in the batch. This marks all batch items as COMPLETE and transitions the batch status to COMPLETE_SUCCESS. The batch is then removed from the pending queue. This step is required — without confirmation, the batch remains in the pending queue and will continue to appear in polling results.