Guides • Build Banking Apps
Work with draft payments
doc

Work with draft payments

Review the important considerations when you build your draft payments integration.

International payments

In the CSV file that you upload to create draft payments, the following fields and multiple address fields are provided for draft payments made to bank accounts across the globe.

  • Account Number
  • Sort Code or Routing Number
  • IBAN
  • BIC
  • Currency
  • Country

For each draft payment, the following fields are required:

  • Name
  • Recipient type
  • Recipient bank country
  • Currency
  • Amount
  • Payment reference

However, depending on the currency and the country of the bank account, some fields are also required for a draft payment in the CSV file, which is shown in the following table:

CountryCurrencyFields Required
GBGBPAccount Number, SortCode
SEPA CountryEURIBAN, BIC
DK, NO, SELocal currency (DKK, NOK, SEK)IBAN, BIC
IBAN CountryAny supported (with exception of Euros in SEPA)IBAN, BIC, Address
USUSDAccount number, Routing number, Address, State or province
USAny supported (with exception of USD)Account number, BIC, Address, State or province
HKAny supportedAccount number, BIC, Address
PHAny supported + PHPAccount number, BIC, Address
IDAny supported + IDRAccount number, BIC, Address

See the following lists for IBAN/SEPA countries and currencies supported.

tip

To use our draft payments endpoint in any countries/currencies not listed below, reach out and we can look to incorporate your request.

TypeList
SEPA countriesAT, BE, BG, CH, CZ, DE, DK, EE, ES, FI, FR, GB, GF, GR, HR, HU, IE, IS, IT, LT, LU, LV, MQ, NL, NO, PL, PM, PT, RO, SE, SI, SK, SM, TF, VA, YT
IBAN countriesAD, AE, AL, AO, AT, BA, BE, BG, BH, CH, CR, CY, CZ, DE, DK, DO, DZ, EE, ES, FI, FO, FR, GB, GE, GF, GI, GL, GR, HR, HU, IE, IL, IS, IT, JO, KW, KZ, LB, LI, LT, LU, LV, MC, MD, ME, MG, MK, MQ, MR, MT, MU, NL, NO, PK, PL, PM, PS, PT, QA, RO, RS, SA, SE, SI, SK, SM, TF, TN, TR, VA, VG, YT
Currencies supportedAED, AUD, BGN, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HRK, HUF, ILS, JPY, MXN, NOK, NZD, PLN, QAR, RON, SAR, SEK, SGD, THB, TRY, USD, ZAR
note

Address is defined as Country, Address line 1, City and Postcode fields. It should be the address of the recipient.

PHP and IDR transfers are only supported within the Philippines and Indonesia respectively.

Account selection

In Revolut Business, an account can have multiple pockets in different currencies.

The pocket selected for a draft payment is the pocket with the highest amount of currency that matches the currency of the payment.

If no pocket matches the currency of the payment, the pocket with the default currency of the account is chosen and there is an automatic currency conversion while the payment is being executed.

CSV validation

CSV with errors:

Name,Recipient type,Account number,Sort code or Routing number,IBAN,BIC,Recipient bank country,Currency,Amount,Payment reference,Recipient country,State or province,Address line 1,Address line 2,City,Postal code
Dmitry Vim,INDIVIDUAL,40513598,207409,,,GB,GBP,10,Comment Comment Comment Comment Comment Comment Comment Comment Comment Comment Comment Comment Comment Comment,GB,,Revolutest LTD, Level 39,Somewhere in London,E14 5AB
Dmitry Vim,INDIVIDUAL,40513598,207409,,,GB,abc,25,Second comment,uk,,Revolutest LTD, Level 39,Somewhere in London,E14 5AB
,INDIVIDUAL,,,,,GB,GBP,25,Second comment,GB,,Revolutest LTD Level 39,Somewhere in London,Taumatawhakatangihangakoauauotamateaturipukakapikimaungahoronukupokaiwhenuakitanatahu,E14 5AB
Dmitry Vim,INDIVIDUAL,776644,,,BOFMHKHH,CN,USD,10,User comment,CN,,1 Yuan,,Beijing City,100046
Dmitry Vim,,40513598,207409,,,GB,GBP,0.10,User comment,GB,,Revolutest LTD, Level 39,Somewhere in London,E14 5AB
Dmitry Vim,INDIVIDUA,40513598,207409,,,GB,GBP,10,User comment,GB,,Revolutest LTD, Level 39,Somewhere in London,E14 5AB
Dmitry Vim,INDIVIDUAL,ÓŁ,2409,1234,ABC,GB,GBP,10,User comment,GB,,Revolutest LTD, Level 39,Somewhere in London,E14 5AB
DmitryVim,INDIVIDUAL,40513598,207409,,,GB,GBP,10,User comment,GB,,,Somewhere in London,123
Dmitry Vim,INDIVIDUAL,40513598,207409,,,GB,GBP,10,User comment,GB,,Revolutest LTD, Level 39,Somewhere in London,123

Response:

