For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Batches - Guide | Global Payments

Batches - Guide

Learn how to close batches and later review them

This feature is only available for Customer Present transaction processing.
Please contact Global Payments before coding this feature to confirm it will be available to you when you go live.

This guide focuses on sending an API request to manually close a batch and researching a closed batch using the batch ID.

What is it?

Card-present transactions are managed in batches. Typically, a batch of transactions is an entire business day for a merchant. A batch must be closed for transactions to be settled and funded. Depending on your region, our platform may automatically batch your daily transactions for you. However, in some regions, you may need to batch them yourself on your application.

How does it work?

The main things to know about batches:

Before implementing batches, check with your account manager for any specific market or platform requirements.
The batch_id is returned in all transaction responses and is required to submit a batch-close request.
The Batch ID is made up of three parts:
- The resource identifier: BAT_
- Our batch ID – Not sequential, unique per terminal
- Our batch sequence number – Sequential per terminal, starting at 001 and incrementing with each transaction
A financial transaction (for example, a sale or refund) will create a batch if one is not open. Non-financial commands, such as verify, will not open a batch.
Batch queries are limited to 90 days.
Batch size in all regions except Asia-Pacific is limited to 9,999. In Asia Pacific, the maximum batch size is 900 transactions.
The total combined amount of all transactions in a batch cannot exceed 9,999,999,999.99.

Prerequisites

Before starting the steps in this guide, you must do the following:

Send a batch-close request

Body data is not necessary to close a batch, only the standard header data (including your valid access token). You can close the current batch by sending a POST command to the /batches endpoint with the batch ID returned in every transaction.

A successful batch close will return a status of CLOSED.

Sample request

Sample response

{
    "id": "BAT_933340-213",
    "status": "CLOSED",
    "time_created": "2024-01-31T13:33:00Z",
    "time_last_updated": "2024-01-31T18:08:29.307Z",
    "time_closed": "2024-01-31T18:08:00Z",
    "open_action_id": "1945288291",
    "close_action_id": "ACT_nwmrHEmZ7iT94n1pwkPCCuS17gzhh9",
    "merchant_id": "MER_c4c0df11039c48a9b63701adeaa296c3",
    "merchant_name": "Sandbox_merchant_2",
    "account_id": "TRA_6716058969854a48b33347043ff8225f",
    "account_name": "Transaction_Processing",
    "site_reference": "140271",
    "device_reference": "514",
    "transaction_count": 48,
    "amount": "31396",
    "currency": "USD",
    "gratuity_amount": "100",
    "sales": {
        "count": 36,
        "amount": "45012"
    },
    "refunds": {
        "count": 12,
        "amount": "-13616"
    },
    "funding_debit": {
        "count": 0,
        "amount": "0"
    },
    "funding_credit": {
        "count": 48,
        "amount": "31396"
    },
    "brand_breakdown": [
        {
            "brand": "MASTERCARD",
            "count": 1,
            "amount": "100",
            "gratuity_amount": "0",
            "sales": {
                "count": 1,
                "amount": "100"
            },
            "refunds": {
                "count": 0,
                "amount": "0"
            },
            "funding_debit": {
                "count": 0,
                "amount": "0"
            },
            "funding_credit": {
                "count": 1,
                "amount": "100"
            }
        },
        {
            "brand": "VISA",
            "count": 47,
            "amount": "31296",
            "gratuity_amount": "100",
            "sales": {
                "count": 35,
                "amount": "44912"
            },
            "refunds": {
                "count": 12,
                "amount": "-13616"
            },
            "funding_debit": {
                "count": 0,
                "amount": "0"
            },
            "funding_credit": {
                "count": 47,
                "amount": "31296"
            }
        }
    ],
    "host_breakdown": {
        "merchant_name": "GP API CP",
        "reference": "2323",
        "count": 48,
        "amount": "31396",
        "funding_debit": {
            "sales": {
                "count": 0,
                "amount": "0"
            },
            "refunds": {
                "count": 0,
                "amount": "0"
            }
        },
        "funding_credit": {
            "sales": {
                "count": 36,
                "amount": "45012"
            },
            "refunds": {
                "count": 12,
                "amount": "-13616"
            }
        }
    },
    "action": {
        "id": "ACT_nwmrHEmZ7iT94n1pwkPCCuS17gzhh9",
        "type": "CLOSE",
        "time_created": "2024-01-31T18:08:29.307Z",
        "result_code": "SUCCESS",
        "app_id": "i9R0byBBor6RqTQNj3g4MuVBwH5rd7yR",
        "app_name": "demo_app"
    }
}

