Skip to main content
Migo Docs

Pre-authorisation and capture

A normal charge moves the money in one go. The two-step flow splits it: first you hold funds on the card, then you decide whether to charge what you held β€” all of it or less β€” or to release the hold.

It fits when the final amount isn't known at purchase time: a consumption that gets adjusted, a security deposit, an order that may ship incomplete, or a validation you need to run before charging.

How it's enabled​

It doesn't change your integration. You keep calling the same payment endpoint you already use; what changes is that it holds instead of charging.

It's enabled through your merchant account configuration and Migo turns it on. It is not a field you send in the request. Coordinate it with your operations contact, specifying which processor and which merchant you want enabled.

Enabling it affects no one else

The configuration is per merchant and per processor. Turning it on for one account does not alter the behaviour of any other, and an account without the configuration keeps charging immediately, exactly as before.

The flow​

1 Β· Payment
β†’
AUTHORIZED
funds held, not yet charged
└─
2a Β· Capture
β†’
APPROVED
charged (full amount or less)
└─
2b Β· Cancel
β†’
CANCELLED
hold released

2a and 2b are mutually exclusive. A hold ends up either captured or cancelled, never both: once you have captured, cancelling answers 4014.

By default a hold allows a single capture. If your account has multiple capture enabled, you can charge it in parts β€” several successive captures β€” up to the amount held. It is enabled the same way as the two-step flow itself: through your account configuration, not through a field in the request.

Its availability depends on your account's processor, so ask us before you build on it. When your account does not have it enabled, a second capture on the same hold answers 4011.

The transaction stays in AUTHORIZED until you send a valid request or its capture window expires. No automatic process charges it.

The Capture Window​

A hold has a capture window that starts when the transaction is created. It is 24 hours by default and can be adjusted per account when we enable the flow.

When the window expires without a capture, Migo releases the hold for you: it asks the processor to free the funds and, once the processor confirms, the transaction moves to CANCELLED and you get the same cancelled notification as when you cancel it yourself. The release runs in periodic passes, so it can happen a few hours after the window expires: do not count on being able to capture after the window.

If the processor does not confirm the release, the transaction stays in AUTHORIZED but can no longer be captured or cancelled, and the cardholder's funds stay reserved until their issuer releases them on its own. That is why you should always capture or cancel within the window instead of waiting for the automatic release.

Endpoints​

MethodPathWhat it does
POST/pay/capture/{trxUid}Charges the hold, in full or for a lower amount
POST/pay/cancel/{trxUid}Releases the hold

They authenticate with your merchant token in the Authorization header, like the rest of the API.

EnvironmentHost
Sandboxhttps://sb-mw.migopayments.com
Productionhttps://mw.migopayments.com

Full schema detail lives in the interactive reference.

Capture​

The amount goes in the totalCapture field of the body, and it is required.

curl -X POST https://sb-mw.migopayments.com/pay/capture/<trx-uid> \
-H 'Content-Type: application/json' \
-H 'Authorization: <merchant-token>' \
-d '{ "totalCapture": 60.00 }'
Response
{
"transaction": {
"uid": "<trx-uid>",
"status": "approved",
"total": 100.00,
"totalCapture": 60.00
}
}

Amount rules:

  • It must be greater than zero.
  • It must be less than or equal to the uncaptured balance: the amount held minus what you have already captured.
  • Outside that range it is rejected with code 2003, and the request never reaches the processor.
  • If you omit the field, the response is code 5000.

What was actually charged lands in totalCapture on the transaction β€” accumulated, if you captured in parts β€” and that is what the receipt and the transaction information reflect. With a single capture, if you charged 60 of a 100 hold the charge is 60 and the remainder is not left pending.

A capture that did not get a response must not be repeated without first checking the transaction state. If it ended in approved with the totalCapture you expected, the charge went through even though the response never arrived.

Serialise the captures of a given hold: two simultaneous requests can both reach the processor.

Capturing in parts​

