Integration guide. Version 0.1

Transcription

1 Integration guide Version 0.1 This document contains the proprietary information of Close Brothers Retail Finance Limited and may not be reproduced in any form or disclosed to any third party without the written permission of a duly authorised representative of Close Brothers Retail

2 Table of Contents Table of Contents Getting Started CBRF Retailer Portal: Test vs Live Versions Installation Settings Live Trading Checklist Test and Live Trading URLs Credit Application Process Overview... 7 Credit/Debit Card Deposits... 7 Settlement... 8 Credit Application Value Limits... 8 Credit Application States... 9 Test Consumer Data Credit Application Initialisation Credit Status Notifications (Credit Application Response) Advanced Integration Using The CBRF API (Optional) Registering Your IP Address(es) Secure Application Initialisation Fulfilment Requests Cancellation Requests Part Refunds Order Amendments Javascript Finance Calculator Tool Finance Calculator Tool Web Service Remittance CSV Appendix A: Error Codes Appendix B: Optional Credit Application Variables (Pass Thru Data) Appendix C: Fulfilment Request Array Appendix D: Status Requests and resending CSNs Appendix E: Close Brothers Retail Finance Product Codes This document contains the proprietary information of Close Brothers Retail Finance Limited and may not be reproduced in any form or disclosed to any third party without the written permission of a duly authorised representative of Close Brothers Retail

3 1 Getting Started You will receive a welcome confirming your Close Brothers Retail Finance (CBRF) application has been approved and that your test account is setup and ready for you to begin integration. The CBRF Retailer Portal is a web-based system that provides detailed information and powerful tools to assist you in managing your CBRF account. You can access your account at Retailer Portal is also used to submit credit applications in-store (when the customer is present) and to manually create credit links that can be ed to customers. Your welcome will contain primary login details for your account. Once logged in you can change passwords and setup access for additional users. Please refer to the Retailer Portal User Guide (which can be downloaded from Resources section in Retailer Portal) for more information. If you have any questions or you require further information, please cbrfretailersupport@closebrothers.com or call us on If you require further clarification regarding the sections covered in this guide please us stating the section heading in the guide. This document contains the proprietary information of Close Brothers Retail Finance Limited and may not be reproduced in any form or disclosed to any third party without the written permission of a duly authorised representative of Close Brothers Retail

4 2 CBRF Retailer Portal: Test vs Live Versions When your CBRF account is approved you can apply for a test account through the live Portal. To access your test account you will need to use The test platform is a slimmed down version of the Retailer Portal strictly for demoing and integration purposes. You will only be able to view test credit applications made during the test process. Test credit applications are only visible on the test version of Retailer Portal. Live credit applications are only visible on the live version of Retailer Portal. Retailers that wish to continue or revisit testing after going live can continue to access the test version of Retailer Portal directly at Platform Test Live Url Table 1: Platforms and their URLs

5 3 Installation Settings Retailers that trade across multiple sales channels, physical locations or web sites, can use installations to specify unique settings for each website and location. You can setup your account and configure installations by logging in to the Retailer Portal. Click on the Account Management tab and then select Installations. If you re integrating our service into your website(s), an API key is required. This is your unique account identifier, which is automatically created when your account is approved. You ll find your API key on the installation screen and in the containing your test account login details. You can add up to 2 additional installations to Standard Accounts and an unlimited number for Corporate Accounts. Installation settings are as shown below: Installation Setting Installation Name Installation ID Return URL (Accept) Return URL (Refer) Return URL (Decline) Return URL (Cancel) CSN URL CSN Type Logo Auto Unique Ref Description A friendly name to enable you to identify credit applications associated with different installations - such as trading names, URL s or store locations. A numeric ID, used to associate a credit request with this installation. The URL we'll use to return the consumer back to your website upon successful completion of a credit application. If you do not specify a return URL, the Return to Retailer button on the complete screen is not displayed. Your retaileruniqueref for the credit application will be appended to this URL should you wish to present the user with details of their order upon return. Same as above, but for refer credit applications. Same as above, but for declined credit applications. Same as above, if the consumer cancels at the start of the application process. The URL to your script, handling Credit Status Notifications (CSN). The address to which CSN s are sent. Specifying whether this installation is being used online or in-store. Your logo, displayed at the top of credit applications associated with this installation. Automatically creates a unique order reference when you submit a credit application. Table 2: Installation Settings

6 4 Live Trading Checklist You can begin submitting live credit applications when our partner lender issues your Outlet Number and you have completed the checklist below. We will send you an to confirm when your account is ready for live trading and update your account status to LIVE in Retailer Portal. Description Test credit application successfully completed with an ACCEPT response CBRF payment logo displayed on your website Notes Please see Chapter 7 below Payment logo can be downloaded from Retailer Portal > Resources. Table 3: Live Trading Checklist

