Skip to main content

Batch-upload API

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

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

HTTP Upload Request

Endpoint

POST https://gateway.ixopay.com/api/v3/batchUpload/{apiKey}/uploadFile

Payload

FieldRequiredDescription
apiKeytrueAPI Key of the Connector
batchFiletrueThe data of your batch file. Maximum upload size: 8 MB
callbackUrlfalseThe url the link to the resulting csv 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
# Replace $USERNAME, $PASSWORD, $API_KEY, $FILENAME and $CALLBACK_URL with their corresponding values
curl https://gateway.ixopay.com/api/v3/batchUpload/$API_KEY/uploadFile \
--request POST \
--header "Content-Type: application/json" \
--user '$USERNAME:$PASSWORD' \
--form "batchFile=@$FILENAME.csv" \
--form "callbackUrl=$CALLBACK_URL"

Transaction batch file structure

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 with both debit and preauthorize transactions

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"

Response examples

The file and the included keys in the first line of the file will be checked at the file upload. If no file is given, if a given key is not allowed or if one of the required keys is missing, an error will be returned.

The response will be in JSON-format and can include following fields.

FieldDescription
batchIdThe batch id identifying the uploaded file. With this id the status of the processing can be recalled, as can the resulting file once the processing is finished.
errorThe description of an error if the uploaded file was invalid.
{
"batchId": "someBatchId123"
}

Transaction types

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

Debit

NameTypeRequiredDescription
transactionMethodstringtrueThe method of the transaction, in this case 'debit'
referenceUuidstringtrueThe id of the initial transaction this one is referring to
merchantTransactionIdstringtrueyour unique transaction ID
amountstringtruedecimals separated by ., max. 3 decimals
currencystringtrue3 letter currency code
additionalId1stringfalseany additional ID if required by adapter
additionalId2stringfalseany additional ID if required by adapter
extraDataobjectfalseobject containing key-value pairs (string-to-string)
merchantMetaDatastringfalsemax. 255 characters
callbackUrlstringfalseendpoint to receive status notifications
transactionTokenstringfalsetoken generated via payment.js
descriptionstringfalsemax. 255 characters
itemsobjectfalseobject containing Items
withRegisterbooleanfalsestore customer's payment instrument for recurring transactions
transactionIndicatorstringfalseRECURRING
customerobjectfalsesee Customer
customer.paymentDataobjectfalseone of PaymentData
scheduleobjectfalsesee Schedule
customerProfileDataobjectfalsesee CustomerProfileData
threeDSecureDataobjectfalsesee ThreeDSecureData
languagestringfalse2 characters

Preauthorize

NameTypeRequiredDescription
transactionMethodstringtrueThe method of the transaction, in this case 'preauthorize'
referenceUuidstringtrueThe id of the initial transaction this one is referring to
merchantTransactionIdstringtrueyour unique transaction ID
amountstringtruedecimals separated by ., max. 3 decimals
currencystringtrue3 letter currency code
additionalId1stringfalseany additional ID if required by adapter
additionalId2stringfalseany additional ID if required by adapter
extraDataobjectfalseobject containing key-value pairs (string-to-string)
merchantMetaDatastringfalsemax. 255 characters
callbackUrlstringfalseendpoint to receive status notifications
transactionTokenstringfalsetoken generated via payment.js
descriptionstringfalsemax. 255 characters
itemsobjectfalseobject containing Items
withRegisterbooleanfalsestore customer's payment instrument for recurring transactions
transactionIndicatorstringfalseRECURRING
customerobjectfalsesee Customer
customer.paymentDataobjectfalseone of PaymentData
scheduleobjectfalsesee Schedule
customerProfileDataobjectfalsesee CustomerProfileData
threeDSecureDataobjectfalsesee ThreeDSecureData
languagestringfalse2 characters

Refund

NameTypeRequiredDescription
transactionMethodstringtrueThe method of the transaction, in this case 'refund'
referenceUuidstringtrueThe id of the initial transaction this one is referring to
merchantTransactionIdstringtrueyour unique transaction ID
amountstringtruedecimals separated by ., max. 3 decimals
currencystringtrue3 letter currency code
additionalId1stringfalseany additional ID if required by adapter
additionalId2stringfalseany additional ID if required by adapter
extraDataobjectfalseobject containing key-value pairs (string-to-string)
merchantMetaDatastringfalsemax. 255 characters
callbackUrlstringfalseendpoint to receive status notifications
transactionTokenstringfalsetoken generated via payment.js
descriptionstringfalsemax. 255 characters
itemsobjectfalseobject containing Items

