Retailer Integration Guide

About this Guide

PayBreak offer a suite of finance solutions under the brand afforditNOW. afforditNOW offers merchants a secure, online, alternative payment solution that can be easily embedded into their e-commerce website to enable ePOS purchases.

Aim & Targets Audience

This document explains how to integrate afforditNOW into your website and provides you with all you need to know to successfully process your first live transaction.

afforditNOW is not just a payment option, it is a marketing tool that when presented effectively, will increase online sales. To optimise the customer experience and increase sales conversions, we recommend that afforditNOW is presented at all key customer touch points throughout your website.

Note: Finance promotions must meet the required guidelines set out by the Consumer Credit (Advertisements) Regulations 2010.

To ensure a compliant and effective promotion of the afforditNOW finance offering. Please refer to the afforditNOW Merchant Marketing Guide, available at http://www.afforditnow.com/retailer/retailer-developer-support/

If you would like any advice or assistance on how to promote afforditNOW finance on your website, please contact your account manager or email sales@afforditnow.com.

Upgrading from v3.* to v4.0

We’ve changed our loan product makeup to provide additional products. Our existing products become Flexible Finance and we’ve added Interest Free Credit and Interest Bearing Credit. This has forced us to replace the Finance Actions in the Merchant API to reflect the new data structure.

Upgrading to v4.0 provides the following benefits:

  • access to the full suite of our finance products
  • alternative fulfilment
  • pre-population of applicant details
  • improved order statuses
  • maximum order validity has increased from 48 hours to 30 days

How to Get Help

If you have any questions or you require further information, please send us an email retailer@paybreak.com or call us on 033 33 444 226. If you need to query any of the steps in this guide, please indicate the Section Heading in your correspondence.

PayBreak Integration

Introduction

Prerequisites to Integration

You must be approved for an afforditNOW merchant account before you can start integration. Please contact your afforditNOW account manager or email sales@afforditnow.com for approval.

Once approved you will receive a welcome email inviting you to create an afforditNOW merchant account. Please follow the steps in the welcome email to create your account. When you have logged in you will be in the afforditNOW Merchant Back Office.

Note: Invitations are only valid for one email address and expire after 48 hours. If you need this resending please contact retailer@paybreak.com.

Prerequisites to Going Live

Before you can go live with afforditNOW, you will need to have completed all activities below:

  1. Complete integration tests (see Integration Checklist)
  2. afforditNOW logo displayed on your website
  3. Compliant finance promotion
  4. Mandatory finance information page
  5. (Optional) Your logo to be displayed in the checkout process.

Your logo should be of a sufficient resolution to be displayed accross a standard range of monitors. It should have a transparent background, but white is acceptable if transparent is not possible.

Test & Live URLs

Action Test URL Live URL
HTML Form Initialized https://checkout-test.paybreak.com/ https://checkout.paybreak.com/
API https://merchant-api-test.paybreak.com/ https://merchant-api.paybreak.com/

afforditNOW Finance Products

This document details how to integrate the following afforditNOW suite of products:

  • afforditNOW Flexible Finance
  • afforditNOW Interest Free
  • afforditNOW Interest Bearing
  • afforditNOW Buy Now Pay Later

Note: The finance product(s) and their configurations will have been pre-agreed with your account manager, a list of which are available via the Merchant Back Office.

Alternatively, the same information is available using the API.

Status Page

As a part of our support we are providing live system Status Page. As a part of your integration maintenance process we are suggesting that your IT team should subscribe to updates.

Merchant Back Office

Account Setup

The Merchant Back Office is a web based system that allows you to manage and configure your account.

Prior to integration we will issue an email inviting you to create a test account that enables access to our test environment.

Once integration is completed, we will issue you with a live account.

Environment Merchant Back Office Address
TEST https://merchants-test.paybreak.com/
LIVE https://merchants.paybreak.com/

API Settings

Token

Once your account is set up, a unique API token is created. You will need this to interact with the afforditNOW API, this can be found via the Merchant Back Office.

Installations

Merchants that operate across multiple websites can use installations to specify unique configurations for each website.

The number of installations will have been pre-agreed and your account will be set up accordingly. If you need additional installations, please contact your afforditNOW account manager or email sales@afforditnow.com.

Installation Reference

Unique reference for an installation which you will need to use in every communication with the API.

Return URL

The URL we will use for the return to merchant buttons in the application journey, this will be appended with the application reference and one of the following application statuses:

  • abandoned
  • pre_declined
  • declined
  • referred
  • converted

Example:

http://test.com/return_handler/?application=123&status=abandoned

Notification Service

The Notification Service will send a HTTP POST request when the application status changes. These will be sent to your Notification URL configured in the Back Office, if the Notification URL is not set notifications will not be sent.

Notification Strategy

