Bank account export

Bank account extraction is the process of retrieving the shops that have changed in Mirakl and creating or updating the corresponding bank accounts in Hyperwallet.

Characteristics

  • The connector supports the following bank account types from Mirakl:

    • IBAN

    • United States A.B.A.

    • Canadian bank account

    • United Kingdom bank account

  • When creating the bank account in Hyperwallet, the connector uses the currency of the shop if it’s supported by Hyperwallet. Otherwise, it uses a currency compatible with the bank account country and bank account type.

  • The connector supports updating the bank account information in Hyperwallet. But if the changes in the bank account aren’t compatible with the existing bank account in Hyperwallet, the connector creates a new bank account.

  • When the marketplace currency isn’t supported in Hyperwallet for the bank account of the seller, the connector automatically selects a compatible currency. The payments are always made in the marketplace currency.

Bank account extraction process

bankaccount-extraction

Batch job steps

The bank account extraction process is organized in different phases or steps during the job execution (as explained in phases of a job):

bankaccount-steps
Step 1: Extraction of items

During this step the connector retrieves from Mirakl the shops modified since the last execution of the job, extracting the bank account information from the shop.

Step 2: Item processing

During this step the connector processes each retrieved bank account. The connector creates or updates the corresponding bank account in Hyperwallet, according to certain bank account update restrictions.

Step 1: Extraction of shops

Since bank account information is part of the shop information, the connector retrieves from Mirakl the shops modified since the last execution of the job.

During this phase the connector logs the following information:

[BATCHJOB] Starting processing of job
[BATCHJOB] Starting extraction of items to be processed
[BATCHJOB] Retrieving shops since Tue Apr 18 12:41:42 UTC 2023
[BATCHJOB] Shops retrieved [78766,78764]
[BATCHJOB] Retrieving shops since Tue Apr 18 12:41:42 UTC 2023
[BATCHJOB] Shops retrieved [78765]
[BATCHJOB] Retrieved the following number of items to be processed: 3

The connector filters the shop by type (first individuals and then professionals), that’s why it logs two times the Shop retrieved message.

Step 2: Bank account processing

The seller processing has two phases:

  • Hyperwallet token synchronization, that ensures that the shop has an Hyperwallet bank account token assigned if the bank account already exists in Hyperwallet.

  • Synchronized bank account processing, that creates or updates the bank account in Hyperwallet.

Step 2.1: Hyperwallet token synchronization

bankaccount-token-synchronization

Hyperwallet has some restrictions about the fields of the bank account that the connector can change:

  • Country of the bank account can’t be changed.

  • Type of the bank account can’t be changed.

For example, the following changes can’t be made to an existing bank account in Hyperwallet:

  • If the existing bank account is of type ABA (US bank account), the connector can’t update it to an IBAN (international bank account) type.

  • If the existing bank account has an IBAN from Italy, the connector can’t update it to an IBAN from Spain.

For this reason the bank account token alone isn’t enough to identify the bank account in Hyperwallet, because it doesn’t guarantee that the connector can update the bank account. The connector needs to verify that the existing bank account in Hyperwallet is compatible with the information in Mirakl.

bankaccount-steps

A Mirakl bank account is compatible with an Hyperwallet bank account if:

  • The bank account country is the same as the one in Hyperwallet.

  • The bank account type is the same as the one in Hyperwallet.

Step 2.2: Synchronized bank account processing

bankaccount-processing

Based on whether the bank account has a token or not after the synchronization process, the connector creates or updates the bank account in Hyperwallet.

During this phase the connector logs the following information:

[BATCHJOBITEM] Processing item of type BankAccount with id: 78766
18-04-2023 12:44:45.052 [HyperwalletMiraklScheduler_Worker-3] INFO  [BATCHJOBITEM] Bank account created or updated for seller with clientId [78766]
[BATCHJOBITEM] Updating bank account token for shop [78766]
[BATCHJOBITEM] Bank account token updated for shop [78766]
[BATCHJOBITEM] Processed successfully item of type BankAccount with id: 78766
[BATCHJOBITEM] 1 items processed successfully. 0 items failed. 2 items remaining
...
[BATCHJOBITEM] 3 items processed successfully. 0 items failed. 0 items remaining
[BATCHJOB] Finished processing of job

Job execution

The connector provides can execute the bank account extract job automatically and the users can execute the job manually using a REST API.

Scheduled execution

