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 or targetAmount. 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 of 0.

Temp_Quote_v2_0

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 and clientAddress 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 of registrationCode 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 or 403 with error message tag invalid_token. A new token will be generated by calling Wise Retry Mechanism process, which will update the existing token stored in Wise config state diagram with reference TWconfiguration and the time when the new generated token will expire (parameter refreshDelay) is stored in the second state diagram from Wise config with reference twTokenRefresh.

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"
}

EntryPoint_Personal_Business_User_Profile

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"
}

Personal Profile Creation

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"
}

Update Profile

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

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"
}

Open Update Window

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"
}

Close Update Window

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"
}

User Profiles list

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"
}

Account Requirements

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"
}

Create Account Requirements

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>"
}

Token_from_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"
}

Quote_after_login

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 or targetAmount. 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"
}

Quote Info

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"
}

Recipient creation

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"
}

Recipient list

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"
}

Recipient info

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"
}

Delete Recipient

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"
}

Refund Recipient

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"
}

Receipt PDF

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"
}

Patch quote

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"
}

Transfer requirements

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.

Address

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 configured paymentRails.

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 the TWTransferID and transferStatusField 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.

PG transfers

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 from recipient, transfer and fees 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, the twTransferId 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, the twTransferId, token, transferBody object, transferredAmount, withdrawal object and depositAccountId 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 text Wise Transfer [reference] details: will be mapped.

EntryPoint_PREFUND_Wise_transfer_flow

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.

EntryPoint_PREFUND_Wise_transfer_flow

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).

Settlement

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

Prerequisites