7 5 Test and Live Trading URLs When you are ready to begin submitting live credit applications, please amend the URL(s) in your HTTP POST(s) as shown in the table below. Table 4: Test and Live URLs Action Test URL Live URL Initialise Credit Application via HTML Form POST CBRF API* (Fulfilment, Status & Cancellation Reqeuests + The Finance Calculator Tool Web Service) * If you intend to use the optional CBRF API (Fulfilment/Status/Cancellation Requests and the Finance Calculator Tool Web Service) please notify us of the IP address(es) from which we can expect to receive your POST s by ing cbrfretailersupport@closebrothers.com Note: If have trouble creating a connection to CBRF using our web service please ensure that you have given us the correct IP address to whitelist and that the requests you are sending are coming from that IP address. Sometimes load balancing systems can cause requests to come from different IP addresses than the ones expected. Also note that our Test and Live web services run on very specific ports (I.E and 6686) You will need to ensure that your firewall is setup to allow outgoing requests on these ports. 6 Credit Application Process Overview The Online (Customer Not Present) credit application process starts with an HTTP POST or GET from your website to the CBRF system. The consumer is then redirected to our secure form where they complete, sign and submit their credit application. Upon submission of the credit application, the lender will perform a credit check and various other processes culminating in a decision. The possible decisions are ACCEPT, DECLINE or REFER. If the consumer is accepted, we instruct them to pay their deposit using a credit or debit card. Upon receipt of this card payment, the credit agreement comes into force. At this point we inform the consumer the application process is complete and that we have authorised the retailer to proceed with their order. Finally we redirect the consumer back to your web site using the return URL you specify in your installation settings. Credit/Debit Card Deposits The credit application process incorporates a 3-D Secure authenticated credit or debit card payment. If the retailer specifies a valid deposit in the credit request variables, a card payment equal to this amount is processed. Default deposit limits are as follows: Minimum Deposit % Minimum Deposit Value Maximum Deposit % Maximum Deposit Value 10% % 12, Table 5: Deposit Limits The deposit is routed to the lenders card payment merchant account and the repayment terms of the credit agreement are written accordingly. Card payment deposit functionality is always live, even for test credit application. The deposit is however fixed to a value of 1 for

8 test credit applications. Settlement Credit applications are valid for 90 days from acceptance. You must notify us when you have fulfilled (delivered) the consumers order. We then add the credit application to a settlement file, which is sent to the lender at the end of each working day and paid by BACS to your nominated account the following day. The consumers first repayment will be collected approximately 30 days after you have been settled. Clearly consumers do not expect to start repaying a loan until they have received their order. This is why we require retailers to notify us upon fulfilment, thereby triggering settlement. Credit Application Value Limits By default, the minimum loan value on your account is and the maximum is 25, Loan value is defined as price (multiplied by quantity) minus deposit. Given the deposit percentage limits, the minimum price of goods you can offer credit for is ( loan with 10% deposit of 27.78) and the maximum is 50, ( 25, loan with a 25, deposit). Contact your account manager to request higher limits. Only positive values must be entered when initialising credit applications. Negative values cannot be accepted, as the lender cannot finance negative values or discounts. If you want to give the customer a discount this must be calculated prior to submitting the values to the CBRF servers.

9 When calculating deposits, please round up to the nearest penny. Please note that any delivery costs should be included in the goods price. This can be done by adding delivery as a separate item. Credit Application States Credit application states are defined as below: State Initialise Predecline Accept Decline Refer Verified Amended Fulfilled Complete Cancelled Info Needed Action Customer Action Retailer Description A credit application is initiated when the retailer makes an HTTP POST. The credit application has been declined by CreditSentry The consumer completes, signs and submits the credit application and the lender responds with an ACCEPT and decision. ACCEPT decisions are valid for 30 days. The credit application is submitted and the lender responds with a DECLINE decision. The credit application is submitted and the lender responds with a REFER decision. The consumer has successfully paid their deposit using a credit or debit card. The credit application has been amended and is awaiting the consumer s approval. The retailer has notified CBRF that they have fulfilled the order. Fulfilment is defined as consumer having receipt of all items e.g. their complete order. The credit application has been included in a settlement payment from the lender to the retailer. The credit application has been cancelled. An underwriter requires additional information before being able to make a decision on the credit application. The customer has been accepted, paid their deposit and has been sent an requesting them to upload their ID document The customers identity document could not be validated (you must obtain valid ID from the customer manually) Table 6: Credit Application States We will send you a CSN whenever there is a change in the status of a credit application. For example when a consumer is accepted/declined/referred or when a consumer makes a deposit payment (Verified). We also send you a CSN to acknowledge fulfilment, completion (settlement) and cancellation. Test Consumer Data Submit a credit application using the test consumer data below to return each decision. Name Mrs Ann Heselden Miss Jane Taylor Mr David Pope Date Of Birth 1 July March Feb 1977 Address 155 High Street Westbury BA13 3BN 99 St. Angells Lane, Hemel Hempstead HP2 7BG 1 Fairlands Avenue Buckhurst Hill IG9 5TF Years At Address Residential Status Home Owner Home Owner Home Owner Marital Status Married Single Married Employment Status Employed Employed Employed This document contains the proprietary information of Close Brothers Retail Finance Limited and may not be reproduced in any form or disclosed to any third party without the written permission of a duly authorised representative of Close Brothers Retail

10 Income 25, , ,000+ Decision ACCEPT REFER DECLINE Table 7: Test Consumer Data When making test credit applications, please also ensure you enter the following information: any valid phone number or mobile number any valid address (if you wish you can enter your own address in order to see the s that are sent to consumers during the application process) any valid occupation and employer name bank account name must match applicant surname (for example if the applicant is Ann Heselden, bank account name must contain Heselden ) any valid bank account number and sort code* (alternatively you can use account number and sort code however the direct debit mandate on the next step of the form will be blank) * Please note that no credit search is performed for test credit applications and none of the information provided is passed to the credit bureau. If you wish, you can therefore enter a valid bank account number and sort code when making a test credit application. This ensures the DD mandate on the next step of the process is populated. This document contains the proprietary information of Close Brothers Retail Finance Limited and may not be reproduced in any form or disclosed to any third party without the written permission of a duly authorised representative of Close Brothers Retail

