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. Tenants 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. The usage of the two types of entity specificaiton methods are considered to be mutually exclusive and each Entity needs to fit one, and only one type. Meaning that 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

Transaction 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 Generate Batch Upload Url endpoint to obtain a pre-signed S3 upload URL and a unique UUID for tracking current status of the 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 fully uploaded to S3, it will be scanned. If the file is clean, processing of the transactions will begin. The timestamp recorded upon completion of uploading the batch file be considered the time at which the system received the batch.

Check status of batch processing​

Call the Retrieve 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 - batch validation starts after the batch file is scanned and accepted
  • 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. If any duplicate modification IDs are detected, the entire batch is rejected upon the first occurrence, regardless of the reject_on_invalid flag. In such cases, line-by-line validation does not commence, as the batch is rejected prior to that stage. When validation is completed, results can be checked by calling Get Batch Validation Results endpoint. If batch is invalid, a new pre-signed URL will be generated in order to download the validation report.

Entity validation​

Each entity in the transaction is validated to ensure it is either:

  • A known CLM entity which is fully onboarded, or
  • An unknown entity with the required details.

Mixing both methods might yield conflicting/contradicting error_messages.

Loading ...