If you have already integrated our core Advance concept to make payments, you may have noticed in our docs that we replaced it with two new concepts. In this guide, we will answer questions you may have about this change. Everything is documented through our guide and the API reference:

• Invoice guide
• Loan guide
• API reference

Our reasons for making this change

A better API

As written on our website, Aria is about invoice financing. Invoice and Loan concepts are therefore more in line with how we process loans and payments:

• Invoice represents the sales invoice you want us to fund
• Loan is the payment Aria makes, that you have to repay

Sometimes, our clients have several Loans they want us to pay, linked to one Invoice. That's why this new change makes a lot of sense for you, and for us.

We also took the opportunity to make endpoints clearer to understand. We got a lot of questions and feedback about the Advance concept: What is a duration ? Why milliseconds ? What is this "PENDING" status? We have taken them all into account to improve our API.

Separated attachments

From now on, it will be easier for you and for us to identify if an uploaded document is a sales invoice (now stored in Invoice endpoint) or a purchase invoice (Loan endpoint). No more messy lists of documents in a single endpoint.

Security checks

You asked how we ensured that an invoice was not funded twice, and the answer was pretty simple: Until then, we were doing this check manually. With the new system, we will programmatically forbid the creation of two Invoices having the same Invoice number. Also, with Invoices & Loans, we now collect the amount of the sales invoice, and will automatically check if the payment asked is larger than the Invoice amount (with taxes) to prevent wrong payments.

These new rules represent essential security control to avoid mistakes.

End of Advance and breaking changes

Advance endpoints will still work until the week of September 4, 2023. From this date, they will no longer work.

There won't be any breaking change: Advance endpoints and webhooks will run until September, 2023.

Migration guide

It is "just" a data split

The main work you will have to do is splitting the data you were sending through Advance in two new separated endpoints.

Every information you were sending using Advance endpoints will still be required when creating an Invoice and a Loan.

Here is the new workflow:

1. Create an Invoice
2. Create as many Loans as you want, and link them to the invoice with the invoiceId param

Invoices and Loans creation now require an application/json format.

Advance inputs: migration

Advance outputs: migration

Bills are now Attachments

bills you were uploading when creating an Advance are now splitted in two ways, in Invoice and Loan. You have to use the upload endpoint to get an url and setting it in an Invoice or a Loan. See our guides and API reference to understand where to put your files.

Some params are now required

You will see a lot of required params that were optional during Advance creation. Carefully read our API reference before implementing our new endpoints.

Simpler list of endpoints

We did not recreate the same list of endpoints: To list Loans for example, you now have one single endpoint: List Loans. If you want to get Loans of a specific User, you need to use our filters. Same rules for Invoice: List Invoices.

Webhooks

You can now subscribe to loan.xxx webhooks. Since Invoices have no status because they "just" represent the proof of sale that has been concluded, we do not propose Invoice webhooks (yet). Advances webhooks will still work until September, 2023, with no breaking change. You may find the payload for Loan webhooks in our guide.

Additional information

• userId is now required as a body params when creating a Loan (vs. path params)
• duration is now called repaymentPeriod and has to be sent in days format (30, 45, 60, ...)
• Company advanceDurations are now returned as a repaymentPeriodOptions, in days. advanceDurations are still supported, until September, 2023.
• dueDate is now stored in Invoice and will still be calculated using the invoiceDate.
• Credit limits and repayments are still related to advance payments, now called Loan.
• Loans status list has changed, read our guides to implement their new names:

For other rules related to each endpoint, please read our Loan and Invoice guides.

Advance - Backward compatibility

Introduction

Releasing Invoices and Loans endpoints forces us to set some rules to maintain backward compatibility for Advances. 99% of the time, you wont see any difference when creating an Advance after our release.

Some quirks

• When CREATING an Advance with an invoiceNumber that is already mentioned on an other Advance, we wont use filled params related to the Invoice (customerName, customerSiren, debtorName, debtorIdentifierType, debtorIdentifierValue, duration). We will use params of the Advance that was already created with this invoiceNumber.
• When CREATING an Advance, we automatically create an Invoice with data we compute or retrieve from the Advance. For example, the created Invoice will have a totalAmountIncludingTaxes that will be incremented each time you create an advance that as a shared invoiceNumber.

Advance output

{
    "id": "e053572d-cc30-4259-acc4-9d97ec1898ca",
    "createdAt": "2022-10-25T09:03:18.407Z",
    "updatedAt": "2022-10-25T09:03:18.407Z",
    "userId": "634ade8bfa6b0c22fc53be0c7",
    "companyId": "6215f335ac79d55a2g1c1fcb",
    "invoiceId": "01e22681-ff71-455a-9d01-9e9e61a88000",
    "amount": 200,
    "currency": "EUR",
    "status": "PROCESSING",
    "repaymentReference": "s52CH2HK",
    "IBAN": "FR7641539000711111111111123",
    "label": "payment-123",
    "debtorName": "Acme",
    "debtorIdentifier": {
        "type": "siren",
        "value": "12345678",
        "country": "FR"
    },
    "billDate": "2022-10-22T06:00:00.000Z",
    "dueDate": "2022-11-21T06:00:00.000Z",
    "duration": 2592000000,
    "attachments": [],
    "isInvoiceDataReliable": false
}

• If an Invoice (created automatically) miss some required information as some related Advance params were optional until then, we will still set UNKNOWN_FIELD_NAME on the related Invoice field.

Invoice output

{
    "id": "01e22681-ff71-455a-9d01-9e9e61a88000",
    "createdAt": "2022-10-25T09:36:38.286Z",
    "updatedAt": "2022-10-25T09:36:38.286Z",
    "currency": "EUR",
    "totalAmountIncludingTaxes": 200,
    "totalAmountExcludingTaxes": 160,
    "debtorIdentifier": {
        "type": "siren",
        "value": "12345678",
        "country": "FR"
    },
    "debtorName": "Acme",
    "invoiceNumber": "UNKNOWN_INVOICE_NUMBER",
    "repaymentPeriod": 30,
    "invoiceDate": "2022-10-22T06:00:00.000Z",
    "dueDate": "2022-11-21T06:00:00.000Z",
    "companyId": "6215f335ac79d55a2g1c1fcb",
    "attachments": []
}

• When you PATCH an Advance that has a shared invoiceNumber with other Advances, every information related to the invoice (customerName, customerSiren, debtorName, debtorIdentifierType, debtorIdentifierValue, duration) will be patched on other Advances as well.
• For every Advance you created with Bill(s), we will set these attachments automatically in a Loan. If you only upload one Bill, the attachment will also be set on the Invoice.

❗

Patching an Advance will now be impossible if it was created through Loan endpoints.

Conclusion

If you have a question, a problem while integrating your new endpoints, or a feedback to share, please feel free to contact us: [email protected].