Multi-capture

Introduction

A pre-authorization allows you to hold a specified amount on a user’s registered card for a defined period, in our case seven days. During this period, you can then capture the payment – that is, complete the transaction and acquire the pre-authorized funds. Alternatively, you can cancel the pre-authorization manually or let it expire, at which point it is canceled automatically.

MANGOPAY’s PreAuthorization object allows you to make one capture or multiple captures of the pre-authorized funds.

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.

Multi-capture is only possible with the payment method CB/Visa/Mastercard.


Scope

Multi-capture is a feature of the object PreAuthorization. Full or partial captures are made using the Card PreAuthorized PayIns 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.

Multi-capture is only possible with the payment method CB/Visa/Mastercard.


Parameters

It will be possible to understand if further captures can be made against a PreAuthorization by using the PaymentStatus, RemainingFunds and DebitedFunds parameters.

PaymentStatus

The parameter PaymentStatus can take 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 one of the following :

  • Within the pre-authorization period, all the pre-authorized funds have been captured – 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

IMAGE

  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


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

For more information, please refer to dempotency 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.

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