Appearance
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:
- If you're not PCI DSS certified – Using the secure form (HiPay’s Hosted Page), or relying on secure fields (HiPay’s Hosted Fields).
- If you're PCI DSS certified – Directly using the dedicated endpoint.
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.
bash
# encode your private credentials in base64
hipayPrivateCredentials=`echo "myprivateuser:myprivatepassword" | base64 -`
# tokenize the card
curl -X POST '{hiPayTokenizationFormBaseUrl}/v1/hpayment' \
--header 'Authorization: Basic {hipayPrivateCredentials}' \ # as encoded above
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is an example of {payload}.
Please bear in mind that the choice of operation impacts the capture mode, which depends on your configuration. Contact Treezor if you're unsure of which one to use.
json
{
"orderid": "order_xxxxx", // Must be unique
"operation": "Authorization", // Authorization || Sale
// 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}}"
},
// Please don't use other custom_data than the ones indicated above.
"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": "1.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": "", // Deprecated, please ignore
"cdata5": "", // Deprecated, please ignore
"cdata6": "", // Deprecated, please ignore
"cdata7": "", // Deprecated, please ignore
"cdata8": "", // Deprecated, please ignore
"cdata9": "", // Deprecated, please ignore
"cdata10": "", // Deprecated, please ignore
"order": {
"id": "order_1685549327",
"dateCreated": "2023-05-31T16:08:47+0000",
"attempts": "0",
"amount": "1.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.
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 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:
|
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 – Authorize tokenized cards first with 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.
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
{
"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
bash
curl -X DELETE '{baseUrl}/v1/topups/cards/users/userId}/topupCards/{topupCardId}' \
--header 'Authorization: Bearer {accessToken}'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"
}
]
}