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

For production: POST https://gateway.ixopay.com/api/v3/batchUpload/{apiKey}/uploadFile
For sandbox: POST https://sandbox.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 you provide a callback URL during your batch upload request, and all transactions within the uploaded file are processed successfully, a notification will be sent to that URL containing a link to the resulting CSV file. This file contains information about the processing status of each transaction.

Format: The file is in CSV format.
Content: It details the processing status of each transaction included in the original batch upload.
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:

Field	Description
`link`	The downloadable URL for the result CSV file. (Available at least 7 days)

Example notification
{
  "link": "https://gateway.ixopay.com/link-to-the-result-csv-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.

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