Card Tokenization

Tokenization is the process of converting the PAN, expiration date, and CVC of a card into a token.

The tokenization request must be sent from the end user's device (for example using JavaScript), as the PAN cannot transit or be stored on your servers.

You may generate the token either:

Using the secure form, or relying on HiPay's SDK (if you're not PCI DSS certified).
Directly using the dedicated endpoint (if you are PCI DSS certified).

Information – These are the only HiPay endpoints allowed

Any other actions must be carried out using the Treezor API.

Tokenize with the secure form

If you're not PCI DSS-certified, HiPay provides 2 endpoints, so you can:

Generate the token of the card using a secure form.
Retrieve the generated token.

1. Generate token through secure form

You can make the following HiPay request to generate the form that will then be used by the end user to tokenize the card.

CURL

bash

# encode your public credentials in base64
hipayPublicCredentials=`echo "mypublicuser:mypublicpassword" | base64 -`
# tokenize the card
curl -X POST {hiPayTokenizationFormBaseUrl}/v1/hpayment \
	--header 'Authorization: Basic {hipayPublicCredentials}' \	# as encoded above
	--header 'Accept: application/json' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

json

{
    "orderid": "order_{{$timestamp}}",
    "operation":"Authorization",

// custom_data error will result in the funds being debited from external account,
// but not credited on the Treezor Wallet of the real beneficiary of the capture.

    "custom_data" : {
                      "1":"{{clientId}}",
                      "2":"{{temp_walletId}}",
                      "3":"{{temp_userId}}"
                     },
    "payment_product_list": "visa, mastercard, cb", 
    "template": "basic-js",
    "merchant_display_name": "Merchant name",
    "display_selector": "1",
    "description": "description",
    "email": "aokm@example.com",
    "card_holder": "Alex Oak",
    "currency": "EUR",
    "amount": "100.00",
    "ipaddr": "",			// IP of the device from which the capture is made
    "accept_url": "",
    "decline_url": "",
    "pending_url": "",
    "exception_url": "",
    "cancel_url": "",
    "language": "FR_fr",

// Cardholder authentification
    "eci" : "7",                       // single-use mode
    "authentication_indicator": "2",   // forces 3DS

    "device_channel" : "2",
    "multi_use" : 1                   
}

Returns an object containing the forwardUrl you need to provide to your end user.

JSON

json

  {
    "forwardUrl": "https://stage-secure-gateway.hipay-tpp.com/0000-133-2882/payment/web/pay/50b6814c-27fd-49e2-adea-33bba7150c9c",
    "test": "true",
    "mid": "00001332882",
    "cdata1": "39625",
    "cdata2": "2220766",
    "cdata3": "4064148",
    "cdata4": "",
    "cdata5": "",
    "cdata6": "",
    "cdata7": "",
    "cdata8": "",
    "cdata9": "",
    "cdata10": "",
    "order": {
        "id": "order_1685549327",
        "dateCreated": "2023-05-31T16:08:47+0000",
        "attempts": "0",
        "amount": "100.00",
        "shipping": "0.00",
        "tax": "0.00",
        "decimals": "2",
        "currency": "EUR",
        "customerId": "",
        "language": "FR_fr",
        "email": "aoak@example.com"
    }
}

By using the forwardUrl, your end user accesses the form to enter their card information, which will in turn generate the token.

Reading – Full parameters documentation available

Refer to HiPay's Documentation to learn everything there is to know about the parameters.

Reading – Customize your hosted payment form

Refer to the Hosted Payments section of HiPay's documentation to learn how to customize your hosted payment form.

2. Retrieve the token

Once the user has generated the token, you may retrieve it.

CURL

bash

# encode your public credentials in base64
hipayPublicCredentials=`echo "mypublicuser:mypublicpassword" | base64 -`
# tokenize the card
curl -X GET {hiPayBaseUrl}/rest/v1/transaction?orderId={orderid} \
	--header 'Authorization: Basic {hipayPublicCredentials}' \	# as encoded above
	--header 'Accept: application/json'

Returns the following Transaction, with the token available in the paymentMethod object.

JSON

json

