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.
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β
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β
| Method | Path | What 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.
| Environment | Host |
|---|---|
| Sandbox | https://sb-mw.migopayments.com |
| Production | https://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 }'
{
"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β
| State | Means | What you can do |
|---|---|---|
| AUTHORIZED | Funds held, not yet charged | Capture or cancel |
| APPROVED | Charged, in full or in part | Void or refund; capture again if you have multiple capture and there is balance left |
| CANCELLED | Hold released, by your cancellation or because the capture window expired | Nothing: the transaction is closed |
| DENIED | The processor declined the hold | Start a new payment |
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β
| Capability | Supported |
|---|---|
| Pre-authorisation | Yes |
| Capture for the full amount | Yes |
| Capture for a lower amount | Yes |
| Capture in parts (several captures) | Yes, with multiple capture enabled |
| Pre-authorisation + 3D Secure | Depends on the processor |
| Pre-authorisation + tokenised card | Depends on the processor |
| Pre-authorisation + instalments | Depends 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:
| Combination | Why |
|---|---|
| Pre-authorisation + 3D Secure | Authentication runs over a separate API that charges on the spot and exposes no hold |
| Pre-authorisation + tokenised card | The hold requires the full card number, which a stored card does not provide |
| Pre-authorisation + instalments | The 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β
| Code | Means |
|---|---|
| 2000 | The transaction does not exist |
| 2003 | Invalid amount: zero, negative, non-numeric, or greater than the uncaptured balance |
| 4011 | The transaction is not in a state that allows capturing |
| 4013 | That transaction's processor does not support capture, or did not confirm the requested capture |
| 4014 | The transaction is not in a state that allows cancelling β typically because it was already captured |
| 4015 | That transaction's processor does not support cancellation |
| 5000 | Missing parameters: typically the capture amount |
| 5001 / 5004 | Your 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.
Relatedβ
- Direct payment API (PCI) β how the payment you later hold is originated.
- Voids and refunds β what to do with a transaction that was already charged.
- Merchant Generic Callback β receive state changes in your backend.