The Notification Service will keep trying to send notifications until a HTTP 200 status code is returned or the maximum number of attempts is reached.

  • To mark notification as successfully delivered HTTP 200 status code MUST be returned.
  • Any other status code will be treated as failed delivery
  • Each subsequent attempt is delayed by x amount of minutes (following Fibonacci sequence: 0,1,1,2…n)
  • Maximum delay time is 8 hours
  • Once delay reaches maximum delay time notification is delayed using maximum delay time
  • Maximum attempts is set to 50 tries
  • At-least-once Delivery rule, means notifications can be resend more than once

Notification Body

Notifications include the application identifier and the new status:

{
    "application": 123,
    "order_reference": "NRE01234",
    "new_status": "initialize"
}
  • Additional information can be retrieved using the Get Application API call.
  • For HTML form based integration Application ID could be linked to order using any received notification as any other communication with PayBreak is based on Application ID.

Handling Notifications

It’s important to note that by default, plain PHP, and some frameworks - including wordpress will not parse the POST data when it’s not sent through a form. You need to use PHP to manually extract the data from the raw response:

$notificationData = json_decode(file_get_contents("php://input"), true);

It would also be prudent to ensure this is valid before parsing it.

Validating Notifications

PayBreak recommend that any endpoint on which you listen for notifications should validate the originating IP address as belonging to PayBreak. The set of allowed IP addresses can be discovered by making a call to the relevant API.

Application Process Overview

You send us an initialization request and we start the credit application process. The customer completes their application, we perform identity and credit checks. The customer will be asked to e-sign their agreement. Once an order is converted you can fulfil this order manually from the Merchant Back Office or optionally through our API.

In the unlikely event that we can’t make an instant decision the application will be referred whilst an underwriter from afforditNOW reviews the application.

Application Statuses

Status Description
initialized The order has been successfully initialized.
abandoned The order validity has been exceeded before reaching a final status. This will typically be where a customer has not completed their application or failed to e-sign their agreement.
pending The customer has reached the application form.
pre_declined afforditNOW have not been able to offer credit to the customer at this time.
declined afforditNOW have not been able to offer credit to the customer at this time.
referred We were unable to make an instant decision and have referred the application for manual underwriting.
cancelled The customer requested cancellation after being referred.
expired The order was referred and we have not been able to get in contact with the customer.
converted The customer has completed their application, they have been approved for credit and have e-signed their agreement. You should not fulfil the customer’s order until you’ve received a converted notification. Once a customer has e-signed their agreement it can take up to two minutes for this notification to be sent, but will most likely be sent within seconds.
fulfilled The order has been fulfilled.
complete The order has been settled and is deemed complete.
pending_cancellation Cancellation for this Application was requested and is in the review.

Test Environment

The test site is a replica of the live site, with the exception that instead of the usual credit checks the decision is made solely on the net monthly income provided. There is no provision to run test orders through the live system; all your testing must be through the test site.

When testing you can run through the process end-to-end, experiencing the customer journey in its entirety. When you first create an account on the test site you will need to complete a credit profile. The details you enter here can be fictitious, but must meet the validation requirements. As with the live site once you have completed your credit profile you do not need to enter the same details again when you next apply.

Simulate Application Decisions

In order for your application to be approved you must enter a net monthly income greater than £1,000. Entering less than £1,000 will result in a declined decision. Entering exactly £1,000 will result in a referred decision. On the test site, the referral underwriting is automated and will occur immediately after the referral decision is made. The automated underwriter will approve your application when your net monthly income is greater than your monthly-unsecured debt and decline it when your net monthly income is less than your monthly-unsecured debt. If the net monthly income and monthly-unsecured debt are identical no decision will be made and the order will be left to expire.

Net Monthly Income Monthly-Debt Repayments Decision
> £1,000 N/A Accepted
< £1,000 N/A Declined
= £1,000 < £1,000 Referred and then Accepted
= £1,000 > £1,000 Referred and then Declined
= £1,000 = £1,000 Referred with no automatic underwriting

Test Card Numbers

Depending on the finance product selected, the customer may be asked for a service fee or deposit.

In testing, please use the following card details:

Card Number 4111 1111 1111 1111
Card Holder Mr Test Tester
Expiry Date 03/2030
CVC 737

You can find more test cards on our card provider’s site.

Simulate Customer Intelligence Responses

We use the day in date of birth to simulate responses. Date of birth must be a valid date.

Date of Birth range Advice.
XXXX-XX-01 - XXXX-XX-10 green
XXXX-XX-11 - XXXX-XX-20 amber
XXXX-XX-21 - XXXX-XX-31 red

Application Initialization

HTML Form Based Application Initialization

The structure of the HTML form is identical to the secure API application submission and follows the same validation rules.

