NAV Navbar

DivideBuy Bespoke Integration Guide

Welcome to the bespoke integration guide for DivideBuy. The following information will help you connect your store with the DivideBuy checkout, allowing your customers to spread the cost of their orders using finance.

Prerequisites

In order to successfully progress through this guide, you will need a few pieces of information related to your DivideBuy account, and to our system in general.

Your Credentials

You will be provided with two tokens by DivideBuy when you begin the onboarding process with us. These are:

These two tokens will be provided by the DivideBuy onboarding team. Each token should be 12 characters in length, and will be a combination of alphanumeric characters and symbols.

You will be provided with a different set of tokens for each of our environments.

Initially you will be provided with credentials to our sandbox server, to allow you to develop and test your integration against our test environment. Once your implementation has been completed and approved by our onboarding team, you will be provided with credentials for our production environment.

We advise that you store these credentials within your system, where they can be easily accessed by you on the front and backend of your site.

Once stored, they should not need to change. You will just need to retrieve the appropriate credentials for the environment you are targeting.

Our Environment URLs

As mentioned above, we have two environments that you will interact with during your time with DivideBuy.

Each environment will have 2 URLs you will need to use throughout your integration.

Sandbox

Our sandbox environment is our test environment, and will be your first interaction with DivideBuy.

Production

Our production environment is our live environment, and you will move to this environment once your integration has been approved by our onboarding team.

Initial Setup

Once you have received and stored your credentials, the first endpoints you will connect to will allow you to confirm that your credentials are valid, retrieve your retailer ID (this will be required in future calls) and also to inform DivideBuy that you have enabled the DivideBuy option from your side.

Confirm Credentials

Example Request

{
   "storeToken": "abcdef123456",
   "storeAuthentication": "zyxwvu987654",
   "retailerStoreCode": "acmeinc_default"
}

Example Response

  {
   "status": "ok",
   "retailerId": 150
  }

Example Error Response (missing values)

{
    "error": {
        "message": "This is a required field.",
        "status_code": 422
    },
    "status": 0
}

Example Error Response (invalid credentials)

{
    "errors": [
        "Auth and Token combination not valid"
    ]
}

The first call you should make is to confirm your credentials are valid against the environment you are targeting.

This will let you know that your credentials are valid, and that you are able to proceed with the rest of the integration. It will also let you inform us of your chosen 'store code'. This allows you to differentiate this store from another you may have, for example different locales or brands. If you only operate a single store, this can be whatever you like. In our example below, we are defining this as our default store.

HTTP Request

PUT /api/confirmretailer

Request Parameters

Response

Successful responses will return a 200 response that include a status of 'ok' and a 'retailerId' parameter. This represents your retailer ID within the DivideBuy system, and should be stored for future API calls.

Error responses, caused by situations such as missing or invalid parameters will return an error object, with an included status code and message.

Examples of both can be seen on the rightbelow.

Activate DivideBuy

Example Request

{
   "storeToken": "abcdef123456",
   "storeAuthentication": "zyxwvu987654",
   "retailerStatus": "1",
   "allowedIps": "159.242.115.2"
}

Example Response

  {
    "status": "ok"
  }

Example Error Response

{
    "error": {
        "message": "422 Unprocessable Entity",
        "errors": {
            "storeToken": [
                "The store token field is required."
            ],
            "storeAuthentication": [
                "The store authentication field is required."
            ]
        }
    }
}

Once you've confirmed your retailer credentials are valid, and you have stored your retailer ID returned in the previous step, you can make the second call to update your status with DivideBuy and enable the service from your side.

For customers to spread the cost of your orders, we will activate your service internally, and we also require that you enable the service from your side.

This gives you the flexibility to enable or disable DivideBuy as a payment option at any time. If customers did make it to our checkout, and you have disabled the service, they would be prevented from completing the order with us, regardless of whether your account is enabled on our end or not.

HTTP Request

POST /api/updateretailerstatus

Request Parameters

Response

Successful responses will return a 200 response that include a status of 'ok', confirming your call was successful.

Error responses, caused by situations such as missing or invalid parameters will return an error object, with an included message and details of the errors.

Examples of both can be seen on the rightbelow.

