Managing Transaction Batches Using the API

This guide walks you through how to retrieve, manage, execute, and void payment batches using the AndDone Transaction Batching API. These API methods allow merchants to manage batch lifecycle events, review batch contents, and void individual or bulk transactions before settlement.

Using the Transaction Batching API, merchants can:

• Retrieve batches currently associated with the merchant using POST Get Batches for Merchant
• Review transactions in a batch using POST Get Batch Details
• Track batch timeline events using POST Get Batch Timeline
• Execute a transaction batch on demand using POST Execute Transaction Batch
• Cancel specific transactions within a batch using POST Cancel Batch Transactions
• Void individual payment transactions using POST Void Payment Transaction
• Reference known void errors using the Void Transaction Error Reference

Prerequisites

Before using the API, ensure the following conditions are met:

Enable Supporting Features

In the AndDone Merchant Portal, enable the following features:

• Enable the Transaction Batching module
• Ensure batch creation is scheduled or configured
• Register API keys and whitelisted IPs or origins

Retrieving Batch Information

Using the methods below, you can retrieve various details about the associated batch.

POST Get Batches for Merchant

To fetch all active or recent batches associated with the merchant, call the POST Get Batches for Merchant method.

Request Body

This method uses the x-app-key (Merchant ID) in the authorization header to request the current batches associated with the merchant.

Response Example

{
    "totalRowCounts": 1,
    "data": [
        {
            "id": "q0xWYdQG",
            "merchantId": "YV8RMxOM",
            "batchStatus": "Active",
            "processMethods": "ACH",
            "processorName": "Dummy",
            "isDefault": true,
            "executionTime": "05-16-2024 18:29:59",
            "completionTime": "05-16-2024 18:29:59",
            "captureCount": 1,
            "captureAmount": 11000,
            "voidedCount": 1,
            "voidedAmount": 11000,
            "createdOn": "05-16-2024 18:29:59",
            "createdBy": "System",
            "modifiedOn": "05-16-2024 18:29:59",
            "modifiedBy": "System"
        }
    ]
}

POST Get Batch Details

To get information about individual transactions associated within a given batch, call the POST Get Batch Details method.

Request Body Example

{
    "batchId": "NJ8Pqodm"
}

Response Example

The response returns information about the individual transactions.

{
    "batchId": "NJ8Pqodm",
    "batchStatus": "Active",
    "executionTime": "08-14-2024 23:59:59",
    "completionTime": null,
    "transactionDetails": [
        {
            "transactionId": "0fc7adfe-f528-4938-974d-156819f516e8",
            "transactionStatus": "Authorized",
            "transactionDateTime": "08-14-2024 15:56:13",
            "transactionAmount": 344.8
        },
        {
            "transactionId": "992d8ace-82e4-4c37-8bc0-24e8490030b6",
            "transactionStatus": "Authorized",
            "transactionDateTime": "08-14-2024 15:56:34",
            "transactionAmount": 154.05
        },
        {
            "transactionId": "10b1b7c4-807f-4af4-b90a-d9a6915a2667",
            "transactionStatus": "Authorized",
            "transactionDateTime": "08-14-2024 15:56:41",
            "transactionAmount": 150.24
        },
        {
            "transactionId": "67fa5783-2e3a-4106-b5a1-b7e8eea440f6",
            "transactionStatus": "Authorized",
            "transactionDateTime": "08-14-2024 15:57:54",
            "transactionAmount": 495.02
        }
    ]
}

POST Get Batch Timeline

To get historical data for when transaction timeline events occurred, call the POST Get Batch Timeline method.

Request Body Example

{
    "batchId": "NJ8Pqodm"
}

Response Example

{
    "id": "gNxr4Gdl",
    "batchId": "NJ8Pqodm",
    "merchantId": "nZ8gAqvo",
    "previousEventStatus": "None",
    "eventStatus": "Created",
    "voidedCount": 0,
    "voidedAmount": 0,
    "closedOn": null,
    "eventDate": "08-13-2024 01:45:14",
    "closingAmount": 0,
    "createdOn": "08-13-2024 01:45:14",
    "createdBy": "System",
    "modifiedOn": "08-13-2024 01:45:14",
    "modifiedBy": "System"
}

Managing Batch Transactions

Using the methods below, you can manage transactions within a batch.

POST Cancel Batch Transactions

To to cancel one or more transactions within a batch, call the POST Cancel Batch Transactions method.

Request Body Example

{
    "merchantId": "OgdZ5m8N",
    "batchId": "OgdZ5m8N",
    "voidReason": "Incorrect amount",
    "transactionIds": [
        "03bf6f8a-4bcb-4abf-8877-46273baa38cb",
        "4eff82fb-cc60-4e0a-93bd-585ef227266d"
    ]
}

Response Example

This method returns code 200 if the specified transactions were successfully canceled.

POST Execute Transaction Batch

To enable the merchant to execute a transaction batch on demand, call the POST Execute Transaction Batch method.

Request Body Example

{
    "batchId": "OgdZ5m8N"
}

Response Example

This method returns code 200 if the specified transactions were successfully canceled.

POST Void Payment Transaction

To cancel an authorized payment transaction that is part of a payment batch before it enters the settlement process, call the POST Void Payment Transaction method.

Request Body Example

{
    "TransactionId": "4da5b184-023f-4820-a142-7c28c5b1fe36",
    "VoidReason": "Duplicate transaction"
}

Response Example

{
    "transactionId": "622251e9-8f2c-43c2-9e90-128b3555cf10",
    "transactionStatus": "CancelAttempt",
    "message": null,
    "isCancelled": true
}

Void Transaction Error Reference

If attempting to void a transaction, the following error codes help identify issues related to timing, transaction state, or eligibility. For further details refer to the  Void Transaction Error Reference page.