# Integrate Hosted Batch source: https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-batch/integrate-hosted-batch/index.md ## Overview {#overview} Hosted Batch is a Mastercard Gateway feature that enables merchants to upload files with multiple payment transactions for bulk processing. Instead of sending transactions individually through an API, merchants upload a CSV file through the Mastercard Gateway portal. This approach is suitable for non-urgent, back-office activities such as end-of-day processing or recurring payments. This method is simple, efficient and cost-effective for merchants with high transaction volumes or limited technical resources. It supports key transaction types, including authorize, capture, and refund, and provides structured response files for easy reconciliation. Warning: The maximum-supported file size is 3 MB. Each Batch can include up to 18,000 records. ## Prerequisites {#prerequisites} * Ensure that your merchant profile is enabled for the Batch service. * Before you start the integration, see [Best Practices and Tips](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-batch/integrate-hosted-batch/index.md#best-practices-and-tips). ## Integration steps {#integration-steps} **Step 1: [Access Mastercard Gateway](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-batch/integrate-hosted-batch/access-mc-gateway/index.md)** As a first step, check your connectivity to the Mastercard Gateway. **Step 2: [Knowing your input fields](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-batch/integrate-hosted-batch/know-your-input-fields/index.md)** Before you start building the integration, you must be prepared with the values for the fields that require your input. **Step 3: [Create a batch request](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-batch/integrate-hosted-batch/create-batch-request/index.md)** Creating the body of the request is a critical step in the integration. **Step 4: [Send a batch request](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-batch/integrate-hosted-batch/send-batch-request/index.md)** There are many components to make sure the transaction request body is sent securely to the Mastercard Gateway. **Step 5: [Retrieve batch status](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-batch/integrate-hosted-batch/retrieve-batch-status/index.md)** Once a batch is submitted, you can periodically request a batch status to determine the current state of the batch processing. **Step 6: [Process batch response](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-batch/integrate-hosted-batch/process-the-batch-response/index.md)** After a batch has completed processing, you can request a response file that contains the result of each of the uploaded operations. **Step 7: [Test and go live](https://developer.mastercard.com/mastercard-gateway/documentation/test-cards/index.md)** ## Troubleshooting and FAQs {#troubleshooting-and-faqs} Yes, you can use multiple merchant profiles in a single batch request if you can ensure that the operation credentials (merchant identifier and authentication password) for each operation record row are valid to enable successful authentication and authorization. By default, the operation credentials for each operation in a batch use the authentication credentials supplied in the batch request header (both merchant identifier and password). You may choose to use the defaulting mechanism, or supply operation credentials against each operation record row. With the latter, authentication of the operation uses the operation level credentials and will not default to the uploading batch credentials. If the operation level credentials are incorrect, then the batch upload will be rejected. In the sample batch file, the VOID operations use the batch request header credentials as the merchant identifier and password have not been supplied. ```java merchant,apiPassword,apiOperation,order.id,transaction.id,transaction.amount,transaction.currency,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,result,error.cause,error.explanation,response.gatewayCode TESTMERCHANT,,PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,, TESTMERCHANT,,PAY,921830104168,TXID1,30,AUD,5123456789012346,05,13,,,,, ,,VOID,1256378915689,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915690,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915691,TXID1,100,AUD,4987654321098769,05,13,,,,, ``` A batch submission may fail due to the following error conditions. | Scenario | Error Message | |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Batch incomplete because the SHA-1 message digest does not match | Batch submission failed for one of the reasons: * The submitted MIC does not match the MIC computed for the batch file received. * The MIC is not hashed using the SHA-1 algorithm. * The MIC encoding is not HEX. * No MIC is provided in the request body. Check the request and try to submit the batch again. | | Duplicate batch name * A batch with the same name but different content has already been uploaded and validated. * A batch with the same name is currently been uploaded. | Batch submission failed: A batch with this name is currently uploading or a batch with this name but different content has already been uploaded. If the file is already uploading, wait for the upload to finish. If you are using a file name that is already taken, rename the file and submit again. | | An authentication error is returned if you do not have sufficient privileges to submit batches: * Merchant does not have the "API and Hosted Batch" privilege * Invalid Merchant ID * Incorrect password | Authentication failed: The credentials provided in record `` are incorrect. This can be caused by: * A merchant ID is provided, but this merchant does not have sufficient privileges to submit batches for processing. * The merchant ID is incorrect. * The provided password is incorrect. Correct the credentials and make sure that the merchant has sufficient privileges to submit batches for processing, then try to submit the request again. | | An authentication error is returned if you provide only the password but no Merchant ID at the operation level. | Authentication failed. In record `` of the batch file a password is provided but no Merchant ID. Either add a Merchant ID or remove the password to use the batch level merchant credentials for this record, then try to submit the request again. | | An authentication error is returned if the batch credentials are formatted incorrectly. | Authentication failed: The credentials provided in the header are: * use an invalid character * use an invalid Base 64 encoding * exceed 70 characters. Correct the request then try to submit again. | | An authentication error is returned if: * Batch credentials are invalid * Merchant does not have the "API and Batch" privilege * Merchant ID is empty * Merchant ID is incorrect * Password is empty * Password is incorrect | Authentication failed: The credentials provided for the batch are invalid. Correct the credentials and try to submit the request again. | | A parsing error is returned if the header contains invalid characters. | Batch submission failed: The batch could not be parsed because the header contained an illegal character. Allowed characters are: * Alphanumeric (a-z, A-Z, 0-9) * Period (.) * Square brackets (\[ \]) Correct the header names and make sure you are using the correct encoding, then try to submit the batch again. | | A parsing error is returned if an operation record row contains more values than defined in the header. | Batch submission failed: The batch could not be parsed because record `` contained more values than defined in the header. Correct the batch, then try to submit again. | | A parsing error is returned if the maximum individual field size is exceeded or an unknown parsing error has occurred in an operation record. | Batch submission failed: The batch could not be parsed due to an error in record ``. Make sure that the batch complies with the file format and that you are using the correct encoding, then try to submit the batch again. | | An encoding error is returned if no encoding or an unsupported encoding has been provided. | Request failed: The provided encoding is not supported. Supported encodings are UTF-8 and LATIN1. Submit the request again using a supported encoding. | | Batch could not be found | Request failed: A batch with this batch name could not be found. Correct the batch name and submit the request again. | | The length check for the provided version failed. | Request failed: The provided version is not valid. Correct the version and submit the request again. | | The length check for the provided Batch Name failed. | Request failed: The provided batch name is not valid. Correct the batch name and submit the request again. | | The length check for the provided Merchant ID failed. | Request failed: The provided Merchant ID is not valid. Correct the Merchant ID and submit the request again. | | A gateway error occurred | The request could not be submitted to the Gateway due to an internal error in the Gateway. Try again later. | Processing of operations by Batch may fail due to communications or systems failure resulting in one of the following errors: * An error occurred due to an internal system failure. * An error occurred because the server had insufficient resources to process the request now. * An error occurred while processing a Tokenization verification transaction When this occurs and an operation is retriable, Batch retries sending the operation for processing either until a non-retriable response is received on the operation or the retry limit is reached. Batch stores the batch names and their corresponding Message Integrity Code (MIC) uploaded by you. Batches with a batch name that has been previously submitted but with a different content can be identified and will be rejected by Batch. Batches with the same name and content as a previously submitted batch can also be identified, and Batch returns the same status as for the batch previously uploaded. So, if the merchant suspects there was a transmission problem, the merchant can verify that the batch was uploaded successfully to Batch. Warning: If a duplicate batch name is submitted with a different batch content or if this batch is uploaded while the first batch is still uploading, then HTTP status code 409 and an error message is returned. Values in the header row of a batch request submitted for processing may only contain characters that can be found in API NVP field names. The following characters are allowed: * Alphanumeric (a-z, A-Z, 0-9) * Period (.) * Square brackets (\[\]) Batch rejects a batch if parsing errors are encountered. Parsing includes splitting the batch into rows, and rows into fields. A parsing error may occur when: * a data row has more commas than the header row, which means it has too many values and does not match the expected format * the maximum individual field size is exceeded Correct these errors first before submitting the batch for processing again. ## Best practices and tips {#best-practices-and-tips} The Batch service does not guarantee that it processes operations in the same order as specified in the batch file because the Batch dispatcher can process operations in parallel. This behavior may also be attributed to the retry function, in other words, if some operations in a batch file need a retry then operations that are ready will be processed first irrespective of the order in which they are specified. For example, even if subsequent operations are specified after initial operations (Capture followed by an Authorization, Void followed by a Pay), then Capture may be performed before Authorization, or Void before Pay. Hence, for operations that must strictly follow an order, it is recommended that you run the initial batch of operations first, wait for the batch response file, and if successful run the subsequent batch of operations. [Tokenization](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/tokenization/index.md) stores cards details in a token. To use Tokenization with Batch, you must use the token identifier in the batch file, as shown in the following file. ```java apiOperation,token,customer.email,customer.firstName,customer.lastName,customer.mobilePhone,customer.phone,repositoryId,sourceOfFunds.provided.card.expiry.month,sourceOfFunds.provided.card.expiry.year,sourceOfFunds.provided.card.nameOnCard,sourceOfFunds.provided.card.brand,sourceOfFunds.provided.card.expiry,sourceOfFunds.provided.card.fundingMethod,sourceOfFunds.provided.card.issuer,sourceOfFunds.provided.card.scheme,sourceOfFunds.provided.card.number,sourceOfFunds.type,status,usage.lastUpdated.merchantId,usage.lastUpdated.time,usage.lastUsedTime,verificationStrategy,response.gatewayCode,result,schemeToken.status,schemeToken.statusTime,schemeTokenProvisioningMode,error.cause,error.explanation,error.field,error.supportCode,error.validationType TOKENIZE,,example.user@email.com,,,,,,1,39,,,,,,,5123450000000008,CARD,,,,,,,,,,,,,,, TOKENIZE,,,,,+61412345678,,,1,60,,,,,,,2223000000000007,CARD,,,,,,,,,,,,,,, TOKENIZE,,,,,,+61412345678,,3,40,,,,,,,4508750015741019,CARD,,,,,,,,,,,,,,, TOKENIZE,,example.user@email.com,,,,+61412345678,,1,50,,,,,,,371881634498004,CARD,,,,,,,,,,,,,,, ``` The operation credentials include merchant identifier and password. The operation credentials for each operation in a batch default to the authentication credentials supplied in the batch request header (both merchant identifier and password). However, if you do specify values for both fields against operation record rows, authentication of the operation uses the operation level credentials and will not default to the uploading batch credentials. Warning: In case of multiple merchant profiles, you may choose to default to authentication credentials supplied with the batch request header and/or supply operation credentials for one or more merchant profiles. Alert: If you wish to use operation level credentials, you must supply both merchant identifier and credentials against every operation record row, not either of them. If you are not authorized to use Batch or if the operation level credentials are incorrect, then the batch upload will be rejected. If you wish to default to the credentials in the batch request header, do not include them in the request. Yes, you can process multiple operation types in a single batch file provided they are not related to the same order, in other words, they do not contain the same order identifier. The Batch service does not guarantee that it processes operations in the same order as specified in the batch file because the Batch dispatcher can process operations in parallel. This behavior may also be attributed to the retry function, in other words, if some operations in a batch file need a retry then operations that are ready will be processed first irrespective of the order in which they are specified. For example, if Pay and Void operations are in the same batch file, the Void may be performed before Pay. However, if the operations are NOT related to the same order, in other words, if they contain different order identifiers, then you can have multiple operation types in a single batch file. Yes, you can use multiple sources of card details in a single batch file, except the payment session identifier. For information on multiple sources, see [Multiple Sources of Card Details](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/direct-payment/integrate-gateway-features/using-multiple-sources-of-payment/index.md). The Authorize operations in the sample below use tokens instead of card details. ```java apiOperation,order.id,transaction.id,transaction.amount,transaction.currency,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,cardDetails.cardToken,result,error.cause,error.explanation,response.gatewayCode PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,,, PAY,921830104168,TXID1,50,AUD,5123456789012346,05,13,,,,,, PAY,921830104169,TXID1,100,AUD,4987654321098769,05,13,,,,,, AUTHORIZE,10072028281,TXID1,,,,,,,200,,,,, AUTHORIZE,10072028282,TXID1,,,,,,,300,,,,, AUTHORIZE,10072028283,TXID1,,,,,,,400,,,,, ``` Yes, there is a restriction on the file size. The hosted batch upload allows a maximum of 30 MB. If the file exceeds the specified limit, ensure that files are split into two or more parts, which must not exceed the specified limit, 30 MB.