Send money

Sending money with Wise Platform is a process with four stages. The journey for your customers starts with a quote which indicates the potential cost of the transaction, and the exchange rate.

Once the quote is agreed, and more information about the transaction has been added, you can give an updated, authenticated quote.

To send money:

  1. Create an authenticated quote using POST /quotes - this optional step allows your customer can see how much the transaction is likely to cost, and the exchange rate.
  2. Authenticate the quote. At this stage, you need to use POST /profiles to create an authenticated quote. This quote is more accurate than the unauthenticated quote, and is required to create the transfer itself.
  3. Add a recipient's account details using POST /accounts - the recipient is the party receiving the money being transferred. You receive a recipientId in the response to this request.
  4. Create the transfer using POST /profiles/{{profileId}}/transfers. In this request, you must include:
    • The authenticated quote ID.
    • Recipient account ID.
  5. Fund the transfer using POST /profiles/{{profileId}}/transfers/{{transferId}}/payments once this step is complete the money is sent.

Create an authenticated quote

POST /v3/profiles/{{profileId}}/quotes

Request Fields
profileIdinteger

Personal or business profile ID of the sender - required.

sourceCurrencytext

Source (sending) currency code.

targetCurrencytext

Target (receiving) currency code.

targetAmountdecimal

Amount in target currency.

sourceAmountdecimal

Amount in source currency.
Either sourceAmount or targetAmount is required, never both.

targetAccountinteger

Optional. This is the ID of transfer recipient, found in response from POST v1/accounts (recipient creation). If provided can be used as an alternative to updating the quote.

payOuttext

Optional. Preferred payout method. Default value is BANK_TRANSFER. Other possible values are BALANCE, SWIFT, SWIFT_OUR and INTERAC.

preferredPayIntext

Optional. Preferred payin method. Use BANK_TRANSFER to return this method at the top of the response's results.

paymentMetadataobject

Optional. Used to pass additional metadata about the intended transfer.

paymentMetadata.transferNaturestring

Optional. Used to pass transfer nature for calculating proper tax amounts (IOF) for transfers to and from BRL. Accepted values are shown dynamically in transfer requirements.

pricingConfigurationobject

Required when configured for your client ID. includes a pricingConfiguration to be used for pricing calculations with the quote.

pricingConfiguration.fee.typetext

Identifies the type of fee that will be configured. Options include only OVERRIDE

pricingConfiguration.fee.variabledecimal

The selected variable percentage (in decimal format) that should be used in the pricingConfiguration

pricingConfiguration.fee.fixeddecimal

The selected fixed fee that should be used in the pricingConfiguration. Always considered in source currency.

If you are funding the transfer from a Multi Currency Balance, you must set the payIn as BALANCE to get the correct pricing in the quote. Not doing so will default to BANK_TRANSFER and the fees will be inconsistent between quote and transfer.

Response

The following describes the fields of the quote response that may be useful when building your integration.

The payOut field is used to select the correct entry in the paymentOptions array in order to know which fees to display to your customer. Find the paymentOption that matches the payOut field shown at the top level of the quote resource and payIn based on the settlement model the bank is using. By default, this is BANK_TRANSFER, unless you are using a prefunded or bulk settlement model. The payOut field will change based on the type of recipient you add to the quote in the PATCH /quote call, for example to-USD swift_code or to-CAD interac have different fees.

For example sending USD to a country other than the United States is supported but with different fees to domestic USD transfers. Please see the later section on Global Currencies to learn more about how to offer this useful feature.

For each paymentOption there is a price field. It gives a full breakdown of all the taxes, fees and discounts. It is preferable to refer to this structure to show breakdowns and totals, rather than the fee structure, found as well in each paymentOption element, that only gives a summary and is not able to surface important specifics such as taxes.

When showing the price of a transfer always show the 'price.total.value.amount' of a payment option.

Disabled Payment Options

Each payment option is either enabled or disabled based on the disabled value. Disabled payment options should be shown to the user in a disabled state in most cases. This ensures users are given the options that they are familiar with regardless of their availability, as well as with options that can be beneficial to their accounts.

The option.disabledReason contains both the code and message, with the message being the user-friendly text to surface to the user if necessary.

Transfer Nature for BRL

When creating or updating a quote, the transfer nature can be set. This is a requirement for transfers to or from BRL and impacts the fees we charge on the quote, specifically the IOF.