{
    "transaction": {
        "state": "completed",
        "reason": "",
        "forwardUrl": "",
        "test": "true",
        "mid": "00001332882",
        "attemptId": "1",
        "authorizationCode": "",
        "transactionReference": "800242932739",
        "dateCreated": "2023-06-30T09:07:41+0000",
        "dateUpdated": "2023-06-30T09:07:52+0000",
        "dateAuthorized": "2023-06-30T09:07:52+0000",
        "status": "116",
        "message": "Authorized",
        "authorizedAmount": "1.00",
        "capturedAmount": "0.00",
        "refundedAmount": "0.00",
        "decimals": "2",
        "currency": "EUR",
        "ipAddress": "212.114.31.26",
        "ipCountry": "FR",
        "deviceId": "",
        "cdata1": "client_id",
        "cdata2": "wallet_id",
        "cdata3": "user_id",
        "cdata4": "",
        "cdata5": "",
        "cdata6": "",
        "cdata7": "",
        "cdata8": "",
        "cdata9": "",
        "cdata10": "",
        "avsResult": "",
        "cvcResult": "",
        "eci": "7",
        "paymentProduct": "visa",
        "paymentMethod": {
            "token": "ba3dd3760142bd6fc715b99429839b06d6de6bd1c6f1eaf36a788668396d011d",
            "cardId": "b1113d3b-5140-4616-abf7-49aeec3f4414",
            "brand": "VISA",
            "pan": "424242******4242",
            "cardHolder": "ALEX OAK",
            "cardExpiryMonth": "05",
            "cardExpiryYear": "2024",
            "issuer": "",
            "country": "GB"
        },
        "threeDSecure": {
            "eci": "5",
            "authenticationStatus": "Y",
            "authenticationMessage": "Authentication Successful",
            "authenticationToken": "",
            "xid": ""
        },
        "fraudScreening": {
            "scoring": "0",
            "result": "ACCEPTED",
            "review": ""
        },
        "order": {
            "id": "order_1688116033",
            "dateCreated": "2023-06-30T09:07:12+0000",
            "gender": "U",
            "firstname": "",
            "lastname": "",
            "streetAddress": "",
            "locality": "",
            "postalCode": "",
            "country": "",
            "attempts": "1",
            "amount": "1.00",
            "shipping": "0.00",
            "tax": "0.00",
            "decimals": "2",
            "currency": "EUR",
            "customerId": "",
            "language": "FR_fr",
            "msisdn": "",
            "phone": "",
            "phoneOperator": "",
            "shippingAddress": {
                "firstname": "",
                "lastname": "",
                "streetAddress": "",
                "locality": "",
                "postalCode": "",
                "country": ""
            },
            "email": "teamimplem@test.com"
        },
        "debitAgreement": {
            "id": "10520843",
            "status": "available"
        }
    }
}

Reading – Full parameters documentation available

Refer to HiPay's Documentation to learn everything there is to know about the parameters.

Tokenize with the create token request

If you are PCI DSS-certified, you can directly use the dedicated endpoint to generate the card token.

Parameters

Attribute	Type	Description
`card_number`	string	The primary account number (PAN) of the card.
`card_expiry_month`	integer	The month on which the card expires.
`card_expiry_year`	integer	The year on which the card expires.
`card_holder`	string	The name of the cardholder, embossed or etched on the card.
`cvc`	integer	The CVC of the card.
`multi_use`	integer	Indicates whether the card can be used multiple times. Either: `0` – The card can only be used once, and the token expires after a month if not used. `1` – The card can be used multiple times and the token expires at the card expiry date.

In addition, you'll need your hipayPublicCredentials in the request Authorization header. It is a concatenation of hipay_public_user : hipay_public_password credentials, without spaces and encoded in base64.

Request example

CURL

bash

# encode your public credentials in base64
hipayPublicCredentials=`echo "mypublicuser:mypublicpassword" | base64 -`
# tokenize the card
curl -X POST {hiPayTokenizationBaseUrl}/rest/v2/token/create \
	--header 'Authorization: Basic {hipayPublicCredentials}' \	# as encoded above
	--header 'Accept: application/json' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

json

{
	"card_number":"5300000000000006",
	"card_expiry_month":12,
	"card_expiry_year":2025,
	"card_holder":"Alex Oak",
	"cvc":123,
	"multi_use":1
}