Checkout Redirect

Once your customers have decided they want to progress with your order, there are a number of steps you will need take to enable them to checkout with DivideBuy. They are as follows:

  1. Create a payment method
    A new payment method needs to be created for DivideBuy - this should allow your customers to select DivideBuy as their chosen payment method at the point of checkout
  2. Create a draft order
    When your customers choose to continue with DivideBuy, you will need to create a draft or hidden order containing the details of the order (to allow us to retrieve these details later)
  3. Redirect to DivideBuy
    You will then redirect your customers to our dedicated checkout service
  4. Order Details Endpoint
    Once your customers land on our checkout, we will make a request to an endpoint on your site to retrieve the details of the order that is being checked out
  5. Handle redirected customers
    Your customers will complete their application on our checkout, and then be redirected back to your site on completion of the application, or if it is declined or cancelled
    You will then receive the customers and either direct them to a 'thank you' style page for successful orders, or back to the checkout if the application was not successful for any reason
  6. Update your internal order
    Once you've handled the redirected customer you'll need to update the order internally so your systems match the data we have for the order

For a more visual representation of the above flow, please consult the flow diagram below.

Checkout Redirect Flow Diagram

Create a payment method

This step will vary for most integrations, as you will need to provide your customers with the option to choose DivideBuy as their payment method of choice at the checkout stage.

Your payment method should allow the customer to select that they wish to pay for their order using DivideBuy, and should conform to the following points:

Create a draft order

Once your customers have chosen to pay with DivideBuy, you will need to create a draft or hidden order within your system that DivideBuy can use to retrieve the details of on our checkout.

The functionality of this will differ for all retailers, as it is highly dependent on your setup. The reason for the draft order is so our dedicated checkout service is able to query the details of the order when your customer lands on our checkout.

Redirect to DivideBuy

Splash Key Generation

$storeToken = 'abcdef123456';
$storeAuthentication = 'zyxwvu098765';
$retailerId = 123;
$orderId = 789;

// Form the base string that our checkout will expect, and the initialization vector
$stringToEncrypt = implode(':', [
    $storeToken,
    $orderId,
    $storeAuthentication,
    $retailerId
]);
// Returns abcdef123456:789:zyxwvu098765:123

$intializationVector = $storeAuthentication . substr($storeToken, 0, 4);

// Now to encrypt the splash key
$encryptedSplashKey = openssl_encrypt(
    data: $stringToEncrypt,
    cipher_algo: 'AES-256-CBC',
    passphrase: $storeToken,
    options: 0,
    iv: $intializationVector
);

$checkoutSubdomain = 'acmeinc';

$checkoutUrl = "https://" . $checkoutSubdomain
    . ".dividebuysandbox.co.uk?secureVersion=1&retailerId=" . $retailerId . "&splashKey="
    . base64_encode(urlencode($encryptedSplashKey));
// Returns https://acmeinc.dividebuysandbox.co.uk?secureVersion=1&retailerId=123&splashKey=oa0m%2BU39tSRx4JnIeTqLhb0QzT82MGBQZaaSP%2FlO9xG%2FddJRrsGq8mg15vit2BlX

Once you have saved the details of your customer's order in a draft state, you will need to form the redirect URL to use to send your customer to our dedicated checkout service.

You will need your store token and authentication, your retailer ID from the confirmretailer call above, and also the ID of the newly created draft order.

An example of how to form the splash key and checkout URL can be found here, using the appropriate checkout URL mentioned in our environment URLs section.

In this example we are creating a checkout URL for a fictional company named 'Acme Inc'. You are free to choose any subdomain you like to represent your brand on our checkout, if you are unsure please contact our onboarding team with any questions!

Once you have formed the checkout URL, you should redirect your customer to that domain in the same window as your store.

After completing their application on our checkout, they will be redirected back to your site to continue with the order as appropriate.

Get Order Details

Get Order Details Response

