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_month1 |
MM |
03 |
Optional Both expiry_XXXXX arguments must be provided together². Desired expiry month (2-digit value) |
expiry_year1 |
YYYY |
2022 |
Optional Both expiry_XXXXX arguments must be provided together². Desired expiry year (4-digit value) |
1 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
|
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
|
|
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 |
{ |
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." } |
Commenti
0 commenti
Questo articolo è chiuso ai commenti.