# Hosted Batch source: https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-batch/index.md ## Overview {#overview} Hosted Batch allows you to submit batch transactions securely and reliably for processing through the Mastercard Gateway. This removes the need to install and maintain batch transaction applications within your environment and help with meeting the Payment Card Industry Data Security Standard (PCI DSS) requirements. For example, you can use an online shopping cart to initiate authorizations, then use batch processing to carry out captures and refunds to the gateway for processing. This does not require direct payer interaction. Once submitted, you can periodically request a batch status to determine the current state of the batch processing. This includes a count of the total uploaded, processed, and erred operations as well as time and date stamps on processing actions. The same batch status is also visible to your payment service provider through the Batch Status Search screen in Merchant Manager. After a batch has completed processing, you can request a response file that contains the result of each of the uploaded operations. The batch functionality provides an integration point to the gateway that can accept multiple Mastercard Gateway API operations sent in a single upload request. The version specified in the upload request determines accepted operations. For example, if version X is specified then the operations accepted are the ones supported in version X of the Mastercard Gateway API. You can submit batches for processing either through REST integration or upload in Merchant Administration. ## Recommended paths {#recommended-paths} Select the path that matches your role and integration requirements. | If you are a... | Then focus on... | |----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| | **Enterprise merchant**, a large merchant integrating directly with Gateway APIs | Accepting card payments from customers with the right balance of speed, control, and compliance. | | **Acquirer**, a bank or acquiring institution that enables merchants | Enabling and settle card payments. | ## API reference {#api-reference} This API supports the Hosted Batch integration capabilities. * [Batch](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#batch) ## API versions {#api-versions} These version guidelines apply to the Hosted Batch support in Mastercard Gateway. | If you need | Then... | |------------------------|-----------------------------------------------------------------------------------------------------------| | To integrate to an API | Integrate with API version 100 for full compatibility. Hosted Batch is supported for version 4 and later. | ## 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,,,,,,,371111111111130,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/build/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. ## Key benefits {#key-benefits} The key benefits of batch processing are as follows: * Processes multiple operations securely and efficiently: You can securely process multiple operations by submitting a batch rather than processing each operation individually. * Removes the need for installing a local application: You need not install an application on your system. This removes the cost of deploying, updating, and maintaining applications. * Supports both small and large merchants: Supports the needs of both a. small merchants, who mainly require a solution that is easy to use and does not require integration, and b. large merchants who want to efficiently process large transaction volumes. * Reduces PCI compliance costs: When used with Tokenization, you get the combined benefits of tokenization and batch processing. ## Batch usage {#batch-usage} At the highest level, batch can be considered as a front-end processor to the Mastercard Gateway API. The batch is processed as follows: * You can upload a request file, which the batch processes and validates. The batch breaks the file into records and stores the records in the database. * According to the available processing capacity, the batch extracts each record from the database, sends it as a Name-Value Pair (NVP) request to the Mastercard Gateway API, and waits for the response. If the response shows a retriable failure, the batch retries the operation at set intervals. * At any time, you can issue a request to download the status file. The batch reads the counts of processed, successful, and failed records from the database, collates them into the status file, and returns it to you. * You can request to download the response file. The batch reads the response records from the database, collates them into the response file, and returns it to you. ## Information flow {#information-flow} The information flow for batch is illustrated as follows: ![](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/batch-info-flow@2x.png) 1. Your integration aggregates payer operations into a batch and uploads the batch of operations using HTTPS PUT over the Internet to the gateway through the gateway batch service. For more information, see [Create a Batch Request](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-batch/integrate-hosted-batch/create-batch-request/index.md). You may choose to combine collected card details with details stored on a previously stored token. For more information, see [Multiple Sources of Card Details](https://developer.mastercard.com/mastercard-gateway/documentation/build/direct-payment/integrate-gateway-features/using-multiple-sources-of-payment/index.md). You may also pass additional fields in the Batch Request depending on your business need. For more information, see [Supported Features](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/index.md). 2. Before the gateway processes the batch, you need to validate the batch contents by sending a Message Integrity Code (MIC) comprising an SHA-1 digest of the batch contents so that any missing or corrupt records are detected. For more information, see [Send a Batch Request](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-batch/integrate-hosted-batch/send-batch-request/index.md). 3. Once validated, the gateway processes each operation in the batch. 4. During processing, you can poll for the status of the batch to determine the number of records processed and the overall status. For more information, see [Retrieve a Batch Status](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-batch/integrate-hosted-batch/retrieve-batch-status/index.md). 5. Once the status indicates that the batch processing is complete, you can request a batch response. The batch response includes the response values as specified in the original uploaded batch header. For more information, see [Process the Batch Response](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-batch/integrate-hosted-batch/process-the-batch-response/index.md).