The Create Batch Transaction request enables you to process multiple transactions at once, including credit card transactions (Auth Capture only), ACH/ECP, SEPA, and PayPal recurring transactions.
The request includes multiple cardTransaction and/or altTransaction resources; a unique batch ID that you define; and a callback URL pointing to where you would like the status of the batch transaction to be sent after processing.
The API sends an immediate response to the Create Batch Transaction request and then the individual transactions in the request are processed. Once all transactions are processed, BlueSnap sends the full batch result to the callback URL you provided in the request. Some of the transactions may be successfully processed and some may fail. However, as long as the batch file was successfully processed, the callback status of the batch will be completed. For an example of the batch result that is sent to your callback URL after the transactions have been processed, see Example Batch Result.
Transaction limit per batch
There is a limit of 2000 transactions per batch.
Request Content
batchTransaction container required, contains the following properties (see batchTransaction ):
batchId string required
callbackUrl string required
cardTransaction container required for credit card transactions (see cardTransaction)
altTransaction container required for ACH/ECP, SEPA, or PayPal transactions (see altTransaction)
Response Details
If successful, the response HTTP status code is 201 Created.
Note that if an error occurs, the error format is slightly different from other error types. See Batch transaction errors.
For an example of the batch result that is sent to your callback URL after the transactions have been processed, see Example Batch Result.
Examples
Request Examples
curl -v -X POST https://sandbox.bluesnap.com/services/2/batch-transactions \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"batchId": "PKB0042",
"callbackUrl": "http://example.com/batch_callback ",
"cardTransaction": [{
"cardTransactionType": "AUTH_CAPTURE",
"merchantTransactionId": "566",
"amount": 20.00,
"currency": "USD",
"cardHolderInfo": {
"firstName": "Joe",
"lastName": "Example"
},
"creditCard": {
"cardNumber": "4263982640269299",
"expirationMonth": "02",
"expirationYear": "2023"
}
},{
"cardTransactionType": "AUTH_CAPTURE",
"merchantTransactionId": "567",
"amount": 25.00,
"currency": "USD",
"cardHolderInfo": {
"firstName": "Jane",
"lastName": "Shopper"
},
"creditCard": {
"cardNumber": "4111111111111111",
"expirationMonth": "07",
"expirationYear": "2023"
}
}]
}'
curl -v -X POST https://sandbox.bluesnap.com/services/2/batch-transactions \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"batchId": "PKB0043",
"callbackUrl": "http://example.com/batch_callback ",
"cardTransaction": [{
"cardTransactionType": "AUTH_CAPTURE",
"merchantTransactionId": "566",
"amount": 11.00,
"currency": "USD",
"vaultedShopperId": 19596516
},{
"cardTransactionType": "AUTH_CAPTURE",
"merchantTransactionId": "567",
"amount": 12.00,
"currency": "USD",
"vaultedShopperId": 19596754,
"creditCard": {
"cardLastFourDigits": "9299"
}
}]
}'
curl -v -X POST https://sandbox.bluesnap.com/services/2/batch-transactions \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"batchId": "PKB0044",
"callbackUrl": "http://example.com/batch_callback ",
"altTransaction": [{
"amount": 100.00,
"currency": "USD",
"paypalTransaction": {
"paypalSubscriptionId": 22758655
}
}]
}'
curl -v -X POST https://sandbox.bluesnap.com/services/2/batch-transactions \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"batchId": "PKB0045",
"callbackUrl": "http://example.com/batch_callback ",
"cardTransaction": [{
"cardTransactionType": "AUTH_CAPTURE",
"merchantTransactionId": "566",
"amount": 20.00,
"currency": "USD",
"cardHolderInfo": {
"firstName": "Joe",
"lastName": "Example"
},
"creditCard": {
"encryptedCardNumber": "$bsjs_1_0_4$BFxgRNbmuILoOGnT+GRqSKUw51ZEwJbaMNVZhSg1vxqaQlk4W3SbO0VE/yMiSUSwff9r08FDm//mY6RUv7i/IpmkgIfQJUhw09vohKzZF0OwPdD4xKX3DP+ZNwDWkI5655hQuAZJz3n/VFo22v4zJu4ZliFujDT9tjq/UjzlNgwMkIgGUa/0Zh6HG2MJWjGU8X0RZI/3aCTq7T/r3qeDWLOko10bHLQ1/YdLIw9LsWAOQfHMvMRB+fx+adFuvAGQfl3KFU9S43ME0IG32O9XhjWdJ8yv6bMa9MScpbeYuWH4lfIZNu3Je+H9coNZtMoY3zHZIAcHhjGcsWpTfTltew==$B3TT62QoCueWA4HoqrSwe+flRtEipADuQMy0XGfdaWHMy8ay6fa8sp8wA7rzxDJv$FYRb0yVz2fTvWemafDpeV1UPxezJkTQTYvdaGlJ5nJU=",
"cardType": "VISA",
"expirationMonth": "02",
"expirationYear": "2023"
}
}]
}'
curl -v -X POST https://sandbox.bluesnap.com/services/2/batch-transactions \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"batchId": "PKB0061",
"callbackUrl": "http://example.com/batch_callback ",
"cardTransaction": [
{
"cardTransactionType": "AUTH_CAPTURE",
"merchantTransactionId": "566",
"softDescriptor": "DescTest txn1",
"amount": 11.00,
"currency": "USD",
"cardHolderInfo": {
"firstName": "John",
"lastName": "Doe"
},
"creditCard": {
"cardNumber": "4263982640269299",
"expirationMonth": "02",
"expirationYear": "2023"
}
}
],
"altTransaction": [
{
"softDescriptor": "ABC COMPANY",
"amount": 100.00,
"currency": "USD",
"payerInfo": {
"firstName": "John",
"lastName": "Doe",
"zip" : "02453",
"phone": "1234567890"
},
"ecpTransaction": {
"accountNumber": "4099999992",
"routingNumber": "011075150",
"accountType": "CONSUMER_CHECKING"
},
"authorizedByShopper": "true"
},
{
"softDescriptor": "SepaPapi",
"amount": 20.00,
"currency": "EUR",
"payerInfo": {
"firstName": "John",
"lastName": "Doe",
"phone": "23123133213",
"zip" : "45353434",
"country": "IT",
"state": "ca",
"city": "London",
"address": "green line 21"
},
"sepaDirectDebitTransaction": {
"iban": "DE09100100101234567891",
"bic": "PBNKDEFFXXX"
},
"authorizedByShopper": "true"
}
]
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/batch-transactions \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"batchId": "PKB0035",
"callbackUrl": "http://example.com/batch_callback ",
"cardTransaction": [{
"cardTransactionType": "CAPTURE",
"transactionId": "38591014",
"merchantTransactionId": "1"
}]
}
Response Example
HTTP/ 1.1 201 Created
Example Descriptions
For details about the above examples, see:
- Basic Create Batch Transaction
- Create Batch Transaction with vaulted shoppers
- Create Batch Transaction with PayPal recurring subscription payment
- Create Batch Transaction with encrypted card details
Basic Create Batch Transaction
This example shows a basic Create Batch Transaction request, containing two cardTransaction resources with the required fields to process a credit card payment.
Note that within each cardTransaction resource you can use any of the options available for a single Auth Capture or Create PayPal Transaction (recurring subscription payment only) request, such as using a vaulted shopper, sending encrypted card information, including metadata, and so on.
Create Batch Transaction with vaulted shoppers
To perform a Create Batch Transaction request with existing vaulted shoppers, you'll need to include the vaultedShopperId property within the cardTransaction or altTransaction resources in your request.
Remember to include the card's last four digits if multiple cards are saved for the shopper.
Above is an example of a request with a vaulted shopper ID within each cardTransaction resource.
Create Batch Transaction with PayPal recurring subscription payment
To perform batch transactions with PayPal payments for subscriptions, you will need to send the altTransaction resource in your request, and include in it the paypalTransaction resource, with the paypalSubscriptionId element.
The request should contain only one transaction per unique paypalSubscriptionId.
On the right is an example of a request with one PayPal subscription transaction.
For more information, see Merchant-managed PayPal subscriptions.
Create Batch Transaction with encrypted card details
Your PCI compliance requirements and API permission level may require that you send credit card data in encrypted format only. To do this, you'll need to include the encryptedCardNumber and encryptedSecurityCode properties within the cardTransaction resources in your request.
On the right is an example of a request with encrypted credit card numbers within each cardTransaction resource.
Back to Top
API Explorer
To test out a call, enter the JSON portion of the request below and then click Try it!
In order to get a successful response, you must enter a unique batch ID in the batchId property.
Tip: Copy the JSON portion from one of the example requests above, or use the JSON code below as a starting point. You can enter different parameters and test credit card numbers to see how your test scenario would work. The request headers, including authorization, are already built in for you in this test area, so you should not include them here.
{
"batch-transaction": {
"batch-id": "567890",
"callback-url": "http://example.com/batch_callback",
"card-transaction": [
{
"card-transaction-type": "AUTH_CAPTURE",
"merchant-transaction-id": "566",
"amount": "20.00",
"currency": "USD",
"card-holder-info": {
"first-name": "Joe",
"last-name": "Example"
},
"credit-card": {
"card-number": "4263982640269299",
"expiration-month": "02",
"expiration-year": "2023"
}
},
{
"card-transaction-type": "AUTH_CAPTURE",
"merchant-transaction-id": "567",
"amount": "25.00",
"currency": "USD",
"card-holder-info": {
"first-name": "Jane",
"last-name": "Shopper"
},
"credit-card": {
"card-number": "4111111111111111",
"expiration-month": "07",
"expiration-year": "2023"
}
}
]
}
}