Wise bulk-settlement API

openapi: 3.1.0
info:
  title: Wise Platform 3ds bulk-settlement 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: bulk-settlement
  x-displayName: Bulk Settlement
  description: 'Bulk settlement allows partners to settle multiple transfers in a single bank transfer at the end of a settlement period. This model splits transfer creation/funding from final settlement, allowing Wise to process transfers before receiving funds based on a partner''s guarantee.


    Use the settlement journal endpoint to submit a list of transfers to be settled, along with the settlement reference that matches your bank transfer payment.

    '
paths:
  /v1/settlements:
    post:
      tags:
      - bulk-settlement
      summary: Send a settlement journal
      operationId: bulkSettlementJournalCreate
      security:
      - ClientCredentialsToken: []
      description: 'Sends the settlement journal to Wise. There are two types of settlement:


        - **Same Currency Settlement** — Settle in the same currency as the transfers (e.g., settle USD transfers with USD).

        - **Cross Currency Settlement** — Settle in a different currency (e.g., settle PHP transfers with USD). In this case, you must specify `settlementCurrency` and include `exchangeRate` on every transfer.


        {% admonition type="info" %}

        You must use a client credentials token to authenticate this call.

        {% /admonition %}

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              - settlementReference
              - settlementDate
              - transfers
              properties:
                type:
                  type: string
                  description: Type of settlement.
                  enum:
                  - TRUSTED_BULK_SETTLEMENT
                  example: TRUSTED_BULK_SETTLEMENT
                settlementReference:
                  type: string
                  description: 'Reference used when paying the end of day settlement monies to Wise. This should match so that Wise can link the payment.


                    Maximum 10 characters, must start with `TPFB` prefix.

                    '
                  pattern: ^TPFB.{1,6}$
                  example: TPFB190322
                settlementDate:
                  type: string
                  format: date-time
                  description: The date you send the settlement funds, ISO 8601 format.
                  example: '2019-03-22T23:59:59-05:00'
                settlementCurrency:
                  type: string
                  description: 'The currency in which the transfers in this journal will be settled. If included, the `exchangeRate` must be set on every transfer in the transfers array.

                    **Only include if you will settle in a currency different to the source currency of transfers.**

                    '
                  example: USD
                transfers:
                  type: array
                  description: Array of transfers to be settled.
                  items:
                    type: object
                    required:
                    - id
                    - date
                    - sourceAmount
                    - sourceCurrency
                    - customerName
                    - partnerReference
                    properties:
                      id:
                        type: integer
                        format: int64
                        description: ID of the transfer to be settled.
                        example: 125678
                      date:
                        type: string
                        format: date-time
                        description: The date the transfer was created, ISO 8601 format.
                        example: '2019-03-22T10:00:12-05:00'
                      sourceAmount:
                        type: number
                        format: decimal
                        description: Transfer source amount with fee, always positive.
                        example: 23.24
                      sourceCurrency:
                        type: string
                        description: Transfer source currency (ISO 4217).
                        example: USD
                      customerName:
                        type: string
                        description: Name of the customer. Helps identify customer when manual operation is required.
                        example: Joe Bloggs
                      partnerReference:
                        type: string
                        description: The transaction/payment identifier in your system, uniquely identifies the transfer in your platform.
                        example: '11111'
                      comment:
                        type: string
                        description: 'Other data about the transfer or sender.


                          For USA, you should send the account refund information for the sending customer (account number, routing number, street address, etc.)

                          '
                        example: Extra Data
                      exchangeRate:
                        type: number
                        format: decimal
                        description: 'The exchange rate you used to calculate the settlement amount for this transfer.


                          **Required if `settlementCurrency` is set on the journal.** You can set this value to be unique per transfer or the same for every transfer, depending on your settlement approach and agreements with Wise.

                          '
                        example: 0.875469
                refundedTransfers:
                  type: array
                  description: Array of transfers for which refunds have been processed. Only for Net Settlement.
                  items:
                    type: object
                    required:
                    - id
                    - partnerReference
                    properties:
                      id:
                        type: integer
                        format: int64
                        description: ID of the refunded transfer.
                        example: 178880
                      exchangeRate:
                        type: number
                        format: decimal
                        description: The exchange rate used for this transfer. Should be the same value as the one used for the original transfer settlement.
                        example: 0.875469
                      partnerReference:
                        type: string
                        description: The transaction/payment identifier in your system, uniquely identifies the transfer in your platform.
                        example: '11108'
                balanceTransfer:
                  type: number
                  format: decimal
                  description: 'The amount of money to be deducted from the expected settlement amount based on what is owed to you for previous days where the total settlement from you to Wise was negative.


                    This value must be 0 or negative.

                    '
                  example: 0
            examples:
              sameCurrency:
                summary: Same Currency Settlement
                value:
                  type: TRUSTED_BULK_SETTLEMENT
                  settlementReference: TPFB190322
                  settlementDate: '2019-03-22T23:59:59-05:00'
                  transfers:
                  - id: 125678
                    date: '2019-03-22T10:00:12-05:00'
                    sourceAmount: 23.24
                    sourceCurrency: USD
                    customerName: Joe Bloggs
                    partnerReference: '11111'
                    comment: Extra Data
                  - id: 178889
                    date: '2019-03-23T12:40:05-05:00'
                    sourceAmount: 125.67
                    sourceCurrency: USD
                    customerName: Mat Newman
                    partnerReference: '11112'
                    comment: Extra Data
                  refundedTransfers:
                  - id: 178880
                    partnerReference: '11108'
                  balanceTransfer: 0
              crossCurrency:
                summary: Cross Currency Settlement
                value:
                  type: TRUSTED_BULK_SETTLEMENT
                  settlementReference: TPFB190322
                  settlementDate: '2019-03-22T23:59:59-05:00'
                  settlementCurrency: USD
                  transfers:
                  - id: 125678
                    date: '2019-03-22T10:00:12-05:00'
                    sourceAmount: 23.24
                    sourceCurrency: PHP
                    customerName: Joe Bloggs
                    partnerReference: '11111'
                    comment: Extra Data
                    exchangeRate: 0.875469
                  - id: 178889
                    date: '2019-03-23T12:40:05-05:00'
                    sourceAmount: 125.67
                    sourceCurrency: PHP
                    customerName: Mat Newman
                    partnerReference: '11112'
                    comment: Extra Data
                    exchangeRate: 0.875469
                  refundedTransfers:
                  - id: 178880
                    partnerReference: '11108'
                  - id: 178881
                    partnerReference: '11109'
                  balanceTransfer: 0
      responses:
        '200':
          description: Settlement journal received successfully. Empty response body.
          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'
      parameters:
      - $ref: '#/components/parameters/X-External-Correlation-Id'
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
  responses:
    '429':
      x-global: true
      description: Rate limit exceeded. Retry after the number of seconds specified in the `Retry-After` header.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
          example: 5
        X-Rate-Limited-By:
          description: Identifies the rate limiter that triggered the 429 response.
          schema:
            type: string
          example: wise-public-api
        X-External-Correlation-Id:
          $ref: '#/components/headers/X-External-Correlation-Id'
        x-trace-id:
          $ref: '#/components/headers/x-trace-id'
      content:
        application/json:
          schema:
            type: object
  headers:
    X-External-Correlation-Id:
      x-global: true
      description: Echoed back when `X-External-Correlation-Id` was included in the request. [Learn more](/guides/developer/headers/correlation-id).
      schema:
        type: string
        format: uuid
        maxLength: 36
      example: f47ac10b-58cc-4372-a567-0e02b2c3d479
    x-trace-id:
      x-global: true
      description: Unique trace identifier assigned by Wise. Useful when contacting support about a specific request.
      schema:
        type: string
      example: fba501b6d453b96789f52338f019341f
  securitySchemes:
    UserToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'User Access Token for making API calls on behalf of a Wise user.


        Can be obtained via two OAuth 2.0 flows:

        - **registration_code grant**: For partners creating users via API

        - **authorization_code grant**: For partners using Wise''s authorization page


        Access tokens are valid for 12 hours and can be refreshed using a refresh token.

        '
    PersonalToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Personal API Token for individual personal or small business users.

        Generated from Wise.com > Settings > Connect and manage apps > API tokens.

        Has limited API access compared to OAuth tokens (PSD2 restrictions apply for EU/UK users).

        '
    ClientCredentialsToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Application-level token for partner operations that don''t require a specific user context, such as bulk settlement and card spend controls.


        Obtained via `POST /oauth/token` with Basic Authentication (client-id:client-secret) and `grant_type=client_credentials`.


        Valid for 12 hours. No refresh token — fetch a new token when expired.


        See [create an OAuth token](/api-reference/oauth-token/oauthtokencreate) for details.

        '
    BasicAuth:
      type: http
      scheme: basic
      description: 'Basic Authentication using your Client ID and Client Secret as the username and password.


        Client credentials are provided by Wise when your partnership begins. See [Getting Started](/guides/developer) for details.

        '
