Point-of-sale financing (either in store or remote) is initiated by the merchant: the seller initiates the financing application by selecting a product (consumer loan, credit line, etc.) and setting the conditions (loan principal, term, instalment amount, etc.). After introducing the customer’s contact information, the financing application is generated and the link to the digital onboarding is sent off to the customer. The customer completes the onboarding process, either in-store or remotely, and the financing application is distributed amongst Nemuru’s pool of lenders, thus maximising the approval rate.

To create a financing invitation (Create loan) it is necessary to provide three types of information: loan conditions, contact details about the customer (borrower), and asset details. Prior to this, it might be necessary to check the available loan conditions for an specific amount and term. Your agent id is also required, which you can obtain from the Get agent profile use case, after having obtained an access token using the Login use case. Once a loan is created, it is possible to check its details and status in a couple of ways: (1) get the loan details on demand by calling the Get loan by id use case, or (2) Create a webhook to get notifications about all loan status changes automatically If needed, you can use the Upload documentation use case to upload files and documents for an specific loan.

To sum up, this is the list of requests that are typically needed for integrating Nemuru for in-store / remote financing:

• Login
• Get agent profile (optional, if you already know your agent id)
• Get loan conditions (optional, if you already know your pricings)
• Create loan
• Upload documentation (optional, if documentation upload by the merchant is not needed)
• Get loan by id (optional, if you have a webhook already created)
• Create a webhook (optional, if you don't use webhooks)

Nemuru's APIs use HTTP status codes together with error objects to handle errors. When an API call fails, the response will include a 4xx or 5xx status code together with a response body.

The error object MUST contain an exception and an error property. ONLY in case of 400 Bad Request error, the schema_errors property will also be present:

• The exception is a path referring to the unique and enumerable error that occurred in Nemuru. The intent of this property is that it is machine readable and so that you can act properly on its value.
• The error is the message that accompanies Nemuru's exception. It's value is a human readable message to aid in debugging.
• The schema_errors returns an object indicating invalid fields in the request. This property is ONLY available when an API call returns a status 400 Bad Request —the request data do not comply with the scheme validation.

Examples

A few examples of error response bodies:

404 Not Found

{
    "status": "ko",
    "exception": "Nemuru\\Module\\Financial\\Domain\\Loan\\Exception\\LoanNotFoundByIdException",
    "error": "\\Loan\\ with id \\c7d07661-8644-425e-91e0-afdcaef6f8d9\\ not found"
}

Status codes

A Webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately.

Webhooks are an effective way to get information as it happens, rather than continually polling for that data.

State

Webhooks can be enabled or disabled. By default, webhooks are always enabled.

• Enabled: 1
• Disabled: 2

Client

The notification can be sent to an email address (email) or posted to an endpoint (callback).

• Email: email
• Callback: callback

Callbacks

In case the response was a callback, the payload for each type of event would vary:

// loan_steps
{
  "id": "e7c52ad3-0473-4fbc-bc36-7eb755b1c18d",
  "event": "loan_steps",
  "step": "status_opened",
  "triggered_at": "2020-06-18T00:00:00+00:00"
}

where:

• id: the loan id
• event: the event name (loan_steps by default)
• triggered_at: timestamp of the event

Loan steps

Authentication

Webhook callbacks can use multiple authentication methods. The authentication information has to be provided by you at the moment of creating the webhook.

• No authentication

• Authorization header: callbacks will include a static authorization token in the header, tipically used for basic authentication applications. Independent of the authentication scheme, the full header has to be provided by you. For example, if you wish to apply a Basic Authorization header, you should provide 'authorization_header': 'Basic bG9sOnNlY3VyZQ==' and 'content_type': 'application/json'.

• OAuth 2.0: callbacks will use an OAuth 2.0 authentication scheme. For this, a specific user should be created in your resource server and it will be necessary for you to provide the url (= token url), client_id, client_secret, username, and password of the client, at the moment of creating the webhook.