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