Batch-upload API

Beta

This API is currently in its beta phase and is provided on an "as is" and "as available" basis. It may contain bugs, errors, or other issues and is subject to changes without prior notice. Thank you for your understanding.

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	Type	Description
apiKey	requiredstring	API Key of the Connector
batchFile	requiredstring	The data of your batch file. Maximum upload size: 8 MB
callbackUrl	optionalstring?	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

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

Flattened CSV

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

• Flattened array of objects:

JSON object

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

Flattened CSV

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

Success

{
  "batchId": "someBatchId123"
}

Error

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

Preauthorize

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

Refund

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

Payout

Name	Type	Description
transactionMethod	requiredstring	The method of the transaction, in this case 'payout'
referenceUuid	requiredstring	The id of the initial transaction this one is referring to
merchantTransactionId	requiredstring	your unique transaction ID
amount	requiredstring	decimals separated by ., max. 3 decimals
currency	requiredstring	3 letter currency code
transactionToken	requiredstring conditional	token generated via payment.js
additionalId1	optionalstring?	any additional ID if required by adapter
additionalId2	optionalstring?	any additional ID if required by adapter
extraData	optionalobject?	object containing key-value pairs (string-to-string)
merchantMetaData	optionalstring?	max. 255 characters
callbackUrl	optionalstring?	endpoint to receive status notifications
description	optionalstring?	max. 255 characters
items	optionalobject?	object containing Items
customer	optionalobject?	see Customer
↳customer.paymentData	optionalobject?	one of PaymentData
language	optionalstring?	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	Type	Description
link	requiredstring	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	optionalboolean?	returns true or false depending on whether the request was successful
transactionStatus	optionalstring?	status of the transaction
uuid	optionalstring?	UUID of the transaction
referenceUuid	optionalstring?	UUID of the related transaction
merchantTransactionId	optionalstring?	your transaction ID
purchaseId	optionalstring?	purchase ID
transactionType	optionalstring?	transaction type
paymentMethod	optionalstring?	payment method
amount	optionalstring?	transaction amount
currency	optionalstring?	transaction currency
schedules	optionalobject?	an array containing attached schedules, see ScheduleData
errors	optionalobject?	an array containing transaction errors, see TransactionError
chargebackData	optionalobject?	see ChargebackData
chargebackReversalData	optionalobject?	see ChargebackReversalData
extraData	optionalobject?	optionalobject? containing key-value pairs ( optionalstring?-to- optionalstring?)
merchantMetaData	optionalstring?	merchant metadata
returnData	optionalobject?	one of ReturnData
customer	optionalobject?	see Customer
customerProfileData	optionalobject?	see CustomerProfileData
errorMessage	optionalstring?	description if request fails
errorCode	optionalnumber?	error identifier

Batch information request

Endpoint

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

Payload

Field	Type	Description
apiKey	requiredstring	API Key of the Connector
batchId	requiredstring	The batchId returned by the /uploadFile request.
getDocument	optionalstring?	If this value is set to true and the processing is finished, the result document will be returned. Otherwise, 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	Type	Description
status	requiredstring	The status of the batch file if the parameter "getDocument" was set to "false" in the request. Can contain "initial", "processing" or "completed".
link	optionalstring?	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

{
  "status": "initial"
}

Processing

{
  "status": "processing"
}

Completed

getDocument set to false

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