Online RESTful API documentation. V-Series

Size: px

Start display at page:

Download "Online RESTful API documentation. V-Series"

Erica Garrett
5 years ago
Views:

1 Online RESTful API documentation V-Series

2 V-Series Online RESTful API documentation Version 5.0 Copyright Bottomline Technologies Limited, All Rights Reserved Information in this document is subject to change without notice and does not represent a commitment on the part of Bottomline Technologies. Bottomline Technologies makes no warranties with respect to this documentation and disclaims any implied warranties of merchantability or fitness for particular purpose. Bottomline Technologies Limited Internet: Europe, Middle East, Africa 115 Chatham Street Reading, Berkshire RG17JX UK Telephone: emea-info@bottomline.com Page 2

3 Table of Contents Table of Contents... 3 Why use V-Series?... 5 What does V-Series do?... 5 Validation... 5 Verification... 5 RESTful API Usage notes... 6 General... 6 GET api/getversion GET api/getlicensedinfo GET api/getcredits POST manage/updateverify... 7 Request Information GET manage/verifyupdatestatus UK Bank Account Validation... 9 GET api/validateukbankaccount... 9 Request Information GET api/getukbankbranches Request Information GET api/getukbankbranch Request Information UK Bank Account Ownership Verification Test Data GET api/getukaddresses Request Information GET api/verifyukaccountownership Request Information Page 3

4 GET api/verifyukaccountownershipwithaddresses Request Information Credit Card Validation GET api/validatecreditcardnumber Request Information Page 4

5 Why use V-Series? Fully accredited by the Payments Council, V-Series enables you to authenticate your customer s account details in real time, ensuring that you can successfully make or collect payments first time, every time. Powerful validation and verification capabilities mean that you can avoid being tripped up by accidental mistakes, or targeted by fraudsters giving incorrect banking details. V-Series safeguards you by ensuring compliance with the Bacs Direct Debit scheme regulations, streamlines your customer on-boarding process and saves the time, cost, errors and opportunity for fraud associated with failed transactions. What does V-Series do? Validation Verification The validation process checks bank account and sort code details against the Extended Industry Sort Code Directory (EISCD) to ensure that the bank branch exists, and then confirms the validity of the account number for that sort code algorithmically. Account details are automatically transposed where appropriate and building society roll number requirements are also validated. Full administrative information about the bank offices is retrieved, including contact details and particulars about the UK clearing services that the office is able to participate in Direct Debits, Direct Credits, Faster Payments, CHAPS for example. The full database of bank office information can be searched based on a variety of criteria to identify matches. Algorithmic validation of credit card numbers is also available. Validation data, including the EISCD, is automatically updated to ensure that you are always checking against the latest records. The verification service allows you to connect an individual to the account details they provide to protect your goods and services against potential fraudsters. V-Series confirms that the individual is actually associated with the address and the account details provided and that the account is still open. By integrating the check into your acquisition systems at the point of contact, the customer sign up process is streamlined and efficient, reducing the need for alternative document based verification procedures. Page 5

6 RESTful API Usage notes When using the API, you'll need to prefix the URLs described below with the correct value. This depends on how you're using the service: If testing against our online RESTful API: If in production with our online RESTful API: It is important to note, that when using our online RESTful API you must provide your API key with each request. This can be done simply by appending &apikey=[yourkey] to the end of the request URL. This document will describe how to make RESTful calls for integration into your own application, with sample responses where appropriate. There is also a separate, comprehensive CHM help file that provides full detail of all responses and their meanings that should be used in conjunction with this document. General GET api/getversion Gets the version number. A version number string. GET api/getlicensedinfo Retrieves information detailing what the current user is licenced for. An object detailing current licenced status. Sample response "Name": null, "Identifier": null, "Expires": " T00:00:00", "LicencedItems": [ "Verifier": 0, "OnlineOnly": false, "VerifierDescription": "UK Bank Account Validation", "Verifier": 2, Page 6

7 "OnlineOnly": false, "VerifierDescription": "IBAN Validation" ] GET api/getcredits Retrieves the number of credits remaining for the current user. The current number of credits remaining for the current user POST manage/updateverify Request that Verify updates its data. Request Information Parameters Name Description Optional Usage updaterequestmodel Details of the product being updated No Request body 200 OK, if the update could be started. Sample response "Version": "Major": 1, "Minor": 1, "Build": -1, "Revision": -1, "MajorRevision": -1, "MinorRevision": -1, "Content": null, "StatusCode": 200, "ReasonPhrase": "OK", "Headers": [], "RequestMessage": null, "IsSuccessStatusCode": true Page 7

