Skip to main content
API docs by Redocly

Order API v2 (2.0.0)

Download OpenAPI specification:Download

API Support: it@nemuru.com

Introduction

The Order API is used for handling an order after the customer has completed the purchase and the order is confirmed. It is used for all actions you need to manage your orders. Examples being: capturing, reading and refunding an order.

Any capture (shipment) or refund must refer to one or more lines of the cart through their identifiers (item IDs). For this reason, it is necessary to first obtain the order information and retrieve the item IDs from the cart. Check the Order section for more information on how to read the order details.

On another note, bear in mind that not all lenders process captures or refunds in real time. For this reason, you will request a capture or refund and you will receive a server-side callback once the action is processed and confirmed by the corresponding lender. For more information, check the Capture and Refund section on this document.

Errors

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:

400 Bad Request

{
    "status": "ko",
    "exception": "Nemuru\\SharedKernel\\Domain\\Exception\\SchemaValidatorException",
    "error": "Schema validation failed",
    "schema_errors": {
        "/product": "The product you selected is not a valid. Possible choices: {'split_pay', 'instalments'}.",
        "/merchant/notification_auth": "The required properties (content_type) are missing",
        "/customer/birth_date": "The data must match the 'date-time-atom' format",
        "/customer/logged_in": "The data (string) must match the type: boolean",
        "/cart": "The required properties (currency) are missing"
    }
}

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

Code Label Description
200 OK The target resource was successfully found.
201 Created The target resource was successfully created.
204 No content The target resource was successfully modified.
400 Bad Request Some input property does not meet the expected validation.
401 Unauthorized The access token used has expired or is invalid.
403 Forbidden The user’s credentials are not authorized to consume the target service.
404 Not Found The target resource was not found.
409 Conflict There was a conflict with the current state of the target resource.
410 Gone The target resource is no longer available.
500 Internal Error The server encountered an unexpected condition that prevented it from fulfilling the request.
502 Bad Gateway Error The service received an invalid response from the upstream server.
504 Gateway Timeout The service did not get a response in time from the upstream server that it needed in order to complete the request.

Authentication

Login

Retrieve an access token with your username and password, which will be needed in following requests.

Request Body schema: application/json

Login

username
required
string
Example: "username@email.com"

Username

password
required
string
Example: "12345"

Password

Responses

Request samples

Content type
application/json
{
  • "username": "username@email.com",
  • "password": "12345"
}

Response samples

Content type
application/json
{
  • "token_type": "Bearer",
  • "access_token": "1857fdb2-c746-44f9-88a8-507a855fe920",
  • "refresh_token": "f9131f93-5e64-461e-8493-0fb8cb76f31d",
  • "expires_in": 2678400
}

Order

Create order

Create order. If successful, within the response headers you'll find the order_id (key Id), needed in other requests / widgets.

header Parameters
Authorization
required
string
Example: Bearer 1857fdb2-c746-44f9-88a8-507a855fe920

The Authorization header must include Bearer <access_token>. See the authentication section.

Request Body schema: application/json

Order object

product
required
string
Enum: "split_pay" "instalments"
Example: "instalments"

Financial product. Allowed values for this field will depend on the commercial agreement; please contact us when in doubt.

period
integer
Example: 3

Optional Loan's period in months. If informed, this value will be presented to the customer as the default period in the Checkout widget. If not informed, the default period will be the largest period available for the selected product, thus minimizing the monthly payment. In any case, the customer will be able to change the period in the Checkout widget. Allowed values for this field will depend on the commercial agreement; please contact us when in doubt.

purchase_country
string
Enum: "ESP" "FRA"
Example: "ESP"

Optional purchase country of the customer. If not informed, the default value will be the default merchant's purchase country.

client_id
string
Example: "26241e4c-d179-484f-8a43-bf827423df32"

Optional clientId. This is particularly useful when managing orders across different sales accounts under a single set of credentials. If you are using a unique set of credentials (username and password) for authenticating requests, but have multiple sales accounts (i.e., multiple clientId), use this field to specify in which account this Order should be created.

required
object (Merchant)

Merchant information

required
object (Customer)

Customer information

object (Shipping)

Shipping information

object (Billing)

Billing information

