Marketplace

A Marketplace is an e-commerce website selling goods through third-party vendors, and sometimes for its own account as well.

Payment processing

Cart handling through the CART parameter

The CART parameter is mandatory and allows to separate the different order’s items by seller.

It is an array in which each entry corresponds to an item of the order.

CART management sub-parameter

  • CART[X][MERCHANTITEMID] string

    Item ID in the merchant system.

  • CART[X][NAME] string

    Item name.

  • CART[X][PRICE] int

    Unit price in cents, including potential taxes and discounts.

  • CART[X][DISCOUNT] float

    Applied discount in percentage. The decimal separator is the dot symbol.

  • CART[X][TAX] float

    Applied taxes in percentage. The decimal separator is the dot symbol.

  • CART[X][QUANTITY] integer

    Quantity of this item.

  • CART[X][TOTALAMOUNT] integer

    Total amount based on PRICE and QUANTITY.

  • CART[X][SUBMERCHANTEXTERNALID] string

    Submerchant account identifier in the marketplace. This field allow a special value “OPERATOR” when the item is sold by the marketplace itself (and not a sub-merchant).

warning

The sum of the TOTALAMOUNT parameters from all CART items must be equal to the amount indicated in the parameter AMOUNT, or in the case of a ntimes payment, must be equal to the sum of the amounts indicated in the AMOUNTS parameter.

tip

Shipping costs or any other charges, can be added as a new CART.

Practical case

PARAMETERS MERCHANTITEMID NAME PRICE DISCOUNT TAX QUANTITY TOTALAMOUNT SUBMERCHANTEXTERNALID
CART[0] REF-123456 laser printer 50000 0 5 1 50000 OPERATOR
CART[1] REF-234567 printer toner 15000 15 5 2 30000 OPERATOR
CART[2] REF-345678 paper ream 300 0 10 5 3000 myShop1.com
CART[2] REF-456789 tee-shirt 1500 0 10 3 4500 myShop2.com

HTML format

<form method="post" action="https://secure-test.be2bill.com/front/form/process">
    <!-- 1000 => EUR 10 -->
    <input type="hidden" name="AMOUNT" value="1000" />
    <input type="hidden" name="CLIENTIDENT" value="john.snow" />
    <input type="hidden" name="IDENTIFIER" value="YOUR_IDENTIFIER" />
    <input type="hidden" name="OPERATIONTYPE" value="authorization" />
    <input type="hidden" name="ORDERID" value="1234" />
    <input type="hidden" name="VERSION" value="3.0" />
    <!-- Generated hash -->
    <input type="hidden" name="HASH" value="15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" />
    <input type="hidden" name="CART[0][MERCHANTITEMID]" value="REF-123456" />
    <input type="hidden" name="CART[0][NAME]" value="laser printer" />
    <input type="hidden" name="CART[0][PRICE]" value="50000" />
    <input type="hidden" name="CART[0][DISCOUNT]" value="0" />
    <input type="hidden" name="CART[0][TAX]" value="5" />
    <input type="hidden" name="CART[0][QUANTITY]" value="1" />
    <input type="hidden" name="CART[0][TOTALAMOUNT]" value="50000" />
    <input type="hidden" name="CART[0][SUBMERCHANTEXTERNALID]" value="OPERATOR" />
    <input type="hidden" name="CART[1][MERCHANTITEMID]" value="REF-234567" />
    <input type="hidden" name="CART[1][NAME]" value="printer toner" />
    <input type="hidden" name="CART[1][PRICE]" value="15000" />
    <input type="hidden" name="CART[1][DISCOUNT]" value="15" />
    <input type="hidden" name="CART[1][TAX]" value="5" />
    <input type="hidden" name="CART[1][QUANTITY]" value="2" />
    <input type="hidden" name="CART[1][TOTALAMOUNT]" value="30000" />
    <input type="hidden" name="CART[1][SUBMERCHANTEXTERNALID]" value="OPERATOR" />
    <input type="hidden" name="CART[2][MERCHANTITEMID]" value="REF-345678" />
    <input type="hidden" name="CART[2][NAME]" value="paper ream" />
    <input type="hidden" name="CART[2][PRICE]" value="300" />
    <input type="hidden" name="CART[2][DISCOUNT]" value="0" />
    <input type="hidden" name="CART[2][TAX]" value="5" />
    <input type="hidden" name="CART[2][QUANTITY]" value="10" />
    <input type="hidden" name="CART[2][TOTALAMOUNT]" value="3000" />
    <input type="hidden" name="CART[2][SUBMERCHANTEXTERNALID]" value="myshop1.com" />
    <input type="hidden" name="CART[3][MERCHANTITEMID]" value="REF-456789" />
    <input type="hidden" name="CART[3][NAME]" value="tee-shirt" />
    <input type="hidden" name="CART[3][PRICE]" value="1500" />
    <input type="hidden" name="CART[3][DISCOUNT]" value="0" />
    <input type="hidden" name="CART[3][TAX]" value="5" />
    <input type="hidden" name="CART[3][QUANTITY]" value="3" />
    <input type="hidden" name="CART[3][TOTALAMOUNT]" value="4500" />
    <input type="hidden" name="CART[3][SUBMERCHANTEXTERNALID]" value="myshop2.com" />
