Partial Captures

Saferpay does offer the option to do Partial Captures (Hereafter refered to as Multipart Captures) on transactions, made with certain payment methods. Multipart Captures split the money authorized during one transactions into multiple batches, enabling the merchant to only capture the amount he wants to obtain e.g. for deliviering a part of a certain order.

1. Multipart Captures are available for SIX Mastercard/Maestro, Visa Acquiring contracts, PayPal and Klarna Payments only!
2. No MultipartCapture request should be sent before receiving the response of a preceeding request (i.e. no parallel calls are allowed). The timeout for this are 100 seconds.
3. The sum of multipart captures must not exceed the authorized amount.
4. A unique OrderPartId must be used for each request.
5. Multipart Captures execute the money-flow (closing) with the execution of the capture itself! A Cancel of a Multipart Capture therefore is not possible!
6. MultipartCapture is only available for SpecVersions 1.10 and higher!

Before you can even execute a Multipart Capture, you, of course, need a transaction, that needs to be captured. This can be any normal authorization, either done by the Payment Page, or Transaction Interface. You don't have to consider anything special, up to this point!

Additionally to the standard parameters, needed to execute a Capture, the following parameters are important for a Multipart Capture:

• Type: The Type specifies, whether this is one subsequent, or final Capture.
• OrderPartId: Each Multipart Capture is identified by a unique OrderPartId, which will also be forwarded to the respective reconciliation-files you will recieve later. That makes this Id very important for later identification, thus you have to make sure, that said Id is set as unique, so confusions can be averted.

A complete request 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",
    "OrderPartId": "123456789"
}

The response may look like this:

{
    "ResponseHeader": {
        "SpecVersion": "1.10",
        "RequestId": "[unique request identifier]"
    },
    "CaptureId": "723n4MAjMdhjSAhAKEUdA8jtl9jb_c",
    "Status": "CAPTURED",
    "Date": "2018-08-08T12:45:22.258+01:00"
}

Each capture is identified by a CaptureId (Marked with the suffix "_c") , which should be saved, since this Id is used for further actions, like refunds. More on the latter later in this very chapter.

After a transaction has been captured to the merchants liking using Multipart Capture, it should be finalized, in order to seclude the transaction. There are two different ways to finalize a Multipart Capture. Each covering one specific case, that should be differentiated, by asking one specific question:

Does the merchant intend to capture a final amount, or not?

In order to capture a final amount, the merchant-system simply needs to execute Multipart Capture, whilst setting the parameter Type to "FINAL". A full 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": "FINAL",
   "OrderPartId": "123456790"
}

In order to avoid confusion and merchants accidently executing the wrong request, the finalization with amount 0 is done through a completely different request called Multipart Finalize. Executing this request will close the transaction without transfering any money.

There are two reasons, why you, the merchant, should finalize a transactions, once you have finished all your actions:

1. It is the cleaner process! Four you, the merchant, this is the cleaner solution and helps keeping track of every transaction and its status, not just inside your own system, but also inside the Saferpay Backoffice, where still open and closed transactions, will be marked as such!
2. It means less hassle for your customers. Each time you successfully authorize a credit card, the authorized amount gets reserved on the card holders credit limit. That effectively means, that he/she cannot use this money, as long as you haven't claimed the money, or the reservation voids, after a certain time-frame. A finalization will open up the credit-limit for the card holder, so he/she may use it again, which is especially important in situations, where the merchant does not want, or can't claim all of the money originally authorized!

Since Multipart Captures basically split an existing transaction into multiple parts, refunds also need to be processed in a different way. Unlike normal Refunds, you now need to reference each Capture you want to refund individually!

To do so, you have to reference the CaptureId from the Multipart Capture Response, you want to refund. Remember, that all CaptureIds have the suffix _c for that reason.

A Refund request may look like this then:

{
  "RequestHeader": {
    "SpecVersion": "1.10",
    "CustomerId": "[your customer id]",
    "RequestId": "[your request id]",
    "RetryIndicator": 0
  },
  "Refund": {
    "Amount": {
      "Value": 100,
      "CurrencyCode": "CHF"
    }
  },
  "CaptureReference": {
    "CaptureId": "723n4MAjMdhjSAhAKEUdA8jtl9jb_c"
  }
}