Payment processing

Payment via the payment provider

Introduction:

You determine the offer and the price for your products / services. The customer selects a product in your iframe. To initiate the payment process , call a lightbox with the onOffice payment dialog . Here onOffice lets the user confirm the order.

The possible payment methods are credit card and SEPA direct debit. Several credit cards or bank details can be stored per account. The customer chooses the appropriate payment method when purchasing. For the payment transfer we cooperate with the payment provider Mangopay . When adding a merchant, you can let us know if you want to limit the payment methods for your service (e.g. customer should only be able to pay by credit card).

Each Marketplace partner signs a separate contract with Mangopay and receives an account there, which we set up for you. The revenue can then be transferred to the company’s own account via a pay-out . In your transaction overview under the menu item Marketplace >> Provider Account you can view all transactions made.

Sandbox and Production Mode :

There are basically 2 different modes in which the Marketplace runs. Sandbox mode is used to test your store in the development phase and all transactions are performed without real money using test credit cards.

In Production mode , all transactions are performed with real money. When your store is fully programmed and tested, your store can be switched to production mode .

Let us know if you want us to convert your store. We at onOffice then test the interfaces of your store to onOffice enterprise and exchange your wallet ID.

In order to be able to continue testing later extensions of your store, we can gladly set up a second test provider for testing purposes that runs in sandbox mode. Please contact us if you need a test provider in sandbox mode. Please provide us with the activation and service URL as well as the MangoPay walletid of your test service. All other information is the same as for your real provider.

At the top right of the menu bar in enterprise, the status is displayed as“Sandbox” or“Production” in your provider client. If it does not say “Sandbox” or “Production”, then your provider is not (correctly) linked. In this case, please contact us. Under no circumstances should you create any accounts.

Test credit cards:

In order to be able to test the payment processing, Mangopay offers Test cards to simulate transactions. Due to the change to 3DSV2-Secure, only the 2 3DSV2 test cards with “frictionless flow” and “challenge flow” can be used. The “frictionless flow” is more suitable for testing, as no 3DSV2 entry should be necessary here in most cases, but no larger amounts can be posted either.

I.e. Test cards that do not have a 3DSV2 query will therefore not work. The working test cards are currently 49701051923460 and 4970105181854329.

Alternatively, you can use the cards under “liability shift” with the password given on the page, but where there is always a 3DSV2 security prompt.

FR7630004000031234567890143 works for SEPA transactions. If the test credit cards do not work, this can be used as an alternative.

KYC documents for MangoPay:

The EU Anti-Money Laundering Directive requires legitimation verification in the form of KYC (know your customer) documents, so please provide us with the following documents:

