Invoice extraction

The invoice extraction job retrieves pending invoices from Mirakl and creates payments for them in Hyperwallet.

This job can handle credit notes for testing purpose. This job is a composite batch job that runs sequentially:

  • Invoices extraction

  • Credit notes extraction

Enabling manual credit notes processing on production

Mirakl includes the amount of the manual credit notes into the next automatic invoice. This means that if the connector is processing manual credit notes, the amount of the credit notes will be paid two times, one in the credit note and one in the next invoice.

For this reason, it’s strongly urged to use manual credit notes only in test environments while testing.

Since the behavior of the invoice extraction is the same as the credit notes extraction, the following documentation will only refer to invoices.

Characteristics

  • The connector creates payments for the marketplace operator when the commission fees are enabled in the connector configuration.

  • The connector extracts invoices only with a COMPLETE`status. It ignores invoices with `DRAFT, GENERATED or PAID status.

  • The connector can retry the invoice extraction without generating duplicated payments.

Invoice extraction process

invoice-extraction

Batch job steps

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

invoices-steps
Step 1: Extraction of invoices

The connector retrieves from Mirakl the invoices with a pending status created since the last successful invoice extraction.

Step 2: Preparation for processing

The connector retrieves information from Mirakl about the shops associated to the invoices. The connector needs this information for creating the payments in Mirakl.

Step 3: Invoices processing

The connector starts the integration workflow for each of the invoices retrieved during the extraction of items.

Step 3.1: Invoice enrichment

The connector enriches the invoices with shop information obtained during the preparation step.

Step 3.2: Invoice validation

The connector validates that the enriched invoices has all the information it needs to create a payment.

Step 3.3: Payment creation

The connector creates the payments in Hyperwallet.

Step 1: Extraction of invoices

The connector retrieves all invoices with PENDING payment status created since the last successful invoice extraction.

invoices-extraction

During this phase the connector logs the following information:

[BATCHJOB] Starting extraction of items to be processed
[BATCHJOB] Retrieved the following number of items to be processed: 3

Step 2: Preparation for processing

invoices-preparation

The connector retrieves shop information from Mirakl that needs to create the payments in Hyperwallet. Invoice documents in Mirakl doesn’t contain a programToken or a bankAccountToken. This information is stored in custom fields of the shop in Mirakl.

To minimize the number of calls to S20 - List all shops the connector uses an internal cache. This cache stores the relationship between a Mirakl shop and the corresponding Hyperwallet programToken and bankAccountToken.

During this step the connector doesn’t show any specific logs, except if an error happens.

Step 3: Invoices processing

During this step the connector processes each of the received invoices. For each invoice the connector logs the following information:

[BATCHJOBITEM] Processing item of type Invoice with id: 70051
[BATCHJOBITEM] Pending invoices to pay: [70051]

and a message like this when the item has finished it processing:

[BATCHJOBITEM] Processed successfully item of type Invoice with id: 70051
[BATCHJOB] 1 items processed successfully. 0 items failed. 2 items remaining

Step 3.1: Invoice enrichment

invoices-enrichment

The connector only logs error information during this step.

Step 3.2: Invoice validation

The connector validates the invoice to check if it has all the information. It does the following checks:

  1. The invoice has an associated programToken and bankAccountToken

  2. The invoice doesn’t belong to an ignored program

The connector logs the following if the validation fails:

Validation of item of type Invoice with id: 75001 has failed with the following message: {}"

Step 3.3: Payment creation

The connector creates payments for the invoice calling using Hyperwallet API.

payment-creation

Before creating a payment the connector checks if there is an existing payment that’s in progress or paid. For doing this check, the connector only takes into account payments that doesn’t have a failure status (FAILED, RECALLED, CANCELLED, RETURNED, EXPIRED)

If commissions are enabled, the connector creates two payments:

  • A payment for the seller, with the same id as the invoice in Mirakl

  • The payment for the operator, adding the suffix -operatorFee to the id.

The following is an example of the log written during this step (in this case with commissions enabled):

[BATCHJOBITEM]  Trying to create payment for invoice [70051]
[BATCHJOBITEM]  Payment successfully created for invoice [70051]
[BATCHJOBITEM]  Paid invoices: [70051]

[BATCHJOBITEM]  Trying to create payment for invoice [70051-operatorFee]
[BATCHJOBITEM]  Payment successfully created for invoice [70051-operatorFee]
[BATCHJOBITEM]  Paid invoices: [70051-operatorFee]

Job execution

The connector provides can execute the invoice 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_EXTRACT_INVOICES_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/invoices-extract

Invoices extract job
Param Format Description

name

String

The name of the job

delta

yyyy-MM-dd’T’HH:mm:ss.SSSXXX

The start date for retrieving the invoices

includePaid

Boolean

true to retrieve also the paid invoices, false to retrieve only the unpaid invoices. It’s optional and the default value is false.

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

Configuration variables

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

API calls

The following API calls are made during the invoice extraction job:

Invoice extraction

Call Target System Endpoint Parameters

Retrieve all pending invoices since the last specified date

Mirakl

IV01 - List accounting documents

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

  • status: PENDING

  • states: COMPLETE

  • type: AUTO_INVOICE

Create a payment in Hyperwallet

Hyperwallet

POST /payments

A body is generated from the Mirakl Invoice according to the data mapping rules. The following mappings are specially relevant:

  • clientPaymentId: field invoice_id from Mirakl invoice.

  • amount: field amount_transferred from Mirakl invoice.

Create an operator payment in Hyperwallet

Hyperwallet

POST /payments

A body is generated from the Mirakl Invoice according to the data mapping rules. The following mappings are specially relevant:

  • clientPaymentId: field invoice_id from Mirakl invoice plus the suffix -operatorFee.

  • amount: field amount_transferred_to_operator from Mirakl invoice.

Credit notes extraction

Call Target System Endpoint Parameters

Retrieve all pending credit notes since the last specified date

Mirakl

IV01 - List accounting documents

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

  • status: PENDING

  • states: COMPLETE

  • type: MANUAL_CREDIT

Create a payment in Hyperwallet

Hyperwallet

POST /payments

A body is generated from the Mirakl Invoice according to the data mapping rules. The following mappings are specially relevant:

  • clientPaymentId: field invoice_id from Mirakl invoice.

  • amount: field amount_transferred from Mirakl invoice.

Data mapping

Invoice extraction

Mirakl IV01 API field HW API field Notes

amount_transferred

amount

invoice_id

clientPaymentId

currency_iso_code

currency

TRM token

destinationToken

The seller TRM token denoting the bank account in HW Embedded Experience.

Operator token in the Connector

programToken

Operator token

n/a

purpose: OTHER

We will use OTHER for all payouts.

Credit note extraction

Mirakl IV01 API field HW API field Notes

amount_transferred_to_operator

amount

invoice_id

clientPaymentId

currency_iso_code

currency

TRM token

destinationToken

The seller TRM token denoting the bank account in HW Embedded Experience.

Operator token in the Connector

programToken

Operator token

n/a

purpose: OTHER

We will use OTHER for all payouts.

Troubleshooting

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