IBAN Order

Before placing an IBAN order, it is necessary to check its availability. Using the GET /v2/iban/list endpoint, a boolean parameter available is returned:

• true - IBAN order is possible;
• false - IBAN order is prohibited.

Reasons for IBAN Order Prohibition:

• The user's profile specifies an unsupported country.
• The user already has an existing IBAN.
• The user has filled out all necessary IBAN order information, but the request to Walletto returned with a MULTI_ACCOUNT status. This status indicates that a Walletto account already exists for the user's phone number in another merchant application.

Stages of IBAN Order

Initiation of the order

Use the POST /v2/iban/iban-requests endpoint. This creates a new record in the walletto_iban_request table. Upon using GET /v2/iban/list, information about the IBAN order is returned under the ibans parameter.

KYC WALLETTO process

To initiate the KYC process through WALLETTO, use the POST /v4/kyc/start endpoint. Ensure to specify the platform parameter with the value WALLETTO in your request.

Upon completion, you will receive a response containing an identificationId. This serves as a unique identifier for continuous monitoring of the KYC status or for acquiring additional details.

Next, use the received identificationId in a request to POST /v4/kyc/ondato/finished, specifying platform=WALLETTO, to complete the KYC process.

After the KYC request enters our database, the IBAN order status changes to IN_PROGRESS. Subsequently, the status may change to one of the following:

• ACTION_NEEDED - KYC request was rejected either by Ondato or through manual review.
• SUPPORT - attempts to pass KYC have been exhausted.
• COLLECTION - KYC has been successfully completed, allowing the IBAN order to proceed. Upon using GET /v2/iban/list, "ibans"."additionalStatus" is updated to "KYC".

Additional information input and taxId

Clients need to first call GET /v2/iban/additional-personal-info/constants to obtain lists of income sources and monthly turnover ranges. This data is sourced from Walletto.

To submit additional information, use the POST /v2/iban/additional-personal-info endpoint with the following request body schema:

{
  "taxId": "12345678901",
  "taxCountry": "DEU",
  "incomeSource": [
    "legacy", "other"
  ],
  "additionalIncomeSource": "test",
  "estimatedMonthlyTurnoverRange": "3001-8000",
  "dataCorrectnessConfirmation": true,
  "isUsRelated": true,
  "usRelatedPerson": "us related"
}

Upon completion of this stage, "ibans"."additionalStatus" in GET /v2/iban/list is updated to TAXID, ADDITIONAL_PERSONAL_INFO.

Address Submission Stage

To submit the address details, use the POST /v2/iban/addresses endpoint with the following request body:

{
  "country": "string",
  "state": "string",
  "city": "string",
  "address": "string",
  "postalCode": "string"
}

Upon completion of this stage, the ADDRESS status is set in the additionalStatus array in the response from the GET /v2/iban/list endpoint.

Final Stage - IBAN Order Processing by Walletto

Once all statuses ["KYC", "TAXID", "ADDITIONAL_PERSONAL_INFO", "ADDRESS"] are set in the "additionalStatus" array, the backend sends the IBAN order to Walletto. During this time, the order status changes back to IN_PROGRESS. After processing, Walletto may return one of the following statuses:

• SUPPORT: Walletto denied the account creation.
• MULTI_ACCOUNT: The user already has an account in Walletto linked to their phone number but in another merchant's application.
• CREATED: The account and IBAN are successfully created and ready for use.

Additional IBAN Functionality

Receiving Funds from External Sources

Users can replenish their IBAN account from other banking services. Information regarding the current balance and transaction history can be retrieved through the response to the GET /v2/iban/list endpoint.

Withdrawing Funds to External Accounts

Users can transfer funds from their IBAN account to an external bank account. This functionality allows for transfers outside the WALLETTO system and can be utilized for payments and transfers between different banking accounts.

❗️

Please note that these operations do not include internal transfers between WALLETTO users, focusing solely on transactions with external bank accounts