This payment mean can be used with the HiPay Enterprise Gateway API.
Recurring payment
Request
To initiate a new SEPA mandate that will be used for future recurring payments you must add the following parameters to a basic payment request:
The bank account owner must be present to complete the SEPA registration.
Specific required fields if your are using “order” API : (bank info fields in your page)
Parameter name | Value |
payment_product | sdd |
eci | 7 (e-commerce) |
recurring_payment | 1 |
iban | Iban |
firstname | First name |
lastname | Last name |
Specific required fields if your are using “hpayment” API : (bank info fields in HiPay hosted page)
Parameter name | Value |
payment_product | sdd |
eci | 7 (e-commerce) |
recurring_payment | 1 |
Response
See below the received response. Please pay attention to the field debit_agreement_id, which is the most important here. Merchants must save its value to make new recurring transactions on the same mandate. In case of Hpayment (HiPay hosted page), this value is sent in the “Authorization requested” notification and not in the API response.
Response in XML format using “order” API
<?xml version="1.0" encoding="UTF-8"?>
<response>
<state>completed</state>
<forward_url/>
<test>false</test>
<mid>00001328877</mid>
<attempt_id>1</attempt_id>
<authorization_code/>
<transaction_reference>132256656670</transaction_reference>
<status>142</status>
<message>Authorization Requested</message>
. . .
<debit_agreement>
<id>18505</id>
<status>available</status>
</debit_agreement>
</response>Response in XML format using “hpayment” API
<?xml version="1.0" encoding="UTF-8"?>
<response>
<forward_url>https://stage-secure-gateway.hipay-tpp.com/payment/web/pay/12...55</forward_url>
<test>true</test>
<mid>00001328877</mid>
. . .
<order>
<id>5630ccbe32951</id>
<date_created>2016-10-28T13:30:47+0000</date_created>
<attempts>0</attempts>
<amount>113.25</amount>
<shipping>4.50</shipping>
<tax>0.50</tax>
<decimals>2</decimals>
<currency>EUR</currency>
<customer_id>test</customer_id>
<language>fr_FR</language>
<email>[email protected]</email>
</order>
</response>
The merchant will redirect the customer to the HiPay payment page to complete the registration, as shown here.
After completing the registration, the customer is redirected to the success page specified by the merchant in the initial payment request (or to the error page in case of failure).
The transaction status will change to Authenticated, then to Authorization requested. A few days later (approximately 10 bank working days for a first transaction and 5 bank working days for a recurring transaction), the transaction status will change from Authorization requested to Captured directly (due to the lack of information about the status change between the transmission and the receipt of the payment).
Notification response in XML format
<?xml version="1.0" encoding="UTF-8"?>
<notification>
<state>completed</state>
<reason/>
<test>true</test>
<mid>00001328877</mid>
<attempt_id>1</attempt_id>
<authorization_code/>
<transaction_reference>730844386388</transaction_reference>
. . .
<debit_agreement>
<id>599</id>
<status>available</status>
</debit_agreement>
</notification>Existing mandate
Initiating a transaction on an existing mandate
When a merchant wants to make a payment on an existing mandate, the bank account owner doesn’t need to be present.
To proceed, the merchant has to send the value of the aforementioned field debit_agreement_id to HiPay.
Specific required fields
Parameter name | Value |
payment_product | sdd |
eci | 9 (recurring e-commerce) |
debit_agreement_id | 574 (example) |
recurring_payment | 1 |
Response
See below the received response. This time, the transaction status is set to Authorization requested directly, as a confirmation is not required to make another payment on an existing mandate.
<?xml version="1.0" encoding="UTF-8"?>
<response>
<state>pending</state>
<reason/>
<forward_url/>
<test>false</test>
<mid>00035167042</mid>
<attempt_id>1</attempt_id>
<authorization_code/>
<transaction_reference>937783482019</transaction_reference>
<reference_to_pay/>
<date_created>2016-10-05T16:40:21+0000</date_created>
<date_updated>2016-10-05T16:40:29+0000</date_updated>
<date_authorized/>
<status>142</status>
<message>Authorization Requested</message>
. . .
<debit_agreement>
<id>574</id>
<status>available</status>
</debit_agreement>
</response>Debit agreement statuses
Status | Description |
pending | Created but not yet confirmed |
available | Agreement correctly created |
terminated | The agreement is no longer available |
suspended | The agreement was suspended by the customer |
error | An error occurred on agreement creation |
Mandate without transaction
This is intended for merchants who want to create a debit agreement without any first payment for further recurring payments.
Endpoint
Production: https://secure-gateway.hipay-tpp.com/rest/v2/debit-agreement
Specific required fields
Parameter name | Value/Example value/info |
payment_product | sdd |
currency | EUR |
iban | DE23100000001234567890 (this is an example) |
issuer_bank_id | MARKDEF1100 (this is an example) |
bank_name | World bank (this is an example) |
gender | F / M |
firstname | First name |
lastname | Last name |
authentication_indicator | 0 |
agreement_reference | 4465545 (this field is not mandatory; it is used to import an old mandate reference) |
At this point, the merchant can initiate an SDD transaction with the given debit agreement.
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>0</code>
<message><![CDATA[success]]></message>
<description><![CDATA[Debit agreement has been successfully created.]]></description>
<debit_agreement>
<id>992</id>
<provider_reference><![CDATA[xbclql8lff2c81raderivxnqjwwhizrcbu4regh6]]></provider_reference>
<status><![CDATA[available]]></status>
<creation_date><![CDATA[2016-02-19T10:19:19+0100]]></creation_date>
<properties>
<iban><![CDATA[DE23100000001234567890]]></iban>
<issuer_bank_id><![CDATA[MARKDEF1100]]></issuer_bank_id>
<bank_name><![CDATA[World bank]]></bank_name>
<gender><![CDATA[F]]></gender>
<firstname><![CDATA[firstname]]></firstname>
<lastname><![CDATA[lastname]]></lastname>
<authentication_indicator><![CDATA[0]]></authentication_indicator>
<unique_id><![CDATA[000164937158989160]]></unique_id>
<agreement_reference><![CDATA[4465545]]></agreement_reference>
</properties>
</debit_agreement>
</response>