Skip to main content

Batch Upload API — v2

Beta

This API is currently in BETA and is provided on an "as is" and "as available" basis. During this phase, functionality may change without prior notice, and users may encounter bugs, errors, or incomplete features. We appreciate your feedback and understanding as we continue to improve the API.

Upgrade notice

This documentation is for the newly released Batch Upload API v2. Batch Upload API v2 introduces structured JSON result files, processing modes, and improved status responses.

If you're currently using the legacy Batch Upload API v1 endpoint please review the Deprecation Notice!

Using our batch-upload v2 API, you may upload a file in CSV format containing recurring transactions for processing.

As a result a JSON file will be generated containing the transactions after they have been processed.

Endpoints

  • For production: POST https://gateway.ixopay.com/api/v3/batchUpload/v2/{apiKey}/batches
  • For sandbox: POST https://sandbox.ixopay.com/api/v3/batchUpload/v2/{apiKey}/batches

1. Upload a batch file

POST /api/v3/batchUpload/v2/{apiKey}/batches

Request fields

FieldTypeDescription
apiKeyrequiredstringAPI Key of the Connector
batchFilerequiredstringThe data of your batch file. Maximum upload size: 1 MB
callbackUrloptionalstring?The url the link to the resulting JSON file will be sent to once the processing of all transactions in the given batch file is finished, for example: https://api.example.org/callback
processingModeoptionalstring?strict (default) or lenient — see Processing Modes
curl "https://gateway.ixopay.com/api/v3/batchUpload/v2/$API_KEY/batches" \
--request POST \
--user "$USERNAME:$PASSWORD" \
--form "batchFile=@$FILENAME.csv" \
--form "callbackUrl=$CALLBACK_URL" \
--form "processingMode=lenient"

Response — HTTP 201

FieldTypeDescription
batchIdrequiredstringID for tracking this batch. Use it in all subsequent requests.
statusrequiredstringInitial status, always pending
{
"batchId": "a1b2c3d4-...",
"status": "pending"
}

Error responses

HTTPBodyReason
400{"error": "Batch file is missing"}No file attached
422{"error": "File is not a valid CSV format"}File could not be parsed as CSV
422{"error": "Invalid callback URL"}callbackUrl is not a valid, publicly reachable URL
422{"error": "Invalid processing mode"}processingMode value is not strict or lenient
422Validation errorFile exceeds 1 MB or has wrong MIME type

2. Get batch status

GET /api/v3/batchUpload/v2/{apiKey}/batches/{batchId}

Path parameters

FieldTypeDescription
apiKeyrequiredstringAPI Key of the Connector
batchIdrequiredstringThe batchId returned by the upload request
curl "https://gateway.ixopay.com/api/v3/batchUpload/v2/$API_KEY/batches/$BATCH_ID" \
--request GET \
--user "$USERNAME:$PASSWORD"

Response

The shape of the response varies depending on the current status.

FieldTypeDescription
batchIdrequiredstringThe batch identifier
statusrequiredstringAlways pending
processingModerequiredstringThe mode used for this batch: strict or lenient
{
"batchId": "a1b2c3d4-...",
"status": "pending",
"processingMode": "strict"
}

3. Download the result file

GET /api/v3/batchUpload/v2/{apiKey}/batches/{batchId}/file

Returns the result JSON file as a streamed download. The file is only available once the batch has a status of completed or processed_with_errors.

curl "https://gateway.ixopay.com/api/v3/batchUpload/v2/$API_KEY/batches/$BATCH_ID/file" \
--request GET \
--user "$USERNAME:$PASSWORD" \
--output result.json

Error responses

HTTPBodyReason
202{"error": "Batch is not completed yet"}Processing has not finished
404{"error": "Document not found"}batchId does not exist

4. List batches

GET /api/v3/batchUpload/v2/{apiKey}/batches

Returns a paginated list of all batches submitted for the given connector.

Query parameters

FieldTypeDefaultDescription
pageoptionalinteger?1Page number (minimum: 1)
perPageoptionalinteger?25Results per page (min: 1, max: 100)
curl "https://gateway.ixopay.com/api/v3/batchUpload/v2/$API_KEY/batches?page=1&perPage=25" \
--request GET \
--user "$USERNAME:$PASSWORD"

Response

{
"data": [
{
"batchId": "a1b2c3d4-...",
"status": "completed",
"createdAt": "2026-04-22T10:00:00+00:00"
},
{
"batchId": "e5f6g7h8-...",
"status": "pending",
"createdAt": "2026-04-22T10:05:00+00:00"
}
],
"total": 42,
"perPage": 25,
"currentPage": 1
}

Processing modes

The processingMode parameter controls what happens when a row in the batch file fails validation or cannot be processed.

strict (default)

The first row that fails validation at parse time causes the entire batch to be marked as failed. No transactions are executed.

Use strict mode when partial execution is not acceptable — for any workflow where you need a guarantee that either all rows are executed or none are.

lenient

Rows that fail validation are skipped and recorded in failedRows of the result file. Valid rows continue to be processed. The final batch status will be processed_with_errors if any rows failed, or completed if all rows succeeded.

Use lenient mode for bulk imports where processing as many valid rows as possible is preferable to an all-or-nothing outcome.

Batch statuses

StatusDescription
pendingThe batch has been queued and processing has not started yet
processingThe batch is currently being parsed or transactions are being executed
completedAll rows were processed successfully
failedThe batch failed — only possible in strict mode. Triggered by either a validation error at parse time or a transaction execution error during processing.
processed_with_errorsSome rows failed — only possible in lenient mode

Transaction batch file structure

File size limit

The maximum upload size per request is 1 MB. If your batch exceeds this limit, you must split it into multiple CSV files and submit each one as a separate upload request. Each upload will receive its own batchId and can be tracked and downloaded independently.

The first line of the batch file needs to be the header line. This line has to contain all keys for following transactions.

The mandatory and possible keys for the transactions can be found in the transaction types documentation.

Any objects (e.g. the Customer object as stated in the transaction data documentation) need to be given as flattened values.

Example for flattened objects

  • Flattened object:
"customer": {
"identification": "616c6578-2e73-6d69-7468-406578616d70",
"firstName": "Alex",
"lastName": "Smith"
}
  • Flattened array of objects:
"errors": [
{
"message": "Some error",
"code": "1234"
},
{
"message": "Another error",
"code": "5678"
}
]

Example batch file

transactionMethod,referenceUuid,merchantTransactionId,extraData.someKey,extraData.otherKey,amount,currency,customer.identification,customer.lastName,threeDSecureData.3dsecure
"debit","4d40738b1194869734f7","your-unique-identifier","someValue","otherValue","9.99","EUR","616c6578-2e73-6d69-7468-406578616d70","Smith",""
"debit","1ed442bdf4f9eb855b1f","your-unique-identifier-2","alsoSomeValue","","4.99","USD","4a6f7264-616e-2e4a-6f6e-657340657861","",""
"preauthorize","44118273d04397020bb5","your-unique-identifier-3","","","99.99","EUR","616c6578-2e73-6d69-7468-406578616d70","Smith","MANDATORY"

Transaction types

The following transaction types can be given with the csv file:

Debit

NameTypeDescription
transactionMethodrequiredstringThe method of the transaction, in this case debit
referenceUuidrequiredstringThe id of the initial transaction this one is referring to
merchantTransactionIdrequiredstringyour unique transaction ID
amountrequiredstringdecimals separated by ., max. 3 decimals
currencyrequiredstring3 letter currency code
additionalId1optionalstring?any additional ID if required by adapter
additionalId2optionalstring?any additional ID if required by adapter
extraDataoptionalobject?object containing key-value pairs (string-to-string)
merchantMetaDataoptionalstring?max. 255 characters
callbackUrloptionalstring?endpoint to receive status notifications
transactionTokenoptionalstring?token generated via payment.js
descriptionoptionalstring?max. 255 characters
itemsoptionalobject?object containing Items
withRegisteroptionalboolean?store customer's payment instrument for recurring transactions
transactionIndicatoroptionalstring?RECURRING
customeroptionalobject?see Customer
customer.paymentDataoptionalobject?one of PaymentData
scheduleoptionalobject?see Schedule
customerProfileDataoptionalobject?see CustomerProfileData
threeDSecureDataoptionalobject?see ThreeDSecureData
languageoptionalstring?2 characters

