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 Treezor 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.

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 (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.

CURL

# encode your public credentials in base64
hipayPublicCredentials=`echo "mypublicuser:mypublicpassword" | base64 -`
# tokenize the card
curl -X POST {hiPayTokenizationFormBaseUrl}/v1/hpayment \
	--header 'Authorization: Basic {hipayPublicCredentials}' \	# as encoded above
	--header 'Accept: application/json' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

{
    "orderid": "order_{{$timestamp}}",
    "operation":"Authorization",

// custom_data error will result in the funds being debited from external account,
// but not credited on the Treezor Wallet of the real beneficiary of the capture.

    "custom_data" : {
        "1":"{{clientId}}",
        "2":"{{temp_walletId}}",
        "3":"{{temp_userId}}"
        },
    "payment_product_list": "visa, mastercard, cb", 
    "template": "basic-js",
    "merchant_display_name": "Merchant name",
    "display_selector": "1",
    "description": "description",
    "email": "a.oak@example.com",
    "card_holder": "Alex Oak",
    "currency": "EUR",
    "amount": "100.00",
    "ipaddr": "",			// IP of the device from which the capture is made
    "accept_url": "",
    "decline_url": "",
    "pending_url": "",
    "exception_url": "",
    "cancel_url": "",
    "language": "FR_fr",

// Cardholder authentification
    "eci" : "7",                       // single-use mode
    "authentication_indicator": "2",   // forces 3DS

    "device_channel" : "2",
    "multi_use" : 1                   
}

Returns an object containing the forwardUrl you need to provide to your end user.

JSON

  {
    "forwardUrl": "https://stage-secure-gateway.hipay-tpp.com/0000-133-2882/payment/web/pay/50b6814c-27fd-49e2-adea-33bba7150c9c",
    "test": "true",
    "mid": "00001332882",
    "cdata1": "39625",
    "cdata2": "2220766",
    "cdata3": "4064148",
    "cdata4": "",
    "cdata5": "",
    "cdata6": "",
    "cdata7": "",
    "cdata8": "",
    "cdata9": "",
    "cdata10": "",
    "order": {
        "id": "order_1685549327",
        "dateCreated": "2023-05-31T16:08:47+0000",
        "attempts": "0",
        "amount": "100.00",
        "shipping": "0.00",
        "tax": "0.00",
        "decimals": "2",
        "currency": "EUR",
        "customerId": "",
        "language": "FR",
        "email": "aoak@example.com"
    }
}

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 to learn everything there is to know about the parameters.

Reading – Customize your hosted payment form

Refer to the Hosted Payments 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.

CURL

# encode your public credentials in base64
hipayPublicCredentials=`echo "mypublicuser:mypublicpassword" | base64 -`
# tokenize the card
curl -X GET {hiPayTokenizationBaseUrl}/rest/v1/transaction?orderId={orderid} \
	--header 'Authorization: Basic {hipayPublicCredentials}' \	# as encoded above
	--header 'Accept: application/json'

Returns the following:

JSON

{
    "transaction": {
        "state": "completed",
        "reason": "",
        "forwardUrl": "",
        "test": "true",
        "mid": "00001332882",
        "attemptId": "1",
        "authorizationCode": "",
        "transactionReference": "800242932739",
        "dateCreated": "2023-06-30T09:07:41+0000",
        "dateUpdated": "2023-06-30T09:07:52+0000",
        "dateAuthorized": "2023-06-30T09:07:52+0000",
        "status": "116",
        "message": "Authorized",
        "authorizedAmount": "1.00",
        "capturedAmount": "0.00",
        "refundedAmount": "0.00",
        "decimals": "2",
        "currency": "EUR",
        "ipAddress": "212.114.31.26",
        "ipCountry": "FR",
        "deviceId": "",
        "cdata1": "client_id",
        "cdata2": "wallet_id",
        "cdata3": "user_id",
        "cdata4": "",
        "cdata5": "",
        "cdata6": "",
        "cdata7": "",
        "cdata8": "",
        "cdata9": "",
        "cdata10": "",
        "avsResult": "",
        "cvcResult": "",
        "eci": "7",
        "paymentProduct": "visa",
        "paymentMethod": {
            "token": "ba3dd3760142bd6fc715b99429839b06d6de6bd1c6f1eaf36a788668396d011d",
            "cardId": "b1113d3b-5140-4616-abf7-49aeec3f4414",
            "brand": "VISA",
            "pan": "424242******4242",
            "cardHolder": "ALEX OAK",
            "cardExpiryMonth": "05",
            "cardExpiryYear": "2024",
            "issuer": "",
            "country": "GB"
        },
        "threeDSecure": {
            "eci": "5",
            "authenticationStatus": "Y",
            "authenticationMessage": "Authentication Successful",
            "authenticationToken": "",
            "xid": ""
        },
        "fraudScreening": {
            "scoring": "0",
            "result": "ACCEPTED",
            "review": ""
        },
        "order": {
            "id": "order_1688116033",
            "dateCreated": "2023-06-30T09:07:12+0000",
            "gender": "U",
            "firstname": "",
            "lastname": "",
            "streetAddress": "",
            "locality": "",
            "postalCode": "",
            "country": "",
            "attempts": "1",
            "amount": "1.00",
            "shipping": "0.00",
            "tax": "0.00",
            "decimals": "2",
            "currency": "EUR",
            "customerId": "",
            "language": "FR",
            "msisdn": "",
            "phone": "",
            "phoneOperator": "",
            "shippingAddress": {
                "firstname": "",
                "lastname": "",
                "streetAddress": "",
                "locality": "",
                "postalCode": "",
                "country": ""
            },
            "email": "teamimplem@test.com"
        },
        "debitAgreement": {
            "id": "10520843",
            "status": "available"
        }
    }
}

Reading – Full parameters documentation available

Refer to HiPay's Documentation 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 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

CURL

# encode your public credentials in base64
hipayPublicCredentials=`echo "mypublicuser:mypublicpassword" | base64 -`
# tokenize the card
curl -X POST {hiPayTokenizationBaseUrl}/rest/v2/token/create \
	--header 'Authorization: Basic {hipayPublicCredentials}' \	# as encoded above
	--header 'Accept: application/json' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

{
	"card_number":"5300000000000006",
	"card_expiry_month":12,
	"card_expiry_year":2025,
	"card_holder":"Alex Oak",
	"cvc":123,
	"multi_use":1
}

Returns the token of the card.

JSON

{
    "token": "ee9ac2901f4c0d651143664659f206bb6e34ee552ab4e693fa21616b0ef69a57",
    "request_id": "0",
    "card_id": "9fd81707-8f41-4a01-b6ed-279954336ada",
    "multi_use": 1,
    "brand": "VISA",
    "pan": "411111xxxxxx1111",
    "card_holder": "Alex Oak",
    "card_expiry_month": "12",
    "card_expiry_year": "2025",
    "issuer": "JPMORGAN CHASE BANK, N.A.",
    "country": "US",
    "card_type": "CREDIT",
    "forbidden_issuer_country": false
}

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 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 associate the 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

CURL

# encode your private credentials in base64
hipayPrivateCredentials=`echo "myprivateuser:myprivatepassword" | base64 -`
# receive the payment
curl -X POST {hiPayBaseUrl}/rest/v1/order \
	--header 'Authorization: Basic {hipayPrivateCredentials}' \		# as encoded above
	--header 'Accept: application/json' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}.

