batch-created

Sent when a new batch is created under your payor account.

batch-created tells you that a new batch exists under your payor account.

When it fires

  • You create a batch with Create Batch or from the dashboard.
  • Payment Labs creates a batch for you, for example when you approve payment requests into a new batch.

What to do

  • Store the batch id next to your referenceId.
  • Payments added to the batch fire their own payment-created events.

Payload

data is the batch as Get Batch describes it, read when the webhook is sent. Fields with no value are omitted. Amounts use the Money object. Totals are arrays with one entry per currency in the batch, and an empty array when there is nothing to count.

FieldTypeDescription
idstringBatch ID.
payorIdstringYour payor ID.
referenceIdstringYour own reference for the batch.
namestringBatch name, shown to you and to payees, for example Weekly payroll.
taxJurisdictionstringTax rules applied to the batch's payments: us, de, fi, gb, my, pl, sa, se, or none.
defaultPaymentCategorystringCategory given to new payments that do not set one. One of online-esport-prize, in-person-esport-prize, in-person-esport-prize-out-of-jurisdiction, athlete-prize, online-misc-prize, online-contest-prize, in-person-misc-prize, in-person-contest-prize, remote-contractors, in-person-contractors, reimbursement, royalties.
archivedbooleantrue if the batch is archived.
allowedPaymentMethodsstring[]Payout methods payees may use for this batch's payments, for example bank-transfer-1. Absent when every method enabled for your account is allowed.
deniedCountriesstring[]Two-letter ISO country codes of payees this batch must not pay. Payments to them become RESTRICTED.
onboardednumberShare of the batch's payments whose payee is payable, from 0 to 1.
numberOfPaymentsnumberPayments in the batch.
numberOfPaidPaymentsnumberPayments that have been paid.
numberOfUnpaidPaymentsnumberPayments not yet paid.
numberOfPayableNowPaymentsnumberPayments you can submit now.
numberOfCancelledPaymentsnumberPayments that were cancelled.
totalAmountMoney[]Total of all payments, excluding cancelled ones.
totalPaidMoney[]Total already paid.
totalUnpaidMoney[]Total not yet paid.
totalPayableNowMoney[]Total you can submit now.
totalCancelledMoney[]Total of cancelled payments.
paymentsSummaryobjectThe same counts and totals grouped by state. Has total, paid, unpaid, payableNow and cancelled, each with amount (Money[]), count (number) and byCurrency (array of {currency, totalAmount, count}), plus onboardedPercentage (number, 0 to 1).
auditInfoobjectcreatedAt, updatedAt (ISO 8601 UTC), createdBy and updatedBy.

Counts and totals are recalculated in the background as payments change. They do not fire this event themselves, so the figures in a delivery are only as current as the moment it was sent. Use Get Batch for current figures.

Example

The full request body Payment Labs sends:

{
  "payorId": "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
  "event": "batch-created",
  "timestamp": "2026-03-14T13:55:03.412Z",
  "data": {
    "archived": false,
    "payorId": "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
    "id": "B-01JC8Z1B2C3D4E5F6G7H8J9K0M",
    "name": "March tournament prizes",
    "referenceId": "payrun-2026-03",
    "taxJurisdiction": "us",
    "defaultPaymentCategory": "online-esport-prize",
    "auditInfo": {
      "createdAt": "2026-03-14T13:55:02.000Z",
      "updatedAt": "2026-03-14T13:55:02.000Z",
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]"
    },
    "allowedPaymentMethods": [
      "bank-transfer-1",
      "paypal"
    ],
    "deniedCountries": [
      "KP"
    ],
    "numberOfPayments": 0,
    "numberOfPaidPayments": 0,
    "numberOfUnpaidPayments": 0,
    "numberOfPayableNowPayments": 0,
    "numberOfCancelledPayments": 0,
    "onboarded": 0,
    "totalAmount": [],
    "totalPaid": [],
    "totalCancelled": [],
    "totalUnpaid": [],
    "totalPayableNow": []
  }
}