The connector automatically executes the jobs in a scheduled manner. The connector reads the schedule configuration from the following variable:

  • PAYPAL_HYPERWALLET_BANK_ACCOUNT_EXTRACT_CRON_EXPRESSION

You can find more information in the configuration variables section.

Manual execution

The connector provides the following REST API to execute the jobs manually:

HTTP method

Path

Job type

POST

/job/bank-accounts-extract

Bank accounts extract job

You can find more information in the generic job REST API reference.

Configuration variables

The section seller onboarding configuration variables, has information about the configuration variables used by the bank account extraction job.

API calls

The connector does the following API calls during the sellers extraction jobs execution:

Call Target System Endpoint Parameters

Retrieve all modified shops since the last specified date

Mirakl

S20 - List shops

  • updated_since: date calculated by the job as the starting date since the last job execution or the date manually specified in the job execution.

Update Hyperwallet bank account token in a Shop

Mirakl

S07 - Patch shop

  • custom field hw-bankaccount-token: the Hyperwallet bank account token.

Create a new bank account

Hyperwallet

POST /users/{user-token}/bank-accounts

The connector generates a body from the bank account information contained in the Mirakl shop according to the data mapping rules. The following mappings are specially relevant:

  • programToken: the program token associated to the program assigned to the shop.

  • profileType: BUSINESS or INDIVIDUAL depending on the business field in the Mirakl shop

  • transferMethodCountry: the country of the bank account.

  • transferMethodCurrency: the currency supported by the bank account. The payment is always made in the marketplace currency.

  • type: BANK_ACCOUNT.

Update an existing bank account

Hyperwallet

PUT /users/{user-token}/bank-accounts/{bank-account-token}

The connector generates a body from the bank account information contained in the Mirakl shop according to the data mapping rules.

Retrieve bank accounts of a user

Hyperwallet

GET /users/{user-token}/bank-accounts

Data mapping

Common fields

Hyperwallet field Mirakl field Notes

profileType

BUSINESS or INDIVIDUAL, based on Professional attribute

transferMethodCountry

Calculated based on the bank account type (using 2 char ISO code): * US for US bank accounts * CA for Canadian bank accounts * GB for UK bank accounts * First two characters of bank account number for IBAN bank accounts

transferMethodCurrency

Calculated based on currency_iso_codefield from Mirakl shop and the supported country/currency combination in Hyperwallet for the selected bank account type.

type

N/A

Fixed value BANK_ACCOUNT

businessName

Company name field under Seller Contact Details

country

Country field under Seller Contact Details

addressLine1

Address field under Seller Contact Details

addressLine2

Address (continued) field under Seller Contact details.

It’s optional and the connector fills it if this data exists in Mirakl.

city

City field in Seller Bank Account Details

postalCode

Postcode field in Seller Bank Account Details

stateProvince

Custom field: hw-bankaccount-state

IBAN Payment method

Hyperwallet field Mirakl field Notes

bankId

BIC

bankAccountId

IBAN

UK payment method

Hyperwallet field Mirakl field Notes

bankId

BIC

bankAccountId

IBAN

U.S. ABA payment method

Hyperwallet field Mirakl field Notes

branchId

Routing number (ABA).

bankAccountId

Bank account number

bankAccountPurpose

N/A

Fixed value CHECKING

Canadian payment method

Hyperwallet field Mirakl field Notes

bankId

3 digit bank code

branchId

5 digit transit number

bankAccountId

Bank account number

Country and currency selection

Hyperwallet API defines the supported countries and currencies combinations, and based on them, it defines the bank account type that should be provided.

The bank account information that the sellers provide in Mirakl defines the bank account type and the country, which is derived from the bank account type and number according to the following rules:

  • US for US bank accounts.

  • CA for Canadian bank accounts.

  • GB for UK bank accounts.

  • First two characters of the bank account number for IBAN bank accounts.

Using the bank account information and Hyperwallet’s country/currency combinations, the connector determines the currency that should be used for the transfer using the following logic:

bankaccount-currency-selection

Automatic currency selection can be disabled setting to false` the environment variable PAYPAL_HYPERWALLET_BANK_ACCOUNTS_ENABLE_AUTOMATIC_CURRENCY_SELECTION. In this case marketplace’s currency is always used during bank account creation, that will fail when the currency isn’t supported by Hyperwallet.

Troubleshooting

This job doesn’t have any specific troubleshooting guides. Follow the generic recommendations detailed in troubleshooting of a job.