A Pay Request completes both authorisation and capture by default. However, it is possible to authorise and capture separately.
The authorise and capture flow could be used in situations when the final amount is not known. For example, you would usually authorise your funds when you check in at a hotel. The money has been put on hold but not yet been captured. Upon checkout, the hotel would determine the actual cost and capture the final amount.
There are two flows for authorisation and capture: one that allows increases to the authorised amount before capture, and one that does not.
A card can be authorised for up to 7 days. If funds have not been captured within that time, it will be released.
Please familiarise yourself with the guide to Accept an Online Payment, as the steps outline in this document builds upon the existing integration.
Instruct the Pay Request to perform only an authorise when creating it.
Set capture.method to MANUAL.
// Node sample code
const express = require("express");
const app = express();
const axios = require('axios');
app.post("/create-order", async (req, res) => {
const { items } = req.body;
const totalAmountInCents = calculateTotal(items);
const payRequest = await axios.post('https://api.tyro.com/connect/pay/requests',
{
"locationId": "tc-examplelocation-3000",
"provider": {
"name": "TYRO",
"method": "CARD"
},
"total": {
"amount": totalAmountInCents,
"currency": "AUD"
},
"capture": {
"method": "MANUAL"
}
},
{
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer exampleJwt'
}
});
res.send({
paySecret: payRequest.paySecret,
});
});Follow the usual pay flow as documented in Accept an Online Payment to submit the authorise.
The Pay Request status will change to AWAITING_CAPTURE upon a successful authorisation.
Update the Pay Request with the CAPTURE action when you are ready to capture the authorisation,
// Node sample code
const express = require("express");
const app = express();
const axios = require('axios');
app.patch("/capture", async (req, res) => {
const { payRequestId } = req.body;
const amountToCapture = getAmountToCapture(payRequestId); // your logic to decide how much to capture
const payRequest = await axios.patch(`https://api.tyro.com/connect/pay/requests/${payRequestId}`,
{
"action": "CAPTURE",
"capture": {
"total": {
"amount": amountToCapture, // amount to capture can optionally be sent
"currency": "AUD",
},
},
},
{
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer exampleJwt'
}
});
res.send({
status: payRequest.status
});
});If the capture.total.amount is not provided, the amount captured will default to the total.amount from the authorised Pay Request.
Once a capture is executed, no additional captures can be performed the on the same Pay Request. Only one capture can be executed per authorisation. The remaining authorisation amount will automatically be released.
This feature is optional and must be enabled for your account. Contact Tyro Support to request access.
This flow extends the basic Authorisation and Capture flow by allowing you to update the authorised amount before the final capture. Use this flow when the final amount may change after the initial authorisation — for example, when additional items or services may be added to an order.
To enable this, set capture.method to MANUAL_ESTIMATED when creating the Pay Request. This tells Tyro that the initial amount is an estimate, and that it can be updated before capture or expiration.
When using MANUAL_ESTIMATED, you must clearly inform the customer at the time of authorisation that the final charged amount may differ from the amount shown. This disclosure is mandatory.
Set capture.method to MANUAL_ESTIMATED to authorise an estimated amount and allow updates before capture.
// Node sample code
const express = require("express");
const app = express();
const axios = require('axios');
app.post("/create-order", async (req, res) => {
const { items } = req.body;
const totalAmountInCents = calculateTotal(items);
const payRequest = await axios.post('https://api.tyro.com/connect/pay/requests',
{
"locationId": "tc-examplelocation-3000",
"provider": {
"name": "TYRO",
"method": "CARD"
},
"total": {
"amount": totalAmountInCents,
"currency": "AUD"
},
"capture": {
"method": "MANUAL_ESTIMATED"
}
},
{
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer exampleJwt'
}
});
res.send({
paySecret: payRequest.paySecret,
});
});Follow the usual pay flow as documented in Accept an Online Payment to submit the authorisation.
The Pay Request status will change to AWAITING_CAPTURE upon a successful authorisation.
If you want to update the authorised amount, send a PATCH request with the UPDATE_AUTHORISATION action and an authorisation object containing the new total. This also extends the authorisation period.
{
"action": "UPDATE_AUTHORISATION",
"authorisation": {
"total": {
"amount": 15000,
"currency": "AUD"
}
}
}Only increases to the authorised amount are supported. If you want to decrease the authorised amount, you must void the existing authorisation and submit a new one.
This feature is only supported for Visa and Mastercard transactions. It is not available for other card schemes. If you have stored the payment method and need to use a scheme that does not support incremental authorisations, void the previous authorisation and create a new one for the updated amount.
When you are ready to capture, update the Pay Request with the CAPTURE action.
// Node sample code
const express = require("express");
const app = express();
const axios = require('axios');
app.patch("/capture", async (req, res) => {
const { payRequestId } = req.body;
const amountToCapture = getAmountToCapture(payRequestId); // your logic to decide how much to capture
const payRequest = await axios.patch(`https://api.tyro.com/connect/pay/requests/${payRequestId}`,
{
"action": "CAPTURE",
"capture": {
"total": {
"amount": amountToCapture, // amount to capture can optionally be sent
"currency": "AUD",
},
},
},
{
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer exampleJwt'
}
});
res.send({
status: payRequest.status
});
});If the capture.total.amount is not provided, the amount captured will default to the total.amount from the authorised Pay Request.
Once a capture is executed, no additional captures can be performed the on the same Pay Request. Only one capture can be executed per authorisation. The remaining authorisation amount will automatically be released.