JSON

{
	"orderid":"Order_1639671746",
	"operation":"Sale",
	"description":"IMP1639671746",
	"currency":"EUR",
	"amount":"100",
	"ipaddr":"192.154.28.65",	
	"custom_data":{
		"1":"123456", 				// your client_id
		"2":"234567", 				// the walletId to credit
		"3":"345678"				// the userId to credit
	},
	"eci": "7",						// list above
	"authentication_indicator":"2",	// see list above
	"email":"teamimplem@test.com",	// the cardholders email
	"card_holder":"Tom Pes",		// the cardholders name as embossed or etched on the card
	"cardtoken":"{{temp_HiPayToken}}",
	"payment_product":"visa",
	"accept_url":"https://dictionary.cambridge.org/fr/dictionnaire/anglais/accept",			// redirection URL in case of authorized payment
	"decline_url":"https://dictionary.cambridge.org/fr/dictionnaire/anglais/decline",		// redirection URL in case of declined payment
	"pending_url":"https://dictionary.cambridge.org/fr/dictionnaire/anglais/pending",		// redirection URL in case the payment is left pending
	"exception_url":"https://dictionary.cambridge.org/fr/dictionnaire/anglais/exception",	// redirection URL in case of fatal error
	"cancel_url":"https://dictionary.cambridge.org/fr/dictionnaire/anglais/cancel",			// redirection URL in case the end user cancels the payment
	"device_channel":"1"
}

Reading – Full parameters documentation available

Refer to HiPay's Documentation to learn everything there is to know about the parameters.