IDENTITY PROOF -> passport, ID card or driver’s license
REGISTRATION PROOF -> Extract from the Commercial Register
ARTICLES OF ASSOCIATION -> Articles of Association
SHAREHOLDER DECLARATION -> List of shareholders (https://www.mangopay.com/terms/shareholder-declaration/Shareholder_Declaration-EN.pdf)

Transaction list: Pay out and cancel transactions

Under the menu item Marketplace >> Provider 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, transaction ID or by other criteria in “Additional filter 1:”. The booking day or the time of the value date can be selected as the date reference. SEPA transactions may take a few days to complete.
Cancel booking: Transactions can be canceled in your transaction overview via the icon for “Cancel booking”. In this case, the repayment of the transfer is triggered via the Mangopay API. The cancelled transaction is displayed in the transaction overview as a transaction with a negative amount. The buyer receives an email about the cancellation of the transaction. No transactions older than 11 months can be cancelled. Cancellation is possible only when the status of the transaction is set to successful. I.e. for transactions with payment type SEPA, which are “in process”, a cancellation is not possible. Cancellation is also possible via API with the API call Cancel transaction possible. In the event that the wallet is not sufficiently covered, the feedback comes: “This Mangopay account has insufficient funds. The cancellation could not be made.” Therefore, we recommend leaving a small amount of money in the accounts in case of cancellations. Otherwise, problems may arise when cancelling on an unfunded account. Note that currently at payout only the full amount can be transferred.
Cancel subscriptions: You can cancel subscriptions via 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 of the transaction: Use the magnifying glass icon to view more details about the transaction . Here you can find other important information such as the payment method (credit card or bank account), the billing address of the buyer and detailed information about the order.
Status of a transaction: The Status column shows the status of the transaction. Possible values are: successful, failed or in progress. The status “in process” is always and only set for the payment type SEPA. In this case, the payment provider has requested the debit from the bank. The money is collected from the customer only after a few days. On the following day, the status is then changed to successful if the payment has worked out. In principle, the status “in preparation” can be treated in the same way as “successful”. If a payment fails, you will be notified by mail and the payment will be set to failed. The money must then be demanded by subsequent payment link .
Reference ID: The “Reference ID” field allows your customers to associate a debit from Mangopay to their bank account with a paid Marketplace service. The reference ID is provided to the bank as a reference number and appears on the account statement. The reference IDs are unique for each customer.
Account balance: The current balance of your Mangopay wallet is displayed here.
Payout: By clicking “Make a withdrawal” you can transfer the full amount of your Mangopay account to the bank account you have deposited. A security prompt follows: “Would you like to make a withdrawal? The full amount on your Mangopay account (XXX,XX€ ) will be transferred to the account with IBAN ***0147. Attention: Cancellations are not possible again thereafter until the account is sufficiently funded.” The purpose of the transfer is “Marketplace”. In the transaction list, the disbursement is displayed as a transaction of type “Disbursement”. Payment of partial amounts is not possible at the moment.
CSV export: Using 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.

Sequence of a transaction:

Using floor plan optimization as an example, the transaction flow is as follows (in italics):

The customer selects the product in your iframe.
Ex: The customer chooses floor plan type B for the price of 14,90€.
The provider calls the payment dialog of onOffice and transmits the name, the price and the quantity for the selected product.
Ex: The floor plan provider calls the onOffice payment dialog and submits the name for the product selected by the customer (e.g. floor plan type B), the price (e.g. 14,95€) and the quantity.

The customer confirms the purchase. Possibly, for some purchases, 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. This collects the sum from the customer and transfers it to your account.
Ex: The customer confirms the purchase of the floor plan type B at the price of 14,95€. The amount will be 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 besides Germany, Switzerland and Austria. Recently, the Marketplace has also been launched in Italy, Spain, Slovenia, Croatia and Luxembourg. In the initial phase, there may still be a few providers available for the new countries. In the order popup, the VAT is taken into account as follows:

if it is a German billing address, the VAT will always be calculated.
if it is an EU country, no VAT will be charged for a registered VAT ID.
if no VAT ID is registered for an EU country, VAT will be charged.
no VAT is charged if the country is a third country (non-European foreign country).

Structure of the link to the payment processing

After the customer places an order from the provider’s Iframe, the lightbox for payment opens.

The service called in the iframe must pass the data for this as a JSON string via postMessage to the parent window. The JSON string must be signed with the provider’s secret, thus 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. Please note: SEPA payments are handled differently and have their own “inprocess” status. More about this in the explanation of the “status” parameter.

Explanation of the parameters

“callbackurl”: This URL is called after a payment and returns several parameters per querystring (plus possibly individual parameters):
- “transactionid”: A unique ID of the specific transaction. This is to be stored by you for subsequent processing purposes as well as for traceability purposes.
- “referenceid” : This reference ID appears on the bank transfer slip as the customer reference number so that the customer can allocate the transaction.
- “status”: Returns either “success”, “inprocess” or “error”. The status “inprocess” is only used for the payment type SEPA direct debit, because there the processing of the transaction can take several days. I.e. “inprocess” is always a SEPA transaction. In this case, the payment provider has requested the debit from the bank. The money is collected from the customer only after a few days. On the following day, the status is then changed to “success” if the payment has worked out. In principle, the “inprocess” status can be treated in the same way as the “success” status. If a payment fails, you will be notified by mail and the payment will be set to failed. The money must then be demanded by subsequent payment link.
- “errorCodes”: Returns an error code if an “error” was returned. (Error codes and descriptions see Error codes.)
- “message”: Returns the description of the error code if an “error” was returned.
- “timestamp”
- “signature”
Other individual parameters (e.g. product ID) that might be necessary for your processing can be freely defined by you. The callback URL should also be checked for the signature.
“parametercacheid”: Is passed to the provider as a querystring parameter during service and must be returned here. The parameter contains internal information that is stored in the parameter cache.
“products”: Here the products selected by the user must be listed with “name”, “price” and “quantity”. “circleofusers” is optional and determines 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 supplied with a dot “.” as a decimal separator . Also, no other separators such as thousands separators may be used, and the price is supplied as the net price . In addition, all prices should always be quoted with two decimal places . Please note: Currently, only one product can be offered per order.
“timestamp”: Here a timestamp is to be generated, which flows into the signature and thus makes it unique.
“totalprice”: This is the total price over all products. (The same rules apply here as for product prices)
“signature”: This must be formed over the JSON string so that the validity can be validated. (see explanation of the signature)

In the code samples you can find a sample store with the implementation of the signature generation. Please note that the demo store does not validate the URL or 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 Parametercacheid is missing.

1031 Transaction has already been executed (for subsequent payments).
1032 The logged in user does not match the submitted userId.
1033 The customer does not have an active account.

1101 MANGOPAY error: Customer does not have 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 can not be made because of 3D Secure.
1105 MANGOPAY error: Deposit 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 payment process at MANGOPAY.

8505 The limit of ten payments per day per credit card was exceeded.

In all cases, no payment has been made, so any errors should be handled by you as the provider.

Explanation of the JSON string signature

The method for signature calculation can be found in CreateProductJsonOrderwithSignature.php of the demo store website. The process of signature calculation happens as follows:

Adding a timestamp.
Sort parameters alphabetically: the parameter names must be sorted in alphabetical order. The parameter names in subarrays (such as products) must also be sorted alphabetically (recursive sorting).
Creating the signature:
- sha256 is used as an algorithm.
- The provider’s secret is used as the key.
- The JSON data is converted to an array via json_decode($jsonString, true) . This is then assembled into a string using http_build_query($jsonArray, '', '&', PHP_QUERY_RFC3986); . This string is then signed via hash_hmac(‘sha256’, $jsonQueryBuildString, $AnbieterSecret); .
Finally, the obtained signature is appended in the JSON array and then the array is converted back to a JSON string via json_encode($jsonArraywithSignature, JSON_UNESCAPED_UNICODE|JSON_UNESCAPED_LINE_TERMINATORS) .

Example of signature calculation with test data:

// Call the Funktion sign($jsonData, $secret) in CreateProductJsonOrderwithSignature.php with parameters $jsonData and
// secret:
$jsonData = '{"totalprice":"17.97","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'

// Add timestamp (in this example 1565689180);
$jsonDecodedContent = json_decode($jsonData, true);
$jsonDecodedContent['timestamp'] = time();

// sorted array after call of sortParameters($jsonDecodedContent):
[
  "callbackurl" => "https://www.anbietershop.de/HandleonOfficeOrderResponse.php",
  "parametercacheid" => "0e81f10f-6de8-4edc-cdcf-de96cf61624c",
  "products" => [
      [
        "circleofusers" => "customer",
        "name" => "onOffice Sample 1",
        "price" => "5.99",
        "quantity" => "3"
     ]
   ],
  "timestamp" => 1565689180,
  "totalprice" => "17.97"
]

// The string to be signed loos like this (after call of http_build_query($jsonContent, '', '&', PHP_QUERY_RFC3986)):
callbackurl=https%3A%2F%2Fwww.anbietershop.de%2FHandleonOfficeOrderResponse.php&parametercacheid=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&timestamp=1565689180&totalprice=17.97

// Generate following signature with secret "myTestSecret" and call of 
// $jsonSignature = hash_hmac('sha256', $jsonQueryContent, $secret):
49b818db62d1b86640ea34f4525e64809fa44d5e0b90ad719aadd5425f66c9ba

The sample code can be downloaded here as a text file. For testing purposes, we recommend working with it instead of copying the code snippet here from the page.

Subscription:

The Marketplace can also offer subscriptions for products or services that are billed on a monthly basis. The subscription starts immediately after the purchase. Then the first installment for the subscription will also be billed. Subscription ID and transaction ID are passed.

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 pass 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 several parameters per querystring (plus possibly individual parameters):
- “transactionid” : A unique ID of the specific transaction. With a subscription, each monthly debit is a transaction. This is to be stored by you for subsequent processing purposes as well as for traceability purposes
- “aboid” : A unique ID of the subscription. This is to be stored by you for subsequent processing purposes as well as for traceability purposes
- “referenceid” : This reference ID appears on the bank transfer slip as the customer reference number so that the customer can allocate the transaction.
- { “status”: Returns either “success”, “inprocess” or “error”. The status “inprocess” is only used for the payment type SEPA direct debit, because there the processing of the transaction can take several days. I.e. “inprocess” is always a SEPA transaction.
- “message”: Returns an error text if an “error” was returned. (error texts see below)
- “timestamp”
- “signature”
“parametercacheid: Is passed to the provider as a querystring parameter during service and must be returned here. The parameter contains internal information that is stored in the parameter cache.
“subscription”:
- “monthlycosts”: monthly cost of the subscription
- “monthlyservicedescription”: Description of the product for which the subscription is taken out
- “durationinmonth”: Term in months
- “noticeperiod”: Notice period
- “automaticrenewal”: Period of automatic renewal
- “circleofusers: User group for which the purchase was made. Possible values: Client (customer), office group (group), user (user)
“timestamp”: Here a timestamp is to be generated, which flows into the signature and makes it thus uniquely
“signature”: This must be formed over 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 used only 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.

Notice if subscription payment fails:

It may happen that the monthly subscription amount cannot be collected, e.g. 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 is 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 it.

I.e. after that you are then responsible to charge the missing amount to the customer. You can do this conveniently, for example, via the post-payment link .

3D-Secure: Purchases sometimes require confirmation from the customer through 3D-Secure (3DS2). As a rule, once a subscription has been concluded, no further queries are made by 3DV2-Secure for the following recurring payments. The customer gives the release with the first payment that also the future payments about the same amount can pass without 3DS2.

In rare cases, where a debit nevertheless fails due to 3DS2, the amount due will be collected via a post-payment link. In case of such a failed transaction, a post-payment link will be sent to the buyer by mail. You as a provider will receive an email for information. In this case, no further attempts will be made to debit the account.

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“. Clicking on the “Hourglass” icon opens a view where you can set the cancellation date for the subscription. No debits will be made after this date.

API call to end a subscription:

Subscriptions do not automatically expire. If a subscription is to be terminated, notify us via API. The API call for canceling a subscription passes the “cancellationDate”. From this date (incl.) no more debits will be made.

{
  "actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:do",
  "resourceid": "",
  "identifier": "",
  "resourcetype": "marketplaceCancelAbo",
  "parameters": {
    "aboid": "5",
    "cancelationDate": "2019-10-05"
  }
}

Billing:

onOffice does not invoice customers in the Marketplace when they make a purchase, which means it is your responsibility to invoice the customer. You are obliged to issue an invoice to the customer, as the purchase of your services or products creates a legally binding transaction.

API call “data of the invoice recipient

To automate invoicing, you can read the data of the invoice recipient with the API call “Invoice recipient data“.

{
  "actionid": "urn:onoffice-de-ns:smart:2.5:smartml:action:get",
  "resourceid": "",
  "identifier": "",
  "resourcetype": "getMarketplaceInvoiceRecipient",
  "parameters": {
    "transactionid": "12345678",
    "userid": "123"
  }
}

Necessary parameters are “transactionid” and “userid”
Country is returned as 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 .

Automated invoicing – querying the invoice recipient

Previously, only customer IDs and API keys were stored. There can be X invoice recipients behind a customer ID.

Any number of users can work in one onOffice customer version (in the largest customer version there are over 1000 users). If the brokers are employed as franchisees by 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 accordingly to the respective broker.

As a provider, you can automate invoicing or perform it manually. onOffice sends an e-mail with the data of the respective invoice recipient for each booking. In case of automation, the data of the invoice recipient can be requested from onOffice via the API call“Invoice recipient data” during the purchase.

In the payment dialog, the customer confirms his purchase. onOffice sends the provider the info that the purchase was successfully completed. This event serves you as a trigger for querying the invoice recipient.
The invoice recipient is read via the API call “Invoice recipient data” ..
…and posted in your system for invoicing.

Commission

After the payment process has been initiated at the payment provider, the amount is debited from the customer’s account. Of this amount, one commission goes to onOffice, and the remaining amount is transferred to the provider’s account. You can have the amount paid out via a payout in your provider version (Production).

From the commission, among other things, all fees for the payment provider are deducted. The net price of the product serves as the basis for the commission calculation.

The service of Mangopay is therefore free of charge for you as a provider.

Disputes

In rare cases, disputes may arise in connection with purchases, i.e. a customer may request payment back from the bank. The money is then first debited from onOffice. You will receive a mail from us where you will be asked to cancel the corresponding transaction in your provider client. The buyer will also be informed about this by e-mail.

You can trigger this in the provider client under “Marketplace >> Provider account” via the “Arrow back” icon “Cancel booking” for the individual transactions. Unless this happened in a certain period of time, onOffice would perform the cancellation at your end in the provider client.

If a dispute has been registered for a transaction, the transaction gets the status “Dispute needed” in the transaction list. Notice: There are also disputes that cannot be cancelled because they may not be contestable.

Settle subsequent costs

If the scope of the order changes, the costs must be settled subsequently. This can happen, for example, if the scope of services changes due to subsequent communication with the customer.

Using the example of floor plan optimization, this could look like this:

The customer orders the optimization of a floor plan at a price of 14.95€. He does not pay attention to 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 triggers the payment process.
This link is composed as described in the following section “Structure of the link for subsequent settlement”.
The customer must be logged in with his user when calling the link in onOffice. If this is not the case, he will be prompted to log in.
The payment dialog then opens.
If the customer confirms the dialog, the costs are transferred.

The provider sends the customer an email with the signed link to the payment dialog.
The customer confirms the payment and the provider is informed about the confirmation of the payment.

Send back payments / generator for the back payment link

In your provider client, you have the option to generate a post-payment link that you can send to your customer. The post-payment link takes the customer to the lightbox for the purchase, where he confirms the post-payment. To do this, use the Euro icon for each transaction in your provider account under “Marketplace >> Provider account”.

A lightbox will open where you can enter the name of the additional service and the price. The back payment link will then be generated. You can send this directly to your customer via “Send additional payment 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.

Subsequent Settlement Template

This is always the additional payment to an already made purchase via the Marketplace. This can be a one-time purchase or a subscription. 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 lightbox for the payment will open.

Check for PSP account validity:
We check if the user has an active Mangopay account at the time of the call based on the user ID.

Checking signature and active session:
When the link is executed, we check if the link is correctly signed.

Also, the link can only be called if the user is logged in with his account (from which the original order was placed) in the specified client. If he is not logged in, a login mask opens. After successful login, the link can then be accessed. The recipient must access the link in the same browser where the onOffice session is running.

This post is also available in: German