Payment processing

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)

1. The customer selects the product in your iframe.
   Example: The customer chooses the floor plan type B for the price of 14,90€.
2. 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

3. 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.
4. 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:

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:
  • sha256 is used as an algorithm.
  • The secret of the provider is used as key.
  • The JSON data is converted to an array usingjson_decode($jsonString, true). This is then assembled into a string with http_build_query($jsonArray, '', '&', PHP_QUERY_RFC3986);. This string is then signed with hash_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&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=26.47

// Mit dem Secret "myTestSecret" wird über $jsonSignature = hash_hmac('sha256', $jsonQueryContent, $secret) folgende Signatur generiert:
451d116c62fe3b67a2409e38fcac35cc2ccacd9b5dd799c88c7293e32d61dc46