Create Batch

Creates a batch: a named group of payments that share a payment category, a tax jurisdiction and payout rules.

Create a batch before you create payments, with Create Payment or an import. A batch has no status of its own; you send its
payments with Submit Batch, Submit Payments or Submit Payment. Its totals fill in shortly after its payments change.

Requires the Write permission.

Duplicates. This operation is not idempotent and referenceId is not unique: a retried request creates a second batch. If
a request times out, look for your referenceId with Search Batches before retrying.

Side effects. The batch-created webhook fires.

Errors

  • 400 VALIDATION_ERROR on taxJurisdiction: it is not enabled on your account, or it is missing and your account has several jurisdictions.
  • 400 VALIDATION_ERROR on deniedCountries: a value is not an ISO 3166-1 alpha-2 country code.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Body of Create Batch.

string
required

Name of the batch. Payees see it as the default message on its payments.

string

Your own identifier for the batch, such as the payout run ID in your system. Free text. It is not unique: Payment Labs accepts
a second batch with the same value, so it does not protect you from duplicates.

string
enum
required

Category given to payments created in the batch when they do not set their own. It decides the tax treatment together with the jurisdiction.

string
enum

Tax jurisdiction for the batch's payments. Must be one enabled on your account, or none. Required when your account has
several jurisdictions; otherwise it defaults to your only jurisdiction, or to none when you have none. It cannot be changed
after the batch is created.

allowedPaymentMethods
array of objects

Payout methods the batch's payees may receive its payments on. Omit it to allow every method enabled on your account.

allowedPaymentMethods
deniedCountries
array of strings

Countries the batch must not pay into, as ISO 3166-1 alpha-2 codes. A payment whose payee lives in one of them becomes
RESTRICTED and is not sent.

deniedCountries
boolean
Defaults to false

Create the batch already archived.

Responses

Language
Credentials
Bearer
JWT
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json