8 GET manage/verifyupdatestatus Gets the status of the latest Verify update request. Sample response "Status": 0, "StatusDescription": "", "LatestError": "", "Errors": [], "TotalVerifiers": 0, "CompletedVerifiers": 0, "CompletedVerifiersPercentage": 0, "CurrentVerifierDescription": "", "CurrentVerifierTotalPackages": 0, "CurrentVerifierCompletedPackages": 0, "CurrentVerifierCompletedPackagesPercentage": 0 Page 8

9 UK Bank Account Validation The UK Bank verifier allows you to validate that a UK Bank Sort Code and Account Number are structurally valid, that the Sort Code is live, and that the Account Number is correct for the given Sort Code. V-Series will validate that the Sort Code and Account Number provided are valid, that the Sort Code is a known Sort Code, and that the Account Number passes a modulus check to ensure that it is correct for the given Sort Code. Additionally, in the provided result, V-Series will return all details about the UK Bank Branch that corresponds to the valid Sort Code. V-Series may alter or transpose some of the account details that you provide. You should ensure that you inspect the account details on the provided result as the validity of your information will be based upon the account details that are in the result, not necessarily the exact details that you input. Some UK account details require a Building Society Roll Number. This is an optional input, but if the account details provided require a Roll Number, the result will reflect this. The Roll Number can also be transposed, so you should inspect the details on the result as per above. The UKBank Verifier also provides API methods for finding Bank Branches based upon Sort Codes, or address details. GET api/validateukbankaccount Validates UK bank or building society account details. Request Information Parameters Name Description Optional Usage sortcode Sort code to be validated No accountnumber Account number to be validated No buildingsocietyrollnumber Building society roll number to be validated Yes Page 9

10 Sample response "AccountDetailsInput": "SortCode": "404772", "AccountNumber": " ", "BuildingSocietyRollNumber": "", "AccountDetailsOutput": "SortCode": "404772", "AccountNumber": " ", "BuildingSocietyRollNumber": "", "AccountIBAN": "GB41MIDL ", "AccountTranscribed": false, "UKBankBranch": "BankBIC": "MIDLGB21", "BranchBIC": "67M", "BankName": "HSBC BANK PLC", "BankOfficeTitle": "FIRST DIRECT, LEEDS", "BranchName": "FIRST DIRECT", "OfficeTitle": "First Direct", "ContactAddress1": "40 Wakefield Road", "ContactAddress2": "", "ContactAddress3": "", "ContactAddress4": "", "ContactAddressCity": "Leeds", "ContactAddressCounty": "", "ContactAddressPostCode": "LS98 1FD", "ContactAddressPostCountry": "UNITED KINGDOM", "ContactPhoneNumber": " ", "SortCode": "404772", "DateLastChanged": " T00:00:00", "TransactionInfo": "BacsCredits": true, "BacsDebits": true, "FasterPaymentsService": true, Page 10

11 "ChapsSterling": true, "DirectDebitInstructions": true, "UnpaidChequeClaims": true, "DividendInterest": true, "BuildingSocietyInterest": true, "ChapsBankBIC": "MIDLGB22", "ChapsBranchBIC": "XXX", "RequiresBuildingSocietyRollNumber": false, "BuildingSocietyRollNumberTranscribed": false, "InvalidIssue": 0, "Valid": true, "InvalidReason": "", "InvalidParameter": "" Page 11

