# Partial Captures Saferpay does offer the option to do [Partial Captures (Hereafter referred to as Multipart Captures)](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture) on transactions, made with certain payment methods. [Multipart Captures](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture) split the money authorized during one transaction into multiple batches, enabling the merchant to only capture the amount he wants to obtain, e.g. for delivering a part of a certain order. ## Requirements 1. [Multipart Captures](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture) are only available for * **Worldline** [Mastercard](https://docs.saferpay.com/home/integration-guide/payment-methods/mastercard)/[Maestro](https://docs.saferpay.com/home/integration-guide/payment-methods/maestro) * **Worldline** [Visa/V PAY](https://docs.saferpay.com/home/integration-guide/payment-methods/visa-and-vpay) * [American Express](https://docs.saferpay.com/home/integration-guide/payment-methods/american-express) **-Only for certain Amex providers! Please contact your sales contact!-** * [Diners/Discover](https://docs.saferpay.com/home/integration-guide/payment-methods/diners-and-discover) * [JCB](https://docs.saferpay.com/home/integration-guide/payment-methods/jcb) * [PayPal](https://docs.saferpay.com/home/integration-guide/payment-methods/paypal) * [Klarna Payments](https://docs.saferpay.com/home/integration-guide/payment-methods/klarna-payments) 2. No MultipartCapture request should be sent before receiving the response of a preceding request (i.e. no parallel calls are allowed). The timeout for this are 100 seconds. 3. The total amount of all executed multipart captures must not exceed the authorized amount of the initial transaction. 4. A unique **`OrderPartId`** must be used for each request. 5. [MultipartCapture](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture) is only available for **SpecVersions 1.10 and higher!** {% hint style="warning" %} Note, that you cannot mix the [Multipart Capture](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture) and the [Normal Capture](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_Capture) within one transaction. Either do one, or the other! {% endhint %} ## Executing a Multipart Capture Before you can even execute a [Multipart Capture](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture), you, of course, need a transaction, that needs to be captured. This can be any normal authorization, either done by the [Payment Page](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/payment-page), or [Transaction Interface](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface). You don't have to consider anything special, up to this point! Additionally, to the standard parameters needed to execute a [Capture](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_Capture), the following parameters are important for a [Multipart Capture](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture): * **Type:** The **Type** specifies, whether this is one of many subsequent, or the final Capture. * **OrderPartId:** Each [Multipart Capture](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture) is identified by a unique **OrderPartId**, which will also be forwarded to the respective reconciliation-files you will receive 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. {% tabs %} {% tab title="Request" %} ```json { "RequestHeader": { "SpecVersion": "[CURRENT_SPEC_VERSION]", "CustomerId": "[your customer id]", "RequestId": "[unique request identifier]", "RetryIndicator": 0 }, "TransactionReference": { "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb" }, "Amount": { "Value": 1000, "CurrencyCode": "CHF" }, "Type": "PARTIAL", "OrderPartId": "123456789" } ``` {% endtab %} {% tab title="Response" %} ```json { "ResponseHeader": { "SpecVersion": "[CURRENT_SPEC_VERSION]", "RequestId": "[unique request identifier]" }, "CaptureId": "723n4MAjMdhjSAhAKEUdA8jtl9jb_c", "Status": "CAPTURED", "Date": "2018-08-08T12:45:22.258+01:00" } ``` {% endtab %} {% endtabs %} 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](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface/refunds). More on the latter later in this very chapter. {% hint style="info" %} The basic reservation times [mentioned here](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/capture-and-daily-closing/..#revervation-times) do still apply for [Multipart Captures!](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture) If this time is exceeded, the reservation could void and the money flow will be rejected by the card holders bank! {% endhint %} {% hint style="info" %} The overall amount you submit is not checked on the test-environment, as it is rejected by the processor/acquirer! So it is indeed possible to capture more, than authorized! {% endhint %} ## Finalizing a Capture-Chain After a transaction has been captured to the merchant's liking using [Multipart Capture](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture), it should be finalized, in order to seclude the transaction. There are two different ways to finalize a [Multipart Capture](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture). 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?** {% hint style="warning" %} Once finalized, a transaction cannot be opened again. Make sure, that you really want to finalize the transaction. Other captures won't be possible! {% endhint %} ### Finalizing, while also capturing a certain amount {% hint style="warning" %} Like mentioned previously, make sure to not exceed the initially authorized amount, or the capture will fail! {% endhint %} In order to capture a final amount, the merchant-system simply needs to execute [Multipart Capture](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture), whilst setting the parameter **Type** to **"FINAL"**. A full request then may look like this: ```json { "RequestHeader": { "SpecVersion": "[CURRENT_SPEC_VERSION]", "CustomerId": "[your customer id]", "RequestId": "[unique request identifier]", "RetryIndicator": 0 }, "TransactionReference": { "TransactionId": "723n4MAjMdhjSAhAKEUdA8jtl9jb" }, "Amount": { "Value": 1000, "CurrencyCode": "CHF" }, "Type": "FINAL", "OrderPartId": "123456790" } ``` ### Finalizing without capturing/ Capturing with amount 0 In order to avoid confusion and merchants accidentally executing the wrong request, the finalization with amount 0 is done through a completely different request called [Multipart Finalize](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartFinalize). Executing this request will close the transaction without transferring any money. {% hint style="warning" %} Finalize may only be executed, if the remaining amount is greater, than 0! If you use a normal Multipart Capture to capture the whole transaction amount, please make sure, that the last partial capture is marked as **`"Type": "FINAL"`**. Executing a Multipart Finalize on such a transaction will lead to an error. {% endhint %} ### Why do you need to finalize a transaction? There are two reasons, why you, the merchant, should finalize a transaction, once you have finished all your actions: 1. It is the cleaner process. For 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 cardholders 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 cardholder, so he/she may use it again, which is especially important in situations, where the merchant does not want, or can't claim all the money originally authorized! ## Handling Refunds Since [Multipart Captures](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture) basically split an existing transaction into multiple parts, [refunds](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface/refunds) also need to be processed differently. 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](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture), you want to refund. Remember, that all **CaptureId**s have the suffix **\_c** for that reason. A [Refund request](https://docs.saferpay.com/home/integration-guide/transaction-interface/refunds#method-1-referenced-refunds) may look like this then: ```json { "RequestHeader": { "SpecVersion": "[CURRENT_SPEC_VERSION]", "CustomerId": "[your customer id]", "RequestId": "[your request id]", "RetryIndicator": 0 }, "Refund": { "Amount": { "Value": 100, "CurrencyCode": "CHF" } }, "CaptureReference": { "CaptureId": "723n4MAjMdhjSAhAKEUdA8jtl9jb_c" } } ``` {% hint style="warning" %} Like every other [Refund](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface/refunds), these too need to be captured. However **please make sure to use the** [**normal Capture request**](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_Capture) **in this case and NOT MultipartCapture!** Refunds cannot be split into multiple parts, like authorizations! {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/capture-and-daily-closing/partial-captures.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.