Skip to main content

API - Transaction batch

The Transaction Batch Endpoint allows customers to efficiently upload transaction data in large batches for ingestion. Each batch consists of multiple transactions formatted as JSONL (JSON Lines), with each line representing a single valid transaction JSON. Main use cases include migrating millions of historical transactions during on-boarding and allowing customers to send millions of transactions per day.

Prerequisites​

This feature is not enabled for tenant by default, tenant must request feature enablement.

Batch file specification details​

  • Batches must be uploaded as JSONL files
  • Each line in the JSONL file represents one transaction. For detailed transaction schema follow API - Transaction documentation.
  • Each entity in transaction must be either clm-known entity, defined using by_external_id (which is clm entity id), or unknown entity, defined using external_entity_type and corresponding entity details. Entity needs to fit one, and only one type (defining both by_external_id and external_entity_type is not allowed).
  • Maximum allowed file size per batch: 2GB. Exceeding this limit will result in a batch rejection

Example​

{"request_uuid": "80f9f281-5e4e-49ed-b866-a6fc84356861", "payment_external_id": "c9cc78e6-2d29-4aa2-b870-a8c4ead7e4e8", "transaction_external_id": "4c24d134-ced9-42aa-8781-d1d3ae357117", "payment_source_country": "TJ", "payment_target_country": "CL", "payment_method": "iDeal", "payment_type": "payout", "additional_fields": {"payment_category": "VisaFF"}, "sender": {"by_external_id": "31482684-88e2-4f13-9ad6-a3b12208f633"}, "sending_partner": {"external_entity_type": "unknown", "unknown": {"external_id": "dc1b5656-2d41-4560-a618-a123227c1262", "full_name": "Jane Doe", "risk_assessment": "High"}}, "receiver": {"by_external_id": "a3d6b832-3597-44dc-97ed-47f957ad9de7"}, "modification": {"external_id": "35f9d6a1-8ada-48ad-b2fd-d00729f125ce", "type": "settlement", "amount": 98266, "monitoring_amount": 72125, "original_amount": 94241, "currency": "EUR", "monitoring_currency": "EUR", "original_currency": "EUR", "created_at": "2025-03-25T17:51:20"}}
{"request_uuid": "0f0dcbd9-66fa-4990-bdb3-b50c0bcecae6", "payment_external_id": "6405ae38-90b2-4c09-ba87-564eef312456", "transaction_external_id": "acc40fa6-b169-4b5e-af55-99cbf8007ec5", "payment_source_country": "MV", "payment_target_country": "VN", "payment_method": "iDeal", "payment_type": "payout", "additional_fields": {"payment_category": "VisaFF"}, "sender": {"external_entity_type": "unknown", "unknown": {"external_id": "b34551ee-d8fb-42ab-8be9-d7c3db732ca6", "risk_assessment": "High"}}, "sending_partner": {"by_external_id": "d000afac-9e70-4248-987e-49a863bbc292"}, "receiver": {"external_entity_type": "unknown", "unknown": {"external_id": "614458e8-1fa6-4a87-999d-5f08a00ee812"}}, "modification": {"external_id": "1744db77-3071-46b1-b6fb-9de9f5645eb3", "type": "settlement", "amount": 54858, "monitoring_amount": 97573, "original_amount": 71704, "currency": "EUR", "monitoring_currency": "EUR", "original_currency": "EUR", "created_at": "2025-03-25T16:39:43"}}

Batch processing workflow​

Request a Pre-signed S3 URL​

Call the provided API endpoint to obtain a pre-signed S3 upload URL and a unique UUID for tracking current status of batch processing. Request content allows specifying additional processing parameters.

Upload batch file​

Use the provided pre-signed URL to upload your batch file directly to S3. In order to do it, use PUT method, use multipart/form-data content type, set If-None-Match header with value "*" and provide the batch file under file key. For more details follow AWS docs. After the file is completely uploaded to S3, asynchronous processing of the transactions in the file will start.

Check status of batch processing​

Call the batch-status endpoint to get current status of the batch processing.

Example:

{
  "batch_id": "409cc795-d34f-48d4-b757-57220ae05974",
  "status": "PROCESSED",
  "failed_transaction_modification_ids": [...],
  "error_message": "",
  "progress_percentage": 100
}

Batch status possible values​

  • VALIDATION_STARTED
  • VALIDATION_FAILED
  • INITIALIZED - batch initialization complete, batch queued for processing
  • IN_PROGRESS - batch processing started
  • PROCESSED - batch processing completed successfully
  • ERROR

Batch validation​

Initial step of batch processing includes validation of uploaded transactions. When validation is completed, results can be checked by calling validation-results endpoint. If batch is invalid, per-signed URL will be generated in order to download validation report.

Entity validation​

Each entity in the transaction is validated to ensure it is either a known CLM entity or an unknown entity with the required details. Mixing both methods might yield conflicting/contradicting error_messages.

Loading ...