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:

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.

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

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. custom_data[1] – Your client_id custom_data[2] – The recipient's Wallet id custom_data[3] – The recipient's User id
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	7 – One-time payment (allowing for 3DS) 9 – Recurring payments (following an eci=7 payment)
authentication_indicator	string	Indicates how to handle 3DS. Can be: 0 – Bypasses 3DS 1 – 3DS will be used if the card allows it 2 – Forces the use of 3DS
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 to VALIDATED
• Refused or impossible – With a payinStatus attribute set to CANCELED

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