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}}

422: Unprocessable Entity Problem tokenizing credit card

201: Created Credit card successfully tokenized

Request

{
    "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"
}

Response

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

Request

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

Response

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

Request

{
    "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"
}

Response

HTTP 422

{
    "message": "stripe.card_declined",
    "errors": {
        "paymentMethod": [
            "stripe.card_declined"
        ]
    }
}

Invalid Credit Card Number

Request

{
    "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"
}

Response

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"
        ]
    }
}