Preauthorize

NameTypeDescription
transactionMethodrequiredstringThe method of the transaction, in this case preauthorize
referenceUuidrequiredstringThe id of the initial transaction this one is referring to
merchantTransactionIdrequiredstringyour unique transaction ID
amountrequiredstringdecimals separated by ., max. 3 decimals
currencyrequiredstring3 letter currency code
additionalId1optionalstring?any additional ID if required by adapter
additionalId2optionalstring?any additional ID if required by adapter
extraDataoptionalobject?object containing key-value pairs (string-to-string)
merchantMetaDataoptionalstring?max. 255 characters
callbackUrloptionalstring?endpoint to receive status notifications
transactionTokenoptionalstring?token generated via payment.js
descriptionoptionalstring?max. 255 characters
itemsoptionalobject?object containing Items
withRegisteroptionalboolean?store customer's payment instrument for recurring transactions
transactionIndicatoroptionalstring?RECURRING
customeroptionalobject?see Customer
customer.paymentDataoptionalobject?one of PaymentData
scheduleoptionalobject?see Schedule
customerProfileDataoptionalobject?see CustomerProfileData
threeDSecureDataoptionalobject?see ThreeDSecureData
languageoptionalstring?2 characters

Refund

NameTypeDescription
transactionMethodrequiredstringThe method of the transaction, in this case refund
referenceUuidrequiredstringThe id of the initial transaction this one is referring to
merchantTransactionIdrequiredstringyour unique transaction ID
amountrequiredstringdecimals separated by ., max. 3 decimals
currencyrequiredstring3 letter currency code
additionalId1optionalstring?any additional ID if required by adapter
additionalId2optionalstring?any additional ID if required by adapter
extraDataoptionalobject?object containing key-value pairs (string-to-string)
merchantMetaDataoptionalstring?max. 255 characters
callbackUrloptionalstring?endpoint to receive status notifications
transactionTokenoptionalstring?token generated via payment.js
descriptionoptionalstring?max. 255 characters
itemsoptionalobject?object containing Items

Payout

Either referenceUuid or transactionToken must be provided.

NameTypeDescription
transactionMethodrequiredstringThe method of the transaction, in this case payout
merchantTransactionIdrequiredstringyour unique transaction ID
amountrequiredstringdecimals separated by ., max. 3 decimals
currencyrequiredstring3 letter currency code
referenceUuid
requiredstring
conditional
The id of the initial transaction. Required if transactionToken is not provided.
transactionToken
requiredstring
conditional
token generated via payment.js. Required if referenceUuid is not provided.
additionalId1optionalstring?any additional ID if required by adapter
additionalId2optionalstring?any additional ID if required by adapter
extraDataoptionalobject?object containing key-value pairs (string-to-string)
merchantMetaDataoptionalstring?max. 255 characters
callbackUrloptionalstring?endpoint to receive status notifications
descriptionoptionalstring?max. 255 characters
itemsoptionalobject?object containing Items
customeroptionalobject?see Customer
customer.paymentDataoptionalobject?one of PaymentData
languageoptionalstring?2 characters

Deregister

Deletes a previously registered payment instrument. The instrument must have been created through a register transaction or via a debit / preauthorize with withRegister set to true.

Either referenceUuid or transactionToken must be provided.

  • To deregister a transaction, provide its referenceUuid.