{
"Id": "a3805a6c-ae21-4871-b9a3-2c2c9db60ffa",
"Message": "File validation failed",
"Errors": [{
"Row": 2,
"Errors": [{
"Field": "Payment reference",
"Code": 2003,
"Message": "Payment reference cannot be longer than 100 symbols"
}]
}, {
"Row": 3,
"Errors": [{
"Field": "Currency",
"Code": 2004,
"Message": "Invalid Currency: abc"
}, {
"Field": "Recipient country",
"Code": 2004,
"Message": "Invalid Recipient country: uk"
}]
}, {
"Row": 4,
"Errors": [{
"Field": "Name",
"Code": 2001,
"Message": "Name is required"
}, {
"Field": "City",
"Code": 2003,
"Message": "City cannot be longer than 50 symbols"
}]
}, {
"Row": 5,
"Errors": [{
"Code": 2008,
"Message": "Invalid BIC for CN bank country"
}]
}, {
"Row": 6,
"Errors": [{
"Field": "Recipient type",
"Code": 2001,
"Message": "Recipient type is required"
}]
}, {
"Row": 7,
"Errors": [{
"Field": "Recipient type",
"Code": 2004,
"Message": "Invalid Recipient type: INDIVIDUA"
}]
}, {
"Row": 8,
"Errors": [{
"Field": "Account number",
"Code": 2004,
"Message": "Invalid Account number: �?"
}, {
"Field": "Sort code or Routing number",
"Code": 2004,
"Message": "Invalid Sort code or Routing number: 2409"
}, {
"Field": "IBAN",
"Code": 2004,
"Message": "Invalid IBAN: 1234"
}, {
"Field": "BIC",
"Code": 2004,
"Message": "Invalid BIC: ABC"
}]
}, {
"Row": 9,
"Errors": [{
"Field": "Name",
"Code": 2005,
"Message": "First and last name are required for individuals"
}]
}, {
"Row": 10,
"Errors": [{
"Code": 2008,
"Message": "Postcode 123 is invalid, please change it before continuing"
}]
}],
"Code": 3039
}

We validate if the fields in the CSV match the format required and if the bank account details provided are valid for a payment to be made.

If there is an issue with the CSV uploaded, the API responds with a 3039 error code and give details of the CSV validation errors row by row. Each error message is accompanied by a corresponding code.

In addition, with the exception of error codes 2008 and 1000, we will also pass the relevant Field that causes the validation to fail.

Error codes

Check the example file above and the response with relevant errors.

CodeReasonSample error messages
2001The fields that are required are missing in the CSV.Name is required , Recipient type is required.
2002The amount field is not a valid decimal number.Invalid amount format: 0;10, use only numbers and dot to separate cents, Invalid amount format: A, use only numbers and dot to separate cents.
2003The string size is too large.Name cannot be longer than 80 symbols, City cannot be longer than 50 symbols.
2004One of the fields in the CSV is invalid.Invalid Recipient type: INDIVIDUA, Invalid IBAN: 1234, Invalid Recipient country: uk.
2005The first and last name is required when recipient type is INDVIDUAL.First and last name are required for individuals
2008It was not possible to create counterparty based on the details provided。Invalid BIC for <some_country> bank country, Unsupported currency for external beneficiary, Postcode <postcode> is invalid, please change it before continuing.
2009Payments must be greater than 0.Amount has to be greater than zero.
4025Routing number must be valid for US payments.123456759 is not a valid US routing number.
1000Unknown reasonSomething went wrong. Please contact Revolut Business support., Something went wrong. Please contact Revolut Business support with error ID <error_id>
info

Though the error codes above encapsulate all potential errors, the message provided is subject to changes. Reach out for further details.

HTTP error codes for draft payments

Check the following table to understand the error messages for draft payments:

Http ErrorCodeMessageReason
4002101Maximum file size limit of 10MB bytes exceededFile size uploaded was too large.
4002101Multiple currencies in single file are not allowedOnly payments in one currency can be uploaded.
4003039File validation failedThere was an error in the details provided in the CSV.
4039002This action is forbiddenThe user that tried to make this action was not the Business owner of the account.
4043070/11101Not found errorDraft payment was not found.
4223058/11102Invalid state errorDraft payment was not in the right state for a certain action. For example trying to delete a draft payment that had already been processed.

Payment orders vs transfers

When you create a bulk draft payment, it consists of a draft payment order, which in turn contains a set of transfers.

Both a draft payment order and transfers have own independent states.

Draft payment order

A draft payment order is what the user either approves or deletes from the user interface. It can have the following possible states:

Draft Payment Order StatusDescription
AwaitingThe draft payment order is created and awaiting approval from user.
ApprovedThe draft payment order is approved by the user and the transfers are in the process of being executed.
ProcessedThe draft payment order is processed.
DeletedThe draft payment order is deleted by the user.

Transfers

When the user approves a draft payment order, each transfer is executed individually. Each transfer can have the following possible states:

Transfer StatusDescription
CreatedThe transfer is created but hasn't been executed yet.
PendingThe transfer is in the queue to be executed.
CompletedThe transfer is completed successfully and a payment has been made from the users account.
FailedThe transfer fails and no payment has been made. Accompanying failure reason code and message are returned in GET endpoint.
DeletedThe transfer is deleted by the user.

Failure codes

There are a number of different reasons that transfers can fail.

Check the following table about different values of FailedReasonCode:

Failure CodeDescription
1003Recipient is unable to receive funds.
1006User has insufficient balance to execute the payment.
4000Internal transfer error. Typically occurs when a user is trying to send a payment to a sub-account or sending to an account with the incorrect currency.
4032Invalid transfer reference. The transfer reference that was detailed in the payment was invalid.
3067Unknown error. Please ask user to reach out to support.

Each FailedReasonCode is accompanied by a custom FailedReasonMessage to give detail on the failure.

tip

In case of any questions, reach out to Revolut Business support to get further help in understanding the failure of specific transfers.

Was this page helpful?