11 7 Credit Application Initialisation To initiate a Test credit application submit an HTTP Post via an HTML form to with the following data: Field Type Description Required Identification[api_key] STRING Your unique account identifier Yes Identification[RetailerUniqueRef] STRING Your unique reference for this credit application. Typically generated by your shopping cart/ecommerce software after checkout Yes Identification[InstallationID] INTEGER The installation associated Yes with this credit request. Installations enable you to associate credit requests with different sales channels and/or websites. Each installation can have a unique configuration (logo, return URLs, CSN URLs etc ) Goods[0][Description] STRING Description of goods being Yes purchased Goods[0][Quantity] INTEGER Quantity of goods being Yes purchased Goods[0][Price] FLOAT Item Price. The total will be Yes this multiplied by the item s quantity figure. Note: Do not use negative values Finance[Code] STRING Specifies the finance product. Yes Please refer to Appendix A for a full list of product codes Finance[Deposit]* FLOAT The deposit amount. Note: Do Yes not use negative values Finance[SchemeCode] STRING The scheme code for this transaction if applicable. No Table 8: credit application variables *Please note: if the deposit amount supplied is less than that of your account s minimum deposit, this figured will be rounded up to the minimum deposit value. If the amount supplied is greater than the maximum deposit allowed, this figure will be rounded down to the maximum deposit value. The above example is for an order of one item type, multiple items can be specified by repeating the above Goods section with increasing number (i.e. Goods[1], Goods[2], Goods[3] ). We recommend using HTTP POST but also accept HTTP GET requests. Please be sure to correctly escape all variables. It is also possible to utilise our server-side API service to ensure parameters cannot be altered in any way by the user, this service is details in section 17 (Secure Application Initialisation).

12 <form action=" Here method="post" is some example target="credit_application"> HTML code for a button labelled buy on finance, for a Red Bicycle on 6 months <input Interest type="hidden" Free Credit at name="identification[api_key]" a cost of , with a deposit: value="7370d74cb cd1e5e7be1228d22"/> <input type="hidden" name="identification[retaileruniqueref]" value="100000"/> <input type="hidden" name="identification[installationid]" value="1"/> <input type="hidden" name="goods[0][description]" value="red Bicycle"/> <input type="hidden" name="goods[0][quantity]" value="1"/> <input type="hidden" name="goods[0][price]" value="500.00"/> <input type="hidden" name="finance[code]" value="onif6"/> <input type="hidden" name="finance[deposit]" value="50.00"/> <input type="submit" value="buy On finance"/> </form> Figure 1: Example Credit Application 8 Credit Status Notifications (Credit Application Response) Whilst communicating with the consumer in the foreground, we also send notifications (in the form of HTTP POST s, HTML s or both) to you in the background. These are called Credit Status Notifications (CSN). You can process CSN s manually (upon receipt of the ) using the features in Retailer Portal or automate various tasks by sending and receiving CSN s to/from your server. If the lender responded to the example shown in figure 8 above with an ACCEPT, the CSN would read: Credit Application ID: Status: ACCEPT Credit Sentry Flag: Y Customer: Mrs Anne Heselden Installation: Test Retailer Finance Option: ONIF6 Advance: Deposit: Figure 2: Example CSN ( ) ACCEPT response This status field may contain PRE-DECLINE, ACCEPT, DECLINE, REFER, VERIFIED, FULFILLED, ACTION-CUSTOMER, ACTION-RETAILER, COMPLETE and CANCELLED. Please refer to figure 5 for definitions of each credit application state.

13 [CreditRequestID] => We [Status] optionally => send ACCEPT CSN s in HTTP format to the URL you specify in your installation settings. [Identification] Again using the example credit application in figure 8, the response HTTP would read: [api_key] => 7370d74cb cd1e5e7be1228d22 [InstallationID] => 1 [RetailerUniqueRef] => [Finance] [Code] => ONIF6 [Deposit] => 50 [Goods] [0] [Description] => Red Bicycle [Quantity] => 1 [Price] => 500 [CreditSentryFlags] [0] [Description] => Country Code is not GB [Consumer] [Title] => Mrs [Forename] => Anne [Surname] => Heselden [PhoneNumber] => [MobileNumber] => [ Address] => exampleconsumer@test.com [HouseNumber] => 115 [HouseName] => House [Street] => High Street [Town] => Westbury [Postcode] => BA13 3BN Figure 3: Example CSN (HTTP POST) ACCEPT response Congratulations. You have now completed a CBRF integration! Please refer to chapter 9 below for more information on advanced integration options using the CBRF API. 9 Advanced Integration Using the CBRF API (Optional) CBRF Retailer Portal enables retailers to manage credit applications manually. Alternatively retailers can use our API to integrate CBRF with their own internal systems and automate credit application management. Using either Retailer Portal or our API (or a combination of both) you can fulfil, amend or cancel credit applications. We also provide a finance calculator (you can chose from a JavaScript version or a web service API) that assists online retailers to market finance This document contains the proprietary information of Close Brothers Retail Finance Limited and may not be reproduced in any form or disclosed to any third party without the written permission of a duly authorised representative of Close Brothers Retail

