# 

Many of our partner’s customers need to make multiple payments at once. For instance, they may want to pay all their monthly bills or they may already be used to doing monthly or quarterly payment runs.

Batch Groups enable partners to group up to 1000 transfers under a single reference, this means that all the payments within the batch group can be funded at once.

Follow the guide below to understand more about how batch groups work, how to create a group, add transfers, and funding the batch once closed.

br
Postman Collection
We've created a Postman collection to help you test your integrations easily! It includes:

- Our sandbox environment (https://api.sandbox.transferwise.tech)
- Common API calls for creating users and profiles
- Automated tests that copy response data between calls
- Example responses for reference


Fork the collection to get updates automatically. This lets you test the complete flow with minimal setup!

[](https://god.gw.postman.com/run-collection/24215266-2f0a6a19-ea36-42a4-a10b-8bf08becb3da?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D24215266-2f0a6a19-ea36-42a4-a10b-8bf08becb3da%26entityType%3Dcollection%26workspaceId%3Da247415a-a90f-4b3c-88d2-14aa27592db4#?env%5BWise%20Platform%20API%20(Sandbox)%5D=W3sia2V5IjoiY2xpZW50LWlkIiwidmFsdWUiOiJ0dy10ZXN0LWJhbmsiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImNsaWVudC1zZWNyZXQiLCJ2YWx1ZSI6InR3LXRlc3QtYmFuayIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiaG9zdCIsInZhbHVlIjoiaHR0cHM6Ly9hcGkuc2FuZGJveC50cmFuc2Zlcndpc2UudGVjaCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY2xpZW50LWNyZWRlbnRpYWxzLXRva2VuIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImNsaWVudC1yZWRpcmVjdC11cmkiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoicHJvZmlsZSIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJjbGllbnQtYXV0aC1jb2RlIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRva2VuIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InJlZnJlc2giLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoicGVyc29uYWwtcHJvZmlsZS1pZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJidXNpbmVzcy1wcm9maWxlLWlkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6Im5ldy1xdW90ZS1pZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJuZXctcmVjaXBpZW50LWlkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImlkZW1wb3RlbmN5LWd1aWQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoibmV3LXRyYW5zZmVyLWlkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6IndlYmhvb2sxLWlkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6IndlYmhvb2syLWlkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImJvcmRlcmxlc3MtaWQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYm9yZGVybGVzLXJlY2lwaWVudC1pZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJwcm9maWxlLWlkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiYW55In1d)

Batch Transfers Postman Collection
## The Batch Group resource 

Many Batch Group API endpoints return a *batch group resource*. Batch group resources have the following properties:

Fields
id
Batch group ID

version
Batch version, used for concurrency control. This number is updated whenever there is a change to the batch group state (its status, the identity of the transfers in the batch, etc).  Some API operations will require this version in requests, and operations may be rejected when the requested version does not match the server’s version.  The version will be a signed integer and is not ordered with respect to any previous version.

name
Descriptive name

sourceCurrency
Source currency code (ISO 4217 Alphabetic Code) - This currency is expected to be used for the funding the batch group

status
Current *Batch Group Status* (see below)

transferIds
The IDs of all transfers successfully added to the group

payInDetails
List of pay in details (see *Pay In Details* below). Provided only when the batch-group is in the `COMPLETED` state

status
- `NEW`: New batch group with zero or more transfers. Able to have more transfers added to it. Any transfers in a `NEW` group cannot be yet be funded and paid out.
- `COMPLETED`: The batch group has had all the desired transfers added to it and is now closed to further changes. The transfers in the group are now able to be funded and paid out.Note: `COMPLETED` does not imply that payouts have been successfully completed. It means that all required transfers have been created and associated with the batch group.
- `MARKED_FOR_CANCELLATION`: Cancellation of the transfers in the batch group was requested.
- `PROCESSING_CANCEL`: Transfers in the group are being cancelled. This takes time in Wise's system.
- `CANCELLED`: Transfers in the group have been cancelled.


### Pay In Details

Pay In Details describe how the batch group can be funded.
They are only populated when a batch group is in the `COMPLETED` state.

The following fields are always populated:

Always Populated
type
Method of payment. Currently supported types: `bank_transfer`.

reference
The reference that should be used when funding the transfers in the batch group. This reference should be treated as an opaque value and there should be no attempt to decode or decompose it.

amount
The total pay in amount for all transactions in the batch when paying-in with this reference and method.

currency
Three-character ISO 4217 currency code.

These fields are populated when `type` is `bank_transfer`:

Optionally Populated
name
Name of the bank account holder.

branchName
Name of the bank branch, provided only when the currency route requires it (such as JPY).

accountNumber
Bank account number.

accountType
The *Bank Account Type*, provided only when the currency route requires it.

bankCode
Bank identifier or routing number, depending on pay in type and currency.

bankAddress
The *Pay In Details Address* for the receiving bank, provided only when the currency route requires it.

transferWiseAddress
Wise's *Pay In Details Address*, provided only when the currency route requires it.

iban
ISO 13616 International Bank Account Number (when available).

bban
Basic Bank Account Number (BBAN). Provided only when the currency route requires it (such as NOK).

institutionNumber
Financial Institution number (3 digits). Provided only when the currency route requires it (such as CAD).

transitNumber
Branch Transit Number (5 digits). Provided only when the currency route requires it (such as CAD).

beneficiaryBankBIC
Beneficiary Bank Business Identifier Code (BIC). Provided only when the currency route requires it (such as CAD).

intermediaryBankBIC
Intermediary Bank Business Identifier Code (BIC). Provided only when the currency route requires it (such as CAD).

fpsIdentifier
Faster Payment System identifier. Provided only when the currency route requires it (such as HKD).

clearingNumber
Clearing number. Provided only when the currency route requires it (such as SEK).

### Pay In Details Address

Bank transfer pay in details may contain bank and Wise's addresses for some source currencies.

These currencies include: USD, NOK.

Title
name
Bank name / Wise's company name

firstLine
Street address

postCode
Postcode / ZIP code

city
City

stateCode
State, province or region code

country
Country code

Batch Group Object

```json
{
  "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd89",
  "version": 123,
  "name": "My batch group",
  "sourceCurrency": "NOK",
  "status": "COMPLETED",
  "transferIds": [
    234,
    456
  ],
  "payInDetails": [
    {
      "type": "bank_transfer",
      "reference": "B5323",
      "amount": 12504.54,
      "currency": "NOK",
      "name": "TransferWise Ltd",
      "bankCode": "8301",
      "bankAddress": {
        "name": "CitiBank Europe Plc",
        "firstLine": "Bolette brygge 1",
        "postCode": "0252",
        "city": "Oslo",
        "country": "Norway",
        "stateCode": null
      },
      "transferWiseAddress": {
        "name": "TransferWise Ltd",
        "firstLine": "6th Floor, The Tea Building, 56 Shoreditch High Street",
        "postCode": "E1 6JJ",
        "city": "London",
        "country": "United Kingdom",
        "stateCode": null
      },
      "accountNumber": "9910728",
      "iban": null,
      "bban": "83019910728"
    }
  ]
}
```

## Create a batch group 

**`POST /v3/profiles/{{profileId}}/batch-groups`**

Create a new batch group.

Request
sourceCurrency
Source currency code (ISO 4217 Alphabetic Code) - This currency is expected to be used for the funding the batch group

name
Descriptive name for display purposes, recommended to use a name that uniquely represents this batch. Maximum length of 100 characters.

#### Response

Returns a [batch group object](/api-reference/batch-group#object) without payInDetails.

Example Request

```shell
curl -X POST \
  https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/batch-groups \
  -H 'Authorization: Bearer <your api token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceCurrency": "GBP",
    "name": "my-batch-group"
  }'
```

Example Response

```json
{
  "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88",
  "version": 0,
  "name": "my-batch-group",
  "sourceCurrency": "GBP",
  "status": "NEW",
  "transferIds": [],
  "payInDetails": []
}
```

## Complete a batch group 

**`PATCH /v3/profiles/{{profileId}}/batch-groups/{{batchGroupId}}`**

Completes the batch group and allows funding to proceed. Note: this action prevents any further modification.

Request
profileId
The profile that the batch group is associated with

batchGroupId
Batch group ID

status
Status to be updated to. Use `COMPLETED` as the value.

version
The expected batch group version. This is a concurrency control mechanism. For the change to be accepted by the server, the expected version of the group must match the current version held by the server.  Versions are discovered by [requesting batch group resources](/api-reference/batch-group#get).

#### Response

Returns a [batch group object](/api-reference/batch-group#object) with payInDetails.

Example Request

```shell
curl -X PATCH \
  https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/batch-groups/{{batchGroupId}} \
  -H 'Authorization: Bearer <your api token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "COMPLETED",
    "version": 1234
  }'
```

## Cancel a batch group 

**`PATCH /v3/profiles/{{profileId}}/batch-groups/{{batchGroupId}}`**

Cancel a batch group.
Cancelling closes the group to further modification and initiates the cancellation of all transfers in the batch group.
Only batches that are not funded can be cancelled. Cancellation is final it cannot be undone.

Request
profileId
The profile that the batch group is associated with

batchGroupId
Batch group ID

status
Status to be updated to. Use `CANCELLED` as the value.

version
The expected batch group version. This is a concurrency control mechanism. For the change to be accepted by the server, the expected version of the group must match the current version held by the server.  Versions are discovered by [requesting batch group resources](/api-reference/batch-group#get).

#### Response

Returns a [batch group object](/api-reference/batch-group#object) without payInDetails.

Example Request

```shell
curl -X PATCH \
  https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/batch-groups/{{batchGroupId}} \
  -H 'Authorization: Bearer <your api token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "CANCELLED",
    "version": 1234
  }'
```

Example Request

```json
{
    "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88",
    "version": 12345,
    "name": "my-batch-group",
    "sourceCurrency": "GBP",
    "status": "MARKED_FOR_CANCELLATION",
    "transferIds": [
      100001,
      100002,
      100003
    ],
    "payInReferences": []
}
```

## Retrieving a batch group by ID 

**`GET /v3/profiles/{{profileId}}/batch-groups/{{batchGroupId}}`**

Get an existing batch group.

Request
profileId
The profile that the batch group is associated with

batchGroupId
Batch group ID

#### Response

Returns a [batch group object](/api-reference/batch-group#object).

Example Request

```shell
curl -X GET \
  https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/batch-groups/{{batchGroupId}} \
  -H 'Authorization: Bearer <your api token>'
```

## Create a batch group transfer 

**`POST /v3/profiles/{{profileId}}/batch-groups/{{batchGroupId}}/transfers`**

Create a transfer in the batch group, using a previously created recipient account and quote.
Please see [quote creation](/api-reference/quote#create) and [recipient account creation](/api-reference/recipient#create)
documentation.

For the request body format please see [transfer creation](/api-reference/transfer#create).

#### Response

Returns a [transfer object](/api-reference/transfer#object).

Example Request

```shell
curl -X \
  POST https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/batch-groups/{{batchGroupId}}/transfers \
  -H 'Authorization: Bearer <your api token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceAccount": {{refund recipient account ID}},
    "targetAccount": {{recipient account ID}},
    "quoteUuid": {{quote ID}},
    "customerTransactionId": "{{the unique identifier you generated for the transfer attempt}}",
    "details" : {
      "reference" : "to my friend",
      "transferPurpose": "verification.transfers.purpose.pay.bills",
      "transferPurposeSubTransferPurpose": "verification.sub.transfers.purpose.pay.interpretation.service",
      "sourceOfFunds": "verification.source.of.funds.other"
    }
  }'
```

## Fund a batch group 

**`POST /v3/profiles/{{profileId}}/batch-payments/{{batchGroupId}}/payments`**

Funds all the transfers in a batch, they are paid out immediately. Applicable when funding from a multi-currency account.
The Batch Group must first be completed, and there needs to be enough funds in the account for the whole batch otherwise an insufficient funds error will be returned.

Request
type
The method of payment to use (must always be BALANCE)

#### Response

You need to save transfer ID for tracking its status later.

id
Unique batch group ID.

name
Descriptive name.

fileName
If this batch was submitted as a file, this is the given file name

alreadyPaid
This field is not applicable to this use case

shortId
This field is not applicable to this use case

userId
The ID of the user who initiated this payment

profileId
The ID of the profile this payment belongs to

sourceCurrency
The source currency of the batch (note: we will prefer this currency but if there are insufficient funds then an automatic conversion from another currency can occur)

status
Current *Batch Group Status*

groupType
Whether this batch was submitted over the "API" or as a "FILE"

transferIds
The IDs of all transfers in the group.

This endpoint is SCA protected when it applies. If your profile is registered within the UK and/or EEA, SCA most likely applies to you. For more information please read more [implementing SCA](/guides/developer/auth-and-security/sca-and-2fa).

Example Request

```shell
curl -X \
  POST https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/batch-payments/{{batchGroupId}}/payments \
  -H 'Authorization: Bearer <your api token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "BALANCE"
  }'
```

Example Response

```json
{
    "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88",
    "name": "my-batch-group",
    "fileName": null,
    "alreadyPaid": true,
    "shortId": 12345,
    "userId": 33333333,
    "profileId": 44444444,
    "sourceCurrency": "GBP",
    "status": "COMPLETED",
    "groupType": "API",
    "transferIds": [
      100001,
      100002,
      100003
    ]
}
```

## Fund a batch group via direct debit 

**`POST /v1/profiles/{{profileId}}/batch-groups/{{batchGroupId}}/payment-initiations`**

Funds all the transfers in a batch via direct debit. The Batch Group must be in the completed state.
To use this funding method, you need to link an external bank account first. More info on how to create a direct debit account can be found [here](/api-reference/direct-debit-account#create).

Request
type
The method of payment to use (must always be DIRECT_DEBIT)

accountId
Direct debit account ID [direct debit creation](/api-reference/direct-debit-account#create)

reference
Optional. Payment initiation reference. The current limit is 10 characters. If not provided, the reference will be generated automatically and returned in the response

#### Response

You need to save payment initiation ID for tracking its status later.

id
Payment initiation ID

batchGroupId
Batch group ID

reference
This reference will be passed to the network and can be used for reconciliation

userId
The ID of the user who initiated this payment

profileId
The ID of the profile this payment belongs to

type
Type (`DIRECT_DEBIT`)

status
Status (`NEW`, `PROCESSING`, `COMPLETED`, `FAILED`, `CHARGED_BACK`)

accountId
External account ID associated with the payment

createdTime
Date of payment initiated creation

This endpoint is SCA protected when it applies. If your profile is registered within the UK and/or EEA, SCA most likely applies to you. For more information please read more [implementing SCA](/guides/developer/auth-and-security/sca-and-2fa).

Example Request

```shell
curl -X POST \
  https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/batch-groups/{{batchGroupId}}/payment-initiations \
  -H 'Authorization: Bearer <your api token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "DIRECT_DEBIT",
    "accountId": 1
  }'
```

Example Response

```json
{
  "id": 12345,
  "batchGroupId": "068e186d-9632-4937-b753-af3e53f4d0b0",
  "reference": "B1234567",
  "userId": 33333333,
  "profileId": 44444444,
  "type": "DIRECT_DEBIT",
  "status": "NEW",
  "accountId": 1,
  "createdTime": "2022-01-01T19:51:41.423404Z"
}
```

## Retrieve a batch group initiated payment 

**`GET /v1/profiles/{{profileId}}/batch-groups/{{batchGroupId}}/payment-initiations/{{paymentInitiationId}}`**

Get payment initiation info by ID. In addition to [webhooks](/guides/developer/webhooks/event-types#batch-payment-initiations-state-change-event), this endpoint can be used for polling the status of payment initiation.

Request
profileId
The profile that the batch group is associated with

batchGroupId
Batch group ID

paymentInitiationId
The payment initiation ID

#### Response

You need to save payment initiation ID for tracking its status later.

id
Payment initiation ID

batchGroupId
Batch group ID

reference
This reference will be passed to the network and can be used for reconciliation

userId
The ID of the user who initiated this payment

profileId
The ID of the profile this payment belongs to

type
Type (`DIRECT_DEBIT`)

status
Status (`NEW`, `PROCESSING`, `COMPLETED`, `FAILED`, `CHARGED_BACK`)

accountId
External account ID associated with the payment

transferId
Transfer ID of a direct debit payment. Present only after a direct debit is initiated

createdTime
Date of payment initiated creation

Example Request

```shell
curl -X GET \
  https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/batch-groups/{{batchGroupId}}/payment-initiations/{{paymentInitiationId}} \
  -H 'Authorization: Bearer <your api token>' \
  -H 'Content-Type: application/json'
```

Example Response

```json
{
  "id": 12345,
  "batchGroupId": "068e186d-9632-4937-b753-af3e53f4d0b0",
  "reference": "B1234567",
  "userId": 33333333,
  "profileId": 44444444,
  "type": "DIRECT_DEBIT",
  "status": "PROCESSING",
  "accountId": 1,
  "transferId": 100004,
  "createdTime": "2022-01-01T19:51:41.423404Z"
}
```