12 GET api/getukbankbranches Retrieves a list of up to 1,000 bank branches that match the criteria provided. NOTE: The Optional parameters detailed below must still be specified in the URL. If they are marked as optional then the parameter may be blank. Request Information Parameters Name Description Optional Usage bankname Bank name Yes bankofficetitle The title of the bank branch Yes branchname The name of the bank branch Yes officetitle The title of the branch Yes town Town Yes county County Yes postcode Postcode Yes bacscredits If true, will only return results that support Bacs credits Yes bacsdebits If true, will only return results that support Direct Debits Yes fasterpayments If true, will only return results that support Faster Payments Yes chaps If true, will only return results that support CHAPS Yes Sample response [ "BankBIC": "MIDLGB21", "BranchBIC": "67M", Page 12

13 "BankName": "HSBC BANK PLC", "BankOfficeTitle": "FIRST DIRECT, LEEDS", "BranchName": "FIRST DIRECT", "OfficeTitle": "First Direct", "ContactAddress1": "40 Wakefield Road", "ContactAddress2": "", "ContactAddress3": "", "ContactAddress4": "", "ContactAddressCity": "Leeds", "ContactAddressCounty": "", "ContactAddressPostCode": "LS98 1FD", "ContactAddressPostCountry": "UNITED KINGDOM", "ContactPhoneNumber": " ", "SortCode": "404772", "DateLastChanged": " T00:00:00", "TransactionInfo": "BacsCredits": true, "BacsDebits": true, "FasterPaymentsService": true, "ChapsSterling": true, "DirectDebitInstructions": true, "UnpaidChequeClaims": true, "DividendInterest": true, "BuildingSocietyInterest": true, "ChapsBankBIC": "MIDLGB22", "ChapsBranchBIC": "XXX" ] Page 13

14 GET api/getukbankbranch Retrieves the branch details for a specific sort code. Request Information Parameters Name Description Optional Usage sortcode Branch sort code No Sample response "BankBIC": "MIDLGB21", "BranchBIC": "67M", "BankName": "HSBC BANK PLC", "BankOfficeTitle": "FIRST DIRECT, LEEDS", "BranchName": "FIRST DIRECT", "OfficeTitle": "First Direct", "ContactAddress1": "40 Wakefield Road", "ContactAddress2": "", "ContactAddress3": "", "ContactAddress4": "", "ContactAddressCity": "Leeds", "ContactAddressCounty": "", "ContactAddressPostCode": "LS98 1FD", "ContactAddressPostCountry": "UNITED KINGDOM", "ContactPhoneNumber": " ", "SortCode": "404772", "DateLastChanged": " T00:00:00", "TransactionInfo": "BacsCredits": true, "BacsDebits": true, "FasterPaymentsService": true, "ChapsSterling": true, "DirectDebitInstructions": true, "UnpaidChequeClaims": true, "DividendInterest": true, "BuildingSocietyInterest": true Page 14

15 , "ChapsBankBIC": "MIDLGB22", "ChapsBranchBIC": "XXX" Page 15

16 UK Bank Account Ownership Verification Test Data The UK Account Ownership verifier allows you to verify the owner and address of a set of UK bank account details. Tip: It is strongly recommended that you validate the Sort Code and Account Number using the UK Bank Verifier first to ensure that the sort code exists and the account passes the modulus check if the validation fails then there is no point in proceeding to the account verification check as the account cannot exist. V-Series will verify that the Sort Code and Account Number, Person and Address provided are correct; i.e. that the Person is the owner of the account and that this account is listed at this address. There are two versions of the API method: One method takes the full address text and will attempt to match it to a UK address. The second requires Address Keys which can be found by pre-searching for the address. When entering address details, it is recommended that a Post Code is always entered, along with a house number or name. If the Post Code is not entered then finding a match may prove less likely. You must supply the Current address, but can optionally supply a Previous address. You will receive separate results for these, but if the Current address is not valid or matched, then the Previous address will not be processed. The minimum data that must be entered for the Person is Forename (at least the initial) and Surname. Optionally, you can enter Title, Middlename and Date of birth. For each address supplied, you will receive a result. This result will have a status for both Sort Code and Account Number, along with a Recommended result, which provides a suggestion of how the result should be interpreted, based upon the combination of the two statuses. In most cases, if there is an issue with the Person or Address details, then the two statuses will likely be the same. However, should there be an issue with either the Sort Code or Account Number then the separate statuses allow you to detect which one has the problem. When evaluating this service with the test environment, the following test data is available: Name Date of Birth Address Sort Code Account Number David Archer 01/02/ High St, Westbury, BA133BN Outcome Sort Code and Account Number both match Debbie Mann 278 High St, Westbury, BA133BN Closed account Karen Tennant 01/08/ Rowlands Close, Training Town, IV448TZ Sort Code is not held, but account number does match Page 16

