Integrate our products into your software. Let's make payment happen together!
Look at all the possibilitiesThe boarding API is based on common HTTP API implementations:
GET
& POST
for request. Other verbs don’t apply for now.The API reference can be found here.
As a referral you’ll access the VPOS as a remote service without interaction of the customer. The access is restricted and requires you to authenticate.
We provide you with an API key. See Referral Reference for more info.
Authentication is performed using Basic Authentication which requires you to send an
Authorization
header for each request. The format of the value of the header is defined as username:password
.
The username
is the value of the API key and the password remains empty.
An example: r_referralkey:
Note: The header string must be Base64 encoded.
An API key may have an expiration date associated with it.
If this is the case, it will be indicated by an X-ApiKey-Expiration-Timestamp
HTTP header in each response.
Once the expiration date has passed, the key will no longer be valid.
When a key is generated, you can choose the referral reference of the key. The referral reference defines the context in which boarding requests will be processed.
An example referral reference would be: boarding_group_x
.
In case of an error we respond with a corresponding HTTP status code. The body of the response will be a JSON error object.
Code | Message | Description |
---|---|---|
400 | Bad Request | Invalid input in the request |
401 | Unauthorized | Invalid API key (typo, expired) |
404 | Not Found | Invalid URL |
500 | Internal Server Error | Unexpected error |
504 | Gateway Timeout | Processing the request took too long |
All resources will return a JSON object in case of an error.
Name | Description |
---|---|
type | Possible values: input_error , process_error , `unexpected_error |
message | A generic message. Contains helpful information regarding the cause of the error. This message should not be parsed. In case of input_error this field holds the validation message for the field mentioned in field |
field | In case of type input_error the field that caused an error. Otherwise not present. If multiple field validations failed, field contains the first one. |
fields | In case of type input_error an array of all failed field validations. For each field the error message is shown. See example below. |
reference | A reference that you can provide to the helpdesk for investigation of the failing request |
Example Input error
{
"type": "input_error",
"message": "An input parameter is incorrect",
"reference": "718ee617",
"field": "name"
}
Example of multiple input errors
{
"type": "input_error",
"message": "An amount is required",
"reference": "718ee617",
"field": "amount",
"fields": [
{
"field": "amount",
"message": "An amount is required"
},
{
"field": "method",
"message": "A supported method is required"
},
{
"field": "method",
"message": "may not be null"
},
{
"field": "currency",
"message": "A ISO 4217 currency code is required"
}
]
}
There are several protocols for which the PSP is collecting. This means that the funds from the customer are transferred
to the account of the PSP. The PSP will then make a transfer to the correct merchant when the funds arrive on this
account.
This payout will only happen when the payout
flag on the merchant or methods is enabled.
At this moment the collecting protocols are:
Method | Brand | Acquirer |
---|---|---|
card |
bcmc |
Bancontact |
card |
maestro , visa , mastercard |
Payvision |
card |
maestro , visa , mastercard |
Valitor |
alipay |
||
banktransfer |
||
giropay |
||
ideal |
||
klarna |
||
payconiq |
||
sofort |
||
gift |
||
applepay |
maestro , visa , mastercard , bcmc |
ValitorPay |
googlepay |
visa , mastercard |
ValitorPay |
A payment method/brand combination that supports collecting, can sometimes also be offered to the customer as
non-collecting (a.k.a Switching). This means that the PSP expects the funds to be transferred directly between acquirer
and customer. This also means that the PSP will not check a refund balance. This information is also passed to the
billing component so the invoicing can be done correctly.
Collecting or switching be indicated by the field collecting
.
The only payment methods that support both collecting and switching are:
Method | Brand | Acquirer(s) |
---|---|---|
payconiq |
||
card |
maestro , visa , mastercard |
Payvision, Valitor |
Funds for collecting protocols are transferred to the merchant’s bank account by the PSP. A merchant can also indicate that the collected payment amount should be split up and transferred to other merchants. This can be achieved by sending payout instructions in the payment request, where each payout instruction points to a specific merchant. The merchant that sends the payment requests is also called the super merchant. The merchants that receive funds are called sub merchants. Sub and super merchants need to be linked to each other using their referral references and an additional parameter called ’external reference’. This external reference can than be used in the payout instructions of the payment request to identify the sub merchant. If the super merchant also wants payouts to himself, he also needs to be linked to himself and have an external reference to be used in the payout instruction.
Please note that:
Linking merchants to enable Split Payout is described at Link merchants for Split Payout
The brand visa
also includes the sub-brands VPay and Visa Electron. These sub-brands cannot be activated separately and
are always included when the brand visa
is activated.