nav

Laybuy Merchant API

Integration Flow

Merchant Integration Flow

Flow Description

  1. From the checkout process on the Merchant Site, the customer chooses to pay with Laybuy.
  2. The Merchant Server creates a new Laybuy order by making a request to the Laybuy API and passing the order details.
  3. If the request fails, an error is displayed on the Merchant Site.
  4. If the request is successful, the Laybuy API returns a payment token and the payment URL. The token can be stored by the Merchant Server, and the customer is redirected to the payment URL to begin the payment process.
  5. The customer proceeds through the payment process on the Laybuy Payment site.
  6. When the payment process is completed, the customer is redirected to the return URL.
  7. If the payment failed, an error is displayed on the Merchant Site.
  8. If the payment is successful, then when the customer and merchant are ready to complete the order process then the Merchant Server will attempt to confirm the payment by making a request to the Laybuy API.
  9. If the confirmation failed, an error is displayed on the Merchant Site.
  10. If the confirmation was successful, the customer is shown an order confirmation page on the Merchant Site.

API Endpoints

Production

https://api.laybuy.com/

Sandbox

https://sandbox-api.laybuy.com/

Authentication

The Laybuy API uses Basic Authentication, where the username is your merchant ID and the password is your API key. These details are available from the merchant interface.

Example Requests
curl 'https://api.laybuy.com/order/create' -u '{merchantId}:{apiKey}'
<? $authHeader = 'Authorization: Basic ' . base64_encode($merchantId . ':' . $apiKey); ?>

Requests

The Laybuy Merchant API is REST-based.

Accepts and returns only JSON data.

All communication must be completed securely using HTTPS.



Operations

Create Order

Overview

This method allows merchants to define a Laybuy order and create a new payment process. If successful, the merchant should store the token within their system and redirect the customer to the payment URL provided in the response in order to initiate the payment interface.

When a new order is created, any active orders for the same customer (based on the email address) for the merchant will be cancelled. Any further interactions with any cancelled order will result in an error.

If the customer's order changes on the merchant site after the Laybuy order is created, the merchant should restart the process by creating a new order.

End Point

POST https://api.laybuy.com/order/create

Request Data

The following table shows the request fields that can be sent to the interface. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.

Important: The return URL option should contain the relative or absolute URL to access once the payment process is completed. If a relative URL is specified, it will be prepended with the return host configured for the merchant. This URL will be amended automatically with the relevant result parameters for an order.

Field Description Required Type (Length)
amount The total for the customer to pay. Yes Decimal
currency The currency of the amount. If not specified, the currency of the merchant is used. No String (3)
returnUrl The relative/absolute URL to redirect the customer to once the payment process is completed. No String (255)
merchantReference The merchant's unique reference for the order. Yes String (50)
tax The amount of tax contained within amount. Yes / No* Decimal
customer Container for the customer details. Yes Object
    firstName The customer's first name. Yes String (100)
    lastName The customer's last name. Yes String (100)
    email The customer's email address. Yes String (150)
    phone The customer's phone number. Yes String (20)
billingAddress Container for the billing address. No Object
    name The billing contact's full name. If not specified, the customer's first and last name is used. No String (200)
    phone The billing contact's phone number. If not specified, the customer's phone number is used. No String (20)
    address1 The first line of the billing address. No String (150)
    address2 The second line of the billing address. No String (150)
    suburb The suburb of the billing address. No String (100)
    city The city of the billing address. No String (100)
    state The state of the billing address. No String (100)
    postcode The postcode of the billing address. No String (20)
    country The country of the billing address. If not specified, New Zealand is used. No String (100)
shippingAddress Container for the shipping address. No Object
    name The shipping contact's full name. If not specified, the customer's first and last name is used. No String (200)
    phone The shipping contact's phone number. If not specified, the customer's phone number is used. No String (20)
    address1 The first line of the shipping address. No String (150)
    address2 The second line of the shipping address. No String (150)
    suburb The suburb of the shipping address. No String (100)
    city The city of the shipping address. No String (100)
    state The state of the shipping address. No String (100)
    postcode The postcode of the shipping address. No String (20)
    country The country of the shipping address. If not specified, New Zealand is used. No String (100)
items Container for the items. Yes Array
    ... A single item being purchased. Yes Object
        id The merchant's unique identifier (id, PLU/SKU, barcode, etc.) for the product. Yes String (20)
        description The description of the product. Yes String (150)
        quantity The quantity being purchased. Yes Integer
        price The unit price of the product. Yes Decimal

