API docs by Redocly

Tereina Integration Service API (1.0.0)

Download OpenAPI specification:

Tereina Development Team: support@tereina.com License: Proprietary

What is this doc for?

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.

Endpoints

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.

Upload data block

Upload a single data block using streaming. Batch will auto-process when final data block is received.

path Parameters
batchId
required
string
dataBlockNumber
required
integer <int32>
Request Body schema:

Stream of data containing batch payload. Supported object types: COMPANY, COMPANY_CODE, PAYMENT_REQUEST, INVOICE

One of
required
Array of objects (CompanyRelationRequestPayload) non-empty

List of company relationships with company codes

Array of objects (ContactRequestPayload)

List of contacts for the company

Array of objects (AddressRequestPayload)

List of addresses for the company

Array of objects (CorporateIdentifierRequestPayload)

List of corporate identifiers for the company

Array of objects (BankAccountRequestPayload)

List of bank accounts for the company

name
string
number
string
referenceId
string
registeredCountry
string
registeredState
string

Responses

Request samples

Content type
Example
{
  • "companyRelations": [
    ],
  • "contacts": [
    ],
  • "addresses": [
    ],
  • "corporateIdentifiers": [
    ],
  • "bankAccounts": [
    ],
  • "name": "string",
  • "number": "string",
  • "referenceId": "string",
  • "registeredCountry": "string",
  • "registeredState": "string"
}

Confirm transfer receipt

Confirms that the client has successfully received and processed all items in an outbound batch. This marks all batch items as COMPLETE and the batch status as COMPLETE_SUCCESS. The batch is then removed from the pending queue.

path Parameters
batchId
required
string

Responses

Request samples 

curl -X POST "https://api.tereina.com/api/integration/v1/batch/{batchId}/confirm-transfer-receipt" \
  -H "Authorization: Bearer $TOKEN"

Initiate batch job with data block transfer

Creates a new batch job and returns data block transfer parameters. Batch will auto-process when all data blocks are uploaded.

Request Body schema: application/json
required
clientRefId
required
string

Client reference ID

referenceId
required
string

Reference ID for the batch

payloadObjectType
required
any (PayloadObjectType)
Enum: "COMPANY_CODE" "COMPANY" "INVOICE" "PURCHASE_ORDER" "PAYMENT_REQUEST" "PAYMENT_STATUS" "BANK_STATEMENT"

Type of payload object being uploaded

totalPayloadSize
required
integer <int64>

Total size of the payload in bytes

totalLineItemCount
integer <int32>

Total number of the line item objects in this batch

inputDataFormat
required
any (DataFormat)
Enum: "JSON" "CSV" "XML"

Input data format for the batch payload

Responses

Request samples

Content type
application/json
{
  • "clientRefId": "client_123",
  • "referenceId": "batch_sap_20241006",
  • "payloadObjectType": "COMPANY_CODE",
  • "totalPayloadSize": 104857600,
  • "totalLineItemCount": 200,
  • "inputDataFormat": "JSON"
}

Create and process a batch of records (single data block)

Accepts a complete batch of data in various formats (JSON, CSV, XML, ISO) using streaming. The format is determined by client configuration and validated against expected schema. For large payloads, use the data block transfer endpoints instead.

query Parameters
clientRefId
required
string
referenceId
required
string
payloadObjectType
required
string
totalLineItemCount
required
integer <int32>
totalPayloadSize
required
integer <int64>
inputDataFormat
required
string
Request Body schema:

Stream of data containing batch payload. Supported object types: COMPANY, COMPANY_CODE, PAYMENT_REQUEST, INVOICE

One of
required
Array of objects (CompanyRelationRequestPayload) non-empty

List of company relationships with company codes

Array of objects (ContactRequestPayload)

List of contacts for the company

Array of objects (AddressRequestPayload)

List of addresses for the company

Array of objects (CorporateIdentifierRequestPayload)

List of corporate identifiers for the company

Array of objects (BankAccountRequestPayload)

List of bank accounts for the company

name
string
number
string
referenceId
string
registeredCountry
string
registeredState
string

Responses

Request samples

Content type
Example
{
  • "companyRelations": [
    ],
  • "contacts": [
    ],
  • "addresses": [
    ],
  • "corporateIdentifiers": [
    ],
  • "bankAccounts": [
    ],
  • "name": "string",
  • "number": "string",
  • "referenceId": "string",
  • "registeredCountry": "string",
  • "registeredState": "string"
}

Get batch for transfer

Retrieves the complete batch with all pending items and their transformed payloads for client pickup. Only returns batches in PENDING status that are ready for transfer.

path Parameters
batchId
required
string

Responses

Request samples 

curl -X GET "https://api.tereina.com/api/integration/v1/batch/{batchId}/transfer" \
  -H "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
{
  • "id": "124ABCDEF",
  • "createdDate": "2023-12-01T10:15:30+01:00[Europe/Paris]",
  • "lastUpdatedDate": "2023-12-02T10:15:30+01:00[Europe/Paris]",
  • "lastUpdatedBy": "1234ABCXYZ",
  • "version": 0,
  • "referenceId": "payment_request_123",
  • "groupReferenceId": "payment_group_123",
  • "status": "OPEN",
  • "reasonCode": "REJ_004",
  • "additionalInfo": "Error due to missing amount",
  • "payerReference": "INSTR-001",
  • "paymentInfoId": "PMTINF-001"
}

Get batch job status by batch ID

Returns current status of the batch job including data block transfer progress, missing data blocks, and processing state.

path Parameters
batchId
required
string

Responses

Request samples 

curl -X GET "https://api.tereina.com/api/integration/v1/batch/{batchId}/status" \
  -H "Authorization: Bearer $TOKEN"

Get batch job status by reference ID

Returns current status of the batch job by external reference ID, including data block transfer progress, missing data blocks, and processing state.

path Parameters
referenceId
required
string

Responses

Request samples 

curl -X GET "https://api.tereina.com/api/integration/v1/batch/reference/{referenceId}/status" \
  -H "Authorization: Bearer $TOKEN"

Get pending outbound batches

Returns all outbound batches in PENDING or PARTIAL_PENDING status that are waiting for the client to pick up. Optionally filter by payload object type (e.g., COMPANY, INVOICE).

query Parameters
payloadObjectType
any (PayloadObjectType)
Enum: "COMPANY_CODE" "COMPANY" "INVOICE" "PURCHASE_ORDER" "PAYMENT_REQUEST" "PAYMENT_STATUS" "BANK_STATEMENT"

Payload objects supported by the integration service

Responses

Request samples 

curl -X GET "https://api.tereina.com/api/integration/v1/batch/outbound/pending" \
  -H "Authorization: Bearer $TOKEN"

Important Concepts

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.

Tereina's Terminology

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.

Common Terminology

PAIN 001 (Customer Credit Transfer Initiation)

PAIN 001 (pain.001.001.03) 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.03) 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.02) 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.

Outbound Batch Transfer Flow

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.