Callback

Last update: March 25, 2024

This is a service that you must provide to Oney.

Workflow

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

Requirements

The service must be available 24/7.
The URL must be accessible from the internet.
The URL call is done via the 'POST' method.
The service must be able to accept several notifications for the same order :
- The first to indicate that the file is being studied: "PENDING"
- The second to indicate that Oney has made a decision on the file: "REFUSED" or "FAVORABLE".
The protocol must be HTTPS and you should:
- Use a certificate generated by a recognized certified authority
- Exposes the full chain of the certificate (including the certificate (s) intermediate (s)).
- Inform Oney prior to any change of certificate to ensure the presence of the CA certificate in Oney warehouse.
- Whitelist IP for callback : Please contact us to have the list.

Callback service

It allows Oney to send you notification of the progress of your credit file.

In "Payment" services, you must enter the server_response_url field. It is on this URL you will receive callback from our system.

You'll receive notifications when the credit file is in one of the following states:

PENDING : the customer has completed the subscription and the file is currently being analyzed,
ABORTED : the customer has abandoned the subscription,
REFUSED : Oney has refused the application,
FAVORABLE : Oney has accepted the application.

You will receive a callback no more than 1 hour after the customer has finalized the credit file.
If the first callback has a PENDING status, you will receive another callback when the status change

Response required for Oney callback

You have two options when Oney's callback calling your system. You can either validate the request or send an error :

Treatment is successful : HTTP CODE 204
Processing error : HTTP CODE 500

In case of HTTP CODE 500 our system will retry 2 times to send you the callback request

Example of Oney request

Request of the 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",
    "sub_status_code": "WAITING_ONEY",
    "customer": {
      "customer_external_code": "your customer reference"
    }
  },
  "merchant_context": "your datas",
  "psp_context": "your datas"
}

List of possible status

Case	status_code	status_label (FR)	status_label (EN)
Pending	PENDING	Dossier en cours d'étude	Waiting for Oney acceptance
Favorable	FAVORABLE	La demande de paiement est dans un état favorable pour financement.	Oney accepts the payment
Refused	REFUSED	Dossier refusé	Payment was refused
Aborted	ABORTED	Dossier abandonné	Payment in timeout

On Pending status_code, we add a sub status code to be able to give you more information about step of the payment

status_code	sub_status_code	Details
PENDING	PRE_ACCEPTED	Customer filled the form and validated, waiting document upload
PENDING	WAITING_ONEY	Form of credit file validate by customer, waiting acceptation by Oney

Workflow of status

Sequence of status for Loans

Sequence of status for BNPL

Context

You can provide us with the data in fields merchant_context and psp_context that you wish to receive with the callback.

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 Request

{
  "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",
    "sub_status_code": "WAITING_ONEY",
    "customer": {
      "customer_external_code": "your customer reference"
    }
  },
  "merchant_context": "your datas",
  "psp_context": "your datas"
}