required
object (ProductArticleRequest)

Product cart information

Responses

Request samples

Content type
application/json
Example
{
  • "product": "instalments",
  • "merchant": {
    },
  • "customer": {
    },
  • "shipping": {
    },
  • "billing": {
    },
  • "cart": {}
}

Confirm or put on hold

Confirm or put on hold the Order

path Parameters
order_id
required
string <uuid>
Example: d0f39699-fd10-4da2-a622-be6714dadaf9

Order ID

header Parameters
Authorization
required
string
Example: Bearer 1857fdb2-c746-44f9-88a8-507a855fe920

The Authorization header must include Bearer <access_token>. See the authentication section.

Request Body schema: application/json

Order object

status
required
string
Enum: "confirmed" "on_hold"
Example: "confirmed"
  • confirmed when the merchant receives an approved notification from Nemuru and proceeds to confirm the order
  • on_hold when the merchant receives an on_hold notification by Nemuru and proceeds to place the order on_hold
product
required
string
Enum: "split_pay" "instalments"
Example: "instalments"

Financial product. Allowed values for this field will depend on the commercial agreement; please contact us when in doubt.

required
object (Merchant)

Merchant information

required
object (Customer)

Customer information

object (Shipping)

Shipping information

object (Billing)

Billing information

required
object (ProductArticleRequest)

Product cart information

Responses

Request samples

Content type
application/json
Example
{
  • "status": "confirmed",
  • "product": "instalments",
  • "merchant": {
    },
  • "customer": {
    },
  • "shipping": {
    },
  • "billing": {
    },
  • "cart": {
    }
}

Get order details

Get order details by order_id.

path Parameters
order_id
required
string <uuid>
Example: d0f39699-fd10-4da2-a622-be6714dadaf9

Order ID

header Parameters
Authorization
required
string
Example: Bearer 1857fdb2-c746-44f9-88a8-507a855fe920

The Authorization header must include Bearer <access_token>. See the authentication section.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "payload": {
    }
}

Capture

Capture

Initiate a capture. Nemuru processes the capture request with the corresponding lender. Upon completion, Nemuru will notifiy you about the lender confirmation by sending a order_capture_created notification event (see notification documentation here). The capture can be optionally accompanied by a description.

Capture by items

Specify which items you wish to capture. Prior to initiating a capture, call the order details endpoint to get the item ids and include them within the captured_item_ids key.

Transactional

To avoid asynchronies (awaiting the order_capture_created notification), you can initiate and process the capture transactionally with the lender by making use of the transactional field within the request.

path Parameters
order_id
required
string <uuid>
Example: d0f39699-fd10-4da2-a622-be6714dadaf9

Order ID

header Parameters
Authorization
required
string
Example: Bearer 1857fdb2-c746-44f9-88a8-507a855fe920

The Authorization header must include Bearer <access_token>. See the authentication section.

Request Body schema: application/json

Capture object

description
string
Example: "This is an optional description for this capture"

Optional description about the capture

captured_item_ids
required
Array of strings <uuid>
Example: ["16d63625-1390-4401-9427-fe5dd1de981c"]

List of item IDs to be captured (cart lines)

transactional
boolean

Use this field if you need to avoid any asynchronies. If true, the capture request will be sent transactionally to the lender. In other words, before you obtain a response, Nemuru will request the capture to the corresponding lender and the response code you obtain from this request will include the lender's decision:

  • 201 the capture is confirmed by the lender.
  • 410 the capture is rejected by the lender.

Responses

Request samples

Content type
application/json
Example
{
  • "description": "Optional description for transactional capture",
  • "captured_item_ids": [
    ],
  • "transactional": true
}

Capture full order

Initiate a full order capture, which will capture all the items included within the order. Nemuru processes the capture request with the corresponding lender. Upon completion, Nemuru will notifiy you about the lender confirmation by sending a order_capture_created notification event (see notification documentation here). The capture can be optionally accompanied by a description.

Transactional

To avoid asynchronies (awaiting the order_capture_created notification), you can initiate and process the capture transactionally with the lender by making use of the transactional field within the request.

path Parameters
order_id
required
string <uuid>
Example: d0f39699-fd10-4da2-a622-be6714dadaf9

