Transfer
A transfer is a payment order to recipient account based on a quote.
Once created, a transfer needs to be funded within the next five working days. Otherwise, it will be automatically canceled.
The Transfer resource
Transfer id
Your user id
Recipient account id
Refund recipient account id
v1 quote id (where applicable)
v2 quote id
Transfer current status
Deprecated, use details.reference instead
Exchange rate value
Timestamp when transfer was created
Your business profile id
Not used
Payment reference text
Are there any pending issues which stop executing the transfer?
Source currency code
Transfer amount in source currency
Target currency code
Transfer amount in target currency
Unique identifier randomly generated per transfer request by the calling client
Data block to capture payment originator details
Payment originator legal type.
Unique customer id in your system.
Payment originator first name.
Payment originator middle name(s).
Payment originator family name.
Payment originator patronymic name.
Payment originator full legal name.
Payment originator date of birth.
Payment originator business registry number / incorporation number.
Payment originator address first line.
Payment originator address city.
Payment originator address state code.
Payment originator address first line.
Originator address zip code.
{"id": 16521632,"user": 4342275,"targetAccount": 8692237,"sourceAccount": null,"quote": 657171,"status": "cancelled","reference": "reference text","rate": 0.89,"created": "2017-11-24 10:47:49","business": null,"transferRequest": null,"details": {"reference": "Testing"},"hasActiveIssues": false,"sourceCurrency": "EUR","sourceValue": 0,"targetCurrency": "GBP","targetValue": 150,"customerTransactionId": "54a6bc09-cef9-49a8-9041-f1f0c654cd88"}
{"id": 16521632,"user": 4342275,"targetAccount": 8692237,"sourceAccount": null,"quote": 657171,"status": "cancelled","reference": "reference text","rate": 0.89,"created": "2017-11-24 10:47:49","business": null,"transferRequest": null,"details": {"reference": "Testing"},"originator": {"name": {"givenName": "John","middleNames": ["Ryan"],"familyName": "Godspeed","patronymicName": null,"fullName": "John Godspeed"},"dateOfBirth": "1977-07-01","reference": "CST-2991992","legalEntityType": "PRIVATE","businessRegistrationCode": null,"address": {"firstLine": "Salu tee 14","city": "Tallinn","stateCode": null,"countryCode": "EE","postCode": "12112"}},"hasActiveIssues": false,"sourceCurrency": "EUR","sourceValue": 0,"targetCurrency": "GBP","targetValue": 150,"customerTransactionId": "54a6bc09-cef9-49a8-9041-f1f0c654cd88"}
Create a transfer
POST /v1/transfers
Refund recipient account id
Recipient account id. You can create multiple transfers to same recipient account.
V2 quote id. You can only create one transfer per one quote.
You cannot use same quote ID to create multiple transfers.
This is required to perform idempotency check to avoid duplicate transfers in case of network failures or timeouts.
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.
For example when target currency is THB. See more about conditions at Transfers.Requirements
For example when target currency is CNY. See more about conditions at Transfers.Requirements
For example when target currency is USD and transfer amount exceeds 80k. See more about conditions at Transfers.Requirements
There are two options to deal with conditionally required fields:
- Always call
transfer-requirementsendpoint and submit values only if indicated so. - Always provide values for these fields based on a hard coded list. It is possible these fields change over time so hard coding the options does create some risk of issues.
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.
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"}}'
Create a third party transfer
POST /v2/profiles/{{profileId}}/third-party-transfers
This is very similar to Create transfers endpoint, but please note these differences:
- originator datablock is additionally required
- originalTransferId field is being used instead of customerTransactionId
Recipient account id. You can create multiple transfers to same recipient account.
V2 quote id. You can only create one transfer per one quote.
You cannot use same quote ID to create multiple transfers.
Unique transfer id in your system. We use this field also to perform idempotency check to avoid duplicate transfers in case of network failures or timeouts. You can only submit one transfer with same originalTransferId.
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.
Data block to capture payment originator details.
PRIVATE or BUSINESS. Payment originator legal type.
Unique customer id in your system. This allows us to uniquely identify each originator. Required.
Payment originator first name. Required if legalEntityType = PRIVATE.
Payment originator middle name(s). Used only if legalEntityType = PRIVATE. Optional
Payment originator family name. Required if legalEntityType = PRIVATE.
Payment originator patronymic name. Used only if legalEntityType = PRIVATE. Optional
Payment originator full legal name. Required if legalEntityType = BUSINESS.
Payment originator date of birth. Required if legalEntityType = PRIVATE.
Payment originator business registry number / incorporation number. Required if legalEntityType = BUSINESS.
Payment originator address first line. Required
Payment originator address city. Required
Payment originator address state code. Required if address country code in (US, CA, BR, AU). See Countries and states
Payment originator address first line. Required
Originator address zip code. Optional
Response
Returns an originator transfer object.
You need to save the transfer id for tracking its status later via webhooks.
Avoiding duplicate transfers
We use originalTransferId field to avoid duplicate transfer requests. When your first call fails (error or timeout) then you should use the same value in originalTransferId field that you used in the original call when you are submitting a retry message. This way we can treat subsequent retry messages as repeat messages and will not create duplicate transfers to your account.
curl -X POST https://api.sandbox.transferwise.tech/v2/profiles/{{profileId}}/third-party-transfers \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \-d '{"targetAccount": <recipient account id>,"quote": "<quote id>","originalTransferId": "<unique transfer id in your system>","details" : {"reference" : "Ski trip"},"originator" : {"legalEntityType" : "PRIVATE","reference" : "<unique customer id in your system>","name" : {"givenName": "John","middleNames": ["Ryan"],"familyName": "Godspeed"},"dateOfBirth": "1977-07-01","address" : {"firstLine": "Salu tee 100, Apt 4B","city": "Tallinn","countryCode": "EE","postCode": "12112"}}}'
curl -X POST https://api.sandbox.transferwise.tech/v2/profiles/{{profileId}}/third-party-transfers \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \-d '{"targetAccount": <recipient account id>,"quote": "<quote id>","originalTransferId": "<unique transfer id in your system>","details" : {"reference" : "Payment for invoice 22092"},"originator" : {"legalEntityType" : "BUSINESS","reference" : "<originator customer id in your system>","name" : {"fullName": "Hot Air Balloon Services Ltd"},"businessRegistrationCode": "1999212","address" : {"firstLine": "Aiandi tee 1431","city": "Tallinn","countryCode": "EE","postCode": "12112"}}}'
Create a partner license transfer
POST /v1/profiles/{{profileId}}/partner-licence-transfers
This is very similar to Create transfers endpoint, but please note these differences:
- originator datablock is additionally required
Refund recipient account id.
Recipient account id. You can create multiple transfers to same recipient account.
V2 quote id. You can only create one transfer per one quote.
You cannot use same quote ID to create multiple transfers.
Unique transfer id in your system. We use this field also to perform idempotency check to avoid duplicate transfers in case of network failures or timeouts. You can only submit one transfer with same customerTransactionId.
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.
Data block to capture payment originator details.
PRIVATE or BUSINESS. Payment originator legal type.
Unique customer id in your system. This allows us to uniquely identify each originator. Required.
Payment originator first name. Required if legalEntityType = PRIVATE.
Payment originator middle name(s). Used only if legalEntityType = PRIVATE. Optional
Payment originator family name. Required if legalEntityType = PRIVATE.
Payment originator patronymic name. Used only if legalEntityType = PRIVATE. Optional
Payment originator full legal name. Required if legalEntityType = BUSINESS.
Payment originator date of birth. Required if legalEntityType = PRIVATE.
Payment originator business registry number / incorporation number. Required if legalEntityType = BUSINESS.
Payment originator address first line. Required
Payment originator address city. Required
Payment originator address state code. Required if address country code in (US, CA, BR, AU). See Countries and states
Payment originator address first line. Required
Originator address zip code. Optional
Response
Returns an originator transfer object.
You need to save the transfer id for tracking its status later via webhooks.
Avoiding duplicate transfers
We use customerTransactionId field to avoid duplicate transfer requests. When your first call fails (error or timeout) then you should use the same value in customerTransactionId field that you used in the original call when you are submitting a retry message. This way we can treat subsequent retry messages as repeat messages and will not create duplicate transfers to your account.
curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/partner-licence-transfers \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \-d '{"sourceAccount": <refund recipient account id>,"targetAccount": <recipient account id>,"quote": "<quote id>","customerTransactionId": "<unique transfer id in your system>","details" : {"reference" : "Ski trip"},"originator" : {"legalEntityType" : "PRIVATE","reference" : "<unique customer id in your system>","name" : {"givenName": "John","middleNames": ["Ryan"],"familyName": "Godspeed"},"dateOfBirth": "1977-07-01","address" : {"firstLine": "Salu tee 100, Apt 4B","city": "Tallinn","countryCode": "EE","postCode": "12112"}}}'
curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/partner-licence-transfers \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \-d '{"sourceAccount": <refund recipient account id>,"targetAccount": <recipient account id>,"quote": "<quote id>","customerTransactionId": "<unique transfer id in your system>","details" : {"reference" : "Payment for invoice 22092"},"originator" : {"legalEntityType" : "BUSINESS","reference" : "<originator customer id in your system>","name" : {"fullName": "Hot Air Balloon Services Ltd"},"businessRegistrationCode": "1999212","address" : {"firstLine": "Aiandi tee 1431","city": "Tallinn","countryCode": "EE","postCode": "12112"}}}'
Requesting transfer requirements
POST /v1/transfer-requirements
Almost every region has its own specific nuances when it comes to the nitty gritty details of domestic payment systems and money transfer regulations. The maximum allowed length of reference text is a good example. The US payment system, ACH, supports 10 characters only, but transfers within Mexico allow up to 100 characters, and so on.
The same is true for requirements arising from Anti Money Laundering regulations adopted in different countries. Depending on the chosen currencies and the amount to be transferred, either in one go or cumulatively over time, Wise may require more details about the customer's source of funds or transfer purpose, for example.
The endpoint /transfer-requirements exposes all these specific requirements based on the sender, the specific quote and selected target recipient account.
To make sure that processing of your customer's transfers does not get delayed because of missing details, we highly recommend to verify the transfer requirements before submitting any transfer and collecting the data we request from the user using the returned dynamic form.
Transfer Requirement Options
reference - General reference or memo field for a transfer. Always Optional. It is important to use the minLength and maxLength in your interface to minimize errors.
transferPurpose - A select list of values to help understand the purpose of the transfer. Often required when transfers are over a certain size or through a particular route. As an option is selected, you must refresh requirements, as additional fields could become required.
transferPurposeSubTransferPurpose - A secondary select list of values to further help understand the purpose of the transfer. As an option is selected, you must refresh requirements, as additional fields could become required.
sourceOfFunds - A select list of values to help understand the source of the funds. As an option is selected, you must refresh requirements, as additional fields could become required.
transferNature - A select list of values to help understand the reason for the transfer, specifically for routes to and from BRL. Note that transfer nature needs to be added to a quote through creation or update in order to correctly calculate the IOF tax.
Request
Prepare the request body to create transfer object first. Now post this request body to the
transfer-requirementsendpoint to figure out if there are any other required fields.Analyze the returned list of fields. Our example includes reference, sourceOfFunds and transferPurpose fields. Field 'reference' is optional. Fields 'sourceOfFunds' and 'transferPurpose' are required and both have refreshRequirementsOnChange=true which indicates that there could be additional fields required depending on the selected value.
In our example you will have to POST request to/v1/transfer-requirements` second time as well with values set for 'transferPurpose' and 'sourceOfFunds'. So in case you set sourceOfFunds = 'verification.source.of.funds.other' then another text field called "sourceOfFundsOther" is also required where you need to specify the details in free format.
Once you get to the point where you have provided values for all fields which have refreshRequirementsOnChange=true then you have complete set of fields to compose a valid request to create a transfer object. For example this is a valid request to create a transfer.
"transfer"
Field description
Key is name of the field you should include in the JSON
Field description
Display type of field (e.g. text, select, etc)
Tells you whether you should call POST transfer-requirements once the field value is set to discover required lower level fields.
Indicates if the field is mandatory or not
Display format pattern.
Example value.
Min valid length of field value.
Max valid length of field value.
Regexp validation pattern.
Validator URL and parameter name you should use when submitting the value for validation
List of allowed values. Value key
List of allowed values. Value name.
curl -X POST https://api.sandbox.transferwise.tech/v1/transfer-requirements \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \-d '{"targetAccount": <recipient account id>,"quoteUuid": <quote id>,"details": {"reference": "good times","sourceOfFunds": "verification.source.of.funds.other","sourceOfFundsOther": "Trust funds"},"customerTransactionId": "6D9188CF-FA59-44C3-87A2-4506CE9C1EA3"}'
[{"type": "transfer","fields": [{"name": "Transfer reference","group": [{"key": "reference","name": "Transfer reference","type": "text","refreshRequirementsOnChange": false,"required": false,"displayFormat": null,"example": null,"minLength": null,"maxLength": 10,"validationRegexp": null,"validationAsync": null,"valuesAllowed": null}]},{"name": "Transfer purpose","group": [{"key": "transferPurpose","name": "Transfer purpose","type": "select","refreshRequirementsOnChange": true,"required": true,"displayFormat": null,"example": null,"minLength": null,"maxLength": null,"validationRegexp": null,"validationAsync": null,"valuesAllowed": [{"key": "verification.transfers.purpose.purchase.property","name": "Buying property abroad"},{"key": "verification.transfers.purpose.pay.bills","name": "Rent or other property expenses"},{"key": "verification.transfers.purpose.mortgage","name": "Mortgage payment"},{"key": "verification.transfers.purpose.pay.tuition","name": "Tuition fees or studying expenses"},{"key": "verification.transfers.purpose.send.to.family","name": "Sending money home to family"},{"key": "verification.transfers.purpose.living.expenses","name": "General monthly living expenses"},{"key": "verification.transfers.purpose.other","name": "Other"}]},{"key": "transferPurposeSubTransferPurpose","name": "Please select a specific reason for your transfer","type": "select","refreshRequirementsOnChange": true,"required": true,"displayFormat": null,"example": null,"minLength": null,"maxLength": null,"validationRegexp": null,"validationAsync": null,"valuesAllowed": [{"key": "INTERPRETATION_SERVICE","name": "Interpretation service"},{"key": "TRANSLATION_SERVICE","name": "Translation service"},{"key": "HUMAN_RESOURCE_SERVICE","name": "Human resource service"},{"key": "ESTATE_AGENCY_SERVICE","name": "Estate agency service"},{"key": "SOFTWARE_DEVELOPMENT_SERVICE","name": "Software development service"},{"key": "WEB_DESIGN_OR_DEVELOPMENT_SERVICE","name": "Web design or development service"},{"key": "DRAFTING_LEGAL_SERVICE","name": "Drafting legal service"},{"key": "LEGAL_RELATED_CERTIFICATION_SERVICE","name": "Legal related certification service"},{"key": "ACCOUNTING_SERVICE","name": "Accounting service"},{"key": "TAX_SERVICE","name": "Tax service"},{"key": "ARCHITECTURAL_DECORATION_DESIGN_SERVICE","name": "Architectural decoration design service"},{"key": "ADVERTISING_SERVICE","name": "Advertising service"},{"key": "MARKET_RESEARCH_SERVICE","name": "Market research service"},{"key": "EXHIBITION_BOOTH_SERVICE","name": "Exhibition booth service"}]}]},{"name": "Source of funds","group": [{"key": "sourceOfFunds","name": "Source of funds","type": "select","refreshRequirementsOnChange": true,"required": true,"displayFormat": null,"example": null,"minLength": null,"maxLength": null,"validationRegexp": null,"validationAsync": null,"valuesAllowed": [{"key": "verification.source.of.funds.salary","name": "Salary"},{"key": "verification.source.of.funds.investment","name": "Investments (stocks, properties, etc.)"},{"key": "verification.source.of.funds.inheritance","name": "Inheritance"},{"key": "verification.source.of.funds.loan","name": "Loan"},{"key": "verification.source.of.funds.other","name": "Other"}]}]}]}]
Get a transfer by Id
GET /v1/transfers/{{transferId}}
Get transfer info by id. To receive dynamic updates as the state of the transfer changes, please see our documentation on webhooks.
Response
Returns a transfer object, with or without an originator block depending on the type of transfer.
curl -X GET https://api.sandbox.transferwise.tech/v1/transfers/{{transferId}} \-H 'Authorization: Bearer <your api token>'
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.
There is currently one type of funding that can be completed:
- BALANCE - Funds are pulled from a multi-currency account held with Wise.
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.
"BALANCE"
This indicates the type of funding you would like to apply to the transfer.
"BALANCE"
This indicates the type of funding you would like to apply to the transfer.
"COMPLETED" or "REJECTED"
Failure reason. For example "balance.payment-option-unavailable"
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"}'
{"type": "BALANCE","status": "COMPLETED","errorCode": null}
{"type": "BALANCE","status": "REJECTED","errorCode": "transfer.insufficient_funds"}
List transfers for a profile
GET /v1/transfers
Get the list of transfers for given user's profile (defaults to user's personal profile).
You can add query parameters to specify user's profile (personal or business), time period and/or payment status.
For example, you can query:
- all failed payments created since last week
- all completed payments created since yesterday
User profile id. If parameter is omitted, defaults to user's personal profile
Status code or codes list (as comma separated value list) to filter returned transfers with. See Track transfer status for complete list of statuses.
Source currency code
Target currency code
Starting date to filter transfers, inclusive of the provided date.
Ending date to filter transfers, inclusive of the provided date.
Maximum number of records to be returned in response
Starting record number
Response
Returns an array of transfer objects, with or without an originator block depending on the type of each transfer.
curl -X GET https://api.sandbox.transferwise.tech/v1/transfers?profile={{profileId}}&status=funds_refunded&offset=0&limit=100&createdDateStart=2018-12-15&createdDateEnd=2018-12-30 \-H 'Authorization: Bearer <your api token>'
Cancel a transfer
PUT /v1/transfers/{{transferId}}/cancel
Only transfers which are not funded can be cancelled. Cancellation is final - it can not be undone.
Response
Returns a transfer object, with or without an originator block depending on the type of the transfer.
curl -X PUT https://api.sandbox.transferwise.tech/v1/transfers/{{transferId}}/cancel \-H 'Authorization: Bearer <your api token>'
Get a transfer receipt in PDF format
GET /v1/transfers/{{transferId}}/receipt.pdf
Download transfer confirmation receipt in PDF format for transfers that are in status outgoing_payment_sent.
Response
Transfer confirmation receipt in Wise branded PDF format.
curl -X GET https://api.sandbox.transferwise.tech/v1/transfers/{{transferId}}/receipt.pdf \-H 'Authorization: Bearer <your api token>'
Get payout information
To utilize this endpoint, you will need to replace transferID with the specific transfer's unique identifier. The transfer endpoint will return the details of the transfer, including the processorName, deliveryMode, bankingPartnerReference, bankingPartnerName, and mt103. This information will enable your recipients to track the transfer with their bank. It may take up to 3 days to get the correct information through this endpoint, as some partners don't share the information until 3 days later.
/v1/transfers/{{transferID}}/invoices/bankingpartner
Fetch banking reference information for transfers that are in outgoing_payment_sent status, enabling you to track transfers with the transfer recipient’s bank.
The unique identifier of the transfer.
Response
The legal entity that processed the transfer on behalf of the customer.
The delivery mode for the payment (e.g., SWIFT).
The reference used by the partner bank to identify and track the transfer.
The name of the sending bank to the recipient's bank.
The MT103 of the transfer, if available.
curl -X GET https://api.sandbox.transferwise.tech//v1/transfers/{{transferID}}/invoices/bankingpartner \-H 'Authorization: Bearer <your api token>'
{"processorName": "Acme Bank Ltd.","deliveryMode": "SWIFT","bankingPartnerReference": "ABCD1234","bankingPartnerName": "Global Bank Corp.""mt103": "{1:F01XXXXGBXXAXXX0000000000}{2:I103XXXXGBXXXXXXN}{3:{108:1234567}{111:001}{121:00000000-0000-0000-0000-000000000000}}{4:\n:20:1234567\n:23B:CRED\n:32A:221212USD12345,\n:33B:USD12345,\n:50K:/11111111\nSOME COMPANY INC.\n1 SOME STREET MIAMI 33132 US\n:59:/GB00000000000000\nCOMPANY NAME LTD\nUK LONDON 1234 GB\n:70:REFERENCE\n:71A:OUR\n:71G:USD11,\n-}\n"}