# V1 Flow

Payments received using HiPay's API create Payin objects with a paymentMethodId attribute set to 25 and send payin.create webhooks.

Toolbox icon

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.

Thumbs icon

Best practice – Store Payin Ids as 36-character-long strings

It will make your migration to acquiring v2 simplement, 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 token is then used to make payments.

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 without PCI-DSS (opens new window) certification.

# 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's 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.

Using the following {payload}

Returns the token of the card.

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

  • custom_data is an array used to associate the payment request with the proper Wallet and User
    • custom_data[1] is your client_id
    • custom_data[2] is the recipient's Wallet id
    • custom_data[3] is the recipient's User id
  • cardtoken is the token of the card, as obtained at the previous step
  • accept_url redirection URL in case of authorized payment
  • decline_url redirection URL in case of declined payment
  • pending_url redirection URL in case the payment is left pending
  • exception_url redirection URL in case of fatal error
  • cancel_url redirection URL in case the end user cancels the payment
  • eci
    • 7 for a one-time payment (allowing for 3DS)
    • 9 for a recurring payments (following an eci=7 payment)
  • authentication_indicator
    • 0 Bypasses 3DS
    • 1 3DS will be used if the card allows it
    • 2 Forces the use of 3DS
  • hipayPrivateCredentials is a concatenation of hipay_private_user : hipay_private_password credentials, without spaces and encoded in base64.
red warning icon

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.

Using the following {payload}

books icon

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.

Info icon


  • 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 will receive:

Updated on: 4/5/2024, 6:56:52 AM