Credit Card Customer Token

Tokenizing credit cards

Security considerations when Tokenizing credit cards

For traditional credit cards (eg. VISA, MasterCard, AMEX), you will want to provide some security information, in order to increase the chances of a successful transaction.

We support the following security methods:

3DS2
3DS1
MOTO

Depending on the specified security method, additional data will be required.

3DS2

Attribute

Explanation

cavv

The authenticationValue from your 3D Secure 2 provider

dsTransID

The unique transaction identifier assigned by the DS to identify a single transaction

eci

The electronic commerce indicator

3DS1

Attribute

Explanation

authenticationResponse

From the paResponse from the issuer access control system

directoryResponse

The enrollment response from the VERes message from the directory server

cavv

The authentication value for the 3D Secure authentication session. The returned value is a Base64-encoded 20-byte array

cavvAlgorithm

The CAVV Algorithm used during the authentication

xid

The transaction identifier assigned by directory server (base64 encoded, 20 bytes in a decoded form)

eci

The electronic commerce indicator

MOTO

This is a fallback method if no 3DS information is available.

Create a credit card customer token

Here is an example of a successful request for a credit card tokenisation, with 3DS1.

Create customer token using a credit card

POST https://staging.api.xpay.xcover.com/customer-tokens/credit-card

Headers

Name

Type

Description

Authorization*

string

Bearer {{JWT}}

{
    "customer": {
      "email": "[email protected]"
    },
    "creditCard": {
      "number":"4917610000000000",
      "expiryMonth":"03",
      "expiryYear":"2030",
      "cvc":"737",
      "holderName":"John Smith",
      "cavv": "3q2+78r+ur7erb7vyv66vv\/\/\/\/8=",
      "eci": "05",
      "dsTransID": "c4e59ceb-a382-4d6a-bc87-385d591fa09d" 
    },
    "securityMethod": "3DS2",
    "reference": "Your random reference value"
}

HTTP 201

{
    "data": {
        "id": "2e030333-03e8-469f-b6d5-a91e9e03ffda",
        "customerId": "22c2425c-aaa4-401a-b928-d3f1b1ad1b4b",
        "paymentProviderId": "3def49ad-7365-48eb-982b-526a3b8ea8e0",
        "createdAt": "2020-04-28T00:30:54+00:00",
        "updatedAt": "2020-04-28T00:30:55+00:00",
        "metadata": {
            "variant": "visa",
            "paymentMethod": "Credit card",
            "expiryMonth": "3",
            "expiryYear": "2030",
            "holderName": "John Smith",
            "number": "0000"
        }
    }
}

Failure Scenarios

There are many reasons why a tokenization of a credit card may fail. Here are some examples.

Missing Card Details

{
    "customer": {
      "email": "[email protected]"
    },
    "creditCard": {},
    "securityMethod": "3DS2",
    "reference": "existing reference value"
}

HTTP 422

{
    "message": "The given data was invalid.",
    "errors": {
        "creditCard": [
            "The credit card field is required."
        ],
        "creditCard.holderName": [
            "The credit card.holder name field is required."
        ],
        "creditCard.number": [
            "The credit card.number field is required."
        ],
        "creditCard.expiryYear": [
            "The credit card.expiry year field is required."
        ],
        "creditCard.expiryMonth": [
            "The credit card.expiry month field is required."
        ],
        "creditCard.cvc": [
            "The credit card.cvc field is required."
        ],
        "reference": [
            "The reference has already been taken.",
            "The reference must not be greater than 255 characters."
        ]
    }
}

Card Declined

{
    "customer": {
      "email": "[email protected]"
    },
    "creditCard": {
      "number":"4917610000000000",
      "expiryMonth":"03",
      "expiryYear":"2030",
      "cvc":"{{ Wrong CVC }}",
      "holderName":"John Smith",
      "cavv": "3q2+78r+ur7erb7vyv66vv\/\/\/\/8=",
      "eci": "05",
      "dsTransID": "c4e59ceb-a382-4d6a-bc87-385d591fa09d" 
    },
    "securityMethod": "3DS2",
    "reference": "Your random reference value"
}

Invalid Credit Card Number

{
    "customer": {
      "email": "[email protected]"
    },
    "creditCard": {
      "number":"{{ INVALID NUMBER }}",
      "expiryMonth":"03",
      "expiryYear":"2030",
      "cvc":"WRONG CVC",
      "holderName":"John Smith",
      "cavv": "3q2+78r+ur7erb7vyv66vv\/\/\/\/8=",
      "eci": "05",
      "dsTransID": "c4e59ceb-a382-4d6a-bc87-385d591fa09d" 
    },
    "securityMethod": "3DS2",
    "reference": "Your random reference value"
}

HTTP 422

{
    "message": "The given data was invalid.",
    "errors": {
        "creditCard.number": [
            "validation.credit_card.card_checksum_invalid"
        ],
        "creditCard.cvc": [
            "validation.credit_card.card_cvc_invalid"
        ]
    }
}

PreviousAPI Reference NextDirect Debit Customer Token

Last updated 3 years ago

hashtagSecurity considerations when Tokenizing credit cards

hashtag3DS2

hashtag3DS1

hashtagMOTO

hashtagCreate a credit card customer token

hashtagCreate customer token using a credit card

hashtagHeaders

hashtagFailure Scenarios

hashtagMissing Card Details

hashtagCard Declined

hashtagInvalid Credit Card Number