HiPay Enterprise – SEPA Credit Transfer (SCT / virtual IBAN) – Centro de Apoio HiPay

How to generate a virtual IBAN

Please note:

The virtual IBAN is only available on the Production account.
To test, you need to make a bank transfer of at least €1.

Environment	Availability
Stage	No
Production	Yes

Issued to identify and allocate payments from different customers, virtual IBANs look and function exactly like standard IBANs and greatly facilitate automated reconciliation.

1. Requirements

Production service endpoint	https://secure-gateway.hipay-tpp.com/rest/v2/virtual-iban
Method	POST
Authorization	Basic base64(":")
Character encoding	UTF-8
HiPay Enterprise credentials	Private

2. Request parameters

Parameter	Format	Example	Description
external_reference	Regular expression: /^w[w-]{1,254}$/	my_customer_ID-000009	Mandatory ID defined by the merchant (referring to a customer or an order, for instance), notably enabling to look-up valid virtual IBANs linked to this identifier. The customer needs to specify this ID when making the bank transfer in their bank office. Requirements for the regular expression: Must start with an alphanumeric character ([a-zA-Z0-9_]), followed by 1 to 254 alphanumeric characters or hyphens “-”.
expiry_month¹	MM	03	Optional Both expiry_XXXXX arguments must be provided together². Desired expiry month (2-digit value)
expiry_year¹	YYYY	2022	Optional Both expiry_XXXXX arguments must be provided together². Desired expiry year (4-digit value)

¹If both expiry_XXXXX arguments are missing, the expiry date will be set to 28 days after the date of the creation request.

For instance, if a creation request is made on 01/01/2022, the expiry date will be set to 29/01/2022, inclusive.

Then, every time a virtual IBAN is used, its expiry date is extended by a year.

² expiry_XXXXX arguments must be provided together or both missing in the creation request.

An error will be returned if only one is provided.

Example of a PHP request


        // To make an API call
        $ch = curl_init();
        // API call configuration:
        // In bold: Parameters specific to the merchant – therefore to be customized
        // Production environment URL (to be used for production launch):
        curl_setopt( $ch, CURLOPT_URL, 'https://secure-gateway.hipay-tpp.com/rest/v2/virtual-iban' );
        curl_setopt( $ch, CURLOPT_USERPWD , "my_api_login:my_api_password");
        curl_setopt( $ch, CURLOPT_POST, 1);
        curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Accept: application/xml"]);
        curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt( $ch, CURLOPT_POSTFIELDS , http_build_query(
          array(
            "external_reference" => "my_ID-00019",
            "expiry_month" => 02,
            "expiry_year" => 2022
          )
        ));

        // To execute the API call – the returned response is contained in the $response variable.
        $response = curl_exec($ch);

        // To end the API call
        curl_close( $ch );

3. API response

Format

- In XML by default

- Optionally in JSON if the “Accept” HTTPHEADER only contains “application/json”

Field	Description
code	0 for success. 1010201 for a problem with the input data.
message	Explaining the code.
description	if success: “Virtual iban has been successfully created.”
virtual_iban iban bic creation_date expiry_date external_reference	creation_date (YYYY-MM-DD format) expiry_date (YYYY-MM-DD format)

Example of a JSON response

{
  "code":0,
  "message":"success",
  "description":"Virtual iban has been successfully created.",
  "virtual_iban": {
     "iban":"XXXXXXXXXXXXXXXX",
     "bic":"XXXXXXXX",
     "creation_date":"2022-02-02",
     "expiry_date":"2022-04-30",
     "external_reference":"my_ID-00019"
   }
}

Display information to the customer

Once you have received the API response, you will need to display the following information to the customer so that he or she can make the bank transfer:

IBAN
BIC
External_reference (as the bank label / description)

Payment confirmation by server-to-server notifications

Once the customer has made a bank transfer and the funds have reached the virtual IBAN, you will receive three server-to-server notifications at the same time:

116 Authorized
117 Capture Requested
118 Captured

Example of an authorization notification

<?xml version="1.0" encoding="UTF-8"?>
<notification>
    <state>completed</state>
    <reason/>
    <test>false</test>
    <mid>00001230789</mid>
    <attempt_id>1</attempt_id>
    <authorization_code>>no+code</authorization_code
    <transaction_reference>1112223333444555666</transaction_reference>
    <date_created>2022-03-21T07:03:14+0000</date_created>
    <date_updated>2022-03-21T07:03:14+0000</date_updated>
    <date_authorized>2022-03-21T07:03:14+0000</date_authorized
    <status>116</status>
    <message>Authorized</message>
    <authorized_amount>19.65</authorized_amount>
    <captured_amount>0.00</captured_amount>
    <refunded_amount>0.00</refunded_amount>
    <decimals>2</decimals>
    <currency>EUR</currency>
    [...]
    <payment_product>sct</payment_product>
    <payment_method>
        <iban_debtor>DE62xxxx3300</iban_debtor>
                   <!-- From the customer -->
        <bic_debtor>DxxDEBBXXX</bic_debtor>
                   <!-- From the customer -->
        <iban_creditor>FR76xxxx7406</iban_creditor>
                   <!-- Merchant’s virtual IBAN  -->
        <bic_creditor>DxxTFRPPXXX</bic_creditor>
                   <!-- Merchant’s virtual IBAN -->
         <external_reference>5105-5517-1477407288</external_reference>
                    <!-- ID you defined during virtual IBAN generation -->
         <movement_label>SEPA+INHOUSE+TRANS</movement_label>
         <eref>7173255</eref>
         <svwz/>
         <abwe/>
         <issuer_name>Sumup+Payments+Limited</issuer_name>
      </payment_method>
      [...]
      <order>
      <id>12345909545632695</id>
      <date_created>2022-03-21T07:03:14+0000</date_created>
      <attempts>1</attempts>
      <amount>19.65</amount>
      <shipping>0.00</shipping>
      <tax>0.00</tax>
      <decimals>2</decimals>
      <currency>EUR</currency>
      <customer_id/>
      <language>en_US</language>
      <email/>
      </order>
      <payment_reference>FR76xxxx7406</payment_reference>
               <!-- Corresponding to the iban creditor -->
</notification>

Response status codes

Here is a non-exhaustive list of return codes.

ACTION	HTTP CODE	RETURN CODE	MESSAGE
Virtual IBAN creation request	201	0	{ "code":0, "message":"success", "description":"Virtual iban has been successfully created.", "virtual_iban" { "iban":"FR7617xxxxxxxxxxxxxxxxxxxx", "bic":"XXXXXXXXXXXXX", "creation_date":"2021-03-16", "expiry_date":"2022-12-31", "external_reference":"testExpiryDate" } }
Virtual IBAN creation request	201	0	{ "code":0, "message":"success", "description":"No virtual ibans have been found." }
Virtual IBAN look-up request	201	0	{ "code":0, "message":"success", "description":"A virtual iban has been found.", "virtual_ibans":[ { "iban":"FR7617xxxxxxxxxxxxxxxxxxxx", "bic":"XXXXXXXXXXXXX", "creation_date":"2021-03-16", "expiry_date":"2022-12-31", "external_reference":"test-az" } ] }
Virtual IBAN look-up request	201	0	{ "code":0, "message":"success", "description":"Many virtual ibans have been found.", "virtual_ibans":[ { "iban":"FR7617xxxxxxxxxxxxxxxxxxx1", "bic":"XXXXXXXXXXXXX", "creation_date":"2021-03-16", "expiry_date":"2022-12-31", "external_reference":"test-az" }, { "iban":"FR7617xxxxxxxxxxxxxxxxxxx2", "bic":"XXXXXXXXXXXXX", "creation_date":"2021-03-16", "expiry_date":"2022-12-31", "external_reference":"test-az" } ] }
Virtual IBAN creation request with expiry year and without expiry month (or vice versa)	400	1010101	{ "code":1010101, "message":"Required Parameter Missing", "description":"The arguments 'expiry_year' and 'expiry_month' should be provided together." }
Virtual IBAN creation request with blank external reference	400	1010201	{ "code":1010201, "message":"Invalid Parameter", "description":"The argument 'external_reference' should not be blank." }
Virtual IBAN creation request with outdated expiry date	400	1010201	{ "code":1010201, "message":"Invalid Parameter", "description":"The expiry date should not be outdated." }
Virtual IBAN creation request with invalid expiry_month	400	1010201	{ "code":1010201, "message":"Invalid Parameter", "description":"The argument 'expiry_month' should be between 1 and 12." }
Virtual IBAN creation request with invalid expiry_year	400	1010201	{ "code":1010201, "message":"Invalid Parameter", "description":"The argument 'expiry_year' should be a 4-digit value." }
Virtual IBAN creation request with an invalid parameter	400	1010201	{ "code":1010201, "message":"Invalid Parameter", "description":"A parameter is in an invalid format." }
Virtual IBAN creation request with an invalid external reference	400	1010201	{ "code":1010201, "message":"Invalid Parameter", "description":"The argument 'external_reference' should match \/^\\w[\\w-]{0,254}$\/." }
Virtual IBAN creation request with an incorrectly configured account	404	1020003	{ "code":1020003, "message":"Unsupported Payment Product", "description":"The specified payment product is not valid." }
Virtual IBAN creation request when the IBAN is not available	500	4000004	{ "code":4000004, "message":"Technical Problem", "description":"An internal error occurred when making a virtual iban reservation. Please try again or contact HiPay Support services if the problem persists." }