<form action="https://checkout-test.paybreak.com/" method="post">
    <input type="hidden" name="installation" value="NoveltyRock" />
    <input type="hidden" name="order[reference]" value="NRE01234" />
    <input type="hidden" name="order[amount]" value="0" />
    <input type="hidden" name="order[description]" value="" />
    <input type="hidden" name="order[validity]" value="" />
    <input type="hidden" name="products[group]" value="FF" />
    <input type="hidden" name="products[options][]" value="*" />
    <input type="hidden" name="products[default]" value="FF/1-3" />
    <input type="hidden" name="fulfilment[method]" value="collection" />
    <input type="hidden" name="fulfilment[location]" value="Walmington-on-Sea Store" />
    <input type="hidden" name="applicant[title]" value="Mr" />
    <input type="hidden" name="applicant[first_name]" value="Fillibert" />
    <input type="hidden" name="applicant[last_name]" value="Labingi" />
    <input type="hidden" name="applicant[date_of_birth]" value="1970-01-01" />
    <input type="hidden" name="applicant[email_address]" value="fillibert.labingi@gmail.com" />
    <input type="hidden" name="applicant[phone_home]" value="" />
    <input type="hidden" name="applicant[phone_mobile]" value="07700900123" />
    <input type="hidden" name="applicant[postcode]" value="TN12 6ZZ" />
    <input type="hidden" name="metadata[you]" value="do" />
    <input type="hidden" name="metadata[what_ever]" value="you" />
    <input type="hidden" name="metadata[want]" value="2" />
</form>

Advanced Integration Using the API (Optional)

Complete reference here: afforditNOW API Reference

Secure API Application Submission

Using the form based intialization allows someone to potentially intercept and alter the parameters, so we offer a secure application submission through our API. You should only use the form post where you don’t have access to the server-side.

  1. You submit the order details to the API including a validity period.
  2. The API returns a unique URL to redirect the customer to.
  3. You redirect the customer to the URL which is valid until the validity parameter you provided expires.
POST /v4/initialize-application

Parameters

Name Required Type Description
$.installation Yes string The Merchant Installation Reference supplied by us.
$.order Yes order Details of the order.
$.products Yes product range Details of the products to be offered to the customer.
$.fulfilment No fulfilment How will the order be fulfilled? Defaults to application-address if not set.
$.applicant No applicant Optional applicant details.
$.customer_intelligence No customer intelligence Customer Intelligence data is used for application analytics.
$.metadata No object Metadata is used to add your own meaningful values to an application. It is returned when you Get an Application.

Example with Required Fields

{
    "installation": "NoveltyRock",
    "order": {
        "reference": "NRE01234",
        "amount": 49995,
        "description": "Novelty Rock",
        "validity": "2015-12-25T12:00:00+00:00"
    },
    "products": {
        "group": "FF",
        "options": [
            "*"
        ]
    }
}

Example with Optional Fields

{
    "installation": "NoveltyRock",
    "order": {
        "reference": "NRE01234",
        "amount": 49995,
        "description": "Novelty Rock",
        "validity": "2015-12-25T12:00:00+00:00",
        "deposit_amount": 1000
    },
    "products": {
        "group": "FF",
        "options": [
            "*"
        ],
        "default": "FF/1-3"
    },
    "fulfilment": {
        "method": "collection",
        "location": "Walmington-on-Sea Store"
    },
    "applicant": {
        "title": "Mr",
        "first_name": "Fillibert",
        "last_name": "Labingi",
        "email_address": "fillibert.labingi@gmail.com",
        "phone_home": null,
        "phone_mobile": "07700900123",
        "postcode": "TN12 6ZZ"
    },
    "customer_intelligence": {
        "email_address": "fillibert.labingi@gmail.com",
        "lead_score_id": 64,
        "pre_approval_id": 123
    },
    "metadata": {
        "you": "do",
        "what_ever": "you",
        "want": 2
    }
}

Response

Name Required Type Description
$.application Yes long Application identifier to be used in all subsequent requests regarding this application. It’s a 32-bit long type (see).
$.url Yes string URL to redirect the applicant to.
{
    "application": 123,
    "url": "https:\/\/checkout.paybreak.com\/?id=123&token=ab2141f3b25"
}

Fulfilment Requests

Individual fulfilment requests can be performed manually through the Merchant Back Office. Optionally, you can automate with a request to our API:

POST /v4/applications/:application/fulfil

Response

Returns a 204 No Content status.

Cancellation Requests

Individual cancellation requests can be performed manually through the Merchant Back Office. Optionally, you can automate with a request to our API:

POST /v4/applications/:application/request-cancellation

Parameters

Name Required Type Description
$.description Yes string Describe the reason for requesting a cancellation.

Example

{
    "description": "Customer has requested cancellation under distance selling regulations"
}

Response

Returns a 204 No Content status.

Appendices

Integration Checklist

To integrate with afforditNOW you must send us an initialization request, either through our API, or if you do not have access to server side code you can use the HTML form post method.

Our recommended method of integration is to use our API as this is the most secure.

You may optionally want to integrate with your own back office, in this case you will need to use our API method.

For each PayBreak notification sent out a HTTP 200 (“OK”) response MUST be returned to acknowledge that the notification has been received successfully.

Task Done
Initialize an application  
A description MUST be allocated to every application initialized  
An application’s validity date SHOULD be at least three days in the future from the time when the application was initialized  
Return URLs correctly handle return situations  
Ensure all PayBreak generated notifications are correctly handled and for each notification a HTTP 200 response is returned