Oney Developer Portal FAQ

Yes, it's the same API for all countries. You will integrate our services by connecting to our latest API version.

Therefore, with each new version of the API, an update will be necessary.

Yes, our API is compatible with all technologies that support RESTful APIs.

The delivery address is limited to 38 characters. However, you can split the information into 2 and/or 3 lines of 38 characters each.
If you are implementing our API 1.2, you are not affected because the limit is 256 characters.

Yes, delivery_address field is mandatory for all kind of delivery.
In the event of collection in a store (physical stores/instore) or at third-party point, it must be entered with the address of the store.

Use the get status service as described to update your pending orders.

The possible values for X-Oney-Partner-Country-Code are:

• BE for Belgium
• ES for Spain
• FR for France
• IT for Italy
• PT for Portugal
• RO for Romania

Find here the available ISO 3166 values.
Oney has one exception for French oversea territories. The X-Oney-Partner-Country-Code of each French overseas departments and territories must be mapped to FR and sent as FR to Oney API.

The possible values for country-code are:

• BEL for Belgium
• ESP for Spain
• FRA for France
• ITA for Italy
• PRT for Portugal
• ROU for Romania

Find here the available ISO 3166 values.
Oney has one exception for French oversea territories. The country-code of each French overseas departments and territories must be mapped to FRA and sent as FRA to Oney API.

The possible values for language_code are:

• NL or FR for Belgium
• ES for Spain
• FR for France
• IT for Italy
• PT for Portugal
• RO for Romania

Find here the available ISO 639 values.

To be able to differentiate between stores in the financial report file (also called CRP file), you can use the merchant_guid field, specific to each entity.

You can also use the merchant_context and PSP_context fields. There are optional fields in our Payment APIs that allow you to name each store whatever you want. Since these are “open” fields, you can include any information you want, as long as you do not exceed a maximum of 50 characters/column. These fields correspond to the content sent in the Payment API and are returned as two different columns in your financial report to help you complete your reconciliation.

For France, there is an additional optional field external_merchant_code, which is designated for the store code. It is entered for France, but only if you provide us with a master list of store codes. The column in your financial report is Ref_ext.

No, you must use one API key per country as we have country-specific limits.

The purchase_amount is the total amount of the cart. It can be paid via several payment methods. For this reason, Oney uses another value, payment_amount, to display only the amount funded by Oney. Keep in mind that Oney always expects purchase_amount >= payment_amount.
This field is removed from our API 1.2

To keep the correct total amount of the cart in the item_list: [Sum of (item_price x quantity) = payment_amount] you must indicate the additional charge or discount.
To do this, add them to the list as a separate item. See example below and our payment API documentation

{...
  "purchase": {
    "external_reference": "c73e8dfe-1b28-44e4-b694-6cc0ed68e1b2",
    "delivery": { ...}},
  "item_list": [
        {
        "type": 1,
        "label": "Materassi Comfort Plus-90 x 190 (cm)",
        "item_external_code": "B-S10-1P",
        "quantity": 2,
        "price": 752.22,
        "unit_discount_amount": 0
        },
        {
        "type": 1,
          "label": "Materassi Comfort Plus-90 x 190 (cm)",
        "item_external_code": "B-S10-1P",
        "quantity": 1,
        "price": 673.82,
        "unit_discount_amount": 0
        },
        {
        "type": 3,
        "label": "delivery_cost",
        "item_external_code": "FEDEX",
        "price": 881.64,
        "quantity": 1,
        "unit_discount_amount": 0
        }
      ]
      },
  "customer": {...},
  "payment": {...},
  "navigation": {...}
}

The main item is the most expensive item in the basket, excluding promotions.
If there are several items with the same price, please indicate is_main_item for the first one.
This field has been removed from our API 1.2.

Yes, we have a test environment for each country. Please find all our Environments and corresponding URLs in our documentation.

No, you cannot. You will receive one API key per country.

The merchant_request_id parameter identifies each request made to the API. It is different from the external_reference field used to only identify orders (purchases) in the system. The merchant_request_id helps us track an event throughout its lifecycle.

Note: Both settings are required in all countries.

Fields mobile_phone_number and landine_number must be formatted in ITU-T E.164 format, [+][country code][subscriber number including area code], for example, France: +33XXXXXXXXX, Spain: +34XXXXXXXXX, etc...

Oney has one exception for French oversea territories. The phone code of each French overseas departments and territories must be mapped to “+33” and sent as “+33” to Oney API.