Returns the details regarding the capture.

JSON

{
    "state": "completed",
    "reason": "",
    "forwardUrl": "",
    "test": "true",
    "mid": "00001332882",
    "attemptId": "1",
    "authorizationCode": "test123",
    "transactionReference": "800143609738",
    "referenceToPay": "",
    "dateCreated": "2021-12-21T13:42:15+0000",
    "dateUpdated": "2021-12-21T13:42:20+0000",
    "dateAuthorized": "2021-12-21T13:42:19+0000",
    "status": "118",
    "message": "Captured",
    "authorizedAmount": "100.00",
    "capturedAmount": "100.00",
    "refundedAmount": "0.00",
    "creditedAmount": "0.00",
    "decimals": "2",
    "currency": "EUR",
    "ipAddress": "192.154.28.65",
    "ipCountry": "CA",
    "deviceId": "",
    "cdata1": "212707",		// is your client_id as provided previously
    "cdata2": "1174278",	// is the recipients walletId as provided previously
    "cdata3": "2189821",	// is the recipients userId as provided previously
    "cdata4": "",
    "cdata5": "",
    "cdata6": "",
    "cdata7": "",
    "cdata8": "",
    "cdata9": "",
    "cdata10": "",
    "avsResult": "",
    "eci": "9",
    "paymentProduct": "visa",
    "paymentMethod": {
        "token": "3b1a89dfd033307f7a9fbf8757025f2226766e125b84e1cd616de9d7b7e4ebe4",
        "cardId": "9fd81707-8f41-4a01-b6ed-279954336ada",
        "brand": "VISA",
        "pan": "411111******1111",
        "cardHolder": "TOM PES",
        "cardExpiryMonth": "12",
        "cardExpiryYear": "2025",
        "issuer": "JPMORGAN CHASE BANK, N.A.",
        "country": "US"
    },
    "threeDSecure": "",
    "fraudScreening": {
        "scoring": "0",
        "result": "ACCEPTED",
        "review": ""
    },
    "order": {
        "id": "Order_1639671746",
        "dateCreated": "2021-12-21T13:42:15+0000",
        "attempts": "1",
        "amount": "100.00",
        "shipping": "0.00",
        "tax": "0.00",
        "decimals": "2",
        "currency": "EUR",
        "customerId": "",
        "language": "en_US",
        "email": "teamimplem@test.com"
    },
    "debitAgreement": {
        "id": "10337627",
        "status": "available"
    }
}

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

Legacy payin.update event

JSON (new)

{
    "webhook":"payin.update",
    "object":"payin",
    "object_id":"103700",
    "object_payload":{
        "payins":[
            {
                "payinId":"103700",
                "payinTag":"",
                "walletId":"878744",
                "userId":"1656177",
                "payinStatus":"PENDING",
                "paymentMethodId":"25",
                "messageToUser":"",
                "subtotalItems":"0.00",
                "subtotalServices":"0.00",
                "subtotalTax":"0.00",
                "amount":"12.34",
                "currency":"EUR",
                "createdDate":"2024-09-09 14:04:32",
                "walletEventName":"reset",
                "walletAlias":"alias878744",
                "userFirstname":"Alex",
                "userLastname":"Oak",
                "codeStatus":"150117",
                "informationStatus":"A capture request has been sent to the financial institution.",
                "refundAmount":null,
                "DbtrIBAN":null,
                "forwardUrl":null,
                "paymentAcceptedUrl":null,
                "paymentRefusedUrl":null,
                "paymentWaitingUrl":null,
                "paymentExceptionUrl":null,
                "paymentCanceledUrl":null,
                "payinDate":"0000-00-00",
                "mandateId":"0",
                "creditorName":null,
                "creditorAddressLine":null,
                "creditorCountry":null,
                "creditorIban":null,
                "creditorBIC":null,
                "virtualIbanId":null,
                "virtualIbanReference":null,
                "additionalData":{
                    "card":{
                        "externalProvider":{
                            "state":"completed",
                            "mid":"00001341804",
                            "authorizationCode":"no_code",
                            "transactionReference":"800320947416",
                            "dateCreated":"2024-09-09T12:04:24+0000",
                            "dateUpdated":"2024-09-09T12:04:29+0000",
                            "status":118,
                            "message":"Captured",
                            "authorizedAmount":12.34,
                            "capturedAmount":12.34,
                            "refundedAmount":0,
                            "currency":"EUR",
                            "ipAddress":"0.0.0.0",
                            "ipCountry":"",
                            "cdata1":"212707",
                            "cdata2":"878744",
                            "cdata3":"1656177",
                            "cdata4":"",
                            "cdata5":"",
                            "cdata6":"",
                            "cdata7":"",
                            "cdata8":"",
                            "cdata9":"",
                            "cdata10":"",
                            "eci":"9",
                            "paymentProduct":"mastercard",
                            "paymentMethod":{
                                "pan":"514414******1246",
                                "cardHolder":"ALEX OAK",
                                "token":"d0******78",
                                "issuer":"TREE BANK, INC.",
                                "brand":"MASTERCARD",
                                "country":"US",
                                "cardExpiryMonth":"12",
                                "cardExpiryYear":"2025"
                            },
                            "fraudScreening":{
                                "scoring":"0",
                                "result":"not_launched",
                                "review":""
                            }
                        }
                    }
                },
                "totalRows":1
            }
        ]
    },
    "webhook_created_at":17258834731609,
    "webhook_id":"49383fa6-f72e-43de-a288-506dcxxx9ca6",
    "object_payload_signature":"IO5v1nKaQorSeqsC4dWS2G3wq32ecLZY5xxxxyYFE9c=",
    "auth_key":"true"
}

