Skip to main content

Batch Processing API

Copy page

Copy page as Markdown for LLMs

Anthropic

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   Alpha Max: 20 Required

Service command for batch file upload.
Special characters: _
Value: UPLOAD_BATCH_FILE
Example. UPLOAD_BATCH_FILE
access_code   Alphanumeric Max: 20 Required

Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings.
Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   Alphanumeric Max: 20 Required

Unique merchant identifier assigned by Amazon Payment Services during account setup.
Example. CycHZxVj
batch_reference   Alphanumeric Max: 20 Required

Unique batch reference for tracking purposes. Must be unique per merchant.
Example. BATCH-2024-001
Special characters: - _ . /
language   Alpha Max: 2 Required

Response language for messages and descriptions. Supported values: en (English) or ar (Arabic).
Example. en
file   Alphanumeric Max: 50MB Required

CSV file containing batch transaction data. Must follow the specified format for your transaction type.
Example. transactions.csv
Special characters: . - ! @ # $ % ^ & ( ) _ + , Space
Supported formats: .csv
signature   Alphanumeric 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   Alpha Max: 20

Service command from the request.
Value: UPLOAD_BATCH_FILE
Example. UPLOAD_BATCH_FILE
access_code   Alphanumeric Max: 20

Merchant access code used in the request.
Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   Alphanumeric Max: 20

Merchant identifier used in the request.
Example. CycHZxVj
batch_reference   Alphanumeric Max: 20

Batch reference from the request.
Example. BATCH-2024-001
language   Alpha Max: 2

Language used for the response.
Example. en
batch_id   Numeric Max: 20

Unique batch identifier generated by Amazon Payment Services for tracking.
Example. 150754364000030895
signature   Alphanumeric Max: 200

Response signature for verification.
Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
response_message   Alphanumeric Max: 150

Human-readable response description in requested language.
Example. Success
response_code   Numeric Max: 5

Numeric response code indicating upload result.
Example. 50000
status   Numeric Max: 2

Two-digit status code indicating upload state.
Example. 50
Upload Batch Request
<!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   Alpha Max: 20 Required

Service command for batch validation request.
Special characters: _
Value: GET_BATCH_RESULTS
Example. GET_BATCH_RESULTS
access_code   Alphanumeric Max: 20 Required

Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings.
Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   Alphanumeric Max: 20 Required

Unique merchant identifier assigned by Amazon Payment Services during account setup.
Example. CycHZxVj
batch_reference   Alphanumeric Max: 20 Required

Batch reference used in the upload request. Must match the original upload reference.
Example. BATCH-2024-001
Special characters: - _ . /
language   Alpha Max: 2 Required

Response language for messages and descriptions. Supported values: en (English) or ar (Arabic).
Example. en
signature   Alphanumeric Max: 200 Required

SHA-256 hash signature for request authentication and integrity validation.
Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
batch_id   Numeric 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   Alpha Max: 20

Service command from the request.
Value: GET_BATCH_RESULTS
Example. GET_BATCH_RESULTS
access_code   Alphanumeric Max: 20

Merchant access code used in the request.
Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   Alphanumeric Max: 20

Merchant identifier used in the request.
Example. CycHZxVj
batch_reference   Alphanumeric Max: 20

Batch reference from the request.
Example. BATCH-2024-001
language   Alpha Max: 2

Language used for the response.
Example. en
batch_id   Numeric Max: 20

Unique batch identifier for tracking.
Example. 150754364000030895
transactions_count   Numeric Max: 10

Total number of transactions found in the batch file.
Example. 9
signature   Alphanumeric Max: 200

Response signature for verification.
Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
response_message   Alphanumeric Max: 150

Human-readable response description in requested language.
Example. Success
response_code   Numeric Max: 5

Numeric response code indicating validation result.
Example. 70000
status   Numeric Max: 2

Two-digit status code indicating validation state.
Example. 70
Get Batch Results Request
{
  "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   Alpha Max: 20 Required

Service command for batch processing request.
Special characters: _
Value: PROCESS_BATCH
Example. PROCESS_BATCH
access_code   Alphanumeric Max: 20 Required

Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings.
Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   Alphanumeric Max: 20 Required

Unique merchant identifier assigned by Amazon Payment Services during account setup.
Example. CycHZxVj
batch_reference   Alphanumeric Max: 20 Required

Batch reference used in upload and validation. Must match previous requests.
Example. BATCH-2024-001
Special characters: - _ . /
language   Alpha Max: 2 Required

Response language for messages and descriptions. Supported values: en (English) or ar (Arabic).
Example. en
signature   Alphanumeric Max: 200 Required

SHA-256 hash signature for request authentication and integrity validation.
Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
batch_id   Numeric 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   Alpha Max: 20

Service command from the request.
Value: PROCESS_BATCH
Example. PROCESS_BATCH
access_code   Alphanumeric Max: 20

Merchant access code used in the request.
Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   Alphanumeric Max: 20

Merchant identifier used in the request.
Example. CycHZxVj
batch_reference   Alphanumeric Max: 20

Batch reference from the request.
Example. BATCH-2024-001
language   Alpha Max: 2

Language used for the response.
Example. en
batch_id   Numeric Max: 20

Unique batch identifier for tracking.
Example. 150754364000030895
signature   Alphanumeric Max: 200

Response signature for verification.
Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
response_message   Alphanumeric Max: 150

Human-readable response description in requested language.
Example. Process batch request received
response_code   Numeric Max: 5

Numeric response code indicating processing result.
Example. 72147
status   Numeric Max: 2

Two-digit status code indicating processing state.
Example. 72
Process Batch Request
{
  "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.

Was this page helpful?

Thanks for your feedback!