Batch Processing Guide (XML)

The Payment APIs batch processing capabilities enable you to send multiple transactions for processing at once, enabling greater efficiency and simpler processing. Our batch processing capability is flexible, enabling you to adapt and use it according to your business needs.

Example scenario: batch processing for recurring payments

In this tutorial, we walk through an example for merchants who manage their own subscription orders and want to process their shoppers' recurring payments in a batch. This is easy to achieve by saving the shopper's payment info in BlueSnap, running a query in your system to obtain a list of the subscriptions with payments due, and then compiling those subscription payments into a single batch file to send to BlueSnap for processing.

Step 1: Save payment info for new shoppers

When a new shopper first signs up for a subscription, you'll want to save their payment information in BlueSnap so that you can easily use that information to make future recurring payments.

To save the shopper's details, you can either send BlueSnap a Create Vaulted Shopper request, or simply process the transaction using a request like an Auth Capture.

In either case, BlueSnap will create a vaulted shopper with the information you sent, and send you a response with the ID number we assigned to that stored shopper.

Now all you need to do is associate that vaulted shopper ID from BlueSnap with the shopper in your own system.

Step 2: Build and send the batch request for shoppers whose recurring payment is due

In the subscription management system on your end, pull a list of the subscription payments that are due and the relevant vaulted shopper ID for each one. For example, you might do this each day in order to process all payments that are due that day.

Now you can build a Create Batch Transaction request with the relevant charge amount per shopper. If there is more than one credit card stored for a specific shopper, you'll need to specify which card should be charged.

In the request, you also need to include:

a unique ID for the batch
a callback URL, which is where BlueSnap will send the full batch result once all transactions are processed

Here is an example request with two vaulted shoppers:

<batch-transaction xmlns="http://ws.plimus.com">
   <batch-id>99999</batch-id>
   <callback-url>http://example.com/batch_callback</callback-url>
   <card-transaction>
      <card-transaction-type>AUTH_CAPTURE</card-transaction-type>
      <merchant-transaction-id>566</merchant-transaction-id>
      <soft-descriptor>Description1</soft-descriptor>
      <amount>15.00</amount>
      <currency>USD</currency>
      <vaulted-shopper-id>12345678</vaulted-shopper-id>
   </card-transaction>
   <card-transaction>
      <card-transaction-type>AUTH_CAPTURE</card-transaction-type>
      <merchant-transaction-id>567</merchant-transaction-id>
      <soft-descriptor>Description2</soft-descriptor>
      <amount>20.00</amount>
      <currency>USD</currency>
      <vaulted-shopper-id>87654321</vaulted-shopper-id>
   </card-transaction>
</batch-transaction>

Upon sending the request, you'll get an immediate response. If successful, the response HTTP status code is 201 Created. If an error occurs, details will be sent in the response. See Batch transaction errors.

3. Get the batch results back and update your system

Once the transactions in the batch have been processed, BlueSnap will send details about the status of the batch to the callback URL you sent in the Create Batch Transaction request. You can then update your internal system with the information about each completed payment.

Example Batch Result

The batch result includes the batch-transaction resource with processing-info per transaction.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-transaction xmlns="http://ws.plimus.com">
  <batch-id>123789001ABCD</batch-id>
  <callback-url>http://example/callbackurl</callback-url>
  <transaction-count>2</transaction-count>
  <card-transaction>
    <card-transaction-type>AUTH_CAPTURE</card-transaction-type>
    <merchant-transaction-id>566</merchant-transaction-id>
    <transaction-id>38481682</transaction-id>
    <amount>110</amount>
    <currency>USD</currency>
    <card-holder-info>
      <first-name>test first name</first-name>
      <last-name>test last name</last-name>
    </card-holder-info>
    <credit-card>
      <card-last-four-digits>1881</card-last-four-digits>
      <expiration-month>7</expiration-month>
      <expiration-year>2016</expiration-year>
    </credit-card>
    <transaction-meta-data/>
    <processing-info>
      <processing-status>SUCCESS</processing-status>
    </processing-info>
  </card-transaction>
  <card-transaction>
    <card-transaction-type>AUTH_CAPTURE</card-transaction-type>
    <merchant-transaction-id>566</merchant-transaction-id>
    <amount>110</amount>
    <currency>USD</currency>
    <card-holder-info>
      <first-name>test first name1</first-name>
      <last-name>test last name1</last-name>
    </card-holder-info>
    <credit-card>
      <card-last-four-digits>9299</card-last-four-digits>
      <expiration-month>1</expiration-month>
      <expiration-year>2018</expiration-year>
    </credit-card>
    <transaction-meta-data/>
    <processing-info>
      <processing-status>FAIL</processing-status>
      <processing-errors>
        <processing-error>
          <processing-error-code>14002</processing-error-code>
          <processing-error-description>Transaction failed  because of payment processing failure.: 400120</processing-error-description>
        </processing-error>
      </processing-errors>
    </processing-info>
  </card-transaction>
  <processing-info>
    <processing-status>COMPLETED</processing-status>
  </processing-info>
</batch-transaction>