In step 2 of module configuration, when credentials are saved, they are verified against Oney systems. An error message is displayed if the credentials do not match.

First, clear the browser cache and Prestashop cache, you can clear your store cache in "Advanced Settings" > "Performance".

Finally, check that there are no Javascript errors. If a error is detected, you must correct your code.

If the problem persists, do not hesitate to contact us via your Basecamp.

First, clear the browser cache and Prestashop cache. Additionally, you can clear your store cache in “Advanced Settings” > “Performance”.

Also, check that there are no Javascript errors. If a Javascript error is detected, you must correct your code.

Finally, check that the site's CSS does not affect the pop-in simulation.

If the country tabs on the module configuration page are duplicated, go to “Locations” > “Countries” and deactivate the countries you have duplicates.
This means that the countries you activated have the same ISO code. The ONEY module is based on this ISO code to provide the country tabs and configuration of credentials accordingly.

For more information, please refer to the following documentation and the official website:

• Prestashop 1.6/Countries
• Prestashop 1.7/Countries
• Full list ISO 3166 country codes

We advise you to go to “Advanced Settings” > “Performance” of your Prestashop back-office and click on the “Clear cache” button in the upper right corner of the screen.

When you confirm a shipment, in the module, the Oney module calls the getStatusUpdate URL method to request the status change. The request is scheduled for 2 minutes (site performance issue).
Beyond these 2 minutes if the server was too slow, the Status is not updated in your CMS.

To avoid this, you make a request to your host to ask to renew this request (for example every 2 hours or 1 per day at midnight). Then the statuses will be updated.

Regarding price rounding, you can carry out the following checks:

1. Go to Configure > Store Settings > General and verify that “Number of Decimal Places” is 2.
2. Go to Catalog > Products, in each product, check that all prices are filled with 2 digits after the separator.

In fact, the module does not manipulate any prices. So if Prestashop is configured to send/display a price like: 125.650000001. The Oney module will send: 125.650000001 to our API. The problem has been resolved starting with version 3.x.

This is an API error that is not handled by the module. Do not hesitate to contact us via your Basecamp.

You may encounter an issue with “Friendly URL” not being enabled.

In your Prestashop 1.7 back office, go to Configure > Store Settings > Traffic and SEO. in the SEO and URLs tab, “Friendly URL” must be activated (YES button). Then you can try again. Find more information in the SEO & URLs Prestashop documentation

The Oney module is not compatible with the Prestashop personalized references functionality.

In Prestashop it is possible to modify the entry of the order reference. That said, it is strongly recommended not to associate a cart number (cart id) with an order number (what we call an "external reference"). A risk of phase shift between the module and our systems is present when this functionality is activated.
In addition, for security reasons and non-simultaneous sessions, our module will reset the basket ID as soon as the end customer accesses the Oney form.
This position was taken to compensate for a lack of session management on the Prestashop side. We noticed at the time that with the same session it was possible to validate a single basket for a paltry amount and add items to the order without paying for them.

When the carrier is a delivery company, please use ONLY the parameter nb 5 "Customer delivery address - Carrier (La Poste, Colissimo, UPS, DHL...or any private carrier)" instead of the parameter nb 4 "Customer invoicing - Carrier (La Poste, Colissimo, UPS, DHL...or any private carrier).

Once the customer's order is finalized, Oney only accepts cards issued by banks or financial institutions in the country mentioned in the web contract form. This is a question of legality, as a customer is governed by the rules of their country of residence.

For example, a person residing in Romania and wanting to buy something on an italian website will see the romanian web contract form and all legal notices for that country and will have to pay with a romanian credit card.

A customer can take out a new loan immediately after the previous contract ends.

You cannot modify any personal data or modify the basket, for example, change the model of washing machine or modify a delivery address. the loan itself cannot be modified in any way once financing has been obtained.

However, you can cancel the contract totally or partially. It is also possible for your customer to modify certain personal data via the selfcare portal or via our customer service.

In accordance with the withdrawal right, a customer may cancel a loan within 48 hours of taking out the loan.
For example, this type of situation may arise when there is an incident with your customer due to non-receipt of goods, delivery or after-sales service problems.

Once the 48 hours have elapsed, we expect you to resolve the problem, either by continuing the finance or, in most cases, by sending a full cancellation via our API. You must recover the money by other means if the customer retains the goods.

The 14 days of the withdrawal period begin when the contract is indicated as FUNDED and the end customer has received the instalment schedule.