14 effectively. The following pages (Chapters 10, 11, 12 and 13, plus Appendices B, C and D) in this integration guide detail our optional API features. Registering Your IP Address(es) If you intend to use the CBRF API please notify us of the IP address(es) from which we can expect to receive your POST s by ing cbrfretailersupport@closebrothers.com Note: We do not accept ranges of IP addresses for security reasons. You must specify the exact IP addresses that your requests will be coming from. 10 Secure Application Initialisation The easiest way to initiate CBRF credit applications on your website is by using an HTML form or link to direct users to us (as detailed in section 7). As this approach allows the user s client to potentially intercept and alter the order parameters, we also offer a more secure method of application initialisation. When using our secure application initialisation service, your server first sends a request to our API service with the application s parameters. We then return a URL which will open the application with the parameters you specified. We recommend using an Ajax based approach as follows: 1. The user first clicks a button on your website to initiate a credit application. 2. A JavaScript HTTP (Ajax) request is sent to your server 3. Your server makes the CBRF API request detailed below, returning a unique URL 4. Your server returns this URL to the client and redirects them to it Requesting this credit application link can be done by sending a HTTP POST request from your server with the following data. This url returned is valid for 2 hours following the API request. Field Type Required Notes action STRING Yes This should be credit_application_link in lower case Identification[api_key] STRING Yes Your unique account identifier Identification[RetailerUniqueRef] STRING No Your reference for this order. Must be unique. If not specified or unique, we will generate one for you. This document contains the proprietary information of Close Brothers Retail Finance Limited and may not be reproduced in any form or disclosed to any third party without the written permission of a duly authorised representative of Close Brothers Retail

15 Identification[InstallationID] INTEGER Yes The installation associated with this credit request. Installations enable you to associate credit requests with different sales channels and/or websites. Each installation can have a unique configuration (logo, return URL s, CSN URL s etc ) Goods[Description] STRING Yes Description of order contents Goods[Price] INTEGER Yes The overall total order value expressed in pennies Finance[Code] STRING Yes Specifies the finance product. Please refer to Appendix A for a full list of product codes Finance[Deposit] * INTEGER Yes The deposit amount expressed in pennies Finance[SchemeCode] STRING No The Scheme Code for this transaction, if applicable Table 9: Secure Application Initialisation Variables $interface = " $postfields = Array( "action" => "credit_application_link", Sample "Identification[api_key]" PHP Code: => "[YOUR API KEY]", "Identification[InstallationID]" => "[YOUR INSTALLATION ID]", "Identification[RetailerUniqueRef]" => "[YOUR ORDER REFERENCE]", "Goods[Description]" => "[ORDER DESCRIPTION]", "Goods[Price]" => "[TOTAL ORDER VALUE IN PENNIES]", "Finance[Code]" => "[PRODUCT CODE FROM APPENDIX A (e.g. ONIF6)]", "Finance[Deposit]" => "[DEPOST VALUE IN PENNIES]", ); $curlsession = curl_init(); curl_setopt($curlsession, CURLOPT_URL, $interface); curl_setopt($curlsession, CURLOPT_HEADER, 0); curl_setopt($curlsession, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($curlsession, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curlsession, CURLOPT_FOLLOWLOCATION, 1); curl_setopt($curlsession, CURLOPT_POST, 1); curl_setopt($curlsession, CURLOPT_POSTFIELDS, $postfields); $curl_response = curl_exec($curlsession); Figure 20: Example Secure Application Initialisation in PHP This document contains the proprietary information of Close Brothers Retail Finance Limited and may not be reproduced in any form or disclosed to any third party without the written permission of a duly authorised representative of Close Brothers Retail

16 string url = " NameValueCollection data = new NameValueCollection(); data.add("action", "credit_application_link"); Sample C#.NET Code data.add("identification[api_key]", "[YOUR API KEY]"); data.add("identification[installationid]", "[YOUR INSTALLATION ID]"); data.add("identification[retaileruniqueref]", "[YOUR ORDER REFERENCE]"); data.add("goods[description]", "[ORDER DESCRIPTION]"); data.add("goods[price]", "[TOTAL ORDER VALUE IN PENNIES]"); data.add("finance[code]", "[PRODUCT CODE FROM APPENDIX A (e.g. ONIF6)]"); data.add("finance[deposit]", "[DEPOST VALUE IN PENNIES]"); // WebClient is part of the System.Net namespace WebClient client = new WebClient(); client.uploadvalues(url, data); Figure 4: Example Secure Application Initialisation in.net This document contains the proprietary information of Close Brothers Retail Finance Limited and may not be reproduced in any form or disclosed to any third party without the written permission of a duly authorised representative of Close Brothers Retail

