> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mercoa.com/embedded-ap-ar/guides/accounts-payable/batch-payments/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mercoa.com/_mcp/server.

Batch payments allow your customers to pay multiple invoices in a single transaction.

Batch payments are only available for `bankAccount` and `check` payments. `custom` payments are not officially supported, but you can implement them yourself.

## Enabling Batch Payments

To enable batch payments, you set `batchPayment` on the invoice to `true`. This field will be `true` if the invoice is a batch payment, and `false` otherwise.

The Mercoa `<PayableDetails />` React component also supports batch payments using the `<PaymentOptions />` sub-component. To enable batch payments, you must explicitly include the PaymentOptions component within your PayableDetails implementation.

```tsx
// Usage with PaymentOptions component to enable batch payments
<PayableDetails>
  <PaymentOptions />
</PayableDetails>
```

### Request

POST [https://api.mercoa.com/invoice/\{invoiceId}](https://api.mercoa.com/invoice/\{invoiceId})

**`Batch`**

```curl Batch
curl -X POST https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9 \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "batchPayment": true
}'
```

**`Batch`**

```python Batch
import requests

url = "https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9"

payload = { "batchPayment": True }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`Batch`**

```typescript Batch
import { MercoaClient } from "@mercoa/javascript";

const client = new MercoaClient({ token: "YOUR_TOKEN" });
await client.invoice.update("in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9", {
    batchPayment: true
});

```

**`Batch`**

```go Batch
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9"

	payload := strings.NewReader("{\n  \"batchPayment\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Batch`**

```ruby Batch
require 'uri'
require 'net/http'

url = URI("https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"batchPayment\": true\n}"

response = http.request(request)
puts response.read_body
```

**`Batch`**

```java Batch
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"batchPayment\": true\n}")
  .asString();
```

**`Batch`**

```php Batch
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9', [
  'body' => '{
  "batchPayment": true
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

**`Batch`**

```csharp Batch
using RestSharp;

var client = new RestClient("https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"batchPayment\": true\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Batch`**

```swift Batch
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["batchPayment": true] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.mercoa.com/invoice/in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

## How Batch Payments Work

Mercoa automatically batches payments for invoices that have the `batchPayment` field set to `true`. This means that you don't need to manually batch payments.

Mercoa uses the following logic to determine if an invoice is part of a batch:

1. If the invoice has the `batchPayment` field set to `true`
2. The invoice has the same `payerId` and `vendorId`
3. The invoice has the same `paymentSourceId` and `paymentDestinationId`
4. The invoice has the same `paymentDestinationOptions`
5. The invoice has the same `deductionDate`
6. The invoice has `status` of `SCHEDULED`

If any of these conditions aren't met, the invoice is considered a separate payment.

### Bank Payments

Mercoa sends a single ACH payment for all invoices in a batch. The `paymentDestinationOptions` `memo` assumes that all the invoices in the batch contain the same memo, as one is chosen at random.

### Check Payments

Mercoa sends a single check payment for all invoices in a batch. The check will also contain a table of the invoices in the batch.

## When Batch Payments Are Created

On the `deductionDate`, Mercoa will create a batch payment for the invoices in the batch. This batch will be created at the last payment window of the day, so invoices can be added to the batch until the last payment window.

### Printed Check Batches

Because printed checks are not processed by Mercoa's payment job, when any invoice in a batch is marked as PAID, Mercoa will process all invoices in the batch.