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:
- Using the secure form, or relying on HiPay's SDK (if you're not PCI DSS certified).
- Directly using the dedicated endpoint (if you're PCI DSS certified).
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:
- 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.
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.
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 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"
}
}
}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
| 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:
|
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
}
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"
}
]
}