POST /batches

This operation creates a new payment Batch in DRAFT status.

When creating a new Batch:

1. A unique ID will be returned which can be used for subsequent calls to query and/or modify the Batch.

2. A Batch is created with no Payments. Payments for the batch are added by calling POST /batches/{id}/payments.

3. A new batch will be created in a draft status (i.e. statusCode: DRAFT). Batches in draft status are not processed until POST /batch/{id}/submit is called.

4. externalId (in the request body) can be supplied to map payment identifiers in an external system. If externalId is supplied, then it must be unique.

When a batch is in DRAFT status, it can be updated (e.g. name and payment details can be updated) as well as cancelled.

Request

Creating a new Batch requires the following payload:

{
  "name": "string",
  "externalId": "string"
}

Header	Mandatory	Description
Authorization	Yes	Bearer token from /authentication/getToken

Body Field	Mandatory	Description
name	Yes	Friendly name to give to the Batch.
externalId	No	Optional batch identifier that can be supplied by external system for tracing purposes. If supplied, the externalID across all batches must be unique.

Sample Request

{
  "name": "Test Batch 1",
  "externalId": "testbatch1"
}

Response

If successful, the operation will return a Batch response:

{
  "id": "string($guid)",
  "name": "string",
  "externalId": "string",
  "statusCode": "string",
  "createdAt": "string($date-time)"
}

Field	Response Type	Description
id	string($guid)	Unique ID for the Batch. Used for subsequent calls to other Batch operations.
name	string	Name of the batch as supplied in the request.
externalId	string	External ID of the batch as supplied in the request.
statusCode	string	Status of the Batch. A new Batch will always have a DRAFT status code.
createdAt	string($date-time)	Date and time when the Batch was created.

Sample Response

{
  "id": "b7ccbefd-51e1-4720-81fb-da5700e34e81",
  "name": "Test Batch 1",
  "externalId": "testbatch1",
  "statusCode": "DRAFT",
  "createdAt": "2022-12-13T12:29:39.6332995Z"
}