{
    "order_detail": {
        "store_order_id": "1024",
        "store_order_increment_id": "REF109846",
        "store_token": "abcdef123456",
        "store_authentication": "zyxwvu987654",
        "subtotal": 2000,
        "subtotalInclVat": 2400,
        "vat": 400,
        "discount": 500,
        "discountApplied": "afterVat",
        "grand_total": 1900,
        "shipping": 15,
        "shippingInclVat": 15,
        "shipping_method": "express",
        "shipping_label": "Express Shipping",
        "is_default_shipping": 0,
        "is_default_billing": 0,
        "selected_instalment": 3
    },
    "product_details": [
        {
            "name": "Supreme Cool Mattress",
            "sku": "SUPCOOLMAT-1",
            "qty": 2,
            "price": 1000,
            "priceInclVat": 1200,
            "DivVat": 20,
            "rowTotal": 2000,
            "rowTotalInclVat": 2400,
            "discount": 0,
            "short_description": "Our Supreme Cool Mattress uses AI to adaptively cool you throughout the night!",
            "image_url": "http://retailer.dev:8081/media//dividebuy/product/images//w/b/wbk012t.jpg",
            "product_options": {
                "size": "King"
            }
        }
    ],
    "shipping_address": {
        "first_name": "John",
        "last_name": "Smith",
        "email": "john.smith@email.com",
        "street": [
            "1 Little Cottage",
            "Customtown"
        ],
        "city": "Cityville",
        "region": "Countyshire",
        "postcode": "AB12 3CD"
    },
    "billing_address": {
        "first_name": "John",
        "last_name": "Smith",
        "email": "john.smith@email.com",
        "street": [
            "1 Little Cottage",
            "Customtown"
        ],
        "city": "Cityville",
        "region": "Countyshire",
        "postcode": "AB12 3CD"
    }
}

When your customers land on our checkout, one of the initial steps our checkout service will take is to request the details of the order in question from your site.

To facilitate this, you will need to make a new endpoint accessible on your site. The URI for this endpoint should be formed as follows:

POST https://your_store_domain.com/dividebuy/api/getorderdetails

We will make a POST request to this endpoint, with the following parameters included in the request.

Please note, this endpoint must use the HTTPS protocol.

Request Parameters



We encourage you to authenticate this request by comparing your stored credentials to those given in the request, and also by confirming that the order ID is both a draft order, and potentially has had DivideBuy selected as the payment method (this depends on the functionality and data you have available to you).

Once authenticated, we require a JSON response to be sent, with the following parameters. This informs DivideBuy of who is asking to apply with DivideBuy, and also what the contents and details of their order are. It's important that the information here is accurate and does not change, as this can cause issues later with any refunds or cancellations.

An example response JSON file can be found here.

Expected Response Parameters

The response should have the HTTP status code of 200.

Receive redirected customers

Decrypting the splash key

$storeToken = "abcdef123456";
$storeAuthentication = "zyxwvu987654";

// The encrypted splash key from the redirect URL
$encryptedSplashKey = "TDc0SnVyaUM0a0F2WWVrVWpsc2prZ3FqTjVtQ091OG1yZkhHZmRzd24yVzJzWXFmNHg3RnhOQ2VzRzRzWXpBalJGekxmS0tFOFlhMis4UkUxcmlyYnc9PTpJaLVc800lfkAExqC1UHP%2B";

// After urldecoding the above, we must base64 decode the result to get the original string
$decodedSplashKey = base64_decode(urldecode($encryptedSplashKey));

// Splitting the string on the comma will result in the raw encrypted string, and the random initialization vector
list($encryptedString, $initializationVector) = explode(':', $decodedSplashKey);

// Ensure that the initialization vector is exactly 16 characters, padded with 0 characters if not
if (strlen($initializationVector) < 16) {
    $initializationVector = $initializationVector . (substr($storeToken, 0, 16 - strlen($initializationVector)));
}

// Using the details above, and your stored retailer credentials, we can decrypt the splash key
$decryptedSplashKey = openssl_decrypt(
    data: $encryptedString,
    cipher_algo: 'AES-256-CBC',
    passphrase: $storeToken,
    options: 0,
    iv: $initializationVector
);

// Returns - 5678:success:abcdef123456:zyxwvu987654:store_code
// This represents ORDER_ID : STATUS : STORE TOKEN : STORE AUTHENTICATION : STORE CODE