17 11 Fulfilment Requests When you notify us that you have fulfilled (delivered) the consumers order, we add the credit application to a settlement file, which is sent to the lender at the end of each working day. Individual fulfilment requests can be performed manually using Retailer Portal. Optionally, you can automate the task by sending a HTTP POST to with the following data Field Type Required Description cr_id INTEGER Yes The CBRF ID for this credit application api_key STRING Yes Your unique account identifier new_state STRING Yes This should be fulfilled in lower case. fulfilment_ref STRING Yes A shipping reference for the goods sent. Table 10: Fulfilment Request Variables $interface = " $postfields = Array( // credit request id that we send back in status notifications Sample PHP Code: "cr_id" => "[CREDIT REQUEST ID]", "api_key" => "[YOUR API KEY]", "new_state" => "fulfilled", // a delivery tracking or reference number for this order "fulfilment_ref" => "[A REFERENCE FOR THE FULFILMENT]" ); $curlsession = curl_init(); curl_setopt($curlsession, CURLOPT_URL, $interface); curl_setopt($curlsession, CURLOPT_HEADER, 0); curl_setopt($curlsession, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($curlsession, CURLOPT_POST, 1); curl_setopt($curlsession, CURLOPT_POSTFIELDS, $postfields); curl_setopt($curlsession, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curlsession, CURLOPT_FOLLOWLOCATION, 1); $curl_response = curl_exec($curlsession); string url = " Figure 5: Example Fulfillment Request in PHP NameValueCollection data = new NameValueCollection(); Sample C#.NET Code: // credit request id that we send back in status notifications data.add("cr_id", "[CREDIT REQUEST ID]"); data.add("api_key", "[YOUR API KEY]"); data.add("new_state", "fulfilled"); // a delivery tracking or reference number for this order data.add("fulfilment_ref", "[A REFERENCE FOR THE FULFILMENT]"); // WebClient is part of the System.Net namespace WebClient client = new WebClient(); client.uploadvalues(url, data);

18 Figure 6: Example Fulfillment Request in.net Here <?xml is the version="1.0" XML response to?> a successful fulfillment request: <p4l> <result> success </result> </p4l> Figure 7: Example Successful Fulfillment Request Response Upon a successful fulfillment request, a CSN will be sent with the status field as 'FULFILLED'. Here <?xml is the version="1.0" XML response to?> a valid fulfillment request that has not been executed. <p4l> <result> error </result> </p4l> Figure 8: Example Failed Fulfillment Request Response <?xml version="1.0"?> Here is the XML response to an invalid fulfilment request <p4l> <error> Invalid credit request. Credit request id does not match any credit request </error> </p4l> Figure 9: Example Invalid Fulfillment Request Response Please note that you can optionally send multiple fulfilment requests in an array if you prefer. Please refer to Appendix C for details.

19 12 Cancellation Requests Cancellation requests can be performed manually using Retailer Portal. Optionally, you can automate the task by sending HTTP POST to with the following data. Field Type Required Descriptions cr_id INTEGER Yes The CBRF ID for this credit application api_key STRING Yes Your unique account identifier new_state STRING Yes This should be cancelled in lower case cancellation_note STRING Yes The reason why the credit application is being cancelled Table 11: fulfillment request variables $interface = " $postfields = Array( Sample "cr_id" PHP Code: => "[CREDIT REQUEST ID]", "api_key" => "[YOUR API KEY]", "new_state" => "cancelled", // the reason why the credit application is being cancelled "cancellation_note" => "[CANCELLATION NOTE]" ); $curlsession = curl_init(); curl_setopt($curlsession, CURLOPT_URL, $interface); curl_setopt($curlsession, CURLOPT_HEADER, 0); curl_setopt($curlsession, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($curlsession, CURLOPT_POST, 1); curl_setopt($curlsession, CURLOPT_POSTFIELDS, $postfields); curl_setopt($curlsession, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curlsession, CURLOPT_TIMEOUT, 180); curl_setopt($curlsession, CURLOPT_FOLLOWLOCATION, 1); $curl_response = curl_exec($curlsession); Figure 10: Example Cancellation Request in PHP This document contains the proprietary information of Close Brothers Retail Finance Limited and may not be reproduced in any form or disclosed to any third party without the written permission of a duly authorised representative of Close Brothers Retail

20 string url = " Sample NameValueCollection C# Code: data = new NameValueCollection(); data.add("cr_id", "[CREDIT REQUEST ID]"); data.add("api_key", "[YOU API KEY]"); data.add("new_state", "cancelled"); // the reason why the credit application is being cancelled data.add("cancellation_note", "[CANCELLATION NOTE]"); // WebClient is part of the System.Net namespace WebClient client = new WebClient(); client.uploadvalues(url, data); Figure 11: Example Cancellation Request in.net The response to a successful cancellation request is identical to the example shown in figure 7. Failed and invalid cancellation requests are identical to the examples shown in figures 8 and 9. Upon a successful cancellation request, a CSN will be sent with the status field as 'CANCELLED'. The customer is also sent an informing them that their application has been cancelled. This document contains the proprietary information of Close Brothers Retail Finance Limited and may not be reproduced in any form or disclosed to any third party without the written permission of a duly authorised representative of Close Brothers Retail

