Skip to content

Card Tokenization

The 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:

Info icon

Information – These 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:

  1. Generate the token of the card using a secure form.
  2. 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.

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

books icon

Reading – Full parameters documentation available

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

books icon

Reading – Customize your hosted payment form

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

2. Retrieve the token

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

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

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're PCI DSS-certified, you can directly use the dedicated endpoint to generate the card token.

Parameters

AttributeTypeDescription
card_numberstringThe primary account number (PAN) of the card.
card_expiry_monthintegerThe month on which the card expires.
card_expiry_yearintegerThe year on which the card expires.
card_holderstringThe name of the cardholder, embossed or etched on the card.
cvcintegerThe CVC of the card.
multi_useintegerIndicates 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

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
{
	"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
{
    "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
}
red warning icon

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

bash
curl -X POST {baseUrl}/v1/topups/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
{
    "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 set 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

bash
curl -X DELETE {baseUrl}/v1/topups/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
{
	"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"
		}
	]
}