psp-api-intermerchant

The API offers support for executing an API request on behalf of another merchant account. An example use case is facilitating a marketplace, where each seller is managed by the marketplace itself and it provides the payments integration. In this case, the seller is the subject merchant for which API requests are executed, whereas the market place is the executing merchant that actually performs the API requests.

A merchant account is identified based on the merchant key that is provided as part of the URL.
When creating an order on behalf of another merchant, the authentication header is checked (as executing merchant) with the merchant key to validate that the executing merchant is allowed to perform the operation for the merchant specified in the URL.

Create Order on behalf of another merchant

To create an order on behalf of another merchant, the following details are required.

• Account name and password: This is the account name and password of the executing merchant account that is used to authenticate a call on behalf of another merchant. Refer to the Authentication section for more information.
• Merchant key: The key of the subject merchant account for which the order is created and is provided as part of the Order Api resource URL. The Order Api and Merchant key details can be found in the Order API section.
• Subject merchant token: The merchant token of the subject merchant for which the order is created. The subject merchant token is provided as a value in the HTTP header. The subject merchant is the callee and the subject merchant must given consent to the API caller to create an order on behalf of the subject merchant.
• Subject merchant fees: The fees that the subject merchant has to pay for the order.

Executing Merchant and Subject Merchant contract

• The executing merchant and the subject merchant must be part of the same holding account.
• The subject merchant token must be shared between both accounts.
• The subject merchant token is managed by the subject merchant. They will need to contact support as additional permissions need to be set.

Request HTTP Headers

The following headers are required for the request:

• Authorization: Basic Authentication header with base64 encoded account name and password (separated by a colon). Refer to the Authentication section for more information.
• X-CMP-SubjectMerchantToken: The subject merchant token contains the agreed upon security token, added as a value in the HTTP header. This is a mandatory value to create an order on behalf of another merchant.
• X-CMP-SubjectMerchantFee: The subject merchant fees, passed in the header in base64 encoded format where the whole data is in JSON. This is an optional value.

Subject merchant fees details

An example subject merchant fees, is shown below:

{
  "description": "description of the fee",
  "moment": "IMMEDIATE",
  "fee_amount": {
    "currency": "EUR",
    "amount": 120
  }
}

and before adding the merchant fee data to the header, it should be base64 encoded. The base64 encoded value for the above JSON data is:

ewogICJkZXNjcmlwdGlvbiI6ICJkZXNjcmlwdGlvbiBvZiB0aGUgZmVlIiwKICAibW9tZW50IjogIklNTUVESUFURSIsCiAgImZlZV9hbW91bnQiOiB7CiAgICAiY3VycmVuY3kiOiAiRVVSIiwKICAgICJhbW91bnQiOiAxMjAKICB9Cn0=

Subject merchant fee request details

Subject merchant fee moment details

Subject merchant token details

Please contact the support team to get the subject merchant token for the API caller merchant.

Restrictions

The subject merchant account should give consent to the API caller merchant to create an order on behalf of subject merchant. The permission is granted by the support team. A subject merchant can give access to multiple API caller merchants.
The subject merchant fee and token are applicable only for the creation of payment orders.

Example Request

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic dGVzdHNob3BfaW50ZXJtZXJjaGFudDp3ZHNZRkZRTA==' \
    --header 'X-CMP-SubjectMerchantToken: 3900ee33-de0e-422b-a9d6-e57022221232' \
    --header 'X-CMP-SubjectMerchantFee: ewogICJkZXNjcmlwdGlvbiI6ICJkZXNjcmlwdGlvbiBvZiB0aGUgZmVlIiwKICAibW9tZW50IjogIklNTUVESUFURSIsCiAgImZlZV9hbW91bnQiOiB7CiAgICAiY3VycmVuY3kiOiAiRVVSIiwKICAgICJhbW91bnQiOiAxMjAKICB9Cn0=' \
    https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders \
    -d '{
        "order_reference"   : "vk20170224p",
        "description"   : "Order 12345",
        "amount"        : 3330,
        "currency"      : "EUR",
        "email"         : "johan.devries@cm.com",
        "language"      : "nl",
        "country"       : "BE"
    }'
 
< Http 201 Created
<    '{
        "order_key" : "F1499C097FFA533D46FB05D52680AB9A",
        "expires_on" : "2020-01-31T19:00:12Z",
        "url"   : "https://testsecure.docdatapayments.com/ps/menu?command=show_payment_cluster&amp;merchant_name=testshop&amp;payment_cluster_key=F1499C097FFA533D46FB05D52680AB9A"
    }'

This example demonstrates how to create an order on behalf of another merchant by including the merchant-key parameter as part of the URL. The merchant-key parameter is the merchant account of the merchant for which the order is created.