Marketplace

Introduction

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

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).

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]=" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \