# 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 your Treezor Implementation Manager 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 (opens new window).
# 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 (opens new window) (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.
Here is an example of {payload}
:
Returns an object containing the forwardUrl
you need to provide to your end user.
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 (opens new window) to learn everything there is to know about the parameters.
Reading – Customize your hosted payment form
Refer to the Hosted Payments (opens new window) 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.
Returns the following:
Reading – Full parameters documentation available
Refer to HiPay's Documentation (opens new window) 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 or not 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
Here is an example of {payload}
:
Returns the token
of the card.
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 (opens new window) 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 associat ethe 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
Here is an example of {payload}
.
Reading – Full parameters documentation available
Refer to HiPay's Documentation (opens new window) to learn everything there is to know about the parameters.
Returns the details regarding the capture.
Information
- The
custom_data
attribute 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
payinStatus
attribute set toVALIDATED
- Refused or impossible – With a
payinStatus
attribute set toCANCELED
# Webhooks flow
# Disputes
When a card Acquisition is disputed by the cardholder, you receive:
- A
card.acquiring.chargeback.create
webhook informing you of the dispute - A
payinrefund.create
webhook sending back the fund or locking the funds on the Wallet for future refund