* Tax is required for merchants outside of Australia and New Zealand.


Example Request (Typical)

{
	"amount":156.90,
	"currency":"NZD",
	"returnUrl":"https://www.merchantsite.com/confirm-payment?i=7437377",
	"merchantReference":"17125026",
	"customer": {
		"firstName":"Jenny",
		"lastName":"Smith",
		"email":"jenny.smith@laybuy.com",
		"phone":"0219876543"
	},
	"billingAddress": {
		"address1":"123 Crown Street",
		"city":"Auckland",
		"postcode":"1010",
		"country":"New Zealand",
	},
	"shippingAddress": {
		"name":"Timmy Smith",
		"address1":"Level 4, Goodsmiths Building",
		"address2":"123 Crown Street",
		"suburb":"Redvale",
		"city":"Auckland",
		"postcode":"1010",
		"country":"New Zealand",
		"phone":"097654321"
	},
	"items":[
		{
			"id":"4470356028717",
			"description":"Blue Widget",
			"quantity":2,
			"price":76.95
		},
		{
			"id":"SHIPPING",
			"description":"Shipping",
			"quantity":1,
			"price":3.00
		},
	]
}

Response Data

The following table shows the response fields returned by the interface.

Field Description
result The result of the API request. Either ERROR or SUCCESS.
error A description of the error. Populated when the result is ERROR.
token The Laybuy payment token for the payment. Populated when the result is SUCCESS.
paymentUrl The URL to use that begins the Laybuy payment process. Populated when the result is SUCCESS.

Example Response - Error

{
	"result":"ERROR",
	"error":"Amount is below the minimum"
}

Example Response - Success

{
	"result":"SUCCESS",
	"token":"frOilqUU0DboUCiyRtnzH1VdBXnrj7kD39NWhgsD",
	"paymentUrl":"https://payment.laybuy.com/pay/frOilqUU0DboUCiyRtnzH1VdBXnrj7kD39NWhgsD"
}

Cancel Order

Overview

This method allows merchants to explicitly cancel the payment process for an unconfirmed Laybuy order.

End Point

GET https://api.laybuy.com/order/cancel/{token}

Response Data

The following table shows the response fields returned by the interface.

Field Description
result The result of the API request. Either ERROR, or SUCCESS.
error A description of the error. Populated when the status is ERROR

Example Response - Error (General)

{
	"result":"ERROR",
	"error":"Invalid payment token specified."
}

Example Response - Error (Order Completed)

This response will be returned if the order has already been successfully completed by the customer, in which case the order can not be cancelled.

{
	"result":"ERROR",
	"error":"The order has already been completed."
}

Example Response - Successfully Cancelled

This response will be returned if the order was successfully cancelled. The customer will not be able to continue with the payment process.

{
	"result":"SUCCESS"
}

Confirm Order

Overview

This method allows merchants to confirm the payment process, resulting in a finalised Laybuy order.

If the customer's order has changed on the merchant site since the Laybuy order was created, the merchant should restart the process by creating a new order.

End Point

POST https://api.laybuy.com/order/confirm

Request Data

The following table shows the request fields that can be sent to the interface. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.

Important: Merchants have three options when confirming an order, depending on the level of validation required against the original order that was sent to Laybuy. Merchants can specify:
- The payment token only, or
- The payment token and payment amount, or
- The payment token, payment amount, and order items

Using the appropriate option allows the merchant to offload some of the logic required to handle changes to an order while the Laybuy payment process is active.

Important: This method is idempotent for a limited period. Duplicate requests to confirm an single order (by payment token) will return the same response for a period, after which any duplicate requests will result in an error.

Field Description Required Type (Length)
token The payment token. Yes String (40)
amount The total for the customer to pay. No Decimal
currency The currency of the total. If not specified, NZD is used. New Zealand Dollars (NZD) and Australian Dollars (AUD) are currently the only currencies supported. No String (3)
items Container for the items. No Array
    ... A single item being purchased. No Object
        id The merchant's unique identifier (id, PLU/SKU, barcode, etc.) for the product. No String (20)
        description The description of the product. No String (150)
        quantity The quantity being purchased. No Integer
        price The unit price of the product. No Decimal

Example Request - Token Only

Specifying only the payment token will bypass any additional checks. The amount from the original order will be assumed to be correct, and that the order items have not changed.

{
	"token":"frOilqUU0DboUCiyRtnzH1VdBXnrj7kD39NWhgsD"
}

Example Request - Token and Amount

Specifying the amount will cause an additional check to ensure that the amount specified matches the amount on the original order.

