HiPay Enterprise – SEPA Credit Transfer (SCT / virtual IBAN) – Centro di supporto 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 client 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 he will make the bank transfer in his 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	2018	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/2018, the expiry date will be set to 29/01/2018, 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 red: 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" => 2018
)
));

// 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":"2018-02-02",
"expiry_date":"2018-04-30",
"external_reference":"my_ID-00019"
}
}

Display informations to the customer

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

- iban
- bic

- external_reference (as the bank label / description)

Payment confirmation by the server notification

Once the customer has made a bank transfer and the funds have reached the virtual IBAN, you then 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>2018-03-21T07:03:14+0000</date_created>
<date_updated>2018-03-21T07:03:14+0000</date_updated>
<date_authorized>2018-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>

<bic_debtor>DxxDEBBXXX</bic_debtor>

<iban_creditor>FR76xxxx7406</iban_creditor>

<bic_creditor>DxxTFRPPXXX</bic_creditor>

<external_reference>5105-5517-1477407288</external_reference>

<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>2018-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>

</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":"2017-03-16", "expiry_date":"2018-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":"2017-03-16", "expiry_date":"2018-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":"2017-03-16", "expiry_date":"2018-12-31", "external_reference":"test-az" }, { "iban":"FR7617xxxxxxxxxxxxxxxxxxx2", "bic":"XXXXXXXXXXXXX", "creation_date":"2017-03-16", "expiry_date":"2018-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." }

Articoli in questa sezione

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

Commenti

Articoli in questa sezione

Articoli correlati