Legacy flow
This article focuses on the first version of the Acquiring feature provided by Treezor. It doesn't offer as many features as the newest services. If you have any doubt, don't hesitate to contact Treezor.
Payments received using HiPay's API create Payin objects with a paymentMethodId attribute set to 25 and send payin.create webhooks.
Feature activation – Contact Treezor to activate supported cards
The Card Acquiring V1 feature supports the following cards: CB, Visa, Mastercard, and Maestro.
Best practice – Store Payin Ids as 36-character-long strings
It will make your migration to acquiring v2 simpler, as the Ids will switch to UUIDv4.
Step 1, Tokenize the card
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.
Tokenization can be done in the following ways:
- Generate the token using the secure form, or relying on HiPay's SDK (if you're not PCI DSS certified).
- Generate the token 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.
Process if you're not PCI DSS certified
If you're not PCI DSS certified, HiPay provides two 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": "a.oak@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",
"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 {hiPayTokenizationBaseUrl}/rest/v1/transaction?orderId={orderid} \
--header 'Authorization: Basic {hipayPublicCredentials}' \ # as encoded above
--header 'Accept: application/json'Returns the following:
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",
"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.
Process if you're PCI DSS certified
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.
Step 2, Create the payment
Once you have tokenized the card, you can use this token to request a payment, crediting the Wallet of your choice.
Parameters
| Attribute | Type | Description |
|---|---|---|
custom_data | object | Allows you to associate the payment with the Wallet and User. |
cardtoken | string | The token of the card, as obtained in the tokenization step. |
accept_url | string | The URL to which the user is to be redirected in case of an authorized payment. |
decline_url | string | The URL to which the user is to be redirected in case of a declined payment. |
pending_url | string | The URL to which the user is to be redirected in case of the payment is left pending. |
exception_url | string | The URL to which the user is to be redirected in case they can the payment. |
cancel_url | string | The URL to which the user is to be redirected in case of |
eci | string |
|
authentication_indicator | string | Indicates how to handle 3DS. Can be:
|
hipayPrivateCredentials | string | The concatenation of hipay_private_user : hipay_private_password HiPay credentials, without spaces and encoded in base64. |
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.
Request
bash
# encode your private credentials in base64
hipayPrivateCredentials=`echo "myprivateuser:myprivatepassword" | base64 -`
# receive the payment
curl -X POST {hiPayBaseUrl}/rest/v1/order \
--header 'Authorization: Basic {hipayPrivateCredentials}' \ # as encoded above
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is an example of {payload}.
json
{
"orderid":"Order_1639671746",
"operation":"Sale",
"description":"IMP1639671746",
"currency":"EUR",
"amount":"100",
"ipaddr":"192.154.28.65",
"custom_data":{
"1":"123456", // your client_id
"2":"234567", // the walletId to credit
"3":"345678" // the userId to credit
},
"eci": "7", // list above
"authentication_indicator":"2", // see list above
"email":"teamimplem@test.com", // the cardholders email
"card_holder":"Tom Pes", // the cardholders name as embossed or etched on the card
"cardtoken":"{{temp_HiPayToken}}",
"payment_product":"visa",
"accept_url":"https://dictionary.cambridge.org/fr/dictionnaire/anglais/accept", // redirection URL in case of authorized payment
"decline_url":"https://dictionary.cambridge.org/fr/dictionnaire/anglais/decline", // redirection URL in case of declined payment
"pending_url":"https://dictionary.cambridge.org/fr/dictionnaire/anglais/pending", // redirection URL in case the payment is left pending
"exception_url":"https://dictionary.cambridge.org/fr/dictionnaire/anglais/exception", // redirection URL in case of fatal error
"cancel_url":"https://dictionary.cambridge.org/fr/dictionnaire/anglais/cancel", // redirection URL in case the end user cancels the payment
"device_channel":"1"
}Reading – Full parameters documentation available
Refer to HiPay's Documentation to learn everything there is to know about the parameters.
Returns the details regarding the capture.
json
{
"state": "completed",
"reason": "",
"forwardUrl": "",
"test": "true",
"mid": "00001332882",
"attemptId": "1",
"authorizationCode": "test123",
"transactionReference": "800143609738",
"referenceToPay": "",
"dateCreated": "2021-12-21T13:42:15+0000",
"dateUpdated": "2021-12-21T13:42:20+0000",
"dateAuthorized": "2021-12-21T13:42:19+0000",
"status": "118",
"message": "Captured",
"authorizedAmount": "100.00",
"capturedAmount": "100.00",
"refundedAmount": "0.00",
"creditedAmount": "0.00",
"decimals": "2",
"currency": "EUR",
"ipAddress": "192.154.28.65",
"ipCountry": "CA",
"deviceId": "",
"cdata1": "212707", // is your client_id as provided previously
"cdata2": "1174278", // is the recipients walletId as provided previously
"cdata3": "2189821", // is the recipients userId as provided previously
"cdata4": "",
"cdata5": "",
"cdata6": "",
"cdata7": "",
"cdata8": "",
"cdata9": "",
"cdata10": "",
"avsResult": "",
"eci": "9",
"paymentProduct": "visa",
"paymentMethod": {
"token": "3b1a89dfd033307f7a9fbf8757025f2226766e125b84e1cd616de9d7b7e4ebe4",
"cardId": "9fd81707-8f41-4a01-b6ed-279954336ada",
"brand": "VISA",
"pan": "411111******1111",
"cardHolder": "TOM PES",
"cardExpiryMonth": "12",
"cardExpiryYear": "2025",
"issuer": "JPMORGAN CHASE BANK, N.A.",
"country": "US"
},
"threeDSecure": "",
"fraudScreening": {
"scoring": "0",
"result": "ACCEPTED",
"review": ""
},
"order": {
"id": "Order_1639671746",
"dateCreated": "2021-12-21T13:42:15+0000",
"attempts": "1",
"amount": "100.00",
"shipping": "0.00",
"tax": "0.00",
"decimals": "2",
"currency": "EUR",
"customerId": "",
"language": "en_US",
"email": "teamimplem@test.com"
},
"debitAgreement": {
"id": "10337627",
"status": "available"
}
}Information
- The
custom_dataattribute that you provided is absent from this response, this is on purpose. - The
cdata{n}attributes will be removed from the reponses in the future.
You should not rely on this response but on the Webhooks instead.
Step 3, Receive the webhook
Once the payment has been made by the end user, you will receive a payin.update webhook.
This webhook informs you whether the payment is:
- Accepted – With a
payinStatusattribute set toVALIDATED - Refused or impossible – With a
payinStatusattribute set toCANCELED
Legacy payin.update event
json
{
"webhook":"payin.update",
"object":"payin",
"object_id":"103700",
"object_payload":{
"payins":[
{
"payinId":"103700",
"payinTag":"",
"walletId":"878744",
"userId":"1656177",
"payinStatus":"PENDING",
"paymentMethodId":"25",
"messageToUser":"",
"subtotalItems":"0.00",
"subtotalServices":"0.00",
"subtotalTax":"0.00",
"amount":"12.34",
"currency":"EUR",
"createdDate":"2024-09-09 14:04:32",
"walletEventName":"reset",
"walletAlias":"alias878744",
"userFirstname":"Alex",
"userLastname":"Oak",
"codeStatus":"150117",
"informationStatus":"A capture request has been sent to the financial institution.",
"refundAmount":null,
"DbtrIBAN":null,
"forwardUrl":null,
"paymentAcceptedUrl":null,
"paymentRefusedUrl":null,
"paymentWaitingUrl":null,
"paymentExceptionUrl":null,
"paymentCanceledUrl":null,
"payinDate":"0000-00-00",
"mandateId":"0",
"creditorName":null,
"creditorAddressLine":null,
"creditorCountry":null,
"creditorIban":null,
"creditorBIC":null,
"virtualIbanId":null,
"virtualIbanReference":null,
"additionalData":{
"card":{
"externalProvider":{
"state":"completed",
"mid":"00001341804",
"authorizationCode":"no_code",
"transactionReference":"800320947416",
"dateCreated":"2024-09-09T12:04:24+0000",
"dateUpdated":"2024-09-09T12:04:29+0000",
"status":118,
"message":"Captured",
"authorizedAmount":12.34,
"capturedAmount":12.34,
"refundedAmount":0,
"currency":"EUR",
"ipAddress":"0.0.0.0",
"ipCountry":"",
"cdata1":"212707",
"cdata2":"878744",
"cdata3":"1656177",
"cdata4":"",
"cdata5":"",
"cdata6":"",
"cdata7":"",
"cdata8":"",
"cdata9":"",
"cdata10":"",
"eci":"9",
"paymentProduct":"mastercard",
"paymentMethod":{
"pan":"514414******1246",
"cardHolder":"ALEX OAK",
"token":"d0******78",
"issuer":"TREE BANK, INC.",
"brand":"MASTERCARD",
"country":"US",
"cardExpiryMonth":"12",
"cardExpiryYear":"2025"
},
"fraudScreening":{
"scoring":"0",
"result":"not_launched",
"review":""
}
}
}
},
"totalRows":1
}
]
},
"webhook_created_at":17258834731609,
"webhook_id":"49383fa6-f72e-43de-a288-506dcxxx9ca6",
"object_payload_signature":"IO5v1nKaQorSeqsC4dWS2G3wq32ecLZY5xxxxyYFE9c=",
"auth_key":"true"
}json
{
"webhook":"payin.update",
"object":"payin",
"object_id":"103711",
"object_payload":{
"payins":[
{
"payinId":"103711",
"payinTag":"",
"walletId":"878744",
"userId":"1656177",
"payinStatus":"PENDING",
"paymentMethodId":"25",
"messageToUser":"",
"subtotalItems":"0.00",
"subtotalServices":"0.00",
"subtotalTax":"0.00",
"amount":"12.34",
"currency":"EUR",
"createdDate":"2024-09-09 14:48:10",
"walletEventName":"reset",
"walletAlias":"alias878744",
"userFirstname":"Alex",
"userLastname":"Oak",
"codeStatus":"150116",
"informationStatus":"The financial institution has approved the payment.In the case of a credit card payment, funds are held and deducted from the customer s credit limit (or bank balance, in the case of a debit card), but are not yet transferred to the merchant. In the cas",
"refundAmount":null,
"DbtrIBAN":null,
"forwardUrl":null,
"paymentAcceptedUrl":null,
"paymentRefusedUrl":null,
"paymentWaitingUrl":null,
"paymentExceptionUrl":null,
"paymentCanceledUrl":null,
"payinDate":"0000-00-00",
"mandateId":"0",
"creditorName":null,
"creditorAddressLine":null,
"creditorCountry":null,
"creditorIban":null,
"creditorBIC":null,
"virtualIbanId":null,
"virtualIbanReference":null,
"additionalData":{
"card":{
"externalProvider":{
"transactionReference":"800320947755"
}
}
},
"totalRows":1
}
]
},
"webhook_created_at":17258860905593,
"webhook_id":"13800071-738c-4f08-be82-09f75cf88a67",
"object_payload_signature":"WffEOrVEjcw0W4AKkfUFh19\/ROcqaw9XpGiVrg2\/DuU=",
"auth_key":"true"
}You may also retrieve the payin by using the /v1/payins/{payinId} request.
Webhooks flow
Disputes
When a card Acquisition is disputed by the cardholder, you receive:
- A
card.acquiring.chargeback.createwebhook informing you of the dispute - A
payinrefund.createwebhook sending back the fund or locking the funds on the Wallet for future refund
Legacy emulation
You may emulate a Card Acquisition using the following request. Please note emulated payins can't be refunded.
Parameters
| Attribute | Type | Description |
|---|---|---|
user_id | string | The unique identifier of the user. |
wallet_id | string | The unique identifier of the Wallet to topup. |
amount | float | The amount to credit. |
currency | string | Must be EUR. |
status | integer | Can be the following:
|
transactionReference | integer | Arbitrary reference, generated by HiPay. You need this value to emulate the complete flow composed of multiple requests. |
Request
To emulate a complete flow, you can set a status = 117 followed by a 118 while specifying the same transactionReference for both requests.
bash
- curl -X POST {baseUrl}/simulation/acquiring/payin \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is a {payload} example:
json
{
"status":"117",
"amount":34.56,
"user_id": "{{userId}}",
"wallet_id":"{{walletId}}",
"currency":"EUR",
"payment_product":"mastercard"
}Returns the following:
json
{
"transaction_reference": 1725547253
}