Business Flows
Temporary quote
Users can get a quote sample to see the exchange rate and fees that the Wise system offers. This action can be performed without authenticating in the Wise application.
Corresponding Mambu Process Orchestrator (MPO) process: Wise connector > Entry Points > 1.[EntryPoint] Create Temporary quote v_2.x.
- Process payload:
{
"sourceAmount": int - source amount,
"sourceCurrency": "string - source currency",
"targetAmount": int - target amount,
"targetCurrency": "string - target currency"
}
- Working example:
{
"sourceCurrency": "EUR",
"targetAmount": 200,
"targetCurrency": "CHF"
}
Notes:
- The process receives either the
sourceAmount
ortargetAmount
. Never both. - configuredTemporaryQuote config option filters the temporary quotes that the process responds with.
- The process provides an
Authorization
header which is used to lookup the existing agreement between the customer and Wise and automatically apply fees where necessary. If no fees will be charged, the fee amount will still be indicated in the quote with the value of0
.
User creation or authentication
Personal profile creation for a new user
Users are validated in the Wise backend based on the email address input in the UI application.
For a user that has never had an account created in Wise, a process that creates the user and profile is fired in MPO.
Corresponding MPO process: Wise connector > Entry Points > 2.1. [EntryPoint] PERSONAL/BUSINESS User&profile creation.
Steps to create a Personal Profile:
- User creation
- Personal profile creation
- Profile addresses creation (optional)
- Identification document creation (optional)
Process payload:
{
"clientAddress": {
"client address"
},
"clientEmail": "Mambu client’s email",
"clientFirstName": "Mambu client first name",
"clientLastName": "Mambu client last name",
"dateOfBirth": "Mambu client DOB",
"debtorIBAN": "Mambu client IBAN",
"detailReference": "Transfer details",
"phoneNumber": "Mambu client phone no",
"identificationDocument": {
"client's identification details"
},
"legalType": "Creditor legal type (Private or Business)",
"registrationCode": "Unique text code sent by the client",
"type": "personal"/*keep the value "personal"*/
}
Notes:
- The
identificationDocument
andclientAddress
objects are not required. - When field
registrationCode
is sent that value will be used in MPO process [1. Create new user in TW or redirect to login page] instead of automatically generate a new registration code. The value ofregistrationCode
sent must be unique and be at least 32 characters long. - In case the token is
invalid
when the API call (v1/user/signup/registration_code) is executed Wise will send one of the following HTTP codes:401
or403
with error message taginvalid_token
. A new token will be generated by callingWise Retry Mechanism
process, which will update the existing token stored inWise config
state diagram with referenceTWconfiguration
and the time when the new generated token will expire (parameterrefreshDelay
) is stored in the second state diagram fromWise config
with referencetwTokenRefresh
.
Working example:
{
"clientAddress": {
"country": "RO",
"city": "Iasi",
"postCode": "700625",
"firstLine": "Str.Palat nr.1"
},
"clientEmail": "clientemail@email.com",
"clientFirstName": "John",
"clientLastName": "SmithSr",
"dateOfBirth": "1986-01-01",
"phoneNumber": "+40756765765",
"identificationDocument": {
"firstName": "John",
"lastName": "SmithSr",
"type": "IDENTITY_CARD",
"uniqueIdentifier": "AA299822313",
"issueDate": "2017-12-31",
"issuerCountry": "RO",
"issuerState": "Iasi",
"expiryDate": "2027-12-31"
},
"type": "personal",
"registrationCode":"93233760391469228235708877179491"
}
Personal profile creation for an existent user
Create personal user profile for an existent user and token. One person cannot have multiple active duplicate user profiles, creating multiple profiles with the same details will fail.
Corresponding MPO process: Wise connector > Entry Points > 2.1.2 [EntryPoint] Personal user profile creation.
Objects clientAddress
and identificationDocument
are optional
Process payload:
{
"clientFirstName": "Mambu client first name",
"clientLastName": "Mambu client last name",
"dateOfBirth": "Mambu client DOB",
"phoneNumber": "Mambu client phone no",
"clientAddress": {
"client address"
},
"identificationDocument": {
"client's identification details"
},
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example without optional objects:
{
"clientFirstName": "Sam",
"clientLastName": "Smith",
"dateOfBirth": "1987-01-10",
"phoneNumber": "+31649256509",
"token": "0f94cb3f-bc16-4fd8-9533-8367fa5ff1c4"
}
Working example with optional objects:
{
"clientFirstName": "Sam",
"clientLastName": "Smith",
"dateOfBirth": "1987-01-10",
"phoneNumber": "+31649256509",
"clientAddress": {
"country": "RO",
"city": "Iasi",
"postCode": "700625",
"firstLine": "Str.Palat nr.1"
},
"identificationDocument": {
"firstName": "John",
"lastName": "SmithSr",
"type": "IDENTITY_CARD",
"uniqueIdentifier": "AA299822313",
"issueDate": "2017-12-31",
"issuerCountry": "RO",
"issuerState": "Iasi",
"expiryDate": "2027-12-31"
},
"token": "0f94cb3f-bc16-4fd8-9533-8367fa5ff1c4"
}
Update Personal profile user
Update user profile information. If user profile has been verified then there are restrictions on what information is allowed to change, where permitted, the update window functionality should be used to submit updated data.
Corresponding MPO process: Wise connector > Entry Points > 2.1.3. [EntryPoint] Update user profile.
Objects clientAddress
and identificationDocument
are optional for personal
user profile.
Process payload:
{
"profileId": "profileId", <the user's profile ID retrieved from user creation/login process>,
"type": "personal",
"clientFirstName": "Mambu client first name",
"clientLastName": "Mambu client last name",
"dateOfBirth": "Mambu client DOB",
"phoneNumber": "Mambu client phone no",
"clientAddress": {
"client address"
},
"identificationDocument": {
"client's identification details"
},
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example without optional objects:
{
"profileId": "16341931",
"type": "personal",
"clientFirstName": "Sam",
"clientLastName": "Smith",
"dateOfBirth": "1987-01-10",
"phoneNumber": "+31649256509",
"token": "0f94cb3f-bc16-4fd8-9533-8367fa5ff1c4"
}
Working example with optional objects:
{
"profileId": "16341931",
"type": "personal",
"clientFirstName": "Sam",
"clientLastName": "Smith",
"dateOfBirth": "1987-01-10",
"phoneNumber": "+31649256509",
"clientAddress": {
"country": "RO",
"city": "Iasi",
"postCode": "700625",
"firstLine": "Str.Palat nr.1"
},
"identificationDocument": {
"firstName": "John",
"lastName": "SmithSr",
"type": "IDENTITY_CARD",
"uniqueIdentifier": "AA299822313",
"issueDate": "2017-12-31",
"issuerCountry": "RO",
"issuerState": "Iasi",
"expiryDate": "2027-12-31"
},
"token": "0f94cb3f-bc16-4fd8-9533-8367fa5ff1c4"
}
Business profile creation
Note:
Business profiles cannot be created without a having a Personal profile first.
Corresponding MPO process: Wise connector > Entry Points > 2.1. [EntryPoint] PERSONAL/BUSINESS User & profile creation.
Steps of the Personal&Business Profile creation:
- User creation;
- Business profile creation (optional)
- Business profile addresses creation (optional)
- Business directors creation (optional)
- Business ultimate beneficial owners creation (optional)
Process payload:
{
"type": "business", /*please keep 'business' as type*/
"name": "Business name",
"registrationNumber": "Business registration number",
"descriptionOfBusiness": "Sector / field of activity",
"businessCategory": "Category of business",
"businessSubCategory": "Subcategory of the business",
"businessAddress": {
"business address"
},
"businessDirectors": [
{
"business director 1"
},
{
"business director 2"
}
],
"businessUltimateBeneficialOwners" : [
{
"UBO 1"
},
{
"UBO 2"
}
],
"companyType": "Type of business",
"webpage": "Business webpage"
}
Working example:
{
"name": "Business name",
"businessCategory": "OTHER",
"businessSubCategory": "OTHER_NOT_LISTED_ABOVE",
"companyType": "OTHER",
"descriptionOfBusiness": "OTHER",
"registrationNumber": "12345678",
"businessAddress": {
"country": "RO",
"city": "Iasi",
"postCode": "700625",
"firstLine": "Str.Xulescu nr.3"
},
"businessDirectors": [
{
"firstName": "Smith",
"lastName": "CEO",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa"
},
{
"firstName": "Doe",
"lastName": "CTO",
"dateOfBirth": "1981-12-07",
"countryOfResidenceIso3Code": "usa"
}
],
"businessUltimateBeneficialOwners": [
{
"name": "John Doe",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa",
"addressFirstLine": "123 Fake St",
"postCode": "FK 12345",
"ownershipPercentage": 30
},
{
"name": "Jane Doe",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa",
"addressFirstLine": "123 Fake St",
"postCode": "FK 12345",
"ownershipPercentage": 40
}
],
"type": "business",
"webpage": "www.page.com"
}
Update Business profile user
Update user profile information. If user profile has been verified then there are restrictions on what information is allowed to change, where permitted, the update window functionality should be used to submit updated data.
Corresponding MPO process: Wise connector > Entry Points > 2.1.3. [EntryPoint] Update user profile.
Objects businessUltimateBeneficialOwners
, businessAddress
and businessDirectors
are optional for business
user profile.
Process payload:
{
"profileId": "profileId", <the user's profile ID retrieved from user creation/login process>,
"type": "business", /*please keep 'business' as type*/
"name": "Business name",
"registrationNumber": "Business registration number",
"descriptionOfBusiness": "Sector / field of activity",
"businessCategory": "Category of business",
"businessSubCategory": "Subcategory of the business",
"businessAddress": {
"business address"
},
"businessDirectors": [
{
"business director 1"
},
{
"business director 2"
}
],
"businessUltimateBeneficialOwners" : [
{
"UBO 1"
},
{
"UBO 2"
}
],
"companyType": "Type of business",
"webpage": "Business webpage",
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example without optional objects:
{
"profileId": "16342006",
"type": "business",
"name": "olga business",
"businessCategory": "OTHER",
"businessSubCategory": "OTHER_NOT_LISTED_ABOVE",
"companyRole": "OWNER",
"companyType": "OTHER",
"descriptionOfBusiness": "OTHER",
"registrationNumber": "12345678",
"webpage": "www.page.com",
"token": "0f94cb3f-bc16-4fd8-9533-8367fa5ff1c4",
}
Working example with optional objects:
{
"profileId": "16342006",
"type": "business",
"name": "olga business",
"businessCategory": "OTHER",
"businessSubCategory": "OTHER_NOT_LISTED_ABOVE",
"companyRole": "OWNER",
"companyType": "OTHER",
"descriptionOfBusiness": "OTHER",
"registrationNumber": "12345678",
"webpage": "www.page.com",
"token": "0f94cb3f-bc16-4fd8-9533-8367fa5ff1c4",
"businessAddress": {
"country": "RO",
"city": "Iasi",
"postCode": "700625",
"firstLine": "Str.Xulescu nr.3"
},
"businessDirectors": [
{
"firstName": "Smith",
"lastName": "CEO",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa"
},
{
"firstName": "Doe",
"lastName": "CTO",
"dateOfBirth": "1981-12-07",
"countryOfResidenceIso3Code": "usa"
}],
"businessUltimateBeneficialOwners": [
{
"name": "John Doe",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa",
"addressFirstLine": "123 Fake St",
"postCode": "FK 12345",
"ownershipPercentage": 30
},
{
"name": "Jane Doe",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa",
"addressFirstLine": "123 Fake St",
"postCode": "FK 12345",
"ownershipPercentage": 40
}]
}
Open update window
Opens the update window for updating the profile information: details, addresses, directors, owners, others. Corresponding MPO process: Wise connector > Entry Points > 2.7. [EntryPoint] Open update window - v2.
Process payload:
{
"profileId": "profileId", <the user's profile ID retrieved from user creation/login process>,
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"profileId": "14733",
"token": "e0581691-4e43-474f-88c9-f2583027608b"
}
Close update window
Deletes the update window for updating the profile. Corresponding MPO process: Wise connector > Entry Points > 2.8. [EntryPoint] Close update window - v2.
Process payload:
{
"profileId": "profileId", <the user's profile ID retrieved from user creation/login process>,
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"profileId": "14733",
"token": "e0581691-4e43-474f-88c9-f2583027608b"
}
Retrieve user profiles
Get the list of all profiles belonging to user. Corresponding MPO process: Wise connector > Entry Points > 2.1.1 [Entry Point] Get user profiles - v1.
Process payload:
{
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"token": "e0581691-4e43-474f-88c9-f2583027608b"
}
Retrieve account requirements
The GET account-requirements
endpoint purpose is to identify which fields are required to create a valid recipient for different currencies. Retrieves the list of fields that need to be filled with values in the “details” section for creating a valid recipient account. Corresponding MPO process: Wise connector > Entry Points > 3.1.1 [EntryPoint] Get account requirements - v1.
Process payload:
{
"quoteId": "quoteId", <the quote id retrieved from the quote creation process>,
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"quoteId":"cc14e18d-1bf7-4f55-a350-6271bdefc485",
"token": "e0581691-4e43-474f-88c9-f2583027608b"
}
Create account requirements
The POST account-requirements
endpoint purpose is to identify which fields are required to create a valid recipient for different currencies. Corresponding MPO process: Wise connector > Entry Points > 3.1.3 [EntryPoint] Post account requirements - v1.
Process payload:
{
"quoteId": "quoteId", <the quote id retrieved from the quote creation process>,
"searchRequiredFields": {
"searchRequiredFields"
},
"language": "language" <language code >/* see the Wise [documentation](https://api-docs.transferwise.com/banks#language-support)*/.
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"quoteId":"cc14e18d-1bf7-4f55-a350-6271bdefc485",
"searchRequiredFields": {
"type": "iban",
"details": {
"email": "swissguy@mail.com",
"legalType": "PRIVATE",
"IBAN": "CH1589144313794187662",
"town": "Zürich",
"postCode": 8037,
"address": {
"country": "CH"
}
}
},
"token": "e03099b8-2905-46a3-8f15-811b7cbd0091",
"language":"he"
}
User authentication
Wise user validation is done based on the user email address. If a user with the specific email address already exists in the system, the MPO User creation
process will respond with a 409 User already exists
error. The UI app should pick this error up and redirect the user to the authorization web page.
The user logs in to Wise and agrees to provide access. The redirect page contains a code that is used to generate the token for the user. This code represents the entry payload for the MPO process that retrieves the token.
Corresponding MPO process: Wise connector > Entry Points > 2.2. [EntryPoint] Create token for existing user from code.
Process payload:
{
"code": "<code>"
}
Details about the user creation/authentication flows can be found by accessing the Wise documentation.
Quote creation with authenticated user
The quote resource defines the basic information required for a Wise transfer - the currencies to send between, the amount to send and the profile who is sending the money. The profileId
must be included when creating a quote with an authenticated user.
Corresponding MPO process: Wise connector > Entry Points > 3.1. [EntryPoint] Quotes after user creation/login.
Process payload:
{
"profileId": "profileId", <the user's profile ID retrieved from user creation/login process>
"sourceAmount": source amount,
"sourceCurrency": "source currency",
"targetAmount": target Amount,
"targetCurrency": "target currency",
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"profileId": "16066359",
"sourceAmount": 200,
"sourceCurrency": "EUR",
"targetCurrency": "CHF",
"token": "e0581691-4e43-474f-88c9-f2583027608b"
}
Notes:
- Upon creating a quote the current mid-market exchange rate is locked and will be used for the transfer that is created from the quote. The rate will be locked for 30 minutes to give a user time to complete the transfer creation flow.
- The process receives either the
sourceAmount
ortargetAmount
. Never both.
Retrieve quote info by ID
Retrieves the details for a specific quote by ID. Corresponding MPO process: Wise connector > Entry Points > 3.1.2 [Entry Point] Get quote info by id -v2.
Process payload:
{
"quoteId": "quoteId", <the quote id retrieved from the quote creation process>,
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"quoteId":"cc14e18d-1bf7-4f55-a350-6271bdefc485",
"token": "e0581691-4e43-474f-88c9-f2583027608b"
}
Recipient creation
Recipient is a person or institution who is the ultimate beneficiary of the transfer.
Recipient requirements will vary depending on recipient type. More details about the recipient required data here.
Corresponding MPO process: Wise connector > Entry Points > 3.2. [EntryPoint] Create the recipient for the quote.
Process payload:
{
"recipientBody": {
"recipient data"
},
"token": "access_token" <the user's token retrieved from user creation/login process>,
"language": "language" <language code >/* see the Wise [documentation](https://api-docs.transferwise.com/banks#language-support)*/.
}
Working example:
{
"recipientBody": {
"currency": "GBP",
"type": "sort_code",
"profile": 14733,
"ownedByCustomer": true,
"accountHolderName": "Ann Johnson",
"details": {
"email": "ana_Jhons@mail.com",
"legalType": "PRIVATE",
"sortCode": "231470",
"accountNumber": "28821822"
}
},
"token": "e0172d1b-e17f-40d2-94af-784fc59da298",
"language": "es"
}
Get recipients list
Each user has their own list of recipients associated with their Wise profile. This MPO process retrieves the list of all recipients filtered by profileId
.
Corresponding MPO process: Wise connector > Entry Points > 3.2.1. [EntryPoint] Get recipient list.
Process payload:
{
"profileId": "profileId", <the user's profile ID retrieved from user creation/login process>,
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"profileId": 14733,
"token": "e0581691-4e43-474f-88c9-f2583027608b"
}
Get recipient account info by ID
Get recipient account info by id. The response includes a hash of a recipient, which can be used to track if the recipient details change, which they can in some scenarios. The hash will remain constant unless the recipient’s name or information in the details object changes.
Corresponding MPO process: Wise connector > Entry Points > 3.2.2. [EntryPoint] Get recipient account info by id - v2.
Process payload:
{
"accountId": "recipientId", <the recipient ID retrieved from recipient creation/get process>,
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"accountId": "148165674",
"token": "e0581691-4e43-474f-88c9-f2583027608b"
}
Delete recipient
A recipient can be deleted by changing its status to inactive. Only active recipients can be deleted and a recipient cannot be reactivated, however a new recipient can be created with the same details.
Corresponding MPO process: Wise connector > Entry Points > 3.2.6. [EntryPoint] Delete recipient.
Process payload:
{
"accountId": "recipientId", <the recipient ID retrieved from recipient creation/get process>,
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"accountId": "148165674",
"token": "e0581691-4e43-474f-88c9-f2583027608b"
}
Create Refund recipient
A refund recipient is a person or institution where Wise will refund transfer the money back to if necessary. The format of the request payload for refund recipient creation will be different depending on the currency from which transfers were sent from.
Corresponding MPO process: Wise connector > Entry Points > 3.2.4 [EntryPoint] Create refund recipient - v2.
Process payload:
{
"refundRecipientBody": {
"refundRecipientBody"
},
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"refundRecipientBody": {
"currency": "GBP",
"country": "GB",
"type": "sort_code",
"profile": 14733,
"legalEntityType": "PERSON",
"name": {
"fullName": "Ann Johnson"
},
"details": {
"sortCode": "231470",
"accountNumber": "28821822"
}
},
"token": "e0581691-4e43-474f-88c9-f2583027608b"
}
Get Receipt PDF
Download transfer confirmation receipt in PDF format for transfers that are in status outgoing_payment_sent
. Corresponding MPO process: Wise connector > Entry Points > 3.2.5. [EntryPoint] Get Receipt PDF - v1.
Process payload:
{
"transferId": "transferId", <the transfer ID retrieved from transfer creation/>,
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"transferId": "49511866",
"token": "e0581691-4e43-474f-88c9-f2583027608b"
}
Patch quote with recipient information
All quotes should be updated with the recipient data in order to retrieve the correct payment options, prices and estimated delivery times. This is due to the fact that sending some currencies to some destinations costs a different amount based on the payment networks Wise is using. More documentation on the quotes update can be found here.
Corresponding MPO process: Wise connector > Entry Points > 3.3. [EntryPoint] Patch Quote with recipient information.
Process payload:
{
{
"profileId": "profileId", <the user's profile ID retrieved from user creation/login process>,
"quoteId": "quoteId", <the quote id retrieved from the quote creation process>
"recipientId": "recipientId", <the recipient id retrieved from recipient creation process>,
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"profileId": 14733,
"quoteId": "e2451439-ff94-4146-9ff4-b6e1d65bb3cb",
"recipientId": 147774783,
"token": "e0581691-4e43-474f-88c9-f2583027608b"
}
Retrieve transfer requirements
The process that retrieves the transfer requirements responds with the necessary transfer parameters based on the specific quote and selected target (recipient) account.
For more details on the transfer requirements functionality, see the Wise documentation.
Corresponding MPO process: Wise connector > Entry Points > 3.4. [EntryPoint] Get transfer requirements.
Process payload:
{
"transferBody": {
"transfer body"
},
"token": "access_token" <the user's token retrieved from user creation/login process>,
"language": "language" <language code >/* see the Wise [documentation](https://api-docs.transferwise.com/banks#language-support)*/.
}
Working example:
{
"transferBody": {
"targetAccount": "147774783",
"customerTransactionId": "1941cc88-6afb-4a39-bb45-9be276626402",
"quoteUuid": "e2451439-ff94-4146-9ff4-b6e1d65bb3cb",
"details": {
"reference": "Invoice RF12345"
}
},
"token": "e0581691-4e43-474f-88c9-f2583027608b",
"language": "es"
}
Get address by id
Get a full address based on its ID. Corresponding MPO process: Wise connector > Entry Points > 3.5 [Entry Point] Get address by id - v1.
Process payload:
{
"addressId": "addressId", <the address ID retrieved from address adding/user creation process>,
"token": "access_token" <the user's token retrieved from user creation/login process>
}
Working example:
{
"addressId": "7272341",
"token": "76d8cee8-aa91-4038-9033-6054f2edb502"
}
Notes:
- When
addressId
is not sent, or is empty, an error message will be retrieved.
Transfer creation
The available transfer options will be given by the configuration field configuredPayIn
. At this moment the field can have the following values:
"configuredPayIn": "TRUSTED_PRE_FUND_BULK"
- available transfer option is only prefund bulk transfers;"configuredPayIn": "BANK_TRANSFER"
- available transfer option is only bank transfers;"configuredPayIn": "TRUSTED_PRE_FUND_BULK, BANK_TRANSFER"
- the connector supports both methods for the domestic payment;
Bank transfers
Corresponding MPO process: Wise connector > Entry Points > 5. [EntryPoint] Payments Gateways Wise transfer flow.
Based on the currency of the domestic transfer, the payment can be routed either through the SEPA Gateway - if the sourceCurrency
is EURO or through ClearBank - if the sourceCurrency
of the transfer is GBP. This routing mechanism is dictated by a config parameter that holds the pair of currency of the domestic payment and the process Id of the MPO process that handles the payment:
"paymentRails": {
"GBP": "process id - number",
"EUR": "process id - number"
}
The process Wise connector > 5. PAYMENTS GATEWAY transfer module ENTRY POINT > 5.2. [Continue transfer flow -GBP [plug-in with other Payment Gateways] can be adapted to support other currencies too by adding a new condition that checks the value of the sourceCurrency
and routes the payment to the dedicated Payments Gateway. The same logic should be applied in the “AML Listener” process if the payment will be subjected to the anti-money laundering verification.
Process payload:
{
"clientEmail": "User email",
"debtorIBAN": "Debtor IBAN",
"recipient": {
"recipient object"
},
"transferBody": {
"transfer object"
},
"transferredAmount": "Transferred amount", /* the transferredAmount resulted after the user requests the available quotes and transfer options, from the chosen option */
"token": "User access token" /* the user access_token resulted after the user login or registration */,
"language": "language" <language code >/* see the Wise [documentation](https://api-docs.transferwise.com/banks#language-support)*/.
}
Working example:
{
"clientEmail": "jane.doe@gmail.com",
"debtorIBAN": "RO15BTRLPDRCUKS0LNFYDZOZ",
"recipient": {
"id": 147771497,
"business": null,
"profile": 14733,
"accountHolderName": "Diana Smith",
"currency": "EUR",
"country": "RO",
"type": "iban",
"details": {
"email": "dianaSmith@mail.com",
"legalType": "PRIVATE",
"IBAN": "RO94BTRLD19ACC5KPMF1I89X",
"iban": "RO94BTRLD19ACC5KPMF1I89X"
},
"user": 5474294,
"active": true,
"ownedByCustomer": false
},
"token": "5ebf76a3-cf99-4148-9910-d8371f4e6463",
"transferBody": {
"targetAccount": 147771497,
"customerTransactionId": "392a302e-fead-4a9a-b232-6fa413230002",
"quoteUuid": "3baefb70-f70f-4a2b-aee9-b064bc33d843",
"details": {
"reference": "old debt"
}
},
"transferredAmount": 202,
"language":"es"
}
Transfer flow
Part 1 (common):
- Get Mambu deposit account id by IBAN (the IBAN can be linked to the deposit account either by EAR or stored in a dedicated custom field)
- Wise transfer creation
- Process routing based on transfer
sourceCurrency
and configuredpaymentRails
.
Notes:
- After the transfer is created the
twTransferId
is returned to the UI, and the payment flow continues in the background.
Part 2 (specific):
Mambu SEPA Gateway
- Payment initiation in the Mambu Gateway
- Initiate payment in Mambu
- Payment status retrieval.
- if accepted (ACSP
) -> The process continues with the update of theTWTransferID
andtransferStatusField
custom fields at the withdrawal transaction level in Mambu;
- If rejected (RJCT
) -> Cancel Wise transfer;
Other Payments Gateways
- Create Mambu withdrawal
- Patch Wise transfer id at the withdrawal level in Mambu.
Notes:
- The transfer transaction can be verified by an AML system. The extension point for this plug-in can be found in the 2nd part of the transfer process, after the successful withdrawal transaction.
- The payment is identified via a boolean parameter that shows the origin of the transaction:
isPaymentGatewayTransfer : true
;
Prefunded transfers
Corresponding MPO process: Wise connector > Entry Points > 4. [EntryPoint] PREFUND Wise transfer flow.
This transfer option allows Wise to start processing a transfer before receiving funds from the sending customer, based on the guarantee from the bank partner that the funds will be settled in a fixed future time-frame. In this way, Wise can provide a faster service to the sending customer in situations where using an existing payment network would incur a delay.
The domestic payment is replaced by a bulk reconciliation agreement between the bank and Wise.
Process payload:
{
"clientEmail": "User email",
"depositAccountId": "Mambu client deposit account id",
"userDepositAccountCurrency" : "Mambu deposit account currency",
"recipient": {
"recipient object"
},
"transferBody": {
"transfer object"
},
"transferredAmount": "Transferred amount", /* the transferredAmount resulted after the user requests the available quotes and selects transfer option, from the displayed option */
"sourceCurrency" : "source currency of the transfer",
"token": "User access token" /* the user access_token resulted after the user login or registration */,
"language": "language" <language code >/* see the Wise [documentation](https://api-docs.transferwise.com/banks#language-support)*/
}
Working example:
{
"clientEmail": "jane.doe@gmail.com",
"depositAccountId": "XYZW123",
"userDepositAccountCurrency" : "GBP",
"recipient": {
"id": 147771497,
"business": null,
"profile": 14733,
"accountHolderName": "Diana Smith",
"currency": "EUR",
"country": "RO",
"type": "iban",
"details": {
"email": "dianaSmith@mail.com",
"legalType": "PRIVATE",
"IBAN": "RO94BTRLD19ACC5KPMF1I89X",
"iban": "RO94BTRLD19ACC5KPMF1I89X"
},
"user": 5474294,
"active": true,
"ownedByCustomer": false
},
"token": "5ebf76a3-cf99-4148-9910-d8371f4e6463",
"transferBody": {
"targetAccount": 147771497,
"customerTransactionId": "392a302e-fead-4a9a-b232-6fa413230002",
"quoteUuid": "3baefb70-f70f-4a2b-aee9-b064bc33d843",
"details": {
"reference": "old debt"
}
},
"sourceCurrency" : "GBP",
"transferredAmount": 202,
"language":"es"
}
This flow contains:
Part 1:
- Wise Transfer creation
- Mambu Withdrawal with Wise custom fields mapping:
transferId
and fields fromrecipient
,transfer
andfees
objects - Update of the Wise
transferStatus
custom field at the Withdrawal transaction level in Mambu - Process routing based on the
AMLcheck
option saved in the config
Notes:
Depending on amlExtensionUsed
parameter, there are two cases:
- If
amlExtensionUsed = true
after the transfer is created and Associate Wise transfer Id with the withdrawal is made, thetwTransferId
is returned to the UI, and the payment flow continues in the background. - If
amlExtensionUsed = false
after the transfer is created and Associate Wise transfer Id with the withdrawal is made, thetwTransferId
,token
,transferBody
object,transferredAmount
,withdrawal
object anddepositAccountId
are returned to the UI, and the payment flow ends. The second part of the flow (4.1. Prefund Wise transfer flow (2nd part)
Sync API) should be called separately with the response from the first call (4. PREFUND Wise transfer flow (before AML)
) after the bank called their own extension of AML. - Field
Notes
is populated with the Transfer reference details IF sent, otherwise only default textWise Transfer [reference] details:
will be mapped.
Part 2 (continue payment flow):
- Fund the Wise Transfer
- Deposit Withdrawal amount in the settlement account in Mambu with Wise
transferId
custom field mapping
This second part can be triggered by a Sync API corresponding MPO process: Wise connector > Entry Points > 4.1. [EntryPoint] PREFUND Wise transfer flow (2nd part).
Process payload (all the needed parameters are returned by the Sync API from Part 1):
{
"depositAccountId": "Mambu client deposit account id",
"transferBody": {
"transfer object"
},
"withdrawal": {
"withdrawal object"
},
"twTransferId": "TransferWise transaction id"
"transferredAmount": "Transferred amount", /* the transferredAmount resulted after the user requests the available quotes and selects transfer option, from the displayed option */
"token": "User access token" /* the user access_token resulted after the user login or registration */,
}
Working example:
{
"twTransferId": "50006850",
"token": "679e947f-0ac1-4ac5-abcd-11af2fedcf27",
"transferBody": {
"targetAccount": 147799103,
"customerTransactionId": "7abac1e2-87e3-11eb-8dcd-0242ac130506",
"quoteUuid": "c3cc70a2-a98a-4514-8646-0dd4cf7efb8e"
},
"transferredAmount": 20,
"withdrawal": {
"encodedKey": "8a01393f7b98266d017b9a48651b3038",
"id": "432344",
"creationDate": "2021-08-31T11:47:45+03:00",
"valueDate": "2021-08-31T11:47:45+03:00",
"bookingDate": "2021-08-31T11:47:45+03:00",
"parentAccountKey": "8a012ea378f34e470178f96fa2ac2559",
"type": "WITHDRAWAL",
"amount": -20,
"currencyCode": "EUR",
"affectedAmounts": {
"fundsAmount": 20,
"interestAmount": 0,
"feesAmount": 0,
"overdraftAmount": 0,
"overdraftFeesAmount": 0,
"overdraftInterestAmount": 0,
"technicalOverdraftAmount": 0,
"technicalOverdraftInterestAmount": 0,
"fractionAmount": 0
},
"taxes": {},
"accountBalances": {
"totalBalance": 5465.32
},
"userKey": "8a014036786faa2c01787cdfaab55583",
"terms": {
"interestSettings": {},
"overdraftInterestSettings": {},
"overdraftSettings": {}
},
"transactionDetails": {
"transactionChannelKey": "8a012cf47502ded501750768496b1584",
"transactionChannelId": "TWLP"
},
"transferDetails": {},
"fees": []
},
"depositAccountId": "BCLX995"
}
Notes:
- If the Trusted Prefund Bulk limit is reached when funding the Wise transfer - meaning funds cannot be transferred - a notification is sent, and the flow continues with making a deposit. For any other error, a refund is made and the flow is stopped.
- If making a deposit fails, a notification is sent and a refund must be made manually.
Settlement
Note: PreFund Bulk ONLY
Corresponding MPO process: Wise connector > Main Processes > Settlement module > 6. [EntryPoint] Settlement [ONLY FOR PRE-FUND BULK]
Steps of the settlement flow:
- Validate received currency
- Get deposits for settlement from settlement account
- Create settlement lists for configured currencies
- Perform settlement with Wise for received currency
- Patch settled transactions with settlementReference
- Mark transactions as settled in Mambu.
Process payload:
{
"currencyToSettle": "Currency to settle" /*the client can have multiple settlement agreements for different currencies on the ForPrefund Bulk transfer option */
"offset": "Starting point of list"
"limit": "Maximum number of records retrieved"
}
Working example:
{
"currencyToSettle": "EUR",
"offset": "0",
"limit": "300"
}
Note: If offset
and limit
parameters are not sent then the default limit will be displayed (50 items).
Subscribe to transfer status updates at the transaction level
The transfer updates subscription
is done as part of the connector config.
The scope of the subscription is to receive Wise transfer status updates in MPO. The process responsible with capturing the transfer status webhooks is:
Update Transfer Status Event Receiver.
The status of the Wise transfer is patched at the withdrawal transaction level in Mambu, in the transferStatusField
field, based on the Wise transferId
saved as part of the transfer process, in the transferStatusField
.
Read more about Wise transfer statuses by accessing this link.
Negative Flows
For all the flows except the transfer creation, the wrapper processes will capture and return the process errors regardless of their type (business or technical). The UI application should create the adapted logic based on the captured errors (error messaging, redirect, etc..).
For the transfer flows, the MPO processes respond with the process errors which occur until the creation of the Wise transfer. This step triggers a response to the Wrapper process stating that the transfer has been initiated and providing the Wise transferId
.
After this step, the failures in the flow are handled as follows:
Prefunded transfers
Process | Failure point | Error Handling |
---|---|---|
[EntryPoint] PREFUND Wise transfer flow 1 | Withdrawal from payer’s account | Cancel Wise transfer; Send notification |
Patch Withdrawal with Wise transferStatus | Send notification | |
Continue transfer flow (if AML check = false) | Send notification | |
Continue transfer flow with the AML check (if AML check = true) | Send notification | |
[EntryPoint] PREFUND Wise transfer flow 2 | Deposit in settlement account | Send notification |
Patch deposit with Wise transferId | Send notification; Continue transfer flow | |
Fund transfer in Wise (technical error or “limit.reached” business error) | Send notification |
Bank transfers
Process | Failure point | Error Handling |
---|---|---|
5. [EntryPoint] Payments Gateways Wise transfer flow | Route the transfer to the corresponding Payment Gateway | Cancel Wise transfer; Send notification |
5.1. Continue transfer flow for EUR - Mambu SEPA Gateway | Initiate Mambu payment | Cancel Wise transfer; Send notification |
Get Mambu payment status | Cancel Wise transfer; Send notification | |
Payment status = RJCT (rejected) | Cancel Wise transfer; Send notification | |
5.2. Continue transfer flow -GBP [plug-in with other Payment Gateways] | Withdrawal from payer’s account | Cancel Wise transfer; Send notification |
Patch withdrawal with Wise transferId and status | Send notification ; Continue transfer flow | |
Continue transfer flow with the local payment (if AML check = false) | Cancel Wise transfer; Send notification | |
Continue transfer flow with the AML check (if AML check = true) | Cancel Wise transfer; Send notification |