21 13 Part Refunds Part refunds allow you to refund part of an order but keep the rest of the finance agreement intact. Part refunds can only be performed on application with a status of COMPLETE, and only an amount up to the loan/credit amount of the application can be refunded. Part refunds can be made multiple times. To part refund a deal in ACCEPT or VERIFIED states, please use the Order Amendment facility within Retailer Portal. To completely refund an entire application, please use the Cancellation Request API call. Part refund requests can also be performed manually using Retailer Portal or by sending a HTTP POST to with the following data. Field Type Required Description cr_id INTEGER Yes The CBRF ID for this credit application api_key STRING Yes Your unique account identifier action STRING Yes This should be part_refund in lower case refund_amount INTEGER Yes The amount in pennies to be refunded refund_note STRING No A plain text description of why the credit application is being part-refunded new_description STRING Yes A plain text description for the remaining order Table 12: Part Refund Request Variables $interface = " $postfields = Array( // credit request id that we send back in status notifications Sample "cr_id" PHP Code: => "[CREDIT REQUEST ID]", "api_key" => "[API KEY]", "action" => "part_refund", "refund_amount" => "[AMOUNT TO BE REFUNDED IN PENNIES]", "refund_note" => "[REFUND NOTE]" // a new description for the order "new_description" => "[NEW DESCRIPTION OF GOODS]" ); $curlsession = curl_init(); curl_setopt($curlsession, CURLOPT_URL, $interface); curl_setopt($curlsession, CURLOPT_HEADER, 0); curl_setopt($curlsession, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($curlsession, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curlsession, CURLOPT_FOLLOWLOCATION, 1); curl_setopt($curlsession, CURLOPT_POST, 1); curl_setopt($curlsession, CURLOPT_POSTFIELDS, $postfields); $curl_response = curl_exec($curlsession) Figure 12: Example Part Refund Request in PHP

22 string url = " NameValueCollection data = new NameValueCollection(); Sample C#.NET Code: // credit request id that we send back in status notifications data.add("cr_id", "[CREDIT REQUEST ID]"); data.add("api_key", "[API KEY]"); data.add("action", "part_refund"); data.add("refund_amount", "[AMOUNT TO BE REFUNDED IN PENNIES]"); // a new description for the order data.add("new_description", "[NEW DESCRIPTION OF GOODS] ); // WebClient is part of the System.Net namespace WebClient client = new WebClient(); client.uploadvalues(url, data); Figure 13: Example Part Refund Request in C# The response to a successful part-refund request is identical to the example shown in figure 6. Failed and invalid part-refund requests are identical to the examples shown in figures 7 and Order Amendments Amendments to the value and description of orders of accepted applications can be amended whilst they are in ACCEPT or VERIFIED states (so have not yet been marked as fulfilled). Once an order amendment is issued, the application will be updated to AMENDED status, a CSN will be sent to you and the customer sent an with a link to review and confirm the amendment. Once the customer confirms the amendment it will be resubmitted for credit scoring, if a deposit remains to be paid, it will go return to ACCEPT state, if no deposit remains to be paid it will return to VERIFIED state. The CSN details will be updated to reflect the new amendment. Order Amendments can also be performed manually using Retailer Portal or by sending a HTTP POST to with the following data: Field Type Required Description cr_id INTEGER Yes The CBRF ID for this credit application api_key STRING Yes Your unique account identifier action STRING Yes This should be order_amendment in lower case new_price INTEGER Yes The amount in pennies of the new total order value new_description STRING Yes A plain text description for the entire new order (not just the amendment), it will replace any previous order description Table 13: Order Amendment Request Variables Sample PHP Code:

23 $interface = " $postfields = Array( // credit request id that we send back in status notifications "cr_id" => "[CREDIT REQUEST ID]", "api_key" => "[API KEY]", "action" => "order_amendment", "new_price" => "[NEW TOTAL ORDER VALUE IN PENNIES]", // a new description for the order "new_description" => "[NEW DESCRIPTION OF GOODS]" ); $curlsession = curl_init(); curl_setopt($curlsession, CURLOPT_URL, $interface); curl_setopt($curlsession, CURLOPT_HEADER, 0); curl_setopt($curlsession, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($curlsession, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curlsession, CURLOPT_FOLLOWLOCATION, 1); curl_setopt($curlsession, CURLOPT_POST, 1); curl_setopt($curlsession, CURLOPT_POSTFIELDS, $postfields); $curl_response = curl_exec($curlsession); Figure 14: Example Part Refund Request in PHP string url = " NameValueCollection data = new NameValueCollection(); Sample C#.NET Code: // credit request id that we send back in status notifications data.add("cr_id", "[CREDIT REQUEST ID]"); data.add("api_key", "[API KEY]"); data.add("action", " order_amendment"); data.add("new_price", "[NEW TOTAL ORDER VALUE IN PENNIES]"); // a new description for the order data.add("new_description", "[NEW DESCRIPTION OF GOODS]"); // WebClient is part of the System.Net namespace WebClient client = new WebClient(); client.uploadvalues(url, data); Figure 15: Example Part Refund Request in.net The response to a successful order amendment request is identical to the example shown in figure 6. Failed and invalid order amendment requests are identical to the examples shown in figures 7 and 8.

24 15 JavaScript Finance Calculator Tool We have developed a client-side JavaScript reusable object, for use in calculating the details of a finance deal for display on your website. To use it, simply include this snippet of HTML between your website s head elements: <script type="text/javascript" src=" =[YOUR API KEY]"></script> <script type="text/javascript"> var my_fd_obj = new FinanceDetails("[PRODUCT TYPE]", [COST OF GOODS], [DEPOSIT PERCENTAGE], [DEPOSIT AMOUNT]); </script> Figure 16: JavaScript Finance Calculator Tool HTML Snippet This table shows the properties of your FinanceDetails object and some example values: Property Name Property Example Value Product Name my_fd_obj.p_name 6 Months Interest Free Credit (0% APR) Value of Goods my_fd_obj.goods_val Percentage of Deposit my_fd_obj.d_pc Amount of Deposit my_fd_obj.d_amount Amount of Loan my_fd_obj.l_amount Term of Agreement my_fd_obj.term 6 APR my_fd_obj.apr 0 Monthly Instalment my_fd_obj.m_inst Loan Repayment my_fd_obj.l_repay Total Amount Payable my_fd_obj.total Cost of Loan my_fd_obj.l_cost 0.00 True Cost of Loan My_fd_obj.l_truecost 0.00 Table 14: FinanceDetails Object Properties and Values Please note that the True Cost of Loan should not be displayed on your website or otherwise communicated to the consumer. It exists to show when rounding is in the consumers favour. Use Cost of Loan. A demonstration of the JavaScript finance calculator tool is available at