With multiple capture enabled, each call charges an increment and the transaction accumulates:

curl -X POST https://sb-mw.migopayments.com/pay/capture/<trx-uid> \
-H 'Content-Type: application/json' \
-H 'Authorization: <merchant-token>' \
-d '{ "totalCapture": 30 }'

On a hold of 100, three calls of 30, 30 and 40 leave the transaction at totalCapture 100. Any call that exceeds the uncaptured balance is rejected with 2003 and never reaches the processor.

The transaction moves to approved on the very first capture, and from then on it can no longer be cancelled: whatever you do not capture is simply not charged.

Cancel​

curl -X POST https://sb-mw.migopayments.com/pay/cancel/<trx-uid> \
-H 'Authorization: <merchant-token>'

It releases the hold and the transaction ends in CANCELLED. A transaction that was already captured is not cancelled through this route: it responds 4014.

To undo a charge that already happened, use the voids and refunds flow, which is a different route and not the cancellation one. Two things worth knowing before you promise anything to the cardholder: undoing the charge of a hold is not the same as releasing a hold that was never charged, and depending on the rail there may be a time limit β€” sometimes the same day β€” for undoing it. Confirm with us what applies to your processor.

States​

StateMeansWhat you can do
AUTHORIZEDFunds held, not yet chargedCapture or cancel
APPROVEDCharged, in full or in partVoid or refund; capture again if you have multiple capture and there is balance left
CANCELLEDHold released, by your cancellation or because the capture window expiredNothing: the transaction is closed
DENIEDThe processor declined the holdStart a new payment
A decline does not change the state

If the processor declines your capture or your cancellation, the transaction stays in AUTHORIZED. You can retry or cancel. The internal state only advances on an explicit approval from the processor, so you will never see a transaction marked as charged without the charge having happened.

Which combinations are supported​

CapabilitySupported
Pre-authorisationYes
Capture for the full amountYes
Capture for a lower amountYes
Capture in parts (several captures)Yes, with multiple capture enabled
Pre-authorisation + 3D SecureDepends on the processor
Pre-authorisation + tokenised cardDepends on the processor
Pre-authorisation + instalmentsDepends on the processor

The last three do not depend on Migo but on your account's processor: some support them and some do not. They are settled when the account is configured, not at run time, so if you need any of them, coordinate it before enabling the flow.

What applies with Serfinsa​

On that processor the three combinations are not available, and the reason lies in the rail's protocol:

CombinationWhy
Pre-authorisation + 3D SecureAuthentication runs over a separate API that charges on the spot and exposes no hold
Pre-authorisation + tokenised cardThe hold requires the full card number, which a stored card does not provide
Pre-authorisation + instalmentsThe hold message has no field for an instalment plan

In all three the request is refused without reaching the processor, so it never ends in a charge you did not ask for.

With Serfinsa, a hold that has already been captured can be undone with a revert: the transaction moves to reversed. A hold you have not captured yet is not reverted: you release it with /pay/cancel.

Errors​

CodeMeans
2000The transaction does not exist
2003Invalid amount: zero, negative, non-numeric, or greater than the uncaptured balance
4011The transaction is not in a state that allows capturing
4013That transaction's processor does not support capture, or did not confirm the requested capture
4014The transaction is not in a state that allows cancelling β€” typically because it was already captured
4015That transaction's processor does not support cancellation
5000Missing parameters: typically the capture amount
5001 / 5004Your account's or the processor's configuration could not be resolved

The outcome of a capture travels in the body of the response. To confirm the charge, read status on the transaction: only approved means charged. A capture the processor does not confirm answers with code 4013 and no transaction in the body.

The hold notification​

The authorized notification is not sent by default: it is enabled in your account configuration. If you declare no list of states in your callback, you receive every state that triggers it. If you do declare one, each state must match the real state name exactly; one that does not match is not sent.

After enabling the hold notification, verify with a test transaction that it reaches your backend.