Batch Processing API
Copy page
Copy page as Markdown for LLMs
Open in ChatGPT
Ask questions about this page
Open in Claude
Ask questions about this page
The Batch Processing service enables merchants to automate bulk payment operations by uploading CSV files containing transaction instructions. This service is ideal for scenarios where individual API calls are impractical, such as recurring payments, bulk maintenance operations, or mass invoice generation.
Batch Processing Workflow
The batch processing consists of three sequential steps that must be completed in order:
1. Upload Batch File
Upload your CSV file to Amazon Payment Services for initial validation and storage.
2. Get Batch Results
Validate file format, check merchant reference uniqueness, and retrieve validation status.
3. Process Batch File
Initiate actual transaction processing after successful validation.
1. Upload Batch File
Upload your batch file to Amazon Payment Services for validation and processing. The system will validate the file format and return a batch ID for tracking.
API Endpoints
https://sbpaymentservices.payfort.com/FortAPI/upload/
Request Format
- Method:
POST
- Content-Type:
multipart/form-data
- Submission: HTML Form with file upload
Request Parameters
Parameter |
---|
service_command String Max: 20 Required Service command for batch file upload. Value: UPLOAD_BATCH_FILE Example. UPLOAD_BATCH_FILE |
access_code String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier String Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj |
batch_reference String Max: 20 Required Unique batch reference for tracking purposes. Must be unique per merchant. Example. BATCH-2024-001 Special characters: - _ . / |
language String Max: 2 Required Response language for messages and descriptions. Supported values: en (English) or ar (Arabic). Example. en |
file File Max: 50MB Required CSV file containing batch transaction data. Must follow the specified format for your transaction type. Example. transactions.csv Supported formats: .csv |
signature String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
- Format: Only CSV files are accepted
- Size Limit: Maximum file size is 50MB
- Encoding: UTF-8 encoding is recommended
- Headers: First row should contain column headers matching parameter names
Check signature calculation section to learn how to calculate the signature.
Response Parameters
Parameter |
---|
service_command String Max: 20 Service command from the request. Value: UPLOAD_BATCH_FILE Example. UPLOAD_BATCH_FILE |
access_code String Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier String Max: 20 Merchant identifier used in the request. Example. CycHZxVj |
batch_reference String Max: 20 Batch reference from the request. Example. BATCH-2024-001 |
language String Max: 2 Language used for the response. Example. en |
batch_id String Max: 20 Unique batch identifier generated by Amazon Payment Services for tracking. Example. 150754364000030895 |
signature String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
response_message String Max: 150 Human-readable response description in requested language. Example. Success |
response_code String Max: 5 Numeric response code indicating upload result. Example. 50000 |
status String Max: 2 Two-digit status code indicating upload state. Example. 50 |
<!DOCTYPE html>
<html>
<head>
<title>Batch File Upload</title>
</head>
<body>
<h2>Upload Batch File</h2>
<!-- Form must include proper enctype for file upload -->
<form action="https://sbpaymentservices.payfort.com/FortAPI/upload/"
method="POST"
enctype="multipart/form-data">
<!-- Hidden form fields -->
<input type="hidden" name="service_command" value="UPLOAD_BATCH_FILE">
<input type="hidden" name="merchant_identifier" value="bxgOIxIz">
<input type="hidden" name="access_code" value="1DFxVvhXWV6wumenTTg9">
<input type="hidden" name="batch_reference" value="BATCH-2024-001">
<input type="hidden" name="language" value="en">
<input type="hidden" name="signature" value="9bea9f369473b8355b2c32884f4b2e8425b145b10d647c2fcaeeee79d7f86fdc">
<!-- File upload field -->
<div class="form-group">
<label for="file">Select Batch File (CSV):</label>
<input type="file"
id="file"
name="file"
accept=".csv"
required>
</div>
<button type="submit" class="upload-button">
Upload Batch File
</button>
</form>
</body>
</html>
{
"response_code": "50000",
"service_command": "UPLOAD_BATCH_FILE",
"response_message": "Success",
"batch_id": "151791753100095172",
"signature": "a8888a646b30f756a4f7ce892574e9da7342d7833c3b83cf6f2393978430d74f",
"merchant_identifier": "bxgOIxIz",
"access_code": "1DFxVvhXWV6wumenTTg9",
"batch_reference": "BATCH-2024-001",
"language": "en",
"status": "50"
}
2. Get Batch Results
Validate the format of your uploaded batch file and check transaction uniqueness. This step is required before processing and provides detailed validation results.
API Endpoints
https://sbpaymentservices.payfort.com/FortAPI/batchApi/
Request Format
- Method:
POST
- Content-Type:
application/json
- Submission: Server-to-server HTTPS POST
Request Parameters
Parameter |
---|
service_command String Max: 20 Required Service command for batch validation request. Value: GET_BATCH_RESULTS Example. GET_BATCH_RESULTS |
access_code String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier String Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj |
batch_reference String Max: 20 Required Batch reference used in the upload request. Must match the original upload reference. Example. BATCH-2024-001 Special characters: - _ . / |
language String Max: 2 Required Response language for messages and descriptions. Supported values: en (English) or ar (Arabic). Example. en |
signature String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
batch_id String Max: 20 Optional Batch ID returned from the upload request. Helps with faster lookup. Example. 150754364000030895 |
Your batch file cannot be processed if the validation status indicates "batch file still under validation". Wait for validation to complete before proceeding to processing.
Response Parameters
Parameter |
---|
service_command String Max: 20 Service command from the request. Value: GET_BATCH_RESULTS Example. GET_BATCH_RESULTS |
access_code String Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier String Max: 20 Merchant identifier used in the request. Example. CycHZxVj |
batch_reference String Max: 20 Batch reference from the request. Example. BATCH-2024-001 |
language String Max: 2 Language used for the response. Example. en |
batch_id String Max: 20 Unique batch identifier for tracking. Example. 150754364000030895 |
transactions_count Integer Max: 10 Total number of transactions found in the batch file. Example. 9 |
signature String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
response_message String Max: 150 Human-readable response description in requested language. Example. Success |
response_code String Max: 5 Numeric response code indicating validation result. Example. 70000 |
status String Max: 2 Two-digit status code indicating validation state. Example. 70 |
{
"service_command": "GET_BATCH_RESULTS",
"access_code": "1DFxVvhXWV6wumenTTg9",
"merchant_identifier": "bxgOIxIz",
"batch_reference": "BATCH-2024-001",
"language": "en",
"batch_id": "151791753100095172",
"signature": "17e62207b17ea9f550b41811039cb4a05f86087c5cdec40aad1dcc250909b054"
}
{
"transactions_count": "9",
"response_code": "70000",
"service_command": "GET_BATCH_RESULTS",
"response_message": "Success",
"batch_id": "151791753100095172",
"signature": "036823f98cfca2a1b7efcf7552dd87fc44df666fc345d553ce733efb2003f5cd",
"merchant_identifier": "bxgOIxIz",
"access_code": "1DFxVvhXWV6wumenTTg9",
"batch_reference": "BATCH-2024-001",
"language": "en",
"status": "70"
}
3. Process Batch File
Initiate the processing of transactions after successful validation. The batch file must pass validation before processing can begin.
API Endpoints
https://sbbatch.payfort.com/integration-batch/batchApi/
Request Format
- Method:
POST
- Content-Type:
application/json
- Submission: Server-to-server HTTPS POST
Request Parameters
Parameter |
---|
service_command String Max: 20 Required Service command for batch processing request. Value: PROCESS_BATCH Example. PROCESS_BATCH |
access_code String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier String Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj |
batch_reference String Max: 20 Required Batch reference used in upload and validation. Must match previous requests. Example. BATCH-2024-001 Special characters: - _ . / |
language String Max: 2 Required Response language for messages and descriptions. Supported values: en (English) or ar (Arabic). Example. en |
signature String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
batch_id String Max: 20 Optional Batch ID returned from upload and validation requests. Helps with faster processing. Example. 150754364000030895 |
- Batch file must be successfully uploaded and validated before processing
- All transactions in the batch must have unique merchant references
- Only validated batches with status "70" can be processed
Response Parameters
Parameter |
---|
service_command String Max: 20 Service command from the request. Value: PROCESS_BATCH Example. PROCESS_BATCH |
access_code String Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier String Max: 20 Merchant identifier used in the request. Example. CycHZxVj |
batch_reference String Max: 20 Batch reference from the request. Example. BATCH-2024-001 |
language String Max: 2 Language used for the response. Example. en |
batch_id String Max: 20 Unique batch identifier for tracking. Example. 150754364000030895 |
signature String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
response_message String Max: 150 Human-readable response description in requested language. Example. Process batch request received |
response_code String Max: 5 Numeric response code indicating processing result. Example. 72147 |
status String Max: 2 Two-digit status code indicating processing state. Example. 72 |
{
"service_command": "PROCESS_BATCH",
"access_code": "1DFxVvhXWV6wumenTTg9",
"merchant_identifier": "bxgOIxIz",
"batch_reference": "BATCH-2024-001",
"language": "en",
"batch_id": "151791753100095172",
"signature": "17e62207b17ea9f550b41811039cb4a05f86087c5cdec40aad1dcc250909b054"
}
{
"response_code": "72147",
"service_command": "PROCESS_BATCH",
"response_message": "Process batch request received",
"signature": "ee1d30d4fcc6f61100cca0a5ee0639e3c22620ae88d6dc7ec2b6aad2a2489184",
"merchant_identifier": "bxgOIxIz",
"access_code": "1DFxVvhXWV6wumenTTg9",
"batch_reference": "BATCH-2024-001",
"batch_id": "151791753100095172",
"language": "en",
"status": "72"
}
Processing Results
After processing the batch file successfully, you can send "Get Batch Results – Request" again to see the final status for each transaction inside the file.
Line_Number,response_code,response_message,status,eci,fort_id,merchant_reference,amount,card_number,expiry_date,currency
"5","14000","Success","14","RECURRING","151792390600095202","newww33","10003","400555******0001","2105","USD"
"4","14000","Success","14","RECURRING","151792390600095203","newww32","10002","400555******0001","2105","USD"
"10","14000","Success","14","RECURRING","151792390600095208","newww38","10008","400555******0001","2105","USD"
"8","14000","Success","14","RECURRING","151792390600095204","newww36","10006","400555******0001","2105","USD"
"9","14000","Success","14","RECURRING","151792390600095205","newww37","10007","400555******0001","2105","USD"
"2","14000","Success","14","RECURRING","151792390600095206","newww30","10000","400555******0001","2105","USD"
"6","14000","Success","14","RECURRING","151792390600095201","newww34","10004","400555******0001","2105","USD"
"7","14000","Success","14","RECURRING","151792390600095207","newww35","10005","400555******0001","2105","USD"
"3","14000","Success","14","RECURRING","151792390600095200","newww31","10001","400555******0001","2105","USD"
Testing The Integration
Sandbox Testing
Use the sandbox environment for development and testing:
- Upload URL:
https://sbpaymentservices.payfort.com/FortAPI/upload/
- Batch API URL:
https://sbpaymentservices.payfort.com/FortAPI/batchApi/
- Processing URL:
https://sbbatch.payfort.com/integration-batch/batchApi/
- Test Cards: Use our comprehensive Testing Cards
Go-Live Process
Follow our Go-Live checklist for complete production readiness guidelines.
If you prefer using your account dashboard, you can manage batch processing by navigating to the "Batch Processing" section in your back office. For more information, see our batch processing guide.