Multi-capture


Currently, multi-capture needs to be activated on your account before it can be used, which can be done by contacting the Support team. This new feature will be fully rolled out to all clients on 25 June 2021, permanently changing the behaviour of the PaymentStatus parameter of the PreAuthorization object to the values described below.

Please note: depending on your integration, the changes being made to the PaymentStatus parameter may result in a breaking change for you. For example, PaymentStatus : WAITING is changing its signification, from indicating that a single capture has not yet been made to indicating that partial captures can still be made (and may have already been made).

Please read the explanation below to determine if and how this change will impact you, and please ensure that you make any modifications to your integration to account for this change before 25 June 2021.



Introduction


The multi-capture functionality allows you to make partial captures (acquisitions) of pre-authorized funds. In a pre-authorization, a specified amount is held on a registered card for a limited period (the pre-authorization period), in our case up to seven days. With multi-capture, you can make partial captures or a full capture of the remaining pre-authorized funds during this period. Captures against a PreAuthorization are made using Card PreAuthorized PayIns and this feature only applies to the payment method CB/Visa/Mastercard.


The PreAuthorization object with multi-capture


Included in the PreAuthorization object is the boolean parameter MultiCapture which if true, signifies that the feature is active.
It will be possible to understand if further captures can be made against a PreAuthorization by using the PaymentStatus, RemainingFunds and DebitedFunds parameters.


Payment status


Multi-capture changes the logic of the PaymentStatus parameter to the following values:


WAITING : This status indicates that the pre-authorization has been created and one full capture or several partial captures can be made using Card PreAuthorized PayIns, as long as there are pre-authorized funds remaining and the pre-authorization period has not elapsed. The PaymentStatus will remain as WAITING as long as further Card PreAuthorized PayIns are possible.


VALIDATED :

This status corresponds to the following :

  • All the pre-authorized funds have been captured within the pre-authorization period – there are no remaining funds
  • The pre-authorization period has elapsed and the pre-authorized funds have been totally or partially captured

It is not possible to carry out a Card PreAuthorized PayIn on a PreAuthorization when the PaymentStatus is VALIDATED.

Where at least one partial capture has been made, this status can be manually set to close the pre-authorization and release the remaining funds. However, where no captures have been made this action will result in an error: in that case, the pre-authorization must either be captured, canceled, or left to expire.


CANCELED : This status indicates that the pre-authorization has been manually canceled before any Card PreAuthorized PayIns were made, or that the pre-authorization has failed.

EXPIRED : This status indicates that the pre-authorization period has elapsed and no Card PreAuthorized PayIns were made.


RemainingFunds and DebitedFunds


The parameter DebitedFunds, defined when creating the PreAuthorization, corresponds to the total pre-authorized funds. The parameter RemainingFunds indicates the pre-authorized funds remaining.

After every successful Card PreAuthorized PayIn the RemainingFunds parameter is updated, being equal to the previous total minus the funds captured. If a PreAuthorization has the PaymentStatus VALIDATED, CANCELED or EXPIRED, the RemainingFunds parameter is zero.


Workflow


  1. A PreAuthorization is created

  2. A series of Card PreAuthorized PayIn are made against the PreAuthorization. The RemainingFunds parameter will update after each capture to show the remaining total of the pre-authorized funds.

  3. The pre-authorized funds are released

  • If one or more captures have been made, the pre-authorization must be validated, either automatically (by reaching the pre-authorized limit in captures) or manually (where the limit has not been reached).
  • If no captures have been made, the pre-authorization must be canceled manually or it will expire (that is, cancel automatically) after the pre-authorization period is over.


For more information on how to validate or cancel the pre-authorization, please see here.


Example


  1. A Buyer selects CB/Visa/Mastercard as the payment method to purchase three items, one from Vendor 1, one from Vendor 2 and one from Vendor 3, on a commercial marketplace operated by a Platform.
  2. This basket is treated as one order by the Platform, who pre-authorizes the total order amount on the Buyer’s registered card. These funds will be held for seven days.
  3. Vendors 1 and 2 confirm and ship the items ordered, while Vendor 3 has not. The Platform carries out two Card PreAuthorized PayIns for each item from Vendors 1 and 2.
  4. Vendor 3 declines the order and the Platform does not capture the corresponding funds in the pre-authorization.
  5. The Vendor closes the PreAuthorization (by changing the status to VALIDATED) and the Buyer is only billed for the items shipped.
  6. The Buyer then requests a refund for the item sold by Vendor 1.
  7. The Platform does a Refund call referencing only the Card PreAuthorized PayIn for the item sold by Vendor 1.


As the example above demonstrates, the multi-capture feature allows payment flows to be operated more efficiently than in a scenario without multi-capture, where the entire order total would have been captured by the Platform.


Considerations


Capturing Funds


Full or partial captures are made using the Card PreAuthorized PayIn object. There is no limit to the number of Card PreAuthorized PayIns that can be made on a PreAuthorization, if each of these is valid.


Idempotency


For multi-capture, an Idempotency Key must be used for each Card PreAuthorized PayIn to protect against duplicate transactions. Unless accompanied by an Idempotency Key, two pay-ins are considered as duplicate when they meet the following criteria:

  • Made within 24 hours
  • Same amount and currency
  • Same CardId

Please refer to the following : https://docs.mangopay.com/guide/idempotency-support


Listing transactions for a pre-authorization


The endpoint List a PreAuthorization's Transactions can be used to list all the relevant captures made against a PreAuthorization, including failed captures.


Ending a pre-authorization


A successfully created PreAuthorization will show the PaymentStatus parameter as WAITING. This status is required to be able to close the pre-authorization, and a closed pre-authorization cannot be reopened. Ending the pre-authorization will remove the possibility of future captures and release the funds held. There are three ways for a pre-authorization to end:

  • Validation
  • Cancellation
  • Expiry


Validation can only occur when at least one successful capture has been made. Cancellation and expiry indicate that no successful captures have been made.


Validating a pre-authorization


Where at least one capture has been made against a pre-authorization and there are pre-authorized funds remaining, the PreAuthorization can be closed by manually changing the PaymentStatus to VALIDATED. If at least one successful capture has been made, the status will change to VALIDATED automatically once the pre-authorization period has elapsed.

To validate a PreAuthorization, please make a PUT call specifying the PaymentStatus field as VALIDATED:

{
"PaymentStatus": "VALIDATED",
}

Please note: using this call on a PreAuthorization where no captures have been made will generate an error. If no captures will be made, please cancel the pre-authorization.

Cancelling a pre-authorization


Where no captures have been made or will be made against a pre-authorization, the PreAuthorization can be canceled manually or it will expire (automatically cancel) once the pre-authorization period has elapsed. A canceled pre-authorization cannot be reused.

To cancel a PreAuthorization, please make a PUT call specifying the PaymentStatus field as CANCELED.

{
"PaymentStatus": "CANCELED",
}

Please note: using this call against a PreAuthorization with at least one capture will generate an error and the PreAuthorization will not be closed.


Expiry of a pre-authorization


Pre-authorizations ensure the solvency of funds for a set period of time, in our case seven days. When this period has elapsed, the pre-authorization will close, either as a validation or expiry. The PaymentStatus will become VALIDATED if at least one capture has been made within seven days. If no captures have been made, the PaymentStatus will become EXPIRED. No further Card PreAuthorized PayIns can be made where the PaymentStatus is VALIDATED, CANCELED or EXPIRED.

Live chat
No agent is free at the moment please send us a request through our contact form