Order ID

header Parameters
Authorization
required
string
Example: Bearer 1857fdb2-c746-44f9-88a8-507a855fe920

The Authorization header must include Bearer <access_token>. See the authentication section.

Request Body schema: application/json

Capture object

description
string
Example: "This is an optional description for this capture"

Optional description about the capture

transactional
boolean

Use this field if you need to avoid any asynchronies. If true, the capture request will be sent transactionally to the lender. In other words, before you obtain a response, Nemuru will request the capture to the corresponding lender and the response code you obtain from this request will include the lender's decision:

  • 201 the capture is confirmed by the lender.
  • 410 the capture is rejected by the lender.

Responses

Request samples

Content type
application/json
Example
{
  • "description": "Optional description for transactional capture",
  • "transactional": true
}

Refund

Refund

Initiate a refund of a captured order. Nemuru processes the refund request with the corresponding lender. Upon completion, Nemuru will notifiy you about the lender confirmation by sending a order_refund_created notification event (see notification documentation here). The refund can be optionally accompanied by a description.

Refund by items

Specify which items you wish to refund. Prior to initiating a refund by items, call the order details endpoint to get the item ids and include them within the refunded_item_ids key. Important: the refunded items must have been previously captured.

Refund by amount

If you opt for refunding an amount, instead of specific items in the cart, you can do so by excluding the refunded_item_ids key and including the refunded_amount key within the request body, specifying the amount to refund. Important: the refunded amount must not be higher than the total captured amount.

Transactional

To avoid asynchronies (awaiting the order_refund_created notification), you can initiate and process the refund transactionally with the lender by making use of the transactional field within the request.

path Parameters
order_id
required
string <uuid>
Example: d0f39699-fd10-4da2-a622-be6714dadaf9

Order ID

header Parameters
Authorization
required
string
Example: Bearer 1857fdb2-c746-44f9-88a8-507a855fe920

The Authorization header must include Bearer <access_token>. See the authentication section.

Request Body schema: application/json

Refund object

description
string
Example: "This is an optional description for this refund"

Optional description about the refund

refunded_item_ids
required
Array of strings <uuid>
Example: ["16d63625-1390-4401-9427-fe5dd1de981c"]

List of item IDs to be refunded (cart lines).

refunded_amount
number
Example: 200

Amount to be refunded. You must exclude the refunded_item_ids from the body of the request if you use refunded_amount.

transactional
boolean

Use this field if you need to avoid any asynchronies. If true, the refund request will be sent transactionally to the lender. In other words, before you obtain a response, Nemuru will request the refund to the corresponding lender and the response code you obtain from this request will include the lender's decision:

  • 201 the refund is confirmed by the lender.
  • 410 the refund is rejected by the lender.

Responses

Request samples

Content type
application/json
Example
{
  • "description": "Optional description for transactional refund by items",
  • "refunded_item_ids": [
    ],
  • "transactional": true
}

Notification

Notification

Nemuru sends notifications to your notification_url, specified by you when creating the order, in order to let your systems know about the following events:

  • Order status changes (order_status_changed)
  • Capture confirmed by the lender (order_capture_created)
  • Refund confirmed by the lender (order_refund_created)
Request Body schema: application/json

Notification object

order_id
string <uuid>
Example: "e60fb9d8-97d4-4653-bc7e-d49b203a6980"

The order ID

order_reference_1
string
Example: "76t7y7sau8y398y"

Identifier of the order in your (the merchant) environment.

event
string
Enum: "order_status_changed" "order_capture_created" "order_refund_created"
Example: "order_status_changed"

Name of the event

triggered_at
string
Example: "2022-06-30T09:42:15+00.00"

Timestamp when the event was created (valid 8601 timestamp format)

status
string
Enum: "approved" "on_hold" "confirmed" "denied" "cancelled" "expired" "desisted"
Example: "approved"

Order status

Responses

Request samples

Content type
application/json
Example
{
  • "order_id": "e60fb9d8-97d4-4653-bc7e-d49b203a6980",
  • "order_reference_1": "76t7y7sau8y398y",
  • "event": "order_status_changed",
  • "triggered_at": "2022-06-30T09:42:15+00.00",
  • "status": "approved"
}