Marketplace

• Payment processing
  • Cart handling through the CART parameter
  • Integration modes
• Onboarding your submerchants
• Managing your financial flows

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.

warning

CART sub-parameters must be sorted alphabetically before hash computation. Please refer to Hash generation.

CART management sub-parameter

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

HTML format

<form method="post" action="https://secure-test.dalenys.com/front/form/process">
    <input type="hidden" name="AMOUNT" value="" />
    <input type="hidden" name="CLIENTIDENT" value="" />
    <input type="hidden" name="IDENTIFIER" value="" />
    <input type="hidden" name="OPERATIONTYPE" value="authorization" />
    <input type="hidden" name="ORDERID" value="" />
    <input type="hidden" name="VERSION" value="" />
    <input type="hidden" name="HASH" value="" />
    <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][FEES]" value="1000" />
    <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][FEES]" value="1500" />
    <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][FEES]" value="500" />
    <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][FEES]" value="2500" />
    <input type="hidden" name="CART[3][TOTALAMOUNT]" value="4500" />
    <input type="hidden" name="CART[3][SUBMERCHANTEXTERNALID]" value="myshop2.com" />
    <input type="submit" value="Pay" />
</form>

Integration modes

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

• CB/VISA/MasterCard accounts concerning businesses exclusively based on the French territory can use the Multi-capture or Multi-authorization modes;
• American Express and Bancontact accounts can use the Multi-capture or Multi-authorization modes;
• All other accounts must use the Payment / Refunds mode.

warning

Keep in mind that it is not allowed to launch multiple editing transactions at the same moment (concurrent accesses), (such as refunds or captures…) on the same initial transaction. This would result in a refusal to process these operations and an EXECCODE = 2017

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 Dalenys platform sends a notification per capture.

Multi-authorization

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

The Dalenys 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 Dalenys 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.

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

Notifications and redirection

The Dalenys 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

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 Dalenys 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. The field FEES shall be also sent if specified in the authorization

Each capture or refund operation must indicate the concerned submerchant by including the MERCHANTITEMID parameter. The field FEES shall be also sent if specified in the authorization

$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/process" \
--data "method=capture" \
--data "params[IDENTIFIER]=Demo Shop" \
--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 submerchants

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

Steps:

• First create your submerchants by using the submerchants resource
• Secondly you can create a bank account for it by using the bank accounts resource
• Then you can submit a KYC request
• Once your KYC is validated, you’ll receive a notification with the validation status

Old REST API here.

Managing your financial flows

Our marketplace API allows you to manage your financial flows.

warning

Your financial balance shall always be positive, for all your submerchants.

The API provide these resources to manage your balances:

• payouts to ask a payout order for you (scope = operator) or one of your submerchant (scope = submerchants).
• transfers to do a transfer between to eWallets from you to one for your submerchant or between two of your submerchants or from one of your submerchant to you