Payment

Last update: March 20, 2024

The payment service generates a URL for the payment process on the Oney site for your customers.
Customers redirected to this payment path will be able to fill out the different fields to pay for their orders.

Workflow

To better understand the mechanics of payments at Oney, here is a sequence diagram to understand the workflow

This workflow works with all payment methods offered by Oney (BNPL, Loans..).

Eligibility of Customer

First of all, you need to check whether your customer is eligible for Oney payment method:

Individual customer (BtoC).
A billing and delivery address in the country concerned.
A valid address for the billing and delivery address in the country concerned.
A valid mobile number or landline number in the country concerned.
The amount must be between the minimum and maximum credit limits.

Special cases

In the case of a payment request from a DOM TOM customer, you need to adapt certain fields in the request for it to work with Oney:

delivery/delivery_address/country_code = FRA
delivery/delivery_address/country_label = France
customer/customer_address/country_code = FRA
customer/customer_address/country_label = France
customer/customer_details/mobile_phone_number = Replace the DOM-TOM phone prefix with the FR phone prefix (+33).

Example of Oney payment

When the customer clicks on Oney payment method, you need to send the request (Example below) to Oney API with all mandatory data ( API Explorer ).
If you get a HTTP response code = 200, you will receive the Payment URL in response.
With this payment URL, you can redirect the customer to the Oney form to complete the credit form.

Example with Buy now pay later (BNPL) Payment API V1.1 :

{
  "language_code": "fr",
  "merchant_language_code": "FR",
  "merchant_guid": "24aa0e15db1141b8b1ad76a379bbce21",
  "merchant_context": "Merchant context",
  "purchase": {
    "external_reference_type": "CMDE",
    "external_reference": "IXBJME1GK",
    "purchase_amount": 600,
    "currency_code": "EUR",
    "delivery": {
      "delivery_date": "2023-06-24",
      "delivery_mode_code": 4,
      "delivery_option": 2,
      "priority_delivery_code": null,
      "address_type": 4,
      "delivery_address": {
        "line1": "34 avenue de flandre",
        "postal_code": "59170",
        "municipality": "Croix",
        "country_code": "FRA",
        "country_label": "France"
      }
    },
    "number_of_items": 2,
    "item_list": [
      {
        "is_main_item": 1,
        "category_code": 1,
        "label": "TV",
        "item_external_code": "3OtOsOQZfh",
        "quantity": 2,
        "price": 300,
        "marketplace_merchant_flag": null,
        "marketplace_merchant_name": null
      }
    ]
  },
  "customer": {
    "customer_external_code": "ABCD123",
    "customer_internal_code": null,
    "language_code": "FR",
    "identity": {
      "person_type": "2",
      "honorific_code": "1",
      "birth_name": "Test",
      "last_name": "Test",
      "first_name": "Test",
      "company_name": null
    },
    "contact_details": {
      "landline_number": "0123456789",
      "mobile_phone_number": "0123456789",
      "email_address": "test@test.fr"
    },
    "customer_address": {
      "line1": "34 avenue de flandre",
      "postal_code": "59170",
      "municipality": "Croix",
      "country_code": "FRA",
      "country_label": "France"
    }
  },
  "payment": {
    "payment_amount": 600,
    "currency_code": "EUR",
    "payment_type": 0,
    "business_transaction": {
      "code": "ODOC2"
    }
  },
  "navigation": {
    "success_url": "https://www.exempledomaine.com/success",
    "fail_url": "https://www.exempledomaine.com/fail",
    "server_response_url": "https://www.exempledomaine.com/callback.php"
  }
}

Response of payment service :

{
  "returned_url":"https://hml.e-payments.oney.com/payments/v2/split_payment/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Redirection & Callback

Success

When the customer validates the Oney form, he is redirected to url fill in success_url

Fail

The redirection to the fail_url, will be done in these cases :

Customer click on button "Cancel and returne on merchant website"
Customer waiting too long to fill the form (1h for FR / 20min for others countries)
Customer have an error during form validation

Callback

After synchronious redirection of the customer, you will receive request on url fill in server_response_url If you want to know all about callbacks, see this page : Callback

Adding parameters

You can add parameters to redirect URLs to synchronize data with your systems:

Example :

"navigation": {
    "success_url": "https://www.merchandwebsite.com/order/success?orderid=123&tokenid=123123123&amount=450",
    "fail_url": "https://www.merchandwebsite.com/order/fail?orderid=123&tokenid=123123123&amount=450",
    "server_response_url": "https://www.merchandwebsite.com/order/callback?orderid=123&tokenid=123123123&amount=450"
}

Context

You can provide us with the information you require in the merchant_context and psp_context fields, so that we can include it in the callback request and on the transaction line in the accounting report.

Field name	Description	Type	Length	Presence	Details
`merchant_context`	Merchant data based on the purchase context	String	1000	Optional	Fields returned identically. For France length = 50
`psp_context`	PSP data based on the purchase context	String	1000	Optional	Fields returned identically. For France length = 50

Example of context in request callback

{
  "language_code": "fr",
  "merchant_guid": "your merchant guid",
  "psp_guid": "your psp guid",
  "purchase": {
    "external_reference_type": "CMDE",
    "external_reference": "your purchase reference",
    "status_code": "PENDING",
    "status_label": "Dossier en cours d'étude",
    "customer": {
      "customer_external_code": "your customer reference"
    }
  },
  "merchant_context": "your datas",
  "psp_context": "your datas"
}