Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
1 contributor

Users who have contributed to this file

155 lines (106 sloc) 8.67 KB

Jumio

Credit Card Retrieval API Implementation Guide

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

Table of Contents


Release Notes

Date Description
2017-05-23 Added response parameter "merchantReportingCriteria" for retrieving
credit card details
2016-07-19 Updated endpoint URLs
2016-05-18 Removed TLS_DHE ciphers
2015-10-21 Added ECDHE ciphers to supported cipher suites
2015-06-30 Introduced EU data center
2015-03-24 Removed cipher TLS_RSA_WITH_RC4_128_SHA due to RC4 deprecation
2014-10-07 Added unmasked retrieval of cardAccountNumber
2014-06-10 Updated supported cipher suites during SSL handshake
2014-04-23 Added supported cipher suites during SSL handshake (TLS required)
2014-01-14 Changed location of API credentials due to redesigned customer portal
2013-12-17 Initial release

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.

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).

HTTP request method: GET
REST URL: https://bam-retrieval.jumio.com/api/netswipe/v1/scans/<scanReference>/images/front
If your customer account is in the EU data center, use bam-retrieval.lon.jumio.com instead of bam-retrieval.jumio.com.

Authentication: The API call is protected. To access it, use HTTP Basic Authentication with your API token as the "userid" and your API secret as the "password". Log into your Jumio customer portal, and you can find your 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

    The value for User-Agent must contain a reference to your business or entity for Jumio to be able to identify your requests. (e.g. YourCompanyName YourAppName/1.0.0). Without a proper User-Agent header, Jumio will take longer to diagnose API issues.

TLS 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 marked with an asterisk * and highlighted bold.

Parameter Type Max. length Description
scanReference (path parameter) * String 36 Jumio’s reference number of an existing scan from your account
maskint (query parameter) String Possible values:
• 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.

Sample Request

GET https://bam-retrieval.jumio.com/api/netswipe/v1/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/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.

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).

HTTP request method: GET
REST URL: https://bam-retrieval.jumio.com/api/netswipe/v1/scans/<scanReference>/creditCard
If your customer account is in the EU data center, use bam-retrieval.lon.jumio.com instead of bam-retrieval.jumio.com.

Authentication: The API call is protected. To access it, use HTTP Basic Authentication with your API token as the "userid" and your API secret as the "password". Log into your Jumio customer portal, and you can find your 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

    The value for User-Agent must contain a reference to your business or entity for Jumio to be able to identify your requests. (e.g. YourCompanyName YourAppName/1.0.0). Without a proper User-Agent header, Jumio will take longer to diagnose API issues.

TLS handshake: The TLS protocol is required (see Supported Cipher Suites) 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 Parameters

Note: Mandatory parameters are marked with an asterisk * and highlighted bold.

Parameter Type Max. length Description
scanReference (path parameter) * String 36 Jumio’s reference number of an existing scan from your account
maskint (query parameter) String Possible values:
• 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 parameters are marked with an asterisk * and highlighted bold.

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
Max. value: 12
Month card expires
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 or xxxxxx
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
merchantReportingCriteria String 100 Your reporting criteria for each scan

Sample Request

GET https://bam-retrieval.jumio.com/api/netswipe/v1/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/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"
}

Supported Cipher Suites

Jumio supported cipher suites during the TLS handshake.

View supported cipher suites


© Jumio Corp. 268 Lambert Avenue, Palo Alto, CA 94306

You can’t perform that action at this time.