x-tagGroups:
- name: Authentication
  tags:
  - oauth-token
- name: Enhanced Security
  tags:
  - jose
- name: Users
  tags:
  - user
  - claim-account
- name: Profiles
  tags:
  - profile
  - activity
  - address
- name: Verification
  tags:
  - kyc-review
  - verification
  - facetec
- name: Strong Customer Authentication
  tags:
  - sca-ott
  - sca-sessions
  - sca-pin
  - sca-facemaps
  - sca-device-fingerprints
  - sca-otp
  - user-security
- name: Balances
  tags:
  - balance
  - balance-statement
  - bank-account-details
  - multi-currency-account
- name: Cards
  tags:
  - card
  - card-sensitive-details
  - 3ds
  - card-kiosk-collection
  - card-order
  - card-transaction
  - spend-limits
  - spend-controls
  - digital-wallet
  - disputes
- name: Quotes
  tags:
  - quote
  - rate
  - comparison
- name: Recipients
  tags:
  - recipient
  - contact
- name: Transfers
  tags:
  - transfer
  - delivery-estimate
  - currencies
  - batch-group
- name: Funding
  tags:
  - payin-deposit-detail
  - direct-debit-account
  - bulk-settlement
  - payins
- name: Webhooks
  tags:
  - webhook
  - webhook-event
- name: Simulations
  tags:
  - simulation
- name: Partner Support
  tags:
  - case