Check batch by ID

To query a batch to determine what it contained, send a GET command to the /batches endpoint with the ID you want to investigate. This returns all the relevant data, including the totals for the batch you’re researching. Incidentally, what is returned is separate from our reporting endpoint.

Sample request

curl --compressed -X GET "https://apis.sandbox.globalpay.com/ucp/batches/{id}" \
-H "Authorization: Bearer CdqyD9r7orAGau004u5NecG03JPy" \
-H "X-GP-Version: 2021-03-22" \
-H "Accept: application/json" \

Sample response

{
    "id": "BAT_855049-899",
    "status": "OPEN",
    "time_created": "2021-05-03T21:23:39.718Z",
    "time_closed": "2021-05-03T21:23:39.718Z",
    "open_action_id": "ACT_uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",
    "close_action_id": "ACT_uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",
    "merchant_id": "MER_A6A1EC44522F96630ABEA17A",
    "merchant_name": "ABC INDUSTRIES",
    "account_id": "TRA_86920f927028745yt34d077d88beb29b",
    "account_name": "transaction_processing",
    "site_reference": "string",
    "device_reference": "string",
    "batch_transaction_count": 126,
    "amount": "12000",
    "currency": "USD",
    "gratuity_amount": "500",
    "sales": {
        "count": 123,
        "amount": "12300"
    },
    "refunds": {
        "count": 3,
        "amount": "300"
    },
    "funding_debit": {
        "count": 100,
        "amount": "10000"
    },
    "funding_credit": {
        "count": 26,
        "amount": "2300"
    },
    "brand_breakdown": [
        {
            "brand": "VISA",
            "amount": "8300",
            "count": 83,
            "gratuity_amount": "500",
            "sales": {
                "count": 80,
                "amount": "8000"
            },
            "refunds": {
                "count": 3,
                "amount": "300"
            },
            "funding_debit": {
                "count": 80,
                "amount": "8000"
            },
            "funding_credit": {
                "count": 3,
                "amount": "300"
            }
        }
    ],
    "action": {
        "id": "ACT_uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",
        "type": "BATCH_SINGLE",
        "time_created": "2021-05-03T21:23:39.718Z",
        "result_code": "SUCCESS",
        "app_id": "uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",
        "app_name": "my_lovely_app"
    }
}

Integration references

To get a deeper understanding of this function, we recommend that you use our provided integration references for both API and # integrations. For the full detailed API specification, see the API Explorer.

/accesstoken - API Explorer

Generate an access token.

/batches - API Explorer

Close and review batches by ID.

SDKs & Libraries

Add server-side or client-side code to your integration.

Testing

Batch commands are available for testing in our free Sandbox environment for registered users of this developer portal. Use our resources below to start testing different scenarios.

Test Cards

Test different transaction outcomes with simulated cards or banks.

Postman Collection

View, import, or fork our API collection in Postman.

Responses

View successful responses, HTTP status codes, action response data, and errors.

Policies

Connect

Additional Resources

Batches - Guide

What is it?

How does it work?

Prerequisites

Send a batch-close request

Sample request

Sample response

Check batch by ID

Sample request

Sample response

Integration references

/accesstoken - API Explorer

/batches - API Explorer

SDKs & Libraries

Testing

Test Cards

Postman Collection

Responses