JSON (before)

{
    "webhook":"payin.update",
    "object":"payin",
    "object_id":"103711",
    "object_payload":{
        "payins":[
            {
                "payinId":"103711",
                "payinTag":"",
                "walletId":"878744",
                "userId":"1656177",
                "payinStatus":"PENDING",
                "paymentMethodId":"25",
                "messageToUser":"",
                "subtotalItems":"0.00",
                "subtotalServices":"0.00",
                "subtotalTax":"0.00",
                "amount":"12.34",
                "currency":"EUR",
                "createdDate":"2024-09-09 14:48:10",
                "walletEventName":"reset",
                "walletAlias":"alias878744",
                "userFirstname":"Alex",
                "userLastname":"Oak",
                "codeStatus":"150116",
                "informationStatus":"The financial institution has approved the payment.In the case of a credit card payment, funds are  held  and deducted from the customer s credit limit (or bank balance, in the case of a debit card), but are not yet transferred to the merchant. In the cas",
                "refundAmount":null,
                "DbtrIBAN":null,
                "forwardUrl":null,
                "paymentAcceptedUrl":null,
                "paymentRefusedUrl":null,
                "paymentWaitingUrl":null,
                "paymentExceptionUrl":null,
                "paymentCanceledUrl":null,
                "payinDate":"0000-00-00",
                "mandateId":"0",
                "creditorName":null,
                "creditorAddressLine":null,
                "creditorCountry":null,
                "creditorIban":null,
                "creditorBIC":null,
                "virtualIbanId":null,
                "virtualIbanReference":null,
                "additionalData":{
                    "card":{
                        "externalProvider":{
                            "transactionReference":"800320947755"
                        }
                    }
                },
                "totalRows":1
            }
        ]
    },
    "webhook_created_at":17258860905593,
    "webhook_id":"13800071-738c-4f08-be82-09f75cf88a67",
    "object_payload_signature":"WffEOrVEjcw0W4AKkfUFh19\/ROcqaw9XpGiVrg2\/DuU=",
    "auth_key":"true"
}

You may also retrieve the payin by using the /v1/payins/{payinId} request.

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

Legacy emulation

You may emulate a Card Acquisition using the following request. Please note emulated payins can't be refunded.

Parameters

Attribute	Type	Description
user_id	string	The unique identifier of the user.
wallet_id	string	The unique identifier of the Wallet to topup.
amount	number	The amount to credit.
currency	string	Must be EUR.
status	integer	Can be the following: 109 for an authentication failure 110 for a rejection due to fraud suspicion 113 for a refusal by the payment institution 115 for a payment timeout 116 for an authorization request 117 for a capture request 118 for a successful Card Acquisition 129 for a chargeback 173 for a refused capture
transactionReference	integer	Arbitrary reference, generated by HiPay. You need this value to emulate the complete flow composed of multiple requests.

Request

To emulate a complete flow, you can set a status = 117 followed by a 118 while specifying the same transactionReference for both requests.

CURL

- curl -X POST {baseUrl}/simulation/acquiring/payin \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is a {payload} example:

JSON

{
    "status":"117",
    "amount":34.56,
    "user_id": "{{userId}}",
    "wallet_id":"{{walletId}}",
    "currency":"EUR",
    "payment_product":"mastercard"
}

Returns the following:

JSON

{
    "transaction_reference": 1725547253
}