Wise batch-group API

openapi: 3.1.0
info:
  title: Wise Platform 3ds batch-group API
  version: ''
  description: "The Wise Platform API is a REST-based interface that enables programmatic access to Wise's payment infrastructure. All endpoints return JSON-formatted responses and use standard HTTP methods and status codes.\n{% admonition type=\"success\" name=\"New to wise?\" %}\n  We strongly recommend first reading our **[Getting Started Guide](/guides/developer/index.md)** to help you set up credentials and make your first call.\n{% /admonition %}\n\nBefore you begin {% .title-2 .m-t-5 %}\n\nTo use this API reference effectively, you should have:\n\n- Received Valid [API credentials from Wise](/guides/developer/auth-and-security/index.md) (Client ID and Client Secret)\n- Understand OAuth 2.0 authentication\n- Be familiar with RESTful API concepts\n\nCore API resources {% .title-2 .m-t-5 .m-b-0 %}\n\n| Resource | Purpose |\n|----------|---------|\n| **[Quote](/api-reference/quote)** | Exchange rate and fee calculations |\n| **[Recipient](/api-reference/recipient)** | Beneficiary account management |\n| **[Transfer](/api-reference/transfer)** | Payment creation and execution |\n| **[Balance](/api-reference/balance)** | Multi-currency account operations |\n| **[Profile](/api-reference/profile)** | Account ownership details |\n| **[Rate](/api-reference/rate)** | Current and historical exchange rates |\n\n**Not sure which workflow to build?**<br>\nStart with our [Integration Guides](/guides/product/send-money/use-cases/index.md) for step-by-step implementation examples.{% .m-t-3 .m-b-5 %}\n"
servers:
- url: https://api.wise.com
  description: Production Environment
- url: https://api.wise-sandbox.com
  description: Sandbox Environment
tags:
- name: batch-group
  x-displayName: Batch Payment Groups
  description: 'A batch group is a named collection of up to 1000 transfers that can be managed as a single unit. Batch groups are primarily used for funding multiple transfers with a single payment.


    **Workflow:**

    1. Create a batch group with a source currency

    2. Add transfers to the group (up to 1000)

    3. Complete the batch group to close it for modifications

    4. Fund the batch group from a balance or via direct debit


    Individual transfers in the group follow standard transfer lifecycle and can be tracked separately.

    '