Note that IOF is determined based on the transfer nature, sender information, and recipient information. The default IOF will be included in a quote until all relevant information has been included.

Pricing Configuration

When creating or updating a quote, partners that have flexible partner pricing enabled are able to override the pricing configuration dynamically.

To learn more on how to use this feature, please see the Flexible Partner Pricing Guide

Example Request
curl -X POST https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/quotes \
     -H 'Authorization: Bearer <your api token>' \
     -H 'Content-Type: application/json' \
     -d '{
              "sourceCurrency": "GBP",
              "targetCurrency": "USD",
              "sourceAmount": 100,
              "targetAmount": null,
              "payOut": null,
              "preferredPayIn": null,
              "targetAccount": 12345,
              "paymentMetadata": {
                  "transferNature": "MOVING_MONEY_BETWEEN_OWN_ACCOUNTS"
              },
              "pricingConfiguration": {
                   "fee": {
                         "type": "OVERRIDE",
                         "variable": 0.011,
                         "fixed": 15.42
                   }
             }
        }'

Create a recipient account

A recipient is a person or institution who is the ultimate beneficiary of your payment.

Recipient data includes three data blocks:

  • General data - the personal details of an individual and basic information about a business.
  • Bank details - account numbers, routing numbers, and other region-specific bank details.
  • Address details - country and street address of an individual or business.

General Data

  • Recipient full name
  • Legal type (private/business)
  • Currency
  • Date of Birth
  • Owned by customer

Date of Birth is optional. Its usually not required, but consult with the /account-requirements APIs to confirm if it is needed, or contact Wise Support.

Owned by customer is an optional boolean to flag to record whether this recipient is the same entity (person or business) as the one sending the funds. i.e. A user sending money to their own bank account in another country/currency. This field can be used to separate these recipients in your UI, however we do not recommend this as it adds unnecessary complexity to the solution. It is safe to ignore this field and display recipients with both true and false values.

Bank account data

There are many different variations of bank account details needed depending on recipient target currency. For example:

  • GBP — sort code and account number
  • BGN, CHF, DKK, EUR, GEL, GBP, NOK, PKR, PLN, RON, SEK — IBAN
  • USD — routing number, account number, account type
  • INR — IFSC code, account number
  • etc.

Address data

Recipient address data is required only if target currency is USD, PHP, THB or TRY, or if the source currency is USD or AUD.

  • Country
  • State (US, Canada, Brazil)
  • City
  • Address line
  • Zip code

When creating recipient, the following general rules should be applied to the accountHolderName field:

  • Full names for personal recipients. They must include more than one name, and both first and last name must have more than one character. Numbers are not allowed in personal recipient names.
  • Business names must be in full, but can be just a single name. The full name cannot be just a single character but can be made up of a set of single characters. e.g. "A" is not permitted but "A 1" or "A1" is permitted.
  • Special characters _()'*,. are allowed for personal and business names.
  • In general the following regex describes our permitted characters for a name: [0-9A-Za-zÀ-ÖØ-öø-ÿ-_()'*,.\s].

Recipient requirements will vary depending on recipient type. A GBP example is provided here.
As you can see many of the fields are null, in order to know which fields are required for which currency we expose the Recipients Requirements endpoint.

Request

POST /v1/accounts

currencytext

3 character currency code

typetext

Recipient type

profileinteger

Personal or business profile ID. It is highly advised to pass the business profile ID in this field if your business account is managed by multiple users, so that the recipient can be accessed by all users authorized on the business account.

accountHolderNametext

Recipient full name

ownedByCustomerboolean

Whether this account is owned by the sending user

detailsobject

Currency specific fields

details.legalTypetext

Recipient legal type: PRIVATE or BUSINESS

details.sortCodetext

Recipient bank sort code (GBP example)

details.accountNumbertext

Recipient bank account no (GBP example)

details.dateOfBirthtext

Optional. Recipient Date of Birth in ISO 8601 date format.

Response

A complete Recipient object is returned when created.

Example Request - GBP Recipient
curl -X POST https://api.sandbox.transferwise.tech/v1/accounts \
     -H 'Authorization: Bearer <your api token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "currency": "GBP",
          "type": "sort_code",
          "profile": 30000000,
          "ownedByCustomer": true,
          "accountHolderName": "John Doe",
           "details": {
              "legalType": "PRIVATE",
              "sortCode": "040075",
              "accountNumber": "37778842",
              "dateOfBirth": "1961-01-01"
           }
         }'