The link will be valid for 15 minutes. After this period, the contract status will change to ABORTED.

You can:

• click on Resend text in your merchant space to send another link
• provide a new URL link
• issue a QR code to your customer.

Once the financing is approved, the refund request is no longer subject to the 48-hour time limit following the customer's purchase. This can be made within the hour.

Refunds are made within 48 hours for partial cancellations and up to 10 working days for total cancellations.

Indeed, early settlement is a feature facilitated and managed by the Oney system, and no fees are applied for this service.
You can take advantage of the flexibility of settling your account earlier than expected without incurring additional fees.

The deadlines vary from one country to another.

• France: 5 days SLA. In most cases, files are processed the same day, except in the evening and on Sundays.
• Portugal: 2 days SLA.
• Spain: There is no pending status in Spain.
• Italy, Romania, Belgium: 4 hours on working days unless supporting documents are requested.

If Oney Trust requests supporting documents from the client and the client does not respond within 72 hours, the file is automatically rejected.

Yes. If you have different stores, you can receive one CRP file covering all your stores.

To be able to differentiate between stores in the financial report file (also called CRP file), you can use the merchant_guid field, specific to each entity.

You can also use the merchant_context and PSP_context fields. There are optional fields in our Payment APIs that allow you to name each store whatever you want. Since these are “open” fields, you can include any information you want, as long as you do not exceed a maximum of 50 characters/column. These fields correspond to the content sent in the Payment API and are returned as two different columns in your financial report to help you complete your reconciliation.

For France, there is an additional optional field external_merchant_code, which is designated for the store code. It is entered for France, but only if you provide us with a master list of store codes. The column in your financial report is Ref_ext.

Yes, you can make multiple payments using the same IBAN. Oney makes one transfer per store/day.

For France, we can make a single transfer covering all your stores. Currently this service is not available for other countries.

Oney accepts only cards issued by banks or financial institutions in the country named in the web contract form, e.g. cards issued in Romania in the case of a Romanian web contract form. The same goes for all countries. The country in which the credit card was issued must be same as the country named in the form.

The country of the website is irrelevant to the card used or the web contract form displayed to customers. Customers are governed by the rules in their country of residence. We are legally required to display the legal notices applicable in the billing country, and therefore the form is linked to the billing country.
For example, a Romanian resident wanting to buy something on an Italian website will see the Romanian web contract form and all the legal notices for that country.

Yes, you can make multiple payments using the same IBAN.
Oney makes one transfer per store/day.

For France, we can make a single transfer covering all your stores. Currently this service is not available for other countries.

Yes. If you have multiple stores, you can receive a single financial report file that covers them all.

Oney payment processing time is around 2/3 business days.

Yes, it is possible to create several user IDs/profiles and manage their authorizations. Thanks to them, users will be able to access the same merchant area with the corresponding rights.

Once successfully implemented, all updates/patches to the core of the widget are managed by Oney, nothing to do on your side.

If you have activated a paid and free commercial transaction codes, the widget will display the paid financing terms and conditions by default.
However, we will show both simulations for your customers.

There is a specific profile for our widgets which allows many more calls than the usual profiles of our APIs. The widget call quota is 10 000 000 per hour and the rate limit is 500 every 5 seconds.

In this case, you will not be in charge of the integration of the widget. The PSP will have to do this for you.

You have 21 days to confirm that the order has been shipped once financing has been accepted by Oney with a FAVORABLE contract status.

You will receive an error message if you cancel after the deadline. For the French market, for example, error 409 states: "Le délai d'annulation maximum est dépassé pour réaliser l'annulation après financement" ("The maximum period has been exceeded to cancel after financing"). All error messages are translated in the local language of the country.

Once your customer has obtained financing, you can cancel for a period of 13 months for all countries starting in September 2022.
If you attempt to cancel after the deadline, you will receive an error message.

You will receive a 409 error message if you cancel after the deadline. You can find this information in our API documentation in Service Cancel ERR_20 with other cancellation error types.

All error messages are translated into the local language of the country. For example for France, Error 409: "Le délai d'annulation maximum est dépassé pour réaliser l'annulation après financement"/"The maximum period has been exceeded to cancel after financing".

You have 21 days to confirm that the order has been shipped once financing has been accepted by Oney with a FAVORABLE contract status.

We recommend you to provide in the Payload the right URL (in the field server_response_url), to whitelist IPs of Oney's server and double-check you API keys.

Please find more informations at callback in our documentation.