Authorise and Capture

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.

A card can be authorised for up to 7 days. If funds have not been captured within that time, it will be released.

Prerequisites

Please familiarise yourself with the guide to Accept an Online Payment, as the steps outline in this document builds upon the existing integration.

1. Your Server - Create a Pay Request to authorise only

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,
  });
});

2. Submit the Pay Request

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.

3. Your Server - Capture the Pay Request

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.