Once your customers have completed their application on our checkout, have been declined or otherwise have chosen not to complete the order, they will be redirected back to a specified page on your site.

By default, we will append /dividebuy/payment/response to your standard store URL, and use this to redirect customers to you. If you'd prefer to use a different route, the URL is entirely configurable and can be set by our retailer onboarding team.

The URL that we redirect your customers to will have a splashKey parameter appended to the URL. You should decrypt this key to identify information about the order that was being checked out, and the status of that application.

Decrypting the splash key as shown here will result in a string containing the order ID, order status (success or cancel), and your retailer credentials (store token, authentication and store code).

Successful Orders

From here, if the order status was 'success', this means the order was completed successfully, and you can now proceed to update the associated draft order to a live one, send any order completion communications as your store usually would, and redirect the customer on to a 'thank you' page, or however you would typically handle a customer who has just completed an order.

Failed Orders

If the status comes back as 'cancel', then the order was not successful. This could be for a number of reasons, including a declined application, an error occurring during the process, or simply that the customer changed their mind and hit the back button.

In this case, you should consider the order as still pending, and redirect your customer back to your basket or checkout to allow them to select an alternative payment method.

We advise showing some form of alert, warning or error message to inform the customer that the order has not been completed and is still pending some form of payment.

Update your internal order

For successful orders, once you have successfully redirected your customer to the relevant page, you will need to update your internal order record with the full data from DivideBuy. Once updated, we require that you inform us that you have synced the data between our and your systems, so we are able to proceed with processing the order. A later step in our order processing flow requires that you have notified us that you have syncronised the order details - omitting this step can cause a delay in processing orders.

To do this, we provide two endpoints that you can use to retrieve the details of an order, and a second endpoint to notify us that you have successfully syncronised the details.

Get Order Details

Example Request Body

{
    "storeOrderId": "1024",
    "storeToken": "abcdef123456",
    "storeAuthentication": "zyxwvu987654"
}

Example Response

{
    "status": "ok",
    "data": {
        "trackingDetails": {
            "trackingName": "DPD UK",
            "trackingNumber": "123456789"
        },
        "method": "orderSuccess",
        "store_order_id": "1024",
        "orderIncrementId": "145006485",
        "laravel_order_ref_id": "100054381",
        "laravel_order_status": "Processing",
        "order_status": "success",
        "orderTime": "2020-02-20 20:20:20",
        "customer_email": "john.smith@email.com",
        "address": {
            "prefix": "Mr",
            "first_name": "John",
            "last_name": "Smith",
            "contact_number": "07123456789",
            "house_name": "Little Cottage",
            "house_number": "1",
            "street": "Customer Street",
            "address2": "Customtown",
            "city": "Cityville",
            "region": "Countyshire",
            "postcode": "AB12 3CD"
        },
        "customerName": "John Smith",
        "products": [
            {
                "productId": 24097,
                "sku": "SUPCOOLMAT-1",
                "priceExclVat": 1000,
                "vat": 200,
                "price": 1200,
                "productName": "Supreme Cool Mattress",
                "quantity": 2
            }
        ],
        "subTotal": 2000,
        "vatTotal": 400,
        "subTotalInclVat": 2400,
        "discount": 500,
        "discountApplied": "afterVat",
        "grandTotal": 1900,
        "shippingRate": 15,
        "shippingMethod": "Express Shipping",
        "podFile": ""
    }
}

POST /api/getuserorder

Please note that this is a read-only endpoint, and you are not able to update an order's details on our end via this endpoint

Request Parameters

Response Parameters

Confirm Synced Order

Example Request Body

{
    "storeOrderId": "1024",
    "storeToken": "abcdef123456",
    "storeAuthentication": "zyxwvu987654"
}

Example Response

{
    "status": "ok"
}

POST /api/syncretorder

Request Parameters

Response Parameters

Webhooks

In order for us to relay important information to you programmatically, we require you to create an endpoint on your site that can receive these calls and update your site accordingly.

We use a single endpoint on your site for simplicity, and differentiate the information we send using a 'method' parameter.

By default, we will configure this endpoint with the following URL:

POST https://your_store_domain.com/dividebuy/api/response

Within this guide, we will refer to this endpoint as your 'response webhook'.