paths:
  /v3/profiles/{profileId}/batch-groups:
    post:
      tags:
      - batch-group
      summary: Create a batch group
      operationId: batchGroupCreate
      security:
      - UserToken: []
      - PersonalToken: []
      description: 'Create a new batch group.


        A batch group can hold up to 1000 transfers that will be funded together. After creating the group, add transfers to it, then complete the group to receive pay-in details.

        '
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345678
        description: The ID of the profile to create the batch group for.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - sourceCurrency
              - name
              properties:
                sourceCurrency:
                  type: string
                  description: Source currency code (ISO 4217 Alphabetic Code). This currency is expected to be used for funding the batch group.
                  example: GBP
                name:
                  type: string
                  description: Descriptive name for display purposes. Recommended to use a name that uniquely represents this batch. Maximum length of 100 characters.
                  example: My batch group
      responses:
        '201':
          description: 'Batch group created successfully.


            Note that `payInDetails` is empty for newly created batch groups.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGroup'
              example:
                id: 54a6bc09-cef9-49a8-9041-f1f0c654cd88
                version: 0
                name: My batch group
                sourceCurrency: GBP
                status: NEW
                transferIds: []
                payInDetails: []
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v3/profiles/{profileId}/batch-groups/{batchGroupId}:
    get:
      tags:
      - batch-group
      summary: Retrieve a batch group
      operationId: batchGroupGet
      security:
      - UserToken: []
      - PersonalToken: []
      description: 'Get an existing batch group by ID.

        '
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345678
        description: The ID of the profile that the batch group is associated with.
      - name: batchGroupId
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 54a6bc09-cef9-49a8-9041-f1f0c654cd88
        description: The batch group ID.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Batch group retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGroup'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
    patch:
      tags:
      - batch-group
      summary: Update batch group status
      operationId: batchGroupUpdate
      security:
      - UserToken: []
      - PersonalToken: []
      description: 'Update a batch group''s status to complete or cancel it.


        **Complete a batch group:** Set `status` to `COMPLETED` to close the group for modifications and allow funding to proceed. Once completed, `payInDetails` will be populated with funding instructions.


        **Cancel a batch group:** Set `status` to `CANCELLED` to cancel all transfers in the batch. Only batches that are not funded can be cancelled. Cancellation is final and cannot be undone.


        The `version` parameter is required for concurrency control. The operation will be rejected if the provided version does not match the server''s current version.

        '
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345678
        description: The ID of the profile that the batch group is associated with.
      - name: batchGroupId
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 54a6bc09-cef9-49a8-9041-f1f0c654cd88
        description: The batch group ID.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - status
              - version
              properties:
                status:
                  type: string
                  description: 'Status to update to:

                    - `COMPLETED` — Close the group and allow funding

                    - `CANCELLED` — Cancel the group and all transfers

                    '
                  enum:
                  - COMPLETED
                  - CANCELLED
                  example: COMPLETED
                version:
                  type: integer
                  format: int64
                  description: The expected batch group version for concurrency control. Must match the server's current version.
                  example: 1234
      responses:
        '200':
          description: Batch group updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGroup'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v3/profiles/{profileId}/batch-groups/{batchGroupId}/transfers:
    post:
      tags:
      - batch-group
      summary: Create a batch group transfer
      operationId: batchGroupTransferCreate
      security:
      - UserToken: []
      - PersonalToken: []
      description: 'Create a transfer in the batch group using a previously created recipient account and quote.


        For the request body format, see [transfer creation](/api-reference/transfer#create). For quote and recipient creation, see [quote creation](/api-reference/quote/quotecreate) and [recipient creation](/api-reference/recipient/recipientcreate).

        '
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345678
        description: The ID of the profile that the batch group is associated with.
      - name: batchGroupId
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 54a6bc09-cef9-49a8-9041-f1f0c654cd88
        description: The batch group ID.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - targetAccount
              - quoteUuid
              - customerTransactionId
              properties:
                targetAccount:
                  type: integer
                  format: int64
                  description: Recipient account ID.
                  example: 67890
                sourceAccount:
                  type: integer
                  format: int64
                  description: Refund recipient account ID.
                  example: 12345
                quoteUuid:
                  type: string
                  format: uuid
                  description: Quote ID.
                  example: bd244a95-dcf8-4c31-aac8-bf5e2f3e54c0
                customerTransactionId:
                  type: string
                  format: uuid
                  description: Unique identifier you generate for this transfer attempt.
                  example: a]1b2c3d4-e5f6-7890-abcd-ef1234567890
                details:
                  type: object
                  properties:
                    reference:
                      type: string
                      description: Recipient-facing reference (payment narrative).
                      example: to my friend
                    transferPurpose:
                      type: string
                      description: Transfer purpose code.
                      example: verification.transfers.purpose.pay.bills
                    transferPurposeSubTransferPurpose:
                      type: string
                      description: Sub-purpose code for the transfer.
                      example: verification.sub.transfers.purpose.pay.interpretation.service
                    sourceOfFunds:
                      type: string
                      description: Source of funds code.
                      example: verification.source.of.funds.other
      responses:
        '200':
          description: Transfer created successfully. Returns a transfer object.
          content:
            application/json:
              schema:
                type: object
                description: Transfer object. See [Transfer API reference](/api-reference/transfer#object) for full details.
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v3/profiles/{profileId}/batch-payments/{batchGroupId}/payments:
    post:
      tags:
      - batch-group
      summary: Fund a batch group
      operationId: batchGroupFund
      security:
      - UserToken: []
      - PersonalToken: []
      description: 'Funds all transfers in a batch group from a multi-currency account balance. Transfers are paid out immediately.


        The batch group must first be completed, and there must be enough funds in the account for the whole batch. Otherwise, an insufficient funds error will be returned.


        {% admonition type="warning" %}

        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 [implementing SCA](/guides/developer/auth-and-security/sca-and-2fa).

        {% /admonition %}

        '
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345678
        description: The ID of the profile that the batch group is associated with.
      - name: batchGroupId
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 54a6bc09-cef9-49a8-9041-f1f0c654cd88
        description: The batch group ID.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              properties:
                type:
                  type: string
                  description: The method of payment to use.
                  enum:
                  - BALANCE
                  example: BALANCE
      responses:
        '200':
          description: Batch group funded successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Unique batch group ID.
                    example: 54a6bc09-cef9-49a8-9041-f1f0c654cd88
                  name:
                    type: string
                    description: Descriptive name.
                    example: My batch group
                  fileName:
                    type:
                    - string
                    - 'null'
                    description: If this batch was submitted as a file, this is the given file name.
                    example: null
                  alreadyPaid:
                    type: boolean
                    description: Not applicable to this use case.
                    example: true
                  shortId:
                    type: integer
                    format: int64
                    description: Not applicable to this use case.
                    example: 12345
                  userId:
                    type: integer
                    format: int64
                    description: The ID of the user who initiated this payment.
                    example: 33333333
                  profileId:
                    type: integer
                    format: int64
                    description: The ID of the profile this payment belongs to.
                    example: 44444444
                  sourceCurrency:
                    type: string
                    description: The source currency of the batch. Note that if there are insufficient funds, an automatic conversion from another currency can occur.
                    example: GBP
                  status:
                    type: string
                    description: Current batch group status.
                    enum:
                    - NEW
                    - COMPLETED
                    - MARKED_FOR_CANCELLATION
                    - PROCESSING_CANCEL
                    - CANCELLED
                    example: COMPLETED
                  groupType:
                    type: string
                    description: Whether this batch was submitted over the API or as a file.
                    enum:
                    - API
                    - FILE
                    example: API
                  transferIds:
                    type: array
                    items:
                      type: integer
                      format: int64
                    description: The IDs of all transfers in the group.
                    example:
                    - 100001
                    - 100002
                    - 100003
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v1/profiles/{profileId}/batch-groups/{batchGroupId}/payment-initiations:
    post:
      tags:
      - batch-group
      summary: Fund a batch group via direct debit
      operationId: batchGroupPaymentInitiationCreate
      security:
      - UserToken: []
      description: 'Funds all transfers in a batch group 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. See [direct debit account creation](/api-reference/direct-debit-account/directdebitaccountcreate) for more information.


        {% admonition type="warning" %}

        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 [implementing SCA](/guides/developer/auth-and-security/sca-and-2fa).

        {% /admonition %}

        '
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345678
        description: The ID of the profile that the batch group is associated with.
      - name: batchGroupId
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 54a6bc09-cef9-49a8-9041-f1f0c654cd88
        description: The batch group ID.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              - accountId
              properties:
                type:
                  type: string
                  description: The method of payment to use.
                  enum:
                  - DIRECT_DEBIT
                  example: DIRECT_DEBIT
                accountId:
                  type: integer
                  format: int64
                  description: Direct debit account ID. See [direct debit account creation](/api-reference/direct-debit-account/directdebitaccountcreate).
                  example: 1
                reference:
                  type: string
                  description: Optional payment initiation reference. Maximum 10 characters. If not provided, a reference will be generated automatically.
                  example: B1234567
      responses:
        '200':
          description: 'Payment initiation created successfully. You need to save payment initiation ID for tracking its status later.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInitiation'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v1/profiles/{profileId}/batch-groups/{batchGroupId}/payment-initiations/{paymentInitiationId}:
    get:
      tags:
      - batch-group
      summary: Retrieve a payment initiation
      operationId: batchGroupPaymentInitiationGet
      security:
      - UserToken: []
      - PersonalToken: []
      description: '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 a payment initiation.

        '
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345678
        description: The ID of the profile that the batch group is associated with.
      - name: batchGroupId
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 54a6bc09-cef9-49a8-9041-f1f0c654cd88
        description: The batch group ID.
      - name: paymentInitiationId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345
        description: The payment initiation ID.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Payment initiation retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInitiation'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
components:
  parameters:
    X-External-Correlation-Id:
      x-global: true
      name: X-External-Correlation-Id
      in: header
      required: false
      description: 'Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. [Learn more](/guides/developer/headers/correlation-id).

        '
      schema:
        type: string
        format: uuid
        maxLength: 36
      example: f47ac10b-58cc-4372-a567-0e02b2c3d479
  schemas:
    BatchGroup:
      title: Batch Group
      x-tags:
      - batch-group
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Batch group ID.
          example: 54a6bc09-cef9-49a8-9041-f1f0c654cd88
        version:
          type: integer
          format: int64
          description: '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 require this version in requests, and operations may be rejected when the requested version does not match the server''s version.


            The version is a signed integer and is not ordered with respect to any previous version.

            '
          example: 123
        name:
          type: string
          description: Descriptive name for the batch group.
          example: My batch group
        sourceCurrency:
          type: string
          description: Source currency code (ISO 4217 Alphabetic Code). This currency is expected to be used for funding the batch group.
          example: GBP
        status:
          type: string
          description: 'Current batch group status:

            - `NEW` — New batch group with zero or more transfers. Able to have more transfers added to it. Transfers in a `NEW` group cannot yet be funded and paid out.

            - `COMPLETED` — The batch group has had all desired transfers added and is now closed to further changes. Transfers in the group can now be funded and paid out. Note: `COMPLETED` does not imply payouts have been successfully completed.

            - `MARKED_FOR_CANCELLATION` — Cancellation of the transfers in the batch group was requested.

            - `PROCESSING_CANCEL` — Transfers in the group are being cancelled.

            - `CANCELLED` — Transfers in the group have been cancelled.

            '
          enum:
          - NEW
          - COMPLETED
          - MARKED_FOR_CANCELLATION
          - PROCESSING_CANCEL
          - CANCELLED
          example: COMPLETED
        transferIds:
          type: array
          items:
            type: integer
            format: int64
          description: The IDs of all transfers successfully added to the group.
          example:
          - 234
          - 456
        payInDetails:
          type: array
          description: 'List of pay-in details describing how the batch group can be funded. Provided only when the batch group is in the `COMPLETED` state.


            Currently supported types: `bank_transfer`.

            '
          items:
            $ref: '#/components/schemas/PayInDetails'
    PaymentInitiation:
      type: object
      description: Payment initiation for funding a batch group via direct debit.
      properties:
        id:
          type: integer
          format: int64
          description: Payment initiation ID.
          example: 12345
        batchGroupId:
          type: string
          format: uuid
          description: Batch group ID.
          example: 068e186d-9632-4937-b753-af3e53f4d0b0
        reference:
          type: string
          description: Payment reference that will be passed to the network. Can be used for reconciliation.
          example: B1234567
        userId:
          type: integer
          format: int64
          description: The ID of the user who initiated this payment.
          example: 33333333
        profileId:
          type: integer
          format: int64
          description: The ID of the profile this payment belongs to.
          example: 44444444
        type:
          type: string
          description: Payment type.
          enum:
          - DIRECT_DEBIT
          example: DIRECT_DEBIT
        status:
          type: string
          description: 'Payment initiation status:

            - `NEW` — Payment initiation created

            - `PROCESSING` — Payment is being processed

            - `COMPLETED` — Payment completed successfully

            - `FAILED` — Payment failed

            - `CHARGED_BACK` — Payment was charged back

            '
          enum:
          - NEW
          - PROCESSING
          - COMPLETED
          - FAILED
          - CHARGED_BACK
          example: NEW
        accountId:
          type: integer
          format: int64
          description: External account ID associated with the payment.
          example: 1
        transferId:
          type:
          - integer
          - 'null'
          format: int64
          description: Transfer ID of the direct debit payment. Present only after the direct debit is initiated.
          example: null
        createdTime:
          type: string
          format: date-time
          description: Date and time when the payment initiation was created.
          example: '2022-01-01T19:51:41.423404Z'
    PayInDetails:
      type: object
      description: Pay-in details describe how the batch group can be funded. Only populated when a batch group is in the `COMPLETED` state.
      properties:
        type:
          type: string
          description: Method of payment.
          enum:
          - bank_transfer
          example: bank_transfer
        reference:
          type: string
          description: 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.
          example: B5323
        amount:
          type: number
          format: decimal
          description: The total pay-in amount for all transactions in the batch when paying in with this reference and method.
          example: 12504.54
        currency:
          type: string
          description: Three-character ISO 4217 currency code.
          example: NOK
        name:
          type: string
          description: Name of the bank account holder.
          example: TransferWise Ltd
        branchName:
          type:
          - string
          - 'null'
          description: Name of the bank branch. Provided only when the currency route requires it (such as JPY).
          example: null
        accountNumber:
          type:
          - string
          - 'null'
          description: Bank account number.
          example: '9910728'
        accountType:
          type:
          - string
          - 'null'
          description: Bank account type. Provided only when the currency route requires it.
          example: null
        bankCode:
          type:
          - string
          - 'null'
          description: Bank identifier or routing number, depending on pay-in type and currency.
          example: '8301'
        bankAddress:
          type:
          - object
          - 'null'
          description: Address for the receiving bank. Provided only when the currency route requires it.
          properties:
            name:
              type: string
              description: Bank name.
              example: CitiBank Europe Plc
            firstLine:
              type: string
              description: Street address.
              example: Bolette brygge 1
            postCode:
              type: string
              description: Postcode or ZIP code.
              example: '0252'
            city:
              type: string
              description: City.
              example: Oslo
            stateCode:
              type:
              - string
              - 'null'
              description: State, province, or region code.
              example: null
            country:
              type: string
              description: Country name.
              example: Norway
        transferWiseAddress:
          type:
          - object
          - 'null'
          description: Wise's address. Provided only when the currency route requires it.
          properties:
            name:
              type: string
              description: Wise's company name.
              example: TransferWise Ltd
            firstLine:
              type: string
              description: Street address.
              example: 6th Floor, The Tea Building, 56 Shoreditch High Street
            postCode:
              type: string
              description: Postcode or ZIP code.
              example: E1 6JJ
            city:
              type: string
              description: City.
              example: London
            stateCode:
              type:
              - string
              - 'null'
              description: State, province, or region code.
              example: null
            country:
              type: string
              description: Country name.
              example: United Kingdom
        iban:
          type:
          - string
          - 'null'
          description: ISO 13616 International Bank Account Number (when available).
          example: null
        bban:
          type:
          - string
          - 'null'
          description: Basic Bank Account Number (BBAN). Provided only when the currency route requires it (such as NOK).
          example: '83019910728'
        institutionNumber:
          type:
          - string
          - 'null'
          description: Financial Institution number (3 digits). Provided only when the currency route requires it (such as CAD).
          example: null
        transitNumber:
          type:
          - string
          - 'null'
          description: Branch Transit Number (5 digits). Provided only when the currency route requires it (such as CAD).
          example: null
        beneficiaryBankBIC:
          type:
          - string
          - 'null'
          description: Beneficiary Bank Business Identifier Code

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wise/refs/heads/main/openapi/wise-batch-group-api-openapi.yml