Batch
This product is in pilot mode. Contact us to become a pilot.

- Optimised scalability for submitting huge amounts of transactions/maintenance operations
- Enhanced security by including the data directly in the request body
- Robust data validation through early checks
Optimised processing guidelines
As this product is in pilot mode, limitations apply.
Batch submission capacity must comply with API size limits. These limits vary depending on the properties included in your request and the payment method used:
- For card payments/PayPal using minimum required properties, you can submit over 10,000 transactions.
- For Apple Pay/Google pay transactions, this capacity may decrease to approximately 2,000–2,500 transactions due to JSON request size because of the additional optional properties) constraints, which typically range from 5–15MB.
To optimise your Batch implementation, we recommend
- Testing your payload structure to determine optimal batch sizes.
- Balancing transaction quantity with property variations for efficiency.
Contact us for assistance with this task.
For any failed batch submission, refer to our platform response when sending requests to our SubmitBatch endpoint.
Get Started
To process transactions on our platform with this solution, make sure that
- You have an account on our platform.
- At least one of our card payment methods is activated in the Merchant Portal via Business > Payment methods.
Are you using the Back Office?
You can check the payment method’s activation status via Configuration > PM activation. - You have configured your API Key and API Secret in your account.
- Your server can process server-to-server request via our RESTful API.
Are you all set? Then learn how to use our Batch solution in the next chapter!
How it works
Before you process live transactions, use our test environment. Get to know our solution without costs or any commitments involved! Once you want to go live, check out here how to get a production account or contact us!
Server to server connections require your systems to process card data at some point. This method brings in a very large number of the PCI requirements.
However, you can significantly reduce the scope of your assessment and the number of PCI requirements: Replace the card number with a token via our Hosted Tokenization Page. This allows you to completely outsource the handling of the card data to our platform. Any of your systems using tokens will not require assessment.
Ways to integrate
As this product is in pilot mode, our Server SDKs do not support this integration method yet. Instead, you need to send all requests as described in the "Integration steps" chapter directly to the respective API endpoints. This requires you to follow a specific authentication process as described in the Authentication guide.
JSON formatting
Using Batch requires you to send a JSON containing all necessary data for transaction/maintenance operations. The content of the JSON differs depending on the individual use case. Find the collection of all supported use cases in the dedicated chapter.
However, for any use case, the request itself must meet the following requirements:
- Our SubmitBatch endpoint supports only JSON data in the request body. The request body contains a JSON object with the correct template as value:
{ "header": { "operationType": "CreatePayment", "merchantBatchReference": "unique-batch-reference", "itemCount": 1 }, "createPayment": [ { "cardPaymentMethodSpecificInput": { "card": { "cardNumber": "4150551403657424", "cvv": "031", "expiryDate": "1231", "cardholderName": "Jacqueline" }, "paymentProductId": 130, "transactionChannel": "ECOMMERCE", "authorizationMode": "FINAL_AUTHORIZATION" }, "order": { "amountOfMoney": { "amount": 5600, "currencyCode": "EUR" }, "references": { "merchantReference": "merchant-reference" } } } ] }
- Each transaction/maintenance operation is a record formatted as a JSON object. Depending on the operationType, all records/JSON objects are put in an array of either
createPayment
capturePayment
cancelPayment
refundPayment - The size limit (2000 records).
When submitting a batch, our platform will always parse – validate – the JSON. Validation covers checks for:
- Missing mandatory properties.
- Mismatched data types for any property.
- Syntax and formatting errors.
- Converting the JSON objects contained in an array of either
createPayment
capturePayment
cancelPayment
refundPayment
into individual batch items for further processing. - The size limit (2000 records).
Integration steps
Our Batch solution allows you to process large amounts of transactions in one go. Your customers provide their card data which you store in your system. Instead of submitting them in real-time, you can choose the timing of the transaction process at will.
Consequently, your business does not require a webshop: You send your transaction requests collectively at any given time to our platform. Hence, you either:
- Store your customers' card credentials.
- Use existing tokens for MITs.
For later submission in specific batch JSONs.
Processing transactions this way means you:
- Process transactions/maintenance operations asynchronously: You define the actual timing of submitting the transaction data to our platform.
- Get a delay for receiving the transaction/maintenance operation results. This depends on the so-called daily cut-off time of your acquirer: We receive the actual transaction results in intervals for all transactions submitted within a specific time frame.
The following chapters cover a high-level overview of a typical flow. It describes all the steps you need to follow for processing Batch transactions. Find a detailed overview in this chapter.
Unlike other integration methods, Batch uses individual API endpoints for individual steps in the batch processing flow.
- Send SubmitBatch request
- Process SubmitBatch response
- Send Process request
- Get batch processing status
Send SubmitBatch request
You send a SubmitBatch request to our platform, containing the relevant data in request body. Batch supports two categories of use cases:
- Processing new transactions (using card data or tokens).
- Performing maintenance operations on existing transactions.
Depending on the use case, the request needs to contain specific properties. Find different examples for each in our dedicated chapter.
Endpoint Urls in test / live
- Endpoint URL TEST: https://payment.preprod.direct.worldline-solutions.com/v2/{merchantId}/merchant-batches
- Endpoint URL LIVE: https://payment.direct.worldline-solutions.com/v2/{merchantId}/merchant-batches
Replace "{merchantId}" with your test/live account on our platform. Learn more about the "merchantId" in our glossary.
- This first step only marks the beginning of the transaction flow. You need to go through all the subsequent steps to actually process transactions/perform maintenance operations.
- Do not mix uses cases in a request payload. Always submit separate request per use case.
- Mind that some mistakes or missing/wrong information might not be noticed when you submit a request. After you process the request, our platform will check it again, and any issues found then could cause the transaction to fail.
Process SubmitBatch response
Our platform sends a response containing information about the request:
{
"merchantBatchReference": "string",
"totalCount": 0
}
Properties | Description |
---|---|
merchantBatchReference | The unique merchant reference for the batch. Make sure to send a value for each request to make it distinguishable from other requests. You will use this reference in subsequent requests for follow-up actions. |
totalCount | Total number of records you submitted in the Batch request. |
Send Process request
To actually process the transactions/maintenance operations from a previously submitted data within 12 hrs., you need to instruct our platform accordingly.
Mind that you need to process a previously submitted batch within 12 hrs. After that period, our platform will delete the batch.
Send a request with an empty body to our Process endpoint, replacing {merchantBatchReference} with the value you have defined in the previous SubmitBatch request.
Endpoint Urls in test / live (Method: POST)
- Test: https://payment.preprod.direct.worldline-solutions.com/v2/{merchantId}/merchant-batches/{merchantBatchReference}/process
- Prod: https://payment.direct.worldline-solutions.com/v2/{merchantId}/merchant-batches/{merchantBatchReference}/process
If our platform cannot process the batch request for any reason, our platform’s response provides information via these properties:
Properties | Description |
---|---|
errorId |
The unique identifier of your request on our platform. If you need our help to solve the error linked to this request, make sure to add it in your message when contacting us. |
errors |
errorCode: 8-digit error code. category: Human-readable description of the global error category. httpStatusCode: 3-digit error code linked to standard HTTP status codes. id: Human-readable description of the specific category the error falls into. message: Human-readable description of the specific category the error falls into, providing detailed information if available. |
Get batch processing status
Get the status of the batch file by sending a request to our Batches endpoint, replacing {merchantBatchReference} with the value you have send when submitting the original request:
Endpoint Urls in test / live (Method: GET)
- Test: https://payment.preprod.direct.worldline-solutions.com/v2/{merchantId}/merchant-batches/{merchantBatchReference}
- Prod: https://payment.direct.worldline-solutions.com/v2/{merchantId}/merchant-batches/{merchantBatchReference}
Our platform's response contains various properties, providing information about the batch:
{
"operationType": "CreatePayment",
"merchantBatchReference": "unique-batch-reference",
"itemCount": 1,
"status":"Processed”
}
Properties | Description |
---|---|
operationType |
The type of operation for the batch. Possible values:
|
merchantBatchReference |
The unique identifier of the batch you have sent the request for. |
itemCount |
Total number of transactions/maintenance operations for this batch. |
status |
Status of the submitted batch. Possible values:
|
Flows
Find a full transaction flow involving every party and (optional) steps in this overview:
- Your customer goes to your check-out page and enters her/his credit card data to finalise the purchase.
- You store your customers' credit card data in your system or tokenise the card data.
- You send a SubmitBatch request to our platform.
3'(optional). We perform a fraud prevention check. - Our platform performs a validation check and sends the response containing a unique merchantBatchReference.
- You send a ProcessBatch request to our platform to process the transactions/maintenance operations from the batch.
- We process the transactions and receive the result from the acquirer.
- You send a batch processing status request to our platform.
- If the transaction was successful, you can deliver the goods / services.
Use cases
Batch is a versatile solution for various use cases. Every use case requires you to add a specific set of mandatory/optional properties to each record/JSON object in the request.
We distinguish between processing
Learn in the following chapters how to compose your batch request for these different use cases. Make sure to stick to the JSON formatting rules.
Batch-specific data will be deleted after 540 days; however, we do not have control over the transactional data.
Transactions
Batch allows you to process new transactions as
- One-off stand-alone transactions with card data/Google Pay/Apple Pay/PaypPal
- Merchant-initiated-transactions (MIT) with a token
- Merchant-initiated-transactions (MIT) with a payment.id
One-off stand-alone transactions with card data
Your JSON must contain an array of createPayment while each item in the array represents one transaction:
{
"header": {
"operationType": "CreatePayment",
"merchantBatchReference": "unique-batch-reference",
"itemCount": 1
},
"createPayment": [
{
"cardPaymentMethodSpecificInput": {
"card": {
"cardNumber": "4330264936344675",
"cvv": "031",
"expiryDate": "1231",
"cardholderName": "Jacqueline"
},
"paymentProductId": 1,
"transactionChannel": "ECOMMERCE",
"authorizationMode": "FINAL_AUTHORIZATION"
},
"order": {
"amountOfMoney": {
"amount": 5600,
"currencyCode": "EUR"
},
"references": {
"merchantReference": "unique-transaction-reference"
}
}
}
]
}
One-off stand-alone transactions with Apple Pay / Google Pay / PayPal
Your JSON must contain an array of createPayment while each item in the array represents one transaction:
Apple Pay
{
"header": {
"operationType": "CreatePayment",
"merchantBatchReference": "applepayMan_payments_12k",
"itemCount": 1 },
"CreatePayment": [
{
"mobilePaymentMethodSpecificInput": {
"decryptedPaymentData": {
"dpan": "4818528900107388",
"cryptogram": "AswbnTMABpY6sli9HcJ4MAABAAA=",
"expiryDate": "1225"
},
"paymentProductId": 302
},
"order": {
"amountOfMoney": {
"amount": 4000,
"currencyCode": "EUR"
}
}
}
]
}
Google Pay
{
"header": {
"operationType": "CreatePayment",
"merchantBatchReference": "merchantRef_CreatePayment-NV-GooglePay-MIN",
"itemCount": 1
},
"CreatePayment": [ {
"mobilePaymentMethodSpecificInput": {
"authorizationMode": "FINAL_AUTHORIZATION", "encryptedPaymentData":"{\"signature\":\"MEQCIDIao18aBBvuNN9VsSr3wyPXNObNnepYZemTXPXeKcssAiAsFzc1Yisg2eNKDRKJ3yNXTFQdGnpyl6f5NoZubnMpnQ\\u003d\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEh2zEJsD/Wih76B54p32bVC7usW0FaaTjFteg4wHFUd9fnwFu/009ZfUQJ1ZSLc7QMrwYm+M95IjOtYXFQOODIA\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1747347367330\\\"}\",\"signatures\":[\"MEQCIBD8dSW5JBd7AcDY3bUFhTrGSR+UjOSzqExbYBu+PnZGAiBM7XEEuw3s1+fxqLIgS81+kkJ2/b2y58VBuuRU/TDiVg\\u003d\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"QCPEJcoxB3NJ29wIn4oTfVrkbGY6ru8b6Ts0dxB/WRgGDSN9N5udggmqcmECi+2VH7XJUJQhxqh+Y5VZTIQTdkM9kjUpUa2lgF5bdYvqAiTTMdhOu45s6YAdivvxsDZ9yNDaxS2XLmOJ1FsCjQWu4HEwJnuOuTzAnX86lhjt2RFx7RNgh4CUAcobpjV5qGwIeul1qjK5Z+fe/GRt4b5uN12rToiIOD06r5moxOruJPiMKX4EDTAzcTYZb1t97b7GKuptOvTeQGESgeeegW68WWeKlmFQTgBB4L0DlO8C4pS5rjNqLc5Mwf8NVh/EpXToPgRh2HlzQjGbqYUn3jCbamsLkRZhYC/VR1RJzk6jfYIjAA+lK593ObaJhpZodnH+BDtckR01rnWBxLxc6tW2GIwB58MTikcOQOY6hMTL4nBDQyRalH/v3wv0wNWZIQ6j0yePkJ8Ru/sKHrU6Du1TRqrKCC60Yxh/4v1r9/weQlGxarDkTdzuMFDodR+XqcY7aHEnw1XiP3M0apiCmo8/bVoVOPc/8GKwaIL+iWZs6ZtJn6tBOR09n6SVEYU\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BJP8phYq1EG8JxMs9B+u/3cHPcb9ErRhHuqsGocOcPQY5FCXB40NywL+4yfTzOvzmkp4vshBHOimd/5P1uFyJNo\\\\u003d\\\",\\\"tag\\\":\\\"gWSqgM+uLZfFYlWzDwqnvVBD6v6cjaexXFkWzq1gEqk\\\\u003d\\\"}\"}",
"paymentProductId": 320
},
"order": {
"amountOfMoney": {
"currencyCode": "EUR",
"amount": 3000
},
"references": {
"merchantReference": "merchant-reference"
}
}
}
]
}
PayPal
{
"header": {
"operationType": "CreatePayment",
"merchantBatchReference": "merchant-batch-reference",
"itemCount": 1
},
"CreatePayment": [
{
"order": {
"amountOfMoney": {
"currencyCode": "EUR",
"amount": 2980
},
"references": {
"merchantReference": "merchant-reference"
}
},
"redirectPaymentMethodSpecificInput": {
"requiresApproval": true,
"token": "586a14a88b0044a4becb6918f1a27fca"
}
}
]
}
Server to server connections require your systems to process card data at some point. This method brings in a very large number of the PCI requirements.
However, you can significantly reduce the scope of your assessment and the number of PCI requirements: Replace the card number with a token. This allows you to completely outsource the handling of the card data to our platform.
Merchant-initiated-transactions (MIT) with a token
Make sure to follow the Card On File guidelines for this use case.
Your JSON must contain an array of createPayment while each item in the array represents one transaction. Replace the sensitive card data with a token:
{
"header": {
"operationType": "CreatePayment",
"merchantBatchReference": "TestMerchant123jj456647589",
"itemCount": 1
},
"createPayment": [
{
"cardPaymentMethodSpecificInput": {
"token": "52f6764169fb419785643a9a9751a33c",
"authorizationMode": "FINAL_AUTHORIZATION",
"transactionChannel": "ECOMMERCE",
"paymentProductId": 3,
"unscheduledCardOnFileRequestor": "merchantInitiated",
"unscheduledCardOnFileSequenceIndicator": "subsequent"
},
"order": {
"amountOfMoney": {
"amount": 5600,
"currencyCode": "EUR"
}
}
}
]
}
Although Card On File-guidelines normally do not allow processing MITs with a token, Batch still supports this use case.
However, this requires you to ensure the dynamic linking principle is applied in your request. Depending on the token’s origin, differences apply:
- If you have created the token via a CIT on our platform, we will take care of the dynamic linking. You will not have to modify the JSON mentioned above.
- If you have created the token on a different platform, you need to include property schemeReferenceData in the JSON.
Regardless of the token’s origin, Batch does not support industry practice use cases yet.
Merchant-initiated-transactions (MIT) with a payment.id
Make sure to follow the Card On File guidelines for this use case. Your JSON must contain an array of subsequentPayment while each item in the array represents one transaction:
{
"header": {
"operationType": "SubsequentPayment",
"merchantBatchReference": "merchant-batch-reference",
"itemCount": 1
},
"subsequentPayment": [
{
"paymentId": "48901070_0",
"subsequent": {
"subsequentCardPaymentMethodSpecificInput": {
"subsequentType": "Recurring"
},
"order": {
"amountOfMoney": {
"amount": 1000,
"currencyCode": "EUR"
},
"references": {
"merchantReference": "merchant-reference"
}
}
}
}
]
}
Maintenance operations
Batch allows you to
Cancellations
Create a JSON with an array of cancelPayment while each item in the array represents one cancellation. Refer to each transaction via property paymentId.
{
"header": {
"operationType": "CancelPayment",
"merchantBatchReference": "unique-batch-reference",
"itemCount": 1,
},
"cancelPayment": [
{
"paymentId": "30660197300_0",
"cancel": {
"amountOfMoney": {
"amount": 1000,
"currencyCode": "EUR"
},
"isFinal": true
}
}
]
}
Captures
Create a JSON with an array of capturePayment while each item in the array represents one capture. Refer to each transaction via property paymentId.
{
"header": {
"operationType": "CapturePayment",
"merchantBatchReference": "unique-batch-reference",
"itemCount": 1
},
"capturePayment": [
{
"paymentId": "30660197300_0",
"capture": {
"amount": 0,
"isFinal": true,
"operationReferences": {
"merchantReference": "merchant-reference"
}
}
}
]
}
Refunds
Create a JSON with an array of refundPayment while each item in the array represents one refund. Refer to each transaction via property paymentId.
{
"header": {
"operationType": "RefundPayment",
"merchantBatchReference": "unique-batch-reference",
"itemCount": 1
},
"refundPayment": [
{
"paymentId": "30660197300_0",
"refund": {
"amountOfMoney": {
"amount": 1000,
"currencyCode": "EUR"
},
"operationReferences": {
"merchantReference": "merchant-reference"
}
}
}
]
}