We are able to configure the URL of this endpoint to an alternative if you would prefer. Please let our onboarding team know if you'd like to reconfigure the URL of this endpoint.

When responding to a request to your response webhook, if no errors occurred on your side, you should return a status of 200. This will ensure our system knows the request was received successfully and can be considered complete. If any errors occur during processing the request, an appropriate error code can be returned.

Retailer Configuration

Decrypting the splash key

{
    "method": "retailerConfigurations",
    "retailer_id": 1234,
    "retailer_store_code": "acme_inc",
    "store_token": "abcdef123456",
    "store_authentication": "zyxwvu987654",
    "allowedIps": "123.123.12.24,204.251.12.35",
    "retailerConfigurationDetails": {
        "0": {
            "type": "global",
            "key": "taxClass",
            "value": "20",
            "retailer_id": 1234
        },
        "1": {
            "type": "global",
            "key": "description",
            "value": "Acme Inc is the worlds foremost supplier of anvils to cartoon coyotes",
            "retailer_id": 1234
        },
        "9": {
            "type": "global",
            "key": "representativeAPR",
            "value": "19.9",
            "retailer_id": 1234
        },
        "10": {
            "type": "global",
            "key": "averageIbcTermLength",
            "value": "24",
            "retailer_id": 1234
        },
        "11": {
            "type": "global",
            "key": "averageIbcOrderValue",
            "value": "2450.00",
            "retailer_id": 1234
        },
        "12": {
            "type": "global",
            "key": "markOrderComplete",
            "value": "0",
            "retailer_id": 1234
        },
        "13": {
            "type": "allowedIps",
            "key": "allowedIps",
            "value": "123.123.12.24,204.251.12.35",
            "retailer_id": 1234
        },
        "16": {
            "type": "instalments",
            "key": "3",
            "interest_rate": 0,
            "apr": 0,
            "min": 200.0,
            "max": 6000.0,
            "retailer_id": 1234
        },
        "19": {
            "type": "instalments",
            "key": "6",
            "interest_rate": 0,
            "apr": 0,
            "min": 300.0,
            "max": 6000.0,
            "retailer_id": 1234
        },
        "22": {
            "type": "instalments",
            "key": "9",
            "interest_rate": 0,
            "apr": 0,
            "min": 500.0,
            "max": 6000.0,
            "retailer_id": 1234
        },
        "25": {
            "type": "instalments-ibc",
            "key": "18",
            "interest_rate": 9.5,
            "apr": 9.5,
            "min": 800.0,
            "max": 6000.0,
            "retailer_id": 1234
        },
        "28": {
            "type": "instalments-ibc",
            "key": "24",
            "interest_rate": 19.9,
            "apr": 19.9,
            "min": 1100.0,
            "max": 6000.0,
            "retailer_id": 1234
        }
    }
}

When your retailer account is created or updated within our system, we will send a request to your response webhook with the method of retailerConfigurations.

Upon receiving a request with this method, we advise that you verify the request, extract the data within the request and store it within your system.

In the example shown here, some configuration items have been removed for brevity in the example. All configuration items will be returned in the same format, and a full example can be found here.

Request Parameters

Expected Response Parameters

Successful Orders

Example Request

{
    "method": "orderSuccess",
    "store_order_id": "12345",
    "store_token": "abcdef123456",
    "store_authentication": "zyxwvu987654",
    "order_status": "success",
    "orderTime": "2020-02-20 20:20:20",
    "retailer_store_code": "acme_inc",
    "customer_email": "john.smith@email.com",
    "laravel_order_ref_id" : "100054381",
    "address": {
        "prefix": "Mr",
        "first_name": "John",
        "last_name": "Smith",
        "contact_number": "07123456789",
        "house_name": "Little Cottage",
        "house_number": "1",
        "street": "Customer Street",
        "address2": "Customtown",
        "city": "Cityville",
        "region": "Countyshire",
        "postcode": "AB12 3CD"
    }
}

When one of your customers is redirected to our checkout, successfully completes all required information, passes the credit check and successfully makes their first payment, we will send a request to your response webhook with the method 'orderSuccess' and some details of the order to confirm.

