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
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... 7 2
Release notes Version Date Description 1.0.4 2014-10-07 Added unmasked retrieval of cardaccountnumber 1.0.3 2014-06-10 Updated supported cipher suites during SSL handshake 1.0.2 2014-04-23 Added supported cipher suites during SSL handshake (TLS required) 1.0.1 2014-01-14 Changed location of API credentials due to redesigned merchant backend 1.0.0 2013-12-17 Initial release Contact If you have any questions regarding our implementation guide please contact Jumio Customer Service at support@jumio.com or https://support.jumio.com. 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: https://support.jumio.com. 3
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 support@jumio.com. 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: https://netswipe.com/api/netswipe/v1/scans/<scanreference>/images/front 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 https://netswipe.com, 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
Sample request GET https://netswipe.com/api/netswipe/v1/scans/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx/images/front 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 support@jumio.com. 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: https://netswipe.com/api/netswipe/v1/scans/<scanreference>/creditcard 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 https://netswipe.com, 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
(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 https://netswipe.com/api/netswipe/v1/scans/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx/creditcard 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
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