</form>

Integration modes

Depending on the account type, the Marketplace integration mode will differ.

Multi-capture

This integration mode consists in sending an authorization for the whole order, then sending a capture per sub-merchant.

The amount of the capture will be the total amount owed to the submerchant, thus the sum of the submerchant’s carts amounts have to be calculated.

Payment process
  1. A customer places an order on the online store;
  2. The Marketplace proceeds an authorization for the entire cart;
  3. The Marketplace captures the amount sold by its own store;
  4. Once the order has been validated by a submerchant, the Marketplace captures the validated orders.
reminder

The various captures can take place at different dates, providing that they do not exceed a 7-day delay.

Notifications and redirection

The Be2bill platform sends a notification per capture.

Multi-authorization

This integration mode consists in sending a single authorization for the whole order.

The Be2bill platform automatically divides it into as many authorizations as submerchants concerned by the initial request.

Payment process
  1. A customer places an order on the online store
  2. The Marketplace sends an authorization request for the whole cart
  3. The Be2bill platform groups all the transactions related to a merchant and calculates the total amount owed to it.
  4. The Marketplace captures the amount sold by its own store
  5. Once the order has been validated by a submerchant, the Marketplace sends the capture

In the above example, 2 carts are ordered to the same submerchant, in this case directly to the Marketplace operator.

CARTS MERCHANTITEMID NAME PRICE DISCOUNT TAX QUANTITY TOTALAMOUNT SUBMERCHANTEXTERNALID
CART[0] REF-123456 laser printer 50000 0 5 1 50000 OPERATOR
CART[1] REF-234567 printer toner 15000 15 5 2 30000 OPERATOR
CART[2] REF-345678 paper ream 300 15 5 10 3000 myshop1.com
CART[3] REF-456789 tee-shirt 1500 15 5 3 4500 myshop2.com

The Be2bill platform aggregates both carts’ total amounts to generate a single transaction for this merchant.

OPERATIONTYPE AMOUNT ORDERID
authorization 80000 (50000 + 30000) 20170412_58ee3c403c973_OPERATOR
authorization 3000 20170412_58ee3c403c973_B123
authorization 4500 20170412_58ee3c403c973_B789
Notifications and redirection

The Be2bill platform sends a notification per authorization (thus per submerchant).

The sent back AMOUNT corresponds to the sum of all TOTALAMOUNTs fields of all items ordered by this submerchant.

Suffixed ORDERID

The ORDERID is generated from the one sent by the Marketplace in the initial authorization request.

The corresponding submerchant’s SUBMERCHANTEXTERNALID is added as a suffix to this ORDERID.

In case a cart belongs to the Marketplace operator itself, the SUBMERCHANTEXTERNALID is replaced by the mention OPERATOR.

Example
SUBMERCHANTEXTERNALID ORDERID
A789 20170412_58ee3c403c973_A789
B123 20170412_58ee3c403c973_B123
OPERATOR 20170412_58ee3c403c973_OPERATOR

Payment and refunds

This integration mode consists in processing a payment for the whole order, and issuing potential refunds in case the whole order or part of it cannot be fulfilled.

Notifications and redirection

The Be2bill platform sends a notification for the payment of the whole order and a notification per possible refund.

Captures and refunds

Each capture or refund operation must indicate the concerned submerchant by including the SUBMERCHANTEXTERNALID parameter.

$> curl --request POST --url "https://secure-test.be2bill.com/front/service/rest/process" \
--data "method=capture" \
--data "params[IDENTIFIER]=YOUR_IDENTIFIER" \
--data "params[OPERATIONTYPE]=capture" \
--data "params[TRANSACTIONID]=A1123456" \
--data "params[ORDERID]=1234" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[VERSION]=3.0" \
--data "params[SUBMERCHANTEXTERNALID]=shop1.com" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \

Onboarding your sub-merchants

You can onboard your marketplace shops by using the submerchant marketplace API. You can see the details of this REST API here.

  • First you should upload all the required documents by using the documents resource
  • Then you create the sub-merchant with the submerchants resource. Don’t forget to link all previously uploaded documents.
  • Once your sub-merchant is completely filled you can request a validation by our services with the request_validation resource.
  • You’ll receive a notification depending on the validation status of your request.

Managing your financial balance

Our marketplace API allows you to manage your financial balance.

warning

Your financial balance shall always be positive, for all your sub-merchants.

The API provide these resources to manage your balances:

  • clients/balances to retrieve your actual financial balance.
  • cashouts to ask a cashout order for your own shop (scope = operator) or one of your sub-merchant (scope = submerchant).
  • cashins to register an increase in your financial balance. For example if you process other payment methods with another payment service provider.
  • operator_fees to declare the fees you applied on your sub-merchants.