The Marketplace

In order to understand the Saferpay marketplace-solution, one must first grasp the concept of partial- or Multipart Captures, for they are the very foundation, on which the marketplace-solution is built upon. Please make sure, that you read the Multipart Captures Chapter first.

Requirements

  1. If you want to use the Submerchant and Fee-features, your live merchant-account needs to be configured, in order to support Multipart Captures, or the request will fail!

Important: As mentioned in the beginning, a special setup is necessary to acces the following features. Once this setup has been done, you will be unable to execute normal Captures (Exception being Refunds!) and Captures inside the Saferpay Backoffice won't be possible anymore! Please keep that in mind, during implementation!

Submerchants

IMPORTANT: Please read this chapter completely, INCLUDING the chapter about Applying Fees!

In some cases, a merchant, or marketplace-operator, needs to be able to split the authorized amounts do different contracts, bank accounts and/or submerchants. Saferpay does offer this option through Multipart Captures.

The general money-flow may look like this:

alt text

Now in order for this to work, the following requirements have to be met:

  1. Each Submerchant you want to cover, needs an acquiring-contract with SIX, so the money can be directly transfered to their bank-account! Make sure to specifically request these contracts for the marketplace-solution, since those need a special setup!
  2. Each submerchant will get their own Id (Sometimes also refered to as Contract-Number or VP-Number!), which has to be submitted with each Multipart Capture, to define the merchant, who is getting the money!

Executing a Multipart Capture with a Submerchant

A Multipart Capture request with a submerchant requires you, to correctly fill the Marketplace => SubmerchantId parameter, with the corresponding Id. A request then may look like this:

{
   "RequestHeader": {
     "SpecVersion": "1.10",
     "CustomerId": "[your customer id]",
     "RequestId": "[unique request identifier]",
     "RetryIndicator": 0
   },
   "TransactionReference": {
       "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb"
   },
   "Amount": {
       "Value": 1000,
       "CurrencyCode": "CHF"
   },
   "Type": "PARTIAL",
   "OderPartId": "123456789",
   "Marketplace": {
       "SubmerchantId": "17312345"
   }
}

This request will transfer 10 CHF to the merchant with the Id 17312345!

Applying Fees

IMPORTANT: If you are using the submerchant-feature, you must set either Fee or FeeRefund (Depending on the request!). If you do not intend on applying a fee, you musst still set it, with an amount set to 0!

Especially for marketplace providers, it is not unusual to charge a small fee for each transaction, that is handled through the marketplace, from the respective merchant. Saferpay also offers options to charge these fees, through Multipart Captures.

For that, it is necessary to correctly set the Marketplace => Fee container, within a Multipart Capture request, which may look like this then:

{
   "RequestHeader": {
     "SpecVersion": "1.10",
     "CustomerId": "[your customer id]",
     "RequestId": "[unique request identifier]",
     "RetryIndicator": 0
   },
   "TransactionReference": {
       "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb"
   },
   "Amount": {
       "Value": 1000,
       "CurrencyCode": "CHF"
   },
   "Type": "PARTIAL",
   "OrderPartId": "123456789",
   "Marketplace": {
       "SubmerchantId": "17312345",
       "Fee": {
           "Value": 100,
           "CurrencyCode": "CHF"
       }
   }
}

This request will transfer 10 CHF to the merchant account 17312345, but will also charge a 1 CHF for said transaction. So effectively the merchant will get 9 CHF transferred, not including the acquiring-costs, since that can vary from merchant to merchant and even contract!

Refund fees

But, what if you want to refund said transaction, including the transaction fee? For that, the Capture request also offers the option, to submit a fee, but note, that the container is named FeeRefund this time. A request then may look like this:

{
  "RequestHeader": {
    "SpecVersion": "[CURRENT SPEC_VERSION]",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "Amount": {
    "Value": 1000,
    "CurrencyCode": "CHF"
  },
  "CaptureReference": {
    "CaptureId": "723n4MAjMdhjSAhAKEUdA8jtl9jb_c"
  },
  "Marketplace": {
    "SubmerchantId": "17312345",
    "FeeRefund": {
      "Value": 100,
      "CurrencyCode": "CHF"
    }
  }
}

This request will capture a refund and transfer 10 CHF (Please keep track of this!) from the merchant account 17312345, to the card holder! The fee then will be taken from the marketplace and transfered to the submerchant. So the full amount will be refunded first from the submerchant-account and then they will recieve the fee back from the marketplace!

Back to Top