Once you receive this request, you will be able to update the associated order within your system to whichever status you use to denote a completed, paid order.

You may have already handled the updating of the order at the time that your customer is redirected to your site. If so, just return an HTTP status of 200 OK and no further action is required.

Request Parameters

Expected Response Parameters

The response, if successful, should return a status code of 200. If any errors occur during processing the request, an appropriate error code can be returned.

Failed/Cancelled Orders

Example Request

{
    "method": "orderCancel",
    "store_order_id": "12345",
    "retailer_store_code": "acme_inc",
    "store_token": "abcdef123456",
    "store_authentication": "zyxwvu987654",
    "delete_user_order": 1
}

If a customer is redirected away from our checkout without successfully completing the application for any reason, we will send this notification to your response webhook. This could be caused by a declined application, a change of mind by the customer, or even in rare cases, an error on our checkout.

When you receive this notification, you may have a draft or hidden order with the ID in the request. If so, that order can be closed, deleted or handled however else your system would deal with an incomplete order.

Request Parameters

Expected Response Parameters

Post Sales

Once your customers have successfully completed their order with DivideBuy, there will likely be a number of steps for the order to take after the initial creation. The following endpoints will allow you to communicate these processes to DivideBuy to ensure the appropriate action can be taken on our side.

Order Fulfilment

Example Request Body

{
   "storeToken": "abcdef123456",
   "storeAuthentication": "zyxwvu987654",
   "storeOrderId": "1024",
   "deleteTracking": 0,
   "trackingInfo": [
     {
       "title": "DPD UK",
       "carrierCode": "DPD UK",
       "trackNumber": "123456789",
       "description": null
     }
   ],
   "productDetails": [
     {
       "sku": "SUPCOOLMAT-1",
       "qty": 2
     }
   ]
}

Once you have shipped the customer's order, you will need to inform DivideBuy of the fulfilment in order for us to approve the release of funds to you for the associated order.

To do this, you will need to send an API request to the endpoint below, with the details of the order, the products shipped and the details of the courier and shipment.

HTTP Request

POST /api/tracking

Request Parameters

Successful Response Parameters

Refunds

Example Request Body

{
    "orderId": "1024",
    "retailer": {
        "storeToken": "abcdef123456",
        "storeAuthentication": "zyxwvu987654"
    },
    "refundType": "PARTIAL",
    "product": [
        {
            "sku": "SUPCOOLMAT-1",
            "qty": 1,
            "rowTotal": 1000,
            "rowInclTotal": 1200
        }
    ],
    "totalRefund": 1200,
    "reason": "Customer changed mind about second mattress",
    "shippingCostAmount": 0,
    "shippingTaxAmount": 0
}

Error Response Format

{
    "error": {
        "message": "Retailer not found.",
        "status_code": 422
    },
    "status": 0
}

It's an unfortunate truth of sales that refunds will happen at some point. If and when that does happen for one of your orders that was paid by DivideBuy, you'll need to inform us so we're able to update your customers loan accordingly.

To do so, a request should be sent to the following endpoint as described below.

POST /api/refund

Request Parameters

Response

Successful requests will receive a status code of 200, and a JSON payload containing a 'status' string of 'ok'. If you receive a successful response, your refund request was received by us and will be processed by our accounts team.

If however, there was an issue with your request, an error response will be returned with the following parameters. An example response can be seen below the example request.

Resources

Financial Promotions Guide

As a provider of regulated finance options, we are required to ensure that our integrations properly adhere to the FCA regulations around financial promotions. You will likely have discussed elements of this throughout your onboarding journey with DivideBuy, but we have prepared an overview document to hopefully answer any queries you may have.

Financial Promotions Guide PDF

DivideBuy Credit Page

To inform your customers about who DivideBuy are and how our finance options work, you should include the content of our credit page to a new page on your site. Our credit pages can be found at the following link. If you're unsure which you should include, please contact our retailer onboarding team.

DivideBuy Credit Pages

Brand Assets

When creating your frontend presence, you will likely require our brand assets to properly showcase the DivideBuy options. You can find them at the following link, including guidelines on how to use them properly, and importantly how not to use them.

DivideBuy Brand Assets