NameTypeDescription
transactionMethodrequiredstringThe method of the transaction, in this case deregister
merchantTransactionIdrequiredstringyour unique transaction ID
referenceUuid
requiredstring
conditional
UUID of the register transaction to deregister. Required if transactionToken is not provided.
transactionToken
requiredstring
conditional
Payment token to deregister from a customer profile. Required if referenceUuid is not provided.
tokenTypeoptionalstring?Which token type to deregister. One of ALL, PAN, NT. Defaults to ALL.
additionalId1optionalstring?any additional ID if required by adapter
additionalId2optionalstring?any additional ID if required by adapter
extraDataoptionalobject?object containing key-value pairs (string-to-string)
pspPassthroughDataoptionalobject?Data passed through directly to the PSP
merchantMetaDataoptionalstring?max. 255 characters

Callback notification

If you provide a callback URL during your batch upload request, a notification will be sent to that URL once processing is complete — regardless of whether all rows succeeded, some failed, or the entire batch failed.

  • Format: The notification body is JSON.
  • Trigger: Sent once per batch, when the batch reaches a terminal status (completed, processed_with_errors, or failed).
  • File uniqueness: There will be exactly one result file generated per batch upload request.
  • Availability: The result file will be available for download for at least 7 days. This applies to both the sandbox and production environment.
  • File size: The size of the result file depends on the number of transactions created from the uploaded batch file (more transactions lead to a larger file).

The notification to the url will contain the following field:

FieldTypeDescription
linkrequiredstringThe downloadable URL for the result JSON file. (Available at least 7 days)
Example notification
{
"link": "https://gateway.ixopay.com/link-to-the-result-json-file"
}
Hostname

The link field in the notification will point to the result file hosted on either gateway.ixopay.com (production environment) or sandbox.ixopay.com (sandbox environment), depending on the environment you used to upload the batch file.

Result file

The result file is in JSON format and is available for download for at least 7 days in both sandbox and production.

Structure

Example result file
{
"summary": {
"totalRows": 100,
"successfulRows": 97,
"failedRows": 3
},
"failedRows": [
{
"type": "TX_LOG_CREATE",
"merchantTransactionId": "your-unique-identifier",
"errorMessage": "currency: 'XXX' is not in the list of valid values",
"errorCode": "1000"
}
],
"successfulRows": [
{
"success": true,
"transactionStatus": "SUCCESS",
"uuid": "abcd1234-...",
"merchantTransactionId": "your-unique-identifier",
"transactionType": "debit",
"amount": "9.99",
"currency": "EUR",
"customer.lastName": "Smith"
}
]
}

summary fields

NameTypeDescription
totalRowsrequiredintegerTotal number of rows that were attempted
successfulRowsrequiredintegerNumber of rows that were executed successfully
failedRowsrequiredintegerNumber of rows that failed validation or execution

failedRows entry fields

NameTypeDescription
typerequiredstringTX_LOG_CREATE — failed before execution; TX_LOG_POST_CREATE — failed during execution
merchantTransactionIdoptionalstring?Your transaction ID from the batch row
errorMessageoptionalstring?Human-readable description of the failure
errorCodeoptionalstring?Machine-readable error identifier

successfulRows entry fields

NameTypeDescription
successrequiredbooleanAlways true for entries in this array
transactionStatusrequiredstringstatus of the transaction
uuidrequiredstringUUID of the transaction
merchantTransactionIdrequiredstringyour transaction ID
transactionTyperequiredstringtransaction type
amountrequiredstringtransaction amount
currencyrequiredstringtransaction currency
errorMessageoptionalstring?description if request fails
errorCodeoptionalnumber?error identifier
errorsoptionalarray?an array containing transaction errors, see TransactionError
returnDataoptionalobject?one of ReturnData
customeroptionalobject?see Customer
extraDataoptionalobject?object containing key-value pairs (string-to-string)
merchantMetaDataoptionalstring?merchant metadata
schedulesoptionalarray?an array containing attached schedules, see ScheduleData
chargebackDataoptionalobject?see ChargebackData
customerProfileDataoptionalobject?see CustomerProfileData