Returns the token of the card.

JSON

json

{
    "token": "ee9ac2901f4c0d651143664659f206bb6e34ee552ab4e693fa21616b0ef69a57",
    "request_id": "0",
    "card_id": "9fd81707-8f41-4a01-b6ed-279954336ada",
    "multi_use": 1,
    "brand": "VISA",
    "pan": "411111xxxxxx1111",
    "card_holder": "Alex Oak",
    "card_expiry_month": "12",
    "card_expiry_year": "2025",
    "issuer": "JPMORGAN CHASE BANK, N.A.",
    "country": "US",
    "card_type": "CREDIT",
    "forbidden_issuer_country": false
}

Warning – A tokenized card must first be used with an eci = 7 payment to enforce 3DS

You must receive a successful payment before you can either use it with eci = 9 or store the cardtoken in your database.

If you're encountering an error, please check out the HiPay's error codes documentation.

Associate the card to a User

To acquire funds using the tokenized card, you need to create the corresponding Topup Card object in the Treezor API for a given user.

To do so, use the following request with the token provided by HiPay during the tokenization step.

CURL

bash

curl -X POST {baseUrl}/v1/topups/cards/users/{userId}/topupCards \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{ 
		"token":"{temporaryHiPayToken}"
	}'

Returns the Topup Card object, and sends a topupCard.validate webhook.

JSON

json

{
    "topupCards": [
        {
            "topupCardId": "d88fa963-2cd1-4409-9adc-a06f77b11291",
            "token": "9741899a3e6c109f0f0162117fce703be273e56eaac2f269f9f6304f7474c07c",
            "userId": "1656177",
            "brand": "VISA",
            "maskedPan": "411111xxxxxx1111",
            "cardHolder": "Alex Oak",
            "cardExpiryMonth": "12",
            "cardExpiryYear": "2025",
            "issuer": "JPMORGAN CHASE BANK, N.A.",
            "country": "US",
            "domesticNetwork": null,
            "cardType": "CREDIT",
            "createdDate": "2022-01-26 14:32:17",
            "updatedDate": "2022-01-26 14:32:17",
            "status": "VALIDATED",
            "providerName": "HiPay",
            "clientId": "212707"
        }
    ]
}

To prevent abuse and misuse, there is a maximum of 10 active cards associated to a single User at any given time. You may revoke Topup Cards if necessary.

Revoke a Topup Card

The following request permanently revokes a Topup Card. This action revokes the token and sets the Topup Card status to CANCELED permanently.

Revoking cards is highly recommended to prevent any kind of misuse. Please also note that there is a limit of 10 active cards associated to a single User at any given time.

You can still tokenize the card again if necessary.

Request

CURL

bash

curl -X DELETE {baseUrl}/v1/topups/cards/users/userId}/topupCards/{topupCardId} \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json'

Returns the disabled Tokenized Card and sends a topupCard.cancel webhook.

JSON

json

{
	"topupCards": [
		{
			"topupCardId": "d88fa963-xxxx-xxxx-xxxx-a06f77b11291",
			"token": "9741899[...]7474c07c",
			"userId": "1656177",
			"brand": "VISA",
			"maskedPan": "411111xxxxxx1111",
			"cardHolder": "Alex Oak",
			"cardExpiryMonth": "12",
			"cardExpiryYear": "2025",
			"issuer": "JPMORGAN CHASE BANK, N.A.",
			"country": "US",
			"domesticNetwork": null,
			"cardType": "CREDIT",
			"createdDate": "2022-01-26 14:32:17",
			"updatedDate": "2022-01-26 14:32:17",
			"status": "CANCELED", 
			"providerName": "HiPay",
			"clientId": "212707"
		}
	]
}

Card Tokenization ​

Tokenize with the secure form ​

1. Generate token through secure form ​

2. Retrieve the token ​

Tokenize with the create token request ​

Parameters ​

Request example ​

Associate the card to a User ​

Revoke a Topup Card ​

Request ​

Card Tokenization

Tokenize with the secure form

1. Generate token through secure form

2. Retrieve the token

Tokenize with the create token request

Parameters

Request example

Associate the card to a User

Revoke a Topup Card

Request