Payment via the payment provider
Introduction:
You determine the offer and the price for your products / services. The customer chooses a product in your iframe. To initiate the payment process, you call up a popup with the onOffice payment dialog. Here onOffice allows the user to confirm the order. The possible payment methods are credit card and SEPA direct debit.
For the payment transmission we work together with the payment provider Mangopay. Each Marketplace partner signs a separate contract with Mangopay and receives an account there, which will be set up for you.
The revenues can then be transferred to your own account via a pay-out.
In your transaction overview under the menu item Marketplace >> Merchant account you can see all transactions you have made.
Sandbox and Production Mode:
There are basically 2 different modes in which the Marketplace runs. Sandbox mode is used to test your shop in the development phase and all transactions are carried out without real money with test credit cards. Most Marketplace providers are currently still running in Sandbox mode and are now gradually switching to Production mode. In Production Mode, all transactions are carried out with real money.
Once your shop has been fully programmed and tested, it can be switched to production mode. Let us know when you want us to convert your shop. Then we at onOffice test the interfaces of your shop to onOffice enterprise and exchange your wallet ID.
In order to be able to continue testing later extensions of your shop, we can gladly set up a second test provider for you for testing purposes, which runs in sandbox mode. Please contact us if you need a test provider in sandbox mode. Please tell us the activation and service URL as well as MangoPay walletid of your test service. All other information is the same as with your real provider.
At the top right of the menu bar in enterprise the status as “Sandbox” or “Production” is displayed in your provider client.
If neither “Sandbox” nor “Production” is listed there, then your provider is not (correctly) linked. Please contact us in this case. Do not create any accounts in any case.
Test credit cards:
To test the payment processing, Mangopay offers test cards to simulate transactions. Use the first 4 test cards in the VISA/MC section under “For payments under 50€ you can use these cards”. These allow transactions up to 500€ (five hundred). Higher amounts than 500€ will not work in the test environment, because 3D Secure is required. For transactions with amounts above 500€ an error message is displayed.
KYC documents for MangoPay:
The EU Anti-Money Laundering Directive requires a legitimacy check in the form of KYC (Know your customer) documents, therefore we ask you to provide us with the following documents:
- IDENTITY PROOF -> Passport, identity card or driving licence
- REGISTRATION PROOF -> extract from the commercial register
- ARTICLES OF ASSOCIATION -> Partnership agreement
- SHAREHOLDER DECLARATION -> List of shareholders (https://www.mangopay.com/terms/shareholder-declaration/Shareholder_Declaration-EN.pdf)
Cancel transactions:
Under the menu item Marketplace >> Supplier Account you can view all transactions that your customers have made with you.
Filter bar: In the upper area, you can use the filter bar to control the transactions displayed in the transaction list. You can filter by date ranges, the transaction ID or by further criteria in “Further filter 1:”. The posting date or the value date can be selected as the date reference. SEPA transactions, for example, may take a few days to complete.
Cancel booking: Transactions can be cancelled in your transaction overview via the icon for “Cancel booking”. This will trigger the refund of the transfer via the Mangopay API. The cancelled transaction will be displayed in the transaction overview as a transaction with a negative amount. No transactions older than 11 months can be cancelled. Cancellation is only possible when the status of the transaction is set to successful. I.e. a cancellation is not possible for transactions with payment type SEPA that are “in process”. Cancellation is also possible via API with the API call Cancel transaction.
In case the wallet is not sufficiently funded, the response will be “This Mangopay account is not sufficiently funded. The cancellation could not be performed.”
Therefore, we recommend leaving a small amount of money in the accounts in case of cancellations. Otherwise, there may be problems if cancellations are made on an account that is not funded. Note that currently only the full amount can be transferred during payout.
CSV export: Via the links “current month” and “last month” at “CSV export” the transactions of the current and last month can be downloaded as CSV file. Via “Filtered list” the current filtered selection in the transaction list is exported.
Payout: Via “Execute Payout” you can transfer the total amount of your Mangopay account to the bank account you have deposited. A security prompt will follow:
“Do you want to initiate a payout? The full amount on your Mangopay account (XXX,XX€ ) will be transferred to the account with IBAN ***0147. Attention. Cancellations are only possible again afterwards, when the account is sufficiently covered.”
The purpose of the transfer is “Marketplace”. In the transaction list, the payout is displayed as a transaction of type “Payout”. Payout of partial amounts is not possible at the moment.
Cancel subscriptions: You can cancel subscriptions using the hourglass icon.
Generate post-payment link: Via the Euro icon you can generate a post-payment link and send it to your customers.
Details about the transaction: Via the magnifying glass icon you can view further details about the transaction. Here you can find more important information like the payment method (credit card or bank account), the billing address of the buyer as well as detailed information about the order.
Status of a transaction: in the Status column you can see the status of the transaction. Possible values are: successful, failed or in process. The status “in processing” is always and only set for the SEPA payment type. In this case, the payment provider has requested the debit from the bank. The money will be collected from the customer only after a few days. On the following day, the status is changed to successful if the payment was successful. So in principle, for the time being, the status “in preparation” can be treated in the same way as “successful”. If a payment fails, you will be informed by mail and the payment is set to failed. You then have to ask for the money via a subsequent payment link.
Reference ID: So that your customers can assign a debit from Mangopay on their bank account to a paid Marketplace service, the field “Reference ID” is used. This is provided to the bank as a reference number and appears on the bank statement. The reference IDs are unique for each customer.
Procedure of a transaction:
Using the example of floor plan optimization, the process flow of a transaction is as follows (in italics)
- The customer selects the product in your iframe.
Example: The customer chooses the floor plan type B for the price of 14,90€. - The provider calls up the payment dialog of onOffice and transmits the name, price and quantity for the selected product.
Example: The floor plan provider calls up the onOffice payment dialogue and transmits the name of the product selected by the customer (e.g. floor plan type B), the price (e.g. 14.95€) and the quantity.
Lightbox Marketplace Order
- The customer confirms the purchase. For purchases over 500 €, the customer is redirected to a 3D secure page of his bank/credit card company, where he has to authenticate himself with a security code. Thereupon onOffice triggers the payment process with the payment provider. The payment provider collects the amount from the customer and transfers it to your account.
Example: The customer confirms the purchase of floor plan type B at a price of 14,95€. The sum is transferred to your account. - onOffice sends the information about whether the purchase was confirmed or there was a problem. If the purchase was successful, the customer receives an order confirmation by e-mail.
Marketplace in other countries / VAT:
In the future, the Marketplace will gradually be made available in other countries apart from Germany, Switzerland and Austria. Recently, the Marketplace has also been launched in Italy, Spain and Slovenia. In the initial phase, there may still be a few suppliers available for the new countries.In the order pop-up, VAT is taken into account as follows:
- if it is a German customer, the VAT will always be calculated.
- if it is an EU country, no VAT will be charged if a VAT ID is entered.
- if no VAT ID is registered for an EU country, VAT will be charged.
- no VAT is charged if it is a third country (non-European foreign country).
Structure of the link for payment processing
After the customer has placed an order from the provider-Iframe, the payment popup opens.
The service called up in the iframe must transfer the data for this as JSON string per postMessage to the parent window. The JSON string must be signed with the secret of the provider, so the request can be authenticated.
The JSON should have the following structure:
{
"callbackurl": "https://www.anbietershop.de/HandleonOfficeOrderResponse.php",
"parametercacheid": "0e81f10f-6de8-4edc-cdcf-de96cf61624c",
"products": [
{
"name": "onOffice Sample 1",
"price": "5.99",
"quantity": "3",
"circleofusers": "customer"
}
],
"timestamp": 1565689180,
"totalprice": "26.47",
"signature": "649ee3dfbfb53187a9b2b66fafb658df24ca037c6de473fe9bcee2e327289dd5"
}Please note: Currently only one product can be offered per order.
Explanation of parameters
- “callbackurl”: This URL is accessed after a payment and returns 5 parameters per query string (plus individual parameters if necessary):
- “transactionid”: A unique ID of the specific transaction. This should be saved by you for later processing purposes and for traceability.
- “referenceid” : Via the field “referenceid” your customers can link a debit from Mangopay on their bank account to a paid Marketplace service. The reference ID is communicated to the bank as a reference number and appears on the account statement. The reference IDs are unique for each customer.
- “status”: Returns either “success”, “inprocess” or “error”. The “inprocess” status is only used for the SEPA Direct Debit payment type, as the transaction may take several days to process. This means that “inprocess” is always a SEPA transaction.
- “errorCodes”: Returns an error code if an “error” was returned. (For error codes and descriptions, see Error codes).
- “message”: Returns an error text if an “error” was returned. (Error texts see below)
- “timestamp”
- “signature”
Further individual parameters (e.g. product ID), which could be necessary for your processing, can be freely defined by you. The callback URL should also be checked for the signature in the callback.
- “parametercacheid”: Is transferred to the provider as a query string parameter in the service and must be returned here. The parameter contains internal information that is stored in the parameter cache.
- “products”: The products selected by the user must be listed here with “name”, “price” and “quantity”. “circleofusers” is optional and defines the circle of users for which the purchase was made. Possible values: client (customer), office group (group), user (user). It is important that the price is always delivered with a dot “.” as decimal separator. In addition, no other separators such as thousand separators may be used, and the price is delivered as a net price. Furthermore, all prices should always be specified with two decimal places. Please note: Currently only one product can be offered per order.
- “timestamp”: A timestamp is to be generated here, which will be incorporated into the signature and thus make it unique.
- “totalprice”: This is the total price for all products. (The same rules apply here as for the product prices)
- “signature”: This must be formed via the JSON string, so that the validity can be validated. (see explanation of the signature)
In the code examples you will find an example shop with the implementation of the signature generation. Please note that the demo shop does not validate the URL or the signature, so this must be implemented by you.
Error codes
If an error occurs during the order and an “error” is returned as “status”, the following error codes may appear as “errorCodes”. Possible errors:
- 1000 An unknown error has occurred
- 1001 Json-string could not be read
- 1002 Signature was not correct
- 1011 A price did not have the correct formatting. Expected is a price with two decimal places with decimal point (e.g. 15.23).
- 1012 Total price is not correct. The total price must match the price in the product or monthly subscription payment.
- 1013 Data structure not correct. Either exactly one product record or exactly one subscription record must be passed.
- 1021 Parameter timestamp is missing.
- 1022 Parameter signature is missing.
- 1023 Parameter parametercacheid is missing.
- 1031 Transaction has already been executed (for subsequent payments).
- 1032 The logged-in user does not match the transmitted userId.
- 1033 The customer does not have an active account.
- 1101 MANGOPAY error: Customer does not have a MANGOPAY Wallet.
- 1102 MANGOPAY error: Customer has not set a payment method.
- 1103 MANGOPAY error: Provider does not have a MANGOPAY wallet.
- 1104 MANGOPAY error: Payment cannot be made because of 3D Secure.
- 1105 MANGOPAY error: Payment to MANGOPAY wallet not possible.
- 1106 MANGOPAY error: Transfer to MANGOPAY wallet not possible. Not enough money on the customer’s MANGOPAY wallet.
- 1107 Unknown error during the payment process with MANGOPAY.
- 8505 The limit of ten payments per day per credit card was exceeded.
In all cases, no payment has taken place, so all errors should be handled by you as the provider.
Explanation of the JSON string signature
You can find the sample code in the CreateProductJsonOrderwithSignature.php of the demo shop website.
- Adding a timestamp.
- Sorting the parameters from A-Z: First all entries are sorted according to the parameter name.
- Creating the signature:
sha256is used as an algorithm.- The secret of the provider is used as key.
- The JSON data is converted to an array using
json_decode($jsonString, true). This is then assembled into a string withhttp_build_query($jsonArray, '', '&', PHP_QUERY_RFC3986);. This string is then signed withhash_hmac(‘sha256’, $jsonQueryBuildString, $AnbieterSecret);.
- Finally, the received signature is appended to the JSON array and the array is then converted back to a JSON string using
json_encode($jsonArraywithSignature, JSON_UNESCAPED_UNICODE|JSON_UNESCAPED_LINE_TERMINATORS).
Example of signature calculation with test data:
// Rufe die Funktion sign($jsonData, $secret) in CreateProductJsonOrderwithSignature.php mit den Parametern JSON-Data und Secret auf:
$jsonData = '{"totalprice":"26.47","callbackurl":"https://www.anbietershop.de/HandleonOfficeOrderResponse.php","parametercacheid":"0e81f10f-6de8-4edc-cdcf-de96cf61624c","products":[{"quantity":"3","circleofusers":"customer","price":"5.99","name":"onOffice Sample 1"}]}'
$secret = 'myTestSecret'
// Füge timestamp hinzu (hier 1565689180);
$jsonDecodedContent['timestamp'] = time();
// Sortiertes Array nach Durchlaufen von $contentSorted = sortParameters($jsonDecodedContent):
[
"callbackurl" => "https://www.providershop.de/MarketplaceDemoShop/ResultPage.php",
"parametercacheid" => "84839588-cd83-53be-881b-3fa953a853e2",
"products" => [
[
"circleofusers" => "customer"
"name" => "Produktname"
"price" => "0.08"
"quantity" => "1"
],
],
"timestamp" => "1565689180"
"totalprice" => "0.08"
]
// Der zu signierende String sieht nach Aufruf von http_build_query($jsonArray, '', '&', PHP_QUERY_RFC3986) dann folgendermaßen aus:
callbackurl=https%3A%2F%2Fwww.anbietershop.de%2FHandleonOfficeOrderResponse.php¶metercacheid=0e81f10f-6de8-4edc-cdcf-de96cf61624c&products%5B0%5D%5Bcircleofusers%5D=customer&products%5B0%5D%5Bname%5D=onOffice%20Sample%201&products%5B0%5D%5Bprice%5D=5.99&products%5B0%5D%5Bquantity%5D=3×tamp=1565689180&totalprice=26.47
// Mit dem Secret "myTestSecret" wird über $jsonSignature = hash_hmac('sha256', $jsonQueryContent, $secret) folgende Signatur generiert:
451d116c62fe3b67a2409e38fcac35cc2ccacd9b5dd799c88c7293e32d61dc46
Subscriptions
In the Marketplace, subscriptions to products or services can also be offered, which are billed monthly. The subscription starts immediately after purchase. Then the first payment for the subscription is also billed. The subscription ID and transaction ID are transferred.
The JSON transfer parameter for a subscription is described below.
There is one JSON string for subscriptions and one for products (see above).
It is only possible to transfer either a product or a subscription per call.
{
"callbackurl": "https://www.providershop.de/HandleOrderResponse.php",
"parametercacheid": "0e81f10f-6de8-4edc-cdcf-de96cf61624c",
"abo": {
"monthlycosts": "25.70",
"monthlyservicedescription": "5 3D-Rundgänge",
"durationinmonth": "6",
"noticeperiod": "bis 3 Monate vor Vertragsende",
"automaticrenewal": "12 Monate",
"circleofusers": "customer"
},
"timestamp": 1565689180,
"signature": "649ee3dfbfb53187a9b2b66fafb658df24ca037c6de473fe"
}- callbackurl”: This URL is called after a payment and returns 6 parameters per query string (plus individual parameters if necessary):
- “transactionid” : A unique ID of the specific transaction. In the case of a subscription, each monthly debit is a transaction. This should be stored by you for later processing and traceability purposes.
- “aboid” : A unique ID of the subscription. This is to be stored by you for later processing purposes and for traceability
- “referenceid” : Via the field “referenceid” your customers can link a debit from Mangopay on their bank account to a paid Marketplace service. The reference ID is communicated to the bank as a reference number and appears on the account statement. The reference IDs are unique for each customer.
- “status”: Returns either “success”, “inprocess” or “error”. The “inprocess” status is only used for the SEPA Direct Debit payment type, as the transaction may take several days to process. This means that “inprocess” is always a SEPA transaction.
- “message”: Returns an error text if an “error” was returned. (Error texts see below)
- “timestamp”
- “signature”
- “parametercacheid”: Is transferred to the provider as a query string parameter in the service and must be returned here. The parameter contains internal information that is stored in the parameter cache.
- “abo”:
- “monthlycosts”: monthly costs of the subscription
- “monthlyservicedescription’: description of the product for which the subscription is taken out
- “durationinmonth”: Duration in months
- “noticeperiod”: period of notice
- “automaticrenewal”: period of automatic renewal
- “circleofusers”: circle of users for whom the purchase was made. Possible values: Client (customer), office group (group), user (user)
- “timestamp”: A timestamp is to be generated here, which is incorporated into the signature and thus makes it unique
- “signature”: This must be formed via the JSON string so that the validity can be validated. (see explanation of the signature)
All parameters are mandatory parameters.
All subscription parameters, except prices, are only used for output.
“circleofusers” indicates for which group of users the purchase was made (→ see orders for multiple users).
The error texts as well as the signing of the JSON string are the same as for the one-time purchase of a product.
Advice when subscription payment fails:
It may happen that the monthly subscription amount cannot be collected, for example because the customer’s account is not covered, the account has been closed or the amount could not be collected for other reasons.
In this case you and the customer will receive an e-mail from us that the subscription amount could not be collected. Seven days later, a second and third attempt will be made to collect the amount again. You and the customer will be informed by e-mail.
After 3 failed attempts to collect the amount, the collection of the subscription amount for this month has failed and you will receive an e-mail about this.
This means that you are then responsible to charge the customer for the missing amount. You can easily do this, for example, via the payment link.
The subscription remains set up as long as it is not cancelled by you, so that the subscription amount is collected again in the next month.
Cancel subscriptions:
Subscriptions do not automatically expire. If a subscription is to be terminated, you can cancel the subscription via the GUI in your onOffice provider client.
To do this, call up the menu item “Marketplace >> Provider Account”. When you click on the “Hourglass” icon, a window opens in which you can set the cancellation date for the subscription. After this date, no further debits will be made.
API Call to terminate a subscription:
Subscriptions do not expire automatically. If a subscription is to be terminated, please inform us via API. The API call for terminating a subscription passes the “cancelationDate”. From this date (incl.) no more cancellations are made.
{
"actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:do",
"resourceid": "",
"identifier": "",
"resourcetype": "marketplaceCancelAbo",
"parameters": {
"aboid": "5",
"cancelationDate": "2019-10-05"
}
}API access “Billing Recipient Data”
{
"actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:get",
"resourceid": "",
"identifier": "",
"resourcetype": "getMarketplaceInvoiceRecipient",
"parameters": {
"transactionid": "12345678",
"userid": "123"
}
}To automate the billing process, you can read the data of the bill recipient with the API call “Bill recipient data”.
- Necessary parameters are “transactionid” and “userid”
- Country is returned as an ISO 3166-1 alpha-3 value on API call.
- API error messages:
- 184: User id is not existing or inactive (INFO: User id in the order is not the same as the transaction buying user id)
- 188: The user data could not be found
- 189: The transaction could not be found
- 190: The time to call the transaction has expired
All API calls used in the Marketplace are also described on the official API documentation.
Automatic invoicing – Queries of the invoice recipient
Previously, only customer IDs and API keys were stored. There can be X bill recipients behind a customer ID.
In an onOffice customer version any number of users can work (in the largest customer version there are over 1000 users). If the brokers are employed as franchisees with a large network but still work independently, they have their own group or user account with the payment provider. The invoice must then be issued to the respective broker accordingly.
As a provider you can automate the invoicing process or carry it out manually. onOffice sends an e-mail with the data of the respective invoice recipient for each booking. In the case of an automation, the data of the invoice recipient can be requested from onOffice via the API call “Data of the invoice recipient” when purchasing.
- In the payment dialogue the customer confirms his purchase. onOffice sends the information to the supplier that the purchase was successfully completed. This event serves as a trigger for you to query the invoice recipient.
- The bill recipient is read out via the API call “Bill recipient data”…
- …and posted to your billing system.
Commission
After the payment process has been initiated at the payment provider, the amount is debited to the customer. A commission goes to onOffice, the remaining amount is transferred to the provider’s account.
All fees for the payment provider are deducted from the commission. The net price of the product serves as the basis for the commission calculation.
Therefore service of Mangopay is free of charge for you as a provider.
Bill subsequent costs
In the event that the scope of the order changes, the costs must be settled subsequently. This can happen, for example, if the scope of services changes as a result of subsequent communication with the customer.
Using the example of floor plan optimization, this could look as follows:
The customer orders the optimization of a floor plan at a price of 14.95€. He does not consider the limitation of the provider and orders the optimization with a too large area and number of rooms (e.g. 340m², 18 rooms). The floor plan provider contacts him and refers to the amount to be paid for it, with which the customer agrees. A sum X must be recalculated.
The procedure is as follows:
- The floor plan provider sends the customer an e-mail containing a link that initiates the payment process.
This link is composed as described in the following section “Structure of the link for subsequent billing”. - The customer must be logged in with his user when the link is called up in onOffice. If this is not the case, he is requested to log in.
- Thereupon the payment dialog is built up.
- If the customer confirms the dialog, the costs are transferred.
- The provider sends the customer an e-mail with the signed link to the payment dialog.
- The customer confirms the payment and the provider is informed about the payment confirmation.
Send subsequent payments / generator for the subsequent payment link
In your provider client you have the possibility to generate a postpayment link that you can send to your customer. The postpayment link takes the customer to the purchase popup, where he confirms the postpayment. Use the Euro-Icon for each transaction in your provider account under “Marketplace >> Provider Account”.
A lightbox opens, in which you enter the name of the additional service and the price. The subsequent payment link is then generated. You can send this link directly to your customer via “Send postpayment link by e-mail”. A standard mail template with sender “noreply@onoffice.de” is used for this purpose.
Or you can send the generated link to your customer yourself using your own template.
Creation of the link for subsequent settlement
This is always the additional payment to an already made purchase via the Marketplace. This can be a one-time purchase or a subscription, that is, either an existing transaction ID (transactionid) or subscription ID (aboid) must be transferred. You define the e-mail to the customer for subsequent billing. For example, it could be structured as shown in the figure. You can download this template here as HTML for your use.
After clicking on “Order additional service here” the payment popup opens.
Check the validity of the PSP account:
We use the user ID to check if the user has an active Mangopay account at the time of the call.
Check the signature and active session:
When the link is executed, we check whether the link is signed correctly.
Furthermore the link can only be called if the user is logged in with his account (from which the original order was made) in the specified client. If he is not logged in, a login mask opens. After successful login the link can be called up. The recipient must call the link in the same browser in which the onOffice session is running.
This post is also available in: German