{
	"token":"frOilqUU0DboUCiyRtnzH1VdBXnrj7kD39NWhgsD",
	"amount":79.95,
	"currency":"NZD"
}

Example Request - Token, Amount, and Items

Specifying the amount and items will cause additional checks to ensure that the amount specified matches the amount on the original order, and that the order items have not changed (exclusing changes to item descriptions).

{
	"token":"frOilqUU0DboUCiyRtnzH1VdBXnrj7kD39NWhgsD",
	"amount":79.95,
	"currency":"NZD"
	"items":[
		{
			"id":"4470356028717",
			"description":"Blue Widget",
			"quantity":2,
			"price":76.95
		},
		{
			"id":"SHIPPING",
			"description":"Shipping",
			"quantity":1,
			"price":3.00
		},
	]
}

Response Data

The following table shows the response fields returned by the interface.

Field Description
result The result of the API request. Either DECLINED, SUCCESS or ERROR.
error A description of the error.
orderId The Laybuy order id. Populated when the status is SUCCESS.

Example Response - Error

{
	"result":"ERROR",
	"error":"Invalid payment token specified"
}

Example Response - Error (Insufficient Funds)

{
	"result":"DECLINED",
	"error":"The payment was declined"
}

Example Response - Success

{
	"result":"SUCCESS",
	"orderId":100036
}

Get Order

Overview

This method allows merchants to retrieve the details of a Laybuy order.

End Points

GET https://api.laybuy.com/order/{orderId}

GET https://api.laybuy.com/order/merchant/{merchantReference}

Response Data

The following table shows the response fields returned by the interface.

Field Description
result The result of the API request.
error A description of the error, if one occurred.
orderId The Laybuy order id.
token The Laybuy payment token for the order.
amount The total paid by the customer.
currency The currency of the order total.
merchantReference The merchant's order reference.
processed The date/time that the order was processed.
customer Container for the customer details.
    customerid The Laybuy customer id.
    firstname The customer's first name.
    lastname The customer's last name.
    email The customer's email address.
    phone The customer's phone number.
    dateOfBirth The customer's date of birth in the format YYYY-MM-DD
    address1 The first line of the customer's address.
    address2 The second line of the customer's address.
    suburb The suburb of the customer's address.
    city The city of the customer's address.
    state The state of the customer's address.
    postcode The postcode of the customer's address.
    country The country of the customer's address.

Example Response - Error

{
	"result":"ERROR",
	"error":"Order not found"
}

Example Response - Success

{
	"result":"SUCCESS",
	"orderId":100049,
	"token":"frOilqUU0DboUCiyRtnzH1VdBXnrj7kD39NWhgsD",
	"amount":164.59,
	"currency":"NZD",
	"merchantReference":"1728950142",
	"processed":"2017-02-01 14:35:30",
	"customer":{
		"customerid":143022,
		"firstname":"Jenny",
		"lastname":"Smith",
		"email":"jenny.smith@laybuy.com",
		"phone":"0219876543",
		"dateOfBirth":"1965-06-27",
		"address1":"Level 4, Goodsmiths Building",
		"address2":"123 Crown Street",
		"suburb":"Redvale",
		"city":"Auckland",
		"postcode":"1010",
		"country":"New Zealand"
	}
}

Refund Order

Overview

This method allows merchants to wholly or partially refund a Laybuy order.

End Point

POST https://api.laybuy.com/order/refund

Request Data

The following table shows the request fields that can be sent to the interface. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional.

Important: If specified, the refund reference must be unique across all of a merchant's refunds. This method is idempotent when a refund reference is provided, meaning any duplicate requests (by refund reference) will return the same response.

Field Description Required Type (Length)
orderId The Laybuy order id to process the refund for. Yes Integer
amount The amount to refund on the order, up to the order total. Yes Decimal
refundReference The merchant's unique reference for the refund. No String (50)
note A brief description of the reason for the refund. No String (255)

Example Request

{
	"orderId":100036,
	"amount":35.95,
	"refundReference":"1728950142",
	"note":"Faulty item returned to store"
}

Response Data

The following table shows the response fields returned by the interface.

Field Description
result The result of the API request. Either ERROR or SUCCESS.
error A description of the error.
refundId The refund payment reference.
merchantReference The merchant's reference from the original order.

Example Response - Error

{
	"result":"ERROR",
	"error":"Failed to find order 100036"
}

Example Response - Success

{
	"result":"SUCCESS",
	"refundId":101318,
	"merchantReference":1728950142
}