Introduction

Card Acquiring involves capturing funds from a third-party card to credit a Treezor Wallet.

Treezor relies on HiPay as a payment service provider (PSP) for card acquiring. It is compatible with various payment products such as CB, Visa, and Mastercard.

Feature activation – Acquiring is not enabled by default

Please contact Treezor to obtain your HiPay credentials and to activate your payment products.

Treezor supports 2 versions of Acquiring. While this documentation mainly focuses on the newest version, you may find information specific to the Legacy in the corresponding Legacy flow article.

Use cases

The Card Acquiring feature can be used in the following use cases.

Use case	Description
Top-up	The end user credits their Treezor Wallet by using their external account payment card. In such cases, the end user can credit their wallet either: Occasionally – Single payment made to credit the Treezor Wallet. Periodically – Recurring payments to credit the Wallet at regular intervals.
Complement	When the end user doesn't have enough funds on their Treezor Wallet to make the payment, they may complement the payment with funds captured on their external account payment card. This use case requires the "recurring" mode.

HiPay environments & credentials

HiPay provides 2 environments: Staging (sandbox) and Production.

Each environment has its own set of credentials (public and private) that Treezor provides to you. Your public credentials are to be base64-encoded before being used in the Authorization header of your requests (basic access authentication).

You may replace the values in the code snippets of this documentation as follows:

Value	URLs
{hiPayBaseUrl}	Staging: https://stage-secure-gateway.hipay-tpp.com/ Production: https://secure-gateway.hipay-tpp.com/
{hiPayTokenizationFormBaseUrl}	Staging: https://stage-api.hipay.com/ Production: https://api.hipay.com/
{hiPayTokenizationBaseUrl}	Staging: https://stage-secure2-vault.hipay-tpp.com/ Production: https://secure2-vault.hipay-tpp.com/

HiPay also provides 2 dashboards:

• Staging: https://stage-console.hipay.com
• Production: https://console.hipay.com

Tip – Test cards available

Because HiPay's staging environment and Treezor's sandbox are linked, you can use HiPay's test cards in Sandbox.

Payment products specificities

Below are the specific details for each payment product.

paymentProduct	Mandatory attributes	End user forwarding	Advanced capture	Refunds
mastercard	topupCardId
visa	topupCardId
cb	topupCardId
maestro	topupCardId
bcmc	topupCardId
sofort-uberweisung	∅	To forwardUrl
ideal	issuerBankId	To forwardUrl

Note – Card products and 3DS redirection

For card products, when 3DS authentication is triggered, the forwardUrl is returned in the additionalData of the response and the end user must be redirected. In this case, the payinId returned in the API response may differ from the one in the corresponding webhooks.

HiPay response data

For Card Acquiring payins and authorizations, the additionalData attribute contains transaction information returned by HiPay. This attribute is a JSON-encoded string present in both API responses and webhook payloads.

When populated, additionalData contains a card.externalProvider object with the following structure.

External provider object

Attribute	Type	Description
state	string	The state of the transaction.
mid	string	The Merchant Identifier (MID) used for the transaction.
authorizationCode	string	The authorization code returned by the card network. May be no_code for certain transactions.
transactionReference	string	The unique reference of the transaction on HiPay's side.
dateCreated	string	The date and time at which the transaction was created.
dateUpdated	string	The date and time at which the transaction was last updated.
status	integer	The HiPay transaction status code. See HiPay Transaction Status for the full list.
message	string	A human-readable message describing the transaction status (e.g., Authorized, Captured).
authorizedAmount	number	The amount authorized on the card.
capturedAmount	number	The amount captured on the card.
refundedAmount	number	The amount refunded to the card.
currency	string	The currency of the transaction (ISO 4217 format).
ipAddress	string	The IP address of the end user who initiated the transaction.
ipCountry	string	The country associated with the IP address (ISO 3166-1 alpha-2 format).
cdata1	string	Custom data field containing the clientId.
cdata2	string	Custom data field containing the walletId.
cdata3	string	Custom data field containing the userId.
cdata4 to cdata10	string	Custom data fields reserved for future use.
eci	string	The Electronic Commerce Indicator, indicating the level of authentication.
paymentProduct	string	The payment product used (e.g., visa, mastercard).
paymentMethod	object	Information about the payment method used. See Payment method object.
fraudScreening	object	Fraud screening results. See Fraud screening object.
order	object	Order information (when available).
forwardUrl	string	The URL to redirect the end user for authentication (when applicable).

Payment method object

Attribute	Type	Description
pan	string	The masked Primary Account Number (PAN) of the card (e.g., 545454******5454).
cardHolder	string	The name of the cardholder.
token	string	The HiPay token representing the card. Partially masked for security.
issuer	string	The name of the card issuer.
brand	string	The card brand (e.g., VISA, MASTERCARD).
country	string	The country of issuance (ISO 3166-1 alpha-2 format).
cardExpiryMonth	string	The expiry month of the card.
cardExpiryYear	string	The expiry year of the card.

Fraud screening object

Attribute	Type	Description
scoring	string	The fraud score assigned to the transaction.
result	string	The result of the fraud screening (e.g., not_launched, ACCEPTED).
review	string	The review status, if any.

Reading – Full parameters documentation

Refer to HiPay's Transaction API for the complete list of parameters and their possible values.

Apple Pay payments compatibility

You can capture funds from a card digitized on an Apple Pay wallet. Doing so doesn't fundamentally change your acquiring flow; this is an authentication step that occurs before the tokenization.

To set up card acquiring via Apple Pay, you must follow HiPay's documentation and send your certificate to your Treezor Implementation Manager to configure your environment. Please note that Treezor only supports integration with your own certificate.

Reading – Integration guide

See HiPay's Apple Pay web integration guide for more information.

Once the authentication step is done, you can use the Apple Pay token instead of the card detailed information when tokenizing the card.

Endpoints

Endpoint	Scope
/v1/topups/cards/users/{userId}/topupCards Associate a tokenized topup card to a user	read_write
/v1/topups/cards/users/{userId}/topupCards Search topup cards for a given user	read_only
/v1/topups/cards/users/{userId}/topupCards/{topupCardId} Retrieve information about a topup card	read_only
/v1/topups/cards/users/{userId}/topupCards/{topupCardId} Cancel a topup card	read_write
/v1/topups/cards/authorizations Create a card topup authorization	read_write
/v1/topups/cards/authorizations/{authorizationId} Retrieve a card topup authorization	read_only
/v1/topups/cards/authorizations/{authorizationId} Delete a card topup authorization	read_write
/v1/topups/cards/authorizations/{authorizationId}/payins Create payin from an authorization	read_write
/v1/topups/cards/authorizations/{authorizationId}/payins List all payins from an authorization	read_only
/v1/topups/cards/refunds/{refundId} Retrieve a card topup payin refund	read_only
/v1/topups/cards/refunds Create a card topup payin refund	read_write
/v1/topups/cards/chargebacks/{chargebackId} Retrieve a card topup payin chargeback	read_only

Reading – Learn more about Acquiring

• HiPay official API
• HiPay best practices
• Recurring Payins
• Sentinel profile
• 3DS Strong authentication