17 GET api/getukaddresses Retrieves UK Addresses that match the given input criteria. Blank parameters are ignored. NOTE: The Optional parameters detailed below must still be specified in the URL. If they are marked as optional then the parameter may be blank. If the postcode is not passed, then at least one other field must be completed. Request Information Parameters Name Description Optional Usage housenameornumber The name or number of the property Yes street2 The first street Yes street2 The second street Yes district The district Yes town The town or city Yes county The county Yes postcode The postcode Yes A list of matching UKAddresses instances. Sample response [ "AddressKey": "TEST ", "AddressShortname": "430 ROWLANDS CLOSE, IV448TZ", "HouseNumberOrName": "430", "Street1": "ROWLANDS CLOSE", "Street2": "BARNTON MILLS", "District": "", "Town": "TRAINING TOWN", "County": "ISLE OF SKYE", "Postcode": "IV448TZ" ] Page 17

18 GET api/verifyukaccountownership Verifies if the given Bank Account details are owned by the provided Person and pre-validated Address keys. NOTE: The Optional parameters detailed below must still be specified in the URL. If they are marked as optional then the parameter may be blank. Request Information Parameters Name Description Optional Usage title The subject's title Yes forename The subject's firstname No middlename The subject's middlename Yes surname The subject's surname No dob The subject's data of birth Yes accountnumber The account number No sortcode The sortcode No currentaddresskey The address key of the current address No previousaddresskey An optional address key for a previous address Yes A VerifyUKAccountOwnershipResult instance containing the validation results. Sample response "CurrentAddress": "SortCodeDataStatus": 9, "AccountNumberDataStatus": 10, "RecommendedStatus": 3, "PreviousAddress": "SortCodeDataStatus": 9, "AccountNumberDataStatus": 10, Page 18

19 "RecommendedStatus": 3 GET api/verifyukaccountownershipwithaddresses Verifies if the given Bank Account details are owned by the provided Person and explicit Address details. NOTE: The Optional parameters detailed below must still be specified in the URL. If they are marked as optional then the parameter may be blank. Request Information Parameters Name Description Optional Usage title The subject's title Yes forename The subject's firstname No middlename The subject's middlename Yes surname The subject's surname No dob The subject's data of birth Yes accountnumber The account number No sortcode The sortcode No currentaddress The address details of the current address (refer to CHM documentation for further detail) No Request body previousaddress An optional address details for a previous address (refer to CHM documentation for further detail) Yes Request body A VerifyUKAccountOwnershipResult instance containing the validation results. Sample response "CurrentAddress": Page 19

20 "SortCodeDataStatus": 9, "AccountNumberDataStatus": 10, "RecommendedStatus": 3, "PreviousAddress": "SortCodeDataStatus": 9, "AccountNumberDataStatus": 10, "RecommendedStatus": 3 Credit Card Validation The Credit Card verifier allows you to algorithmically validate a Credit Card number, and if valid, detect the Card Issuer. GET api/validatecreditcardnumber Validates a credit card number. Request Information Parameters Name Description Optional Usage creditcardnumber Credit card number to be validated No Sample response "CardIssuer": "Visa", "InvalidIssue": 0, "Valid": true, "InvalidReason": "", "InvalidParameter": "" Page 20

PT-X Drive. Installation Guide

PT-X Drive. Installation Guide PT-X Drive Installation Guide Notices Copyright Bottomline Technologies, Inc. 2015. All Rights Reserved Information in this document is subject to change without notice and does not represent a commitment