25 16 Finance Calculator Tool Web Service As an alternative to the client-side JavaScript version of the Finance Calculator, we also provide a web service API to facilitate server-side access to the Finance Calculator Tool. The service takes several parameters and then returns a JSON object (a serialised collection of field/value pairs) containing the relevant details. The service can be used to return either the total spend based on a specified monthly budget or a monthly budget based on the specified total spend. A deposit figure can either be specified or automatically calculated. To access the service, send an HTTP GET request to with the following data as an attached query string: Field Type Required Description api_key STRING Yes Your unique account identifier budget FLOAT No** The amount per month that the customer wishes to spend goods_spend FLOAT No** The total value of the order deposit FLOAT No The value of the deposit finance_product STRING Yes The code for the particular finance product the customer would like (e.g. ONIF6 for 6 moths interest free online credit) Table 15: Finance Calculator Tool Web Service API parameters ** You must provide either a budget or goods spend. Sample PHP Code: //Calculate the total spend based on a monthly budget $interface = " KEY]&budget=[MONTHLY BUDGET]&deposit=[DEPOSIT]&finance_product=[FINANCE CODE]"; $curlsession = curl_init(); curl_setopt($curlsession, CURLOPT_URL, $interface); curl_setopt($curlsession, CURLOPT_HEADER, 0); curl_setopt($curlsession, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($curlsession, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curlsession, CURLOPT_USERAGENT, "Pay4Later HTTP Post"); curl_setopt($curlsession, CURLOPT_FOLLOWLOCATION, 1); $curl_response = curl_exec($curlsession); $response = json_decode($curl_response); Sample C#.NET Code: Figure 16: Finance Calculator Tool Web Service Sample Code in PHP

26 string url = " NameValueCollection data = new NameValueCollection(); data.add("api_key", "[API KEY]"); data.add("budget", "[MONTHLY BUDGET]"); data.add("deposit", "[DEPOSIT]"); data.add("finance_product", "[FINANCE CODE]"); // WebClient is part of the System.Net namespace WebClient client = new WebClient(); client.querystring.add(data); String response = client.downloadstring(url); Figure 17: Finance Calculator Tool Web Service Sample Code in.net The serialized fields returned are as follows: Field Type Description goods_spend FLOAT If the monthly_repayment parameter was specified this field will give the resultant goods_spend figure monthly_repayment FLOAT If the goods_spend parameter was specified this field will give the resultant monthly_repayment figure total_cost FLOAT The goods_spend total for a specified monthly_repayment figure cost_of_loan FLOAT Cost to the consumer of the finance error FLOAT Error details if error returned, otherwise 0 loan_amount FLOAT The loan value deposit FLOAT The deposit value term INTEGER Finance agreement term in months apr FLOAT The APR rate for the finance min_deposit FLOAT The minimum valid deposit max_deposit FLOAT The maximum valid deposit Table 16: Finance Calculator Tool Web Service API Reponse Fields

27 17 Remittance CSV For accounting puposes, a CSV file of deals paid out on a specific day can be sent upon request. An will be sent to the specified accounts address for your company with the csv file attached. The service can be initiated by sending an HTTP POST to with the following data. Field Type Required Notes api_key STRING Yes Your unique account identifier action STRING Yes This should be request_remittance in lower case date STRING Yes The date to export in ISO 8601 date format YYYY-MM- DD (e.g ) Table 17: Remittance API Variables $interface = " $postfields = Array( Sample "api_key" PHP Code: => "[API KEY]", "action" => "request_remittance", "date" => "[REQUESTED DATE]", ); $curlsession = curl_init(); curl_setopt($curlsession, CURLOPT_URL, $interface); curl_setopt($curlsession, CURLOPT_HEADER, 0); curl_setopt($curlsession, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($curlsession, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curlsession, CURLOPT_FOLLOWLOCATION, 1); curl_setopt($curlsession, CURLOPT_POST, 1); curl_setopt($curlsession, CURLOPT_POSTFIELDS, $postfields); $curl_response = curl_exec($curlsession); Figure 17: Example Remittance Request in PHP string url = " Sample NameValueCollection C#.NET Code: data = new NameValueCollection(); data.add("api_key", "[API KEY]"); data.add("action", "request_remittance"); data.add("date", "[REQUESTED DATE]"); // WebClient is part of the System.Net namespace WebClient client = new WebClient(); client.uploadvalues(url, data); Figure 18: Example Remittance Request in.net The response to a successful remittance CSV request is identical to the example shown in figure 13. Failed remittance csv requests are identical to the example shown in figure 14.

28 The CSV file will be ed to the accounts contact specified in Retailer Portal. The CSV file is comma delimited with the following columns: Field Type Description App ID INTEGER Credit Request ID Reference STRING Supplied retaileruniqueref parameter Consumer STRING Consumer s name Description STRING Goods Description Advance FLOAT Credit amount Deposit FLOAT Deposit amount Subsidy FLOAT Retailer cost of the finance Outpayment FLOAT Payment made to retailer Table 18: Remittance CSV File Format

