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

Field	Required	Description
`apiKey`	true	API Key of the Connector
`batchFile`	true	The data of your batch file. Maximum upload size: 8 MB
`callbackUrl`	false	The 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:

JSON object
Flattened CSV

"customer": {
    "identification": "616c6578-2e73-6d69-7468-406578616d70",
    "firstName": "Alex",
    "lastName": "Smith"
}

customer.identification,customer.firstName,customer.lastName
"c001","Alex","Smith"

Flattened array of objects:

JSON object
Flattened CSV

"errors": [
  {
    "message": "Some error",
    "code": "1234"
  },
  {
    "message": "Another error",
    "code": "5678"
  }
]

errors.0.message,errors.0.code,errors.1.message,errors.1.code
"Some error","1234","Another error","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.

Field	Description
`batchId`	The 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.
`error`	The description of an error if the uploaded file was invalid.

Success
Error

{
  "batchId": "someBatchId123"
}

One of the keys given in the first line of the csv file was not allowed or a required key was missing.
{
  "error": "invalid keys line"
}

Transaction types

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

Debit

Name	Type	Required	Description
`transactionMethod`	string	true	The method of the transaction, in this case 'debit'
`referenceUuid`	string	true	The id of the initial transaction this one is referring to
`merchantTransactionId`	string	true	your unique transaction ID
`amount`	string	true	decimals separated by `.`, max. 3 decimals
`currency`	string	true	3 letter currency code
`additionalId1`	string	false	any additional ID if required by adapter
`additionalId2`	string	false	any additional ID if required by adapter
`extraData`	object	false	object containing `key-value` pairs (string-to-string)
`merchantMetaData`	string	false	max. 255 characters
`callbackUrl`	string	false	endpoint to receive status notifications
`transactionToken`	string	false	token generated via payment.js
`description`	string	false	max. 255 characters
`items`	object	false	object containing Items
`withRegister`	boolean	false	store customer's payment instrument for recurring transactions
`transactionIndicator`	string	false	`RECURRING`
`customer`	object	false	see Customer
↳`customer`.`paymentData`	object	false	one of PaymentData
`schedule`	object	false	see Schedule
`customerProfileData`	object	false	see CustomerProfileData
`threeDSecureData`	object	false	see ThreeDSecureData
`language`	string	false	2 characters

Preauthorize

Name	Type	Required	Description
`transactionMethod`	string	true	The method of the transaction, in this case 'preauthorize'
`referenceUuid`	string	true	The id of the initial transaction this one is referring to
`merchantTransactionId`	string	true	your unique transaction ID
`amount`	string	true	decimals separated by `.`, max. 3 decimals
`currency`	string	true	3 letter currency code
`additionalId1`	string	false	any additional ID if required by adapter
`additionalId2`	string	false	any additional ID if required by adapter
`extraData`	object	false	object containing `key-value` pairs (string-to-string)
`merchantMetaData`	string	false	max. 255 characters
`callbackUrl`	string	false	endpoint to receive status notifications
`transactionToken`	string	false	token generated via payment.js
`description`	string	false	max. 255 characters
`items`	object	false	object containing Items
`withRegister`	boolean	false	store customer's payment instrument for recurring transactions
`transactionIndicator`	string	false	`RECURRING`
`customer`	object	false	see Customer
↳`customer`.`paymentData`	object	false	one of PaymentData
`schedule`	object	false	see Schedule
`customerProfileData`	object	false	see CustomerProfileData
`threeDSecureData`	object	false	see ThreeDSecureData
`language`	string	false	2 characters

Refund

Name	Type	Required	Description
`transactionMethod`	string	true	The method of the transaction, in this case 'refund'
`referenceUuid`	string	true	The id of the initial transaction this one is referring to
`merchantTransactionId`	string	true	your unique transaction ID
`amount`	string	true	decimals separated by `.`, max. 3 decimals
`currency`	string	true	3 letter currency code
`additionalId1`	string	false	any additional ID if required by adapter
`additionalId2`	string	false	any additional ID if required by adapter
`extraData`	object	false	object containing `key-value` pairs (string-to-string)
`merchantMetaData`	string	false	max. 255 characters
`callbackUrl`	string	false	endpoint to receive status notifications
`transactionToken`	string	false	token generated via payment.js
`description`	string	false	max. 255 characters
`items`	object	false	object containing Items

Payout

Name	Type	Required	Description
`transactionMethod`	string	true	The method of the transaction, in this case 'payout'
`referenceUuid`	string	true	The id of the initial transaction this one is referring to
`merchantTransactionId`	string	true	your unique transaction ID
`amount`	string	true	decimals separated by `.`, max. 3 decimals
`currency`	string	true	3 letter currency code
`transactionToken`	string	conditional	token generated via payment.js
`additionalId1`	string	false	any additional ID if required by adapter
`additionalId2`	string	false	any additional ID if required by adapter
`extraData`	object	false	object containing `key-value` pairs (string-to-string)
`merchantMetaData`	string	false	max. 255 characters
`callbackUrl`	string	false	endpoint to receive status notifications
`description`	string	false	max. 255 characters
`items`	object	false	object containing Items
`customer`	object	false	see Customer
↳`customer`.`paymentData`	object	false	one of PaymentData
`language`	string	false	2 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:

Field	Description
`link`	The 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

Name	Type	Description
`success`	boolean	returns `true` or `false` depending on whether the request was successful
`transactionStatus`	string	status of the transaction
`uuid`	string	UUID of the transaction
`referenceUuid`	string	UUID of the related transaction
`merchantTransactionId`	string	your transaction ID
`purchaseId`	string	purchase ID
`transactionType`	string	transaction type
`paymentMethod`	string	payment method
`amount`	string	transaction amount
`currency`	string	transaction currency
`schedules`	object	an array containing attached schedules, see ScheduleData
`errors`	object	an array containing transaction errors, see TransactionError
`chargebackData`	object	see ChargebackData
`chargebackReversalData`	object	see ChargebackReversalData
`extraData`	object	object containing `key-value` pairs (string-to-string)
`merchantMetaData`	string	merchant metadata
`returnData`	object	one of ReturnData
`customer`	object	see Customer
`customerProfileData`	object	see CustomerProfileData
`errorMessage`	string	description if request fails
`errorCode`	number	error identifier

Batch information request

Endpoint

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

Payload

Field	Required	Description
`apiKey`	true	API Key of the Connector
`batchId`	true	The batchId returned by the /uploadFile request.
`getDocument`	false	If 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:

Field	Description
`status`	The status of the batch file if the parameter "getDocument" was set to "false" in the request. Can contain "initial", "processing" or "completed".
`link`	The 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.

Initial
Processing
Completed

{
  "status": "initial"
}

{
  "status": "processing"
}

getDocument set to false
{
  "status": "completed",
  "link": "https://link-to-result-document"
}

Batch-upload API

HTTP Upload Request​

Endpoint​

Payload​

Transaction batch file structure​

Example for flattened objects​

Example batch file with both debit and preauthorize transactions​

Response examples​

Transaction types​

Debit​

Preauthorize​

Refund​

Payout​

Callback notification​

Possible values in the result file​

Batch information request​

Endpoint​

Payload​

Response​

HTTP Upload Request

Endpoint

Payload

Transaction batch file structure

Example for flattened objects

Example batch file with both debit and preauthorize transactions

Response examples

Transaction types

Debit

Preauthorize

Refund

Payout

Callback notification

Possible values in the result file

Batch information request

Endpoint

Payload

Response