Credit Card Retrieval API Implementation Guide This guide illustrates how to implement the Credit Card Retrieval API.

Transcription

1 Credit Card Retrieval API Implementation Guide This guide illustrates how to implement the Credit Card Retrieval API. Copyright: Jumio Inc. 268 Lambert Avenue, Palo Alto, CA 94306

2 Contents Credit Card Retrieval API Implementation Guide... 1 Contents... 2 Release notes... 3 Contact... 3 Retrieving credit card image... 4 Retrieving credit card details... 5 Supported cipher suites

3 Release notes Version Date Description Added unmasked retrieval of cardaccountnumber Updated supported cipher suites during SSL handshake Added supported cipher suites during SSL handshake (TLS required) Changed location of API credentials due to redesigned merchant backend Initial release Contact If you have any questions regarding our implementation guide please contact Jumio Customer Service at or The Jumio online helpdesk contains a wealth of information regarding our service including demo videos, product descriptions, FAQs and other things that may help to get you started with Jumio. Check it out at: 3

4 Retrieving credit card image By calling the RESTful HTTP GET API below you receive the masked credit card image of a successful scan by specifying the Jumio scan reference as a path parameter. To receive the unmasked image, append the query parameter maskhint=unmasked. By default, retrieval of unmasked images is disabled (HTTP status code 403 Forbidden). If you want to enable it please contact [email protected]. Retrieving unmasked images might impose additional security requirements on your systems depending if you already store/transmit/process credit card data on your systems 1. REST URL: Authentication: The API call is protected. To access it, use HTTP Basic Authentication with your merchant API token as the "userid" and your API secret as the "password". Log into and you can find your merchant API token and API secret on the "Settings" page under "API credentials". Header: The following parameter is mandatory in the "header" section of your request. User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/VERSION (e.g. MyCompany MyApp/1.0.0) SSL handshake: The TLS protocol is required (see Supported cipher suites chapter) and we strongly recommend using the latest version. Note: Calls with missing or suspicious headers, suspicious parameter values, or without HTTP Basic Authentication will result in HTTP status code 403 Forbidden. Request parameters Note: Mandatory parameters are highlighted. Parameter Type Max. length Description scanreference (path parameter) String 36 Jumio s reference number of an existing scan from your account maskhint String Possible values: (query parameter) masked (default) unmasked Response You receive a JPEG image in case of success, or HTTP status code 404 Not Found if the scan or the image is not available, which may take up to 5 minutes. 1 In case you are unsure about the ramifications of retrieving unmasked images regarding PCI DSS please refer to "Information Supplement: PCI DSS E-commerce Guidelines, version 2.0, January 2013" and/or contact your acquirer and/or contact a PCI DSS QSA (Qualified Security Assessor). 4

5 Sample request GET HTTP/1.1 User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x Authorization: Basic Retrieving credit card details By calling the RESTful HTTP GET API below you receive the credit card data of successful scans by specifying the Jumio scan reference as a path parameter. To receive unmasked card details, append the query parameter maskhint=unmasked. By default, retrieval of unmasked credit card details is disabled (HTTP status code 403 Forbidden). If you want to enable it please contact [email protected]. Retrieving unmasked credit card details might impose additional security requirements on your systems depending if you already store/transmit/process credit card data on your systems 2. REST URL: Authentication: The API call is protected. To access it, use HTTP Basic Authentication with your merchant API token as the "userid" and your API secret as the "password". Log into and you can find your merchant API token and API secret on the "Settings" page under "API credentials". Header: The following parameters are mandatory in the "header" section of your request. Accept: application/json User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/VERSION (e.g. MyCompany MyApp/1.0.0) SSL handshake: The TLS protocol is required (see Supported cipher suites chapter) and we strongly recommend using the latest version. Note: Calls with missing or suspicious headers, suspicious parameter values, or without HTTP Basic Authentication result in HTTP status code 403 Forbidden. Request parameter Note: Mandatory parameters are highlighted. Parameter Type Max. length Description scanreference (path parameter) String 36 Jumio s reference number of an existing scan from your account maskhint String Possible values: 2 In case you are unsure about the ramifications of retrieving unmasked images regarding PCI DSS please refer to "Information Supplement: PCI DSS E-commerce Guidelines, version 2.0, January 2013" and/or contact your acquirer and/or contact a PCI DSS QSA (Qualified Security Assessor). 5

6 (query parameter) masked (default) unmasked Response parameters You receive a JSON response in case of success, or HTTP status code 404 Not Found if the scan or the credit card data is not available, which may take up to 5 minutes. Note: Mandatory JSON parameters are highlighted. Parameter Type Max. length Description jumiorequestreference String 36 Jumio s reference number for each scan cardnumber String 19 If maskhint = masked (default): First 6 and last 4 digits of the credit card number, other digits are masked with "x" If maskhint = unmasked: Full credit card number cardexpirymonth Number Min. value: 1 Month card expires Max. value: 12 cardexpiryyear Number 4 Year card expires in the format "YY" cardholdername String 100 Name of the credit card holder in capital letters cardsortcode String 8 Sort code in the format "xx-xx-xx" cardaccountnumber String 8 If maskhint = masked (default): Last two digits of the account number, other digits masked with "x" If maskhint = unmasked: Full account number Sample request GET HTTP/1.1 Accept: application/json User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x Authorization: Basic Sample response { "cardexpirymonth":"1", "cardexpiryyear":"2022", "cardnumber":"123456xxxxxx1234", "jumiorequestreference":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } 6

7 Supported cipher suites The following cipher suites (listed in server-preferred order) are supported by Jumio during the SSL handshake: TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_DHE_RSA_WITH_AES_128_CBC_SHA TLS_DHE_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_RC4_128_SHA TLS_RSA_WITH_AES_256_CBC_SHA 7