29 Appendix A: Error Codes The following is a table of the error codes that can appear on the credit application and their meaning. Error Code 0x001 0x002 0x003 0x004 0x005 0x006 0x007 0x008 0x009 0x00A 0x00B 0x00C 0x00D 0x00E 0x00F 0x010 0x011 0x012 0x013 0x014 0x015 0x016 0x017 0x018 0x019 0x01A 0x020 0x021 0x022 0x026 0x027 Description The credit application was given no hash or POST. One or many of the goods in the POST failed validation due to: Price is less than 0 Description is less than 3 characters or greater than 1024 characters Quantity is not valid Deposit in the POST is not valid. An in-store application was launched without an authorised Retailer Portal user logged in. There was no 'Retailer Installation Id' or 'API Key' in the POST. The API Key is not valid. The link used is incorrect. The link used is expired. The incomplete credit request link is not valid. The link is not valid. The link has expired. The web link is not valid. The web link has expired. The link used to continue an application is invalid. The Retailer Portal User is not authorised to continue a credit application. The link type is not recognized. The Retailer Installation Id is not valid. The Retailer Installation Id is not valid with the API Key given. Applications can't be made from the test platform with the account. No Finance Product was selected. There is no goods data input. An application with the same retailer unique reference has been submitted and automatic unique reference has been turned off. The account being used has no products set up to us the finance code input. The deposit given is either below the minimum or above the maximum allowed. The credit is above the maximum or below the minimum allowed. Could not load the retailer's first credit policy for documents. The account being used is not eligible for this version of the application. Applications can't be made from the live platform with the account. Invalid Goods: Quantity must be a positive number, Price must be greater than 0, Description length must be between 3 and 1024 characters long The link has expired. The link has already been used. Table 19: Error Codes

30 Appendix B: Optional Credit Application Variables (Pass Thru Data) The following optional credit application variables may be submitted, subject to appropriate validation. Field Type Required Description Mr, Mrs, Ms, Title/salutation Consumer[Title] Miss, Dr, Rev, Col, Sgt No Consumer[Forename] STRING No First name Consumer[Surname] STRING No Surname Consumer[DateOfBirthDay] INTEGER No Birth date day Consumer[DateOfBirthMonth] INTEGER No Birth date month Consumer[DateOfBirthYear] INTEGER No Birth date year Consumer[PersonalPhoneNumber] STRING No Consumer[MobileNumber] STRING No General/landlin e phone number Mobile phone number Consumer[ Address] STRING No address Consumer[Postcode] STRING No Postcode Table 20: Pass Thru Data Variables The matching credit application fields will be pre-populated, providing additional convenience to the consumer.

31 Appendix C: Fulfilment Request Array You can batch multiple fulfilment requests into an array by sending an HTTP POST to with the following data. Field Type Required Notes cr_id INTEGER Yes The CBRF ID for this credit application api_key STRING Yes Your unique account identifier fulfilment_array STRING Yes This should be true in lower case fulfilment_ref STRING Yes The shipping reference for the goods sent Table 21: Fulfilment Requests Array Variables $interface = " There $postfields is a 2d array = Array( called fulfillments of credit requests to be set as fulfilled. Each credit request "fulfilment_array"=>"true", must contain the cr_id and fulfilment_ref fields. // your api key Sample PHP Code: "api_key" => "[API KEY]", //first fulfilled credit request id "fulfilments[0][cr_id]" => "[CREDIT REQUEST ID]", // a postal tracking or reference number for this order "fulfilments[0][fulfilment_ref]" => "[FULFILLMENT REFERENCE]" //Second fulfilled credit request "fulfilments[1][cr_id]" => "[CREDIT REQUEST ID]", "fulfilments[1][fulfilment_ref]" => "[FULFILLMENT REFERENCE]" ); $curlsession = curl_init(); curl_setopt($curlsession, CURLOPT_URL, $interface); curl_setopt($curlsession, CURLOPT_HEADER, 0); curl_setopt($curlsession, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($curlsession, CURLOPT_POST, 1); curl_setopt($curlsession, CURLOPT_POSTFIELDS, $postfields); curl_setopt($curlsession, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curlsession, CURLOPT_TIMEOUT, 180); curl_setopt($curlsession, CURLOPT_FOLLOWLOCATION, 1); $curl_response = curl_exec($curlsession); Figure 19: Example Fulfillment Array in PHP

32 string url = " NameValueCollection data = new NameValueCollection(); data.add("fulfilment_array", "true"); Sample data.add("api_key", C#.NET Code: "[YOUR API KEY]"); //first fulfilled credit request data.add("fulfilments[0][cr_id]", "[CREDIT REQUEST ID]"); // a delivery tracking or reference number for this order data.add("fulfilments[0][fulfilment_ref ]", "[A FULFILLMENT REFERENCE]"); //Second fulfilled credit request data.add("fulfilments[1][cr_id]", "[CREDIT REQUEST ID]"); data.add("fulfilments[1][fulfilment_ref ]", "[A FULFILLMENT REFERENCE]"); WebClient client = new WebClient(); client.uploadvalues(url, data); Figure 20: Example Fulfillment Array in.net A CSN will be sent with the status field as 'FULFILLED' for each credit application included in the array.