Treezor Doc

# V2 Flow

red warning icon

Warning – Feature is not available yet

The documentation has been updated to help you anticipate the new acquiring feature.

If you are interested in this feature, please contact your Treezor Account Manager.

Compared to the V1, the V2 flow allows for simpler payments or top-ups (referred to as Payin in this article).

Acquiring funds by card follows these steps:

Info icon

Information – Supported cards

This feature supports the following cards: CB, Visa, Mastercard, Maestro, Bancontact.

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

Info icon

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.

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.

books icon

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:

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.

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

# Request example

Here is an example of {payload}:

Returns the token of the card.

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.

If you're encountering an error, please check out the HiPay's error codes (opens new window) documentation.

# Associate a card to a User

To acquire funds from a card, you need a Topup Card in the Treezor API.

To create said Topup Card and associate it to a User, use the following request with the token provided by HiPay during the tokenization step

Outputs a topupCards object, and sends a topupCard.validate webhook

💡 To prevent abuse and misuse, there is a maximum of 10 (ten) active cards associated to a single User at any given time. You may revoke Topup Cards if necessary.

# Request the funds capture

This step actually requests a capture of funds using either the Topup Card or an alternate mean of payment (specified in the paymentProduct parameter).

# Parameters

  • Treezor-related
    • walletId is the Wallet's id
    • userId is the User's id
    • topupCardId is the Topup Card id (optional)
    • profile is your Merchant ID (mandatory if you have multiple MIDs)
  • HiPay-related (most of HiPay's parameters (opens new window) can be used)
    • orderId
    • amount
    • currency
    • messageToUser
    • acceptUrl
    • declineUrl
    • pendingUrl
    • exceptionUrl
    • cancelUrl
    • notifyUrl
    • eci can be either 7 or 9
    • authenticationIndicator:2
    • description
    • paymentProduct
      • cb CB
      • visa Visa
      • mastercard Mastercard
      • ideal iDEAL
      • sofort-uberweisung Sofort Uberweisung
      • bcmc Bancontact
    • issuerBankId Bank Identifier Code of the end-user issuer bank, only used with iDEAL payment product
    • ipaddr the End User's device IP address

❗️ Please refer to the Swagger, for an exhaustive list of mandatory parameters depending on the paymentProduct.

Outputs the following object and sends an authorization.create, payin.create and payin.udpate webhooks

💡 To determine the actual payment status, you must rely on the Payin's status attribute received in authorization.create, payin.create and payin.update webhooks. The response to the request itself doesn't provide a reliable payment status and doesn't contain the Payin's id.

If the response has the forwardUrl attribute populated, the End User should be redirected to this URL to complete the funds capture process. You can refer to the paymentProduct table, to know when a forwardUrl is provided and when you must forward the End User to it.

💡 Note that payment products requiring forwarding the End User will not send any webhook until the End User has completed the steps available at the forwardUrl.

# Retrieve all Topup Cards

The following request retrieves all Topup Cards, allowing you to display them to the User if desired.

Outputs a list of topupCards objects

# Retrieve a Topup Card

The following request retrieves a single Topup Card.

Outputs a list of topupCards objects

# Revoke a Topup card

The following request permanently revokes a Topup Card. Although you can still tokenize it again if necessary.

Outputs the disabled Tokenized Card and sends a topupCard.cancel webhook

# Advanced funds Capture

💡 This feature is only available with some paymentProducts

Instead of capturing the funds in a single operation which abstracts the authorization step, you may first authorize and then capture funds in distinct operations.

This is often useful when the amount to capture is not accurately known at the time the authorization is issued.

In such situations,

  • you proceed to authorize an amount that could be captured later in one or multiple payins
  • you create one or many payins associated to that authorization without exceeding the total authorized amount
  • any excessively authorized amount is freed up automatically one week after the authorization

# Authorize an amount

To authorize an amount, you can use the following endpoint which accepts the same payload as the simplified capture

Here is a {payload} example:

Outputs the authorization and sends an authorization.create webhook which contains the authorization UUID that will be used to create payin(s) at the next step.

# Capture the funds

To capture funds following an authorization, you can use the following request.

Outputs the following object and sends payin.create and payin.update webhooks.

💡 Note that you can create as many captures as needed for an authorization, as long as the following conditions are both met

  • the total amount doesn't exceed the initial authorization amount
  • the capture happens within 7 days of the authorization.

# Refunds

Refunds are only available for some paymentProducts. They are always associated to Payins, you may create multiple Refunds for a single Payin (just like there can be multiples Payins for a single Authorization).

# Optional parameters

Attribute Type Description
currency string The currency of the refund, in ISO-4217 format.
amount float The amount of the refund. Can be specified to partially refund a payin. If omitted, the payin is entirely refunded.
profile string The MID. Required if you have have multiple MIDs.

Here is an example of {payload}:

Returns the Payin Refund object and sends payinrefund.create and payinrefund.update webhooks.

# Chargebacks

When a Chargeback is received, a chargeback.create webhook is sent. The chargeback is automatically accepted and the Wallet debited (even if insufficiently provisionned). You do not have the ability to refuse it.

# Payment products specificities

Payment product name paymentProduct Additional mandatory Authorization/Payin attributes Requires End User forwarding Advanced funds capture Refund feature
Mastercard mastercard topupCardId ❌ ✅ Available ✅ Available
Visa visa topupCardId ❌ ✅ Available ✅ Available
CB cb topupCardId ❌ ✅ Available ✅ Available
Maestro maestro topupCardId ❌ ✅ Available ✅ Available
Bancontact bcmc topupCardId ❌ ❌ ❌
Sofort sofort-uberweisung ∅ ✅ to forwardUrl ❌ ✅ Available
iDeal ideal issuerBankId ✅ to forwardUrl ❌ ✅ Available

# Webhooks

❗️ If you are migrating from acquiring V1, previously the reception of any payin webhook meant that a payment had been accepted. You must not rely on this anymore as Treezor also sends payin.cancel webhook.

Instead, you must consider the payinStatus attribute of the payin. The payment is accepted when valued to VALIDATED.

# Multi-MID

You may have multiple Merchant IDs registered with HiPay to suit your different acquiring needs.

If you have multiple MIDs, you must specify the MID to be used either:

If you have a single MID, you never have to populate the profile attribute.

Updated on: 7/10/2024, 3:50:22 PM