Create a transfer

POST /v1/transfers

Request
sourceAccount (optional)integer

Refund recipient account ID

targetAccountinteger

Recipient account ID. You can create multiple transfers to same recipient account.

quoteUuidtext

V2 quote ID. You can only create one transfer per one quote. You cannot use same quote ID to create multiple transfers.

customerTransactionIduuid

This is required to perform idempotency check to avoid duplicate transfers in case of network failures or timeouts.

details.referencetext

Recipient will see this reference text in their bank statement. Maximum allowed characters depends on the currency route. Business Payments Tips article has a full list.

details.transferPurpose (conditionally required)text

For example when target currency is THB. See more about conditions at Transfers.Requirements

details.transferPurposeSubTransferPurpose (conditionally required)text

For example when target currency is CNY. See more about conditions at Transfers.Requirements

details.transferPurposeInvoiceNumber (conditionally required)text

For example when target currency is INR. See more about conditions at Transfers.Requirements

details.sourceOfFunds (conditionally required)text

For example when target currency is USD and transfer amount exceeds 80k. See more about conditions at Transfers.Requirements

There are options to deal with conditionally required fields:

  • Always call transfer-requirements endpoint and submit values only if indicated so.
  • Always provide values for these fields based on a dynamically retrieved list (transfer-requirements endpoint). It is possible these fields change over time, so take this into account if hard coding the options.

Contact api@wise.com if you have questions about this property.

Response

Returns a standard transfer object.

Avoiding duplicate transfers

We use customerTransactionId field to avoid duplicate transfer requests. If your initial call to create a transfer fails (error or timeout) then you should retry the call using the same value in the customerTransactionId field that you used in the original call. This way we can treat subsequent retry messages as repeat messages and will not create duplicate transfers to your account should one have succeeded before. You should not retry indefinitely but use a sensible limit, perhaps with a back-off approach.

Payment Approvals

If you use personal tokens and do not use client credentials, and if your business account has payment approvals, your application will run in to this error when attempting to create a transfer

Quote cannot be accepted with this request due to missing approval.

Consider removing the payment rule if you are going to use the API to create transfers.

Example Request
curl -X POST https://api.sandbox.transferwise.tech/v1/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 transfer

POST /v3/profiles/{{profileId}}/transfers/{{transferId}}/payments

This API call is the final step for executing payouts when using a balance with Wise. Upon calling the endpoint, Wise will begin the processing of the transfer, depending on the status of funds.

When using the transfer by transfer settlement model, the following funding type(s) must be used:

  • BALANCE - Funds are pulled from a multi-currency account held with Wise.
  • BANK_TRANSFER - Manually send funds from your business bank account to pay for any transfers. Only applicable when using the Batch Group API.

When funding through the Bulk Settlement model, the following funding type(s) must be used:

  • TRUSTED_PRE_FUND_BULK - Funds for the transfer will be settled through a bulk payment at a later date. This method is not applicable to first party Payouts.

If funding from BALANCE, and your multi-currency account does not have the required funds to complete the action, then this call will fail with an "insufficient funds" error. Once funds are added and available, you must call this endpoint again.

{{profileId}} refers to the profile that created the transfer. It can be either your personal profile ID, or your business profile ID.

Request
typetext

"BALANCE"
This indicates the type of funding you would like to apply to the transfer.

partnerReference (conditionally required)string

The transaction/payment identifier in your system, uniquely identifies the transfer in your platform. This is required for the Cross Currency Bulk Settlement model.

Response
typetext

"BALANCE"
This indicates the type of funding you would like to apply to the transfer.

statustext

"COMPLETED" or "REJECTED"

errorCodetext

Failure reason. For example "balance.payment-option-unavailable".

Example Request
curl -X POST https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/transfers/{{transferId}}/payments \
     -H 'Authorization: Bearer <your api token>' \
     -H 'Content-Type: application/json' \
     -d '{
            "type": "BALANCE"
         }'
Example Request - Balance - Completed
{
    "type": "BALANCE",
    "status": "COMPLETED",
    "errorCode": null
}
Example Request - Balance - Insufficient Funds
{
    "type": "BALANCE",
    "status": "REJECTED",
    "errorCode": "transfer.insufficient_funds"
}