Payout

NameTypeRequiredDescription
transactionMethodstringtrueThe method of the transaction, in this case 'payout'
referenceUuidstringtrueThe id of the initial transaction this one is referring to
merchantTransactionIdstringtrueyour unique transaction ID
amountstringtruedecimals separated by ., max. 3 decimals
currencystringtrue3 letter currency code
transactionTokenstringconditionaltoken generated via payment.js
additionalId1stringfalseany additional ID if required by adapter
additionalId2stringfalseany additional ID if required by adapter
extraDataobjectfalseobject containing key-value pairs (string-to-string)
merchantMetaDatastringfalsemax. 255 characters
callbackUrlstringfalseendpoint to receive status notifications
descriptionstringfalsemax. 255 characters
itemsobjectfalseobject containing Items
customerobjectfalsesee Customer
customer.paymentDataobjectfalseone of PaymentData
languagestringfalse2 characters

Callback notification

If a callback url is given in the batch upload request and all transactions inside the uploaded batch file were processed, a link to the resulting csv file will be sent to the callback url. With this link the result file can be downloaded.

This file will also be given in the csv format and will contain information about the status of the transactions after their processing. The first line of the result document contains all keys for the transactions stated in the following lines.

The notification to the url will contain the following field:

FieldDescription
linkThe url to the result file
Example notification
{
"link": "https://gateway.ixopay.com/link-to-the-result-csv-file"
}
Example result files
# This example result file includes part of a successful transaction, a successful transaction with a transaction error and a failed transaction.

success,transactionStatus,uuid,merchantTransactionId,transactionType,customer.lastName,customer.company,returnData.creditcardData.type,returnData.creditcardData.cardHolder,errorMessage,errorCode,errors.0.message,errors.0.code
true,"SUCCESS","abcd1234","2019-09-02-0001","debit","Smith","Alex's Artisan Goods","visa","Alex Smith","","","",""
true,"ERROR","bcde4567","2019-09-02-0002","debit","","","","","","","Payment could not be processed.","1234"
false,"","","","","","","","","Transaction not found","8001","",""

Possible values in the result file

NameTypeDescription
successbooleanreturns true or false depending on whether the request was successful
transactionStatusstringstatus of the transaction
uuidstringUUID of the transaction
referenceUuidstringUUID of the related transaction
merchantTransactionIdstringyour transaction ID
purchaseIdstringpurchase ID
transactionTypestringtransaction type
paymentMethodstringpayment method
amountstringtransaction amount
currencystringtransaction currency
schedulesobjectan array containing attached schedules, see ScheduleData
errorsobjectan array containing transaction errors, see TransactionError
chargebackDataobjectsee ChargebackData
chargebackReversalDataobjectsee ChargebackReversalData
extraDataobjectobject containing key-value pairs (string-to-string)
merchantMetaDatastringmerchant metadata
returnDataobjectone of ReturnData
customerobjectsee Customer
customerProfileDataobjectsee CustomerProfileData
errorMessagestringdescription if request fails
errorCodenumbererror identifier

Batch information request

Endpoint

GET https://gateway.ixopay.com/api/v3/batchUpload/{apiKey}/{batchId}/get

Payload

FieldRequiredDescription
apiKeytrueAPI Key of the Connector
batchIdtrueThe batchId returned by the /uploadFile request.
getDocumentfalseIf this value is set to "true" and the processing is finished, the result document will be returned. If it is set to "false", a link to the result document is returned.
# Replace $USER, $PASSWORD, $API_KEY, $BATCH_ID and $GET_DOCUMENT with their corresponding values!
curl https://gateway.ixopay.com/api/v3/batchUpload/$API_KEY/$BATCH_ID/get?getDocument=$GET_DOCUMENT \
--request GET \
--header "Content-Type: application/json" \
--user "$USER:$PASSWORD"

Response

The response will be in JSON-format and may include following fields:

FieldDescription
statusThe status of the batch file if the parameter "getDocument" was set to "false" in the request. Can contain "initial", "processing" or "completed".
linkThe link to the result file if the parameter "getDocument" was set to "false" in the request.

If the processing is already finished and "getDocument" was set to "true" in the request, the result document will be returned.

{
"status": "initial"
}