Batch

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.

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!

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 Authentifizierung 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).

Flows

Find a full transaction flow involving every party and (optional) steps in this overview:

1. Your customer goes to your check-out page and enters her/his credit card data to finalise the purchase.
2. You store your customers' credit card data in your system or tokenise the card data.
3. You send a SubmitBatch request to our platform. 
   3'(optional). We perform a fraud prevention check.
4. Our platform performs a validation check and sends the response containing a unique merchantBatchReference.
5. You send a ProcessBatch request to our platform to process the transactions/maintenance operations from the batch.
6. We process the transactions and receive the result from the acquirer.
7. You send a batch processing status request to our platform.
8. 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

• Transactions.
• Maintenance operations.

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.

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"
           }
       }
   ]
}    

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"
				}
			}
		}
	]
}

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

• Cancel authorisations.
• Capture authorisations.
• Refund payments.

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"
				}
			}
		}
	]
}