Payment Links

5 min

A payment link is the simplest way to request payment from a customer. Here's how it works:

Create a payment link by supplying a transaction amount (the amount you wish to request).

Provide your submerchant ID. For operators, you can supply the submerchant ID of the account who should receive the transaction, for example a driver who has been allocated to a booking.

Choose for us to send the payment link directly to your customer by SMS, or if you prefer you can send the URL to your customer via another channel.

The customer can open the link using any web browser, on any device, and make payment by entering their payment details.

You can view the status of a payment link by polling the API, or alternatively use our Webhooks feature to be notified programatically when a payment link is completed.

API Operations

Create a Payment Link

Use this endpoint to create a payment link. You can optionally send it to your customer. The only required parameters are: saleAmount and submerchantId. Note that transaction amounts should always be specified in currency minor units (for example pence).

POST

https://api.cabcard.services/v1/intents

const fetch = require('node-fetch');

const url = 'https://api.cabcard.services/v1/intents';

const body = {
  "saleAmount": 1259,
  "currency": "gbp",
  "submerchantId": "sub_2t4dp89kja9fnf79",
  "description": "Payment request for taxi journey",
  "reference": "EXMPL-01",
  "customerName": "John Smith",
  "brandIdentifier": "sub_2t4dp89kja9fnf79",
  "customerPhoneNumber": "+447763306128",
  "sendCustomerSms": true,
  "expiryNaturalLanguage": "7 days"
};

const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
  },
  body: JSON.stringify(body),
};
fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Once created, you may wish to send the payment link directly to your customer (for example by embedding it within a message, email or invoice).

Use the clientAccessUrl property for this. Alternatively, you can use the convenient clientAccessQrCode property, which is a QR code representation of the clientAccessUrl.

Retrieve a payment link

Get a payment link by its ID

GET

https://api.cabcard.services/v1/intents/:id

const fetch = require('node-fetch');

let url = 'https://api.cabcard.services/v1/intents/int_l3bj87hv';
let options = {
  method: 'GET',
  headers: {
    Accept: 'application/json',
  }
};
fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

List Payment Links

List all payment links, optionally filtering the list

GET

https://api.cabcard.services/v1/intents/

fetch("https://api.cabcard.services/v1/intents", {
  "method": "GET",
  "headers": {
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

Update a payment link

This operation can only be carried out while the payment link is in allowed statuses, usually the 'created'

PATCH

https://api.cabcard.services/v1/intents/:id

Reset a payment link

Sometimes, a customer may get stuck when attempting a payment, for example due to 3DS problems. This function resets the authorization state of the payment link, allowing the customer to try agin.

PUT

https://api.cabcard.services/v1/intents/:id/reset

const fetch = require('node-fetch');

let url = 'https://api.cabcard.services/v1/intents/:id/reset';
let options = {
  method: 'PUT',
headers: {
    Accept: 'application/json',
  }
};
fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Cancel a payment link

If you need to cancel a payment link (for example, if the price of a booking has changed and you wish to invalidate the payment request), use this operation. The customer will not be able to carry out a payment. This operation is only available if the payment link status is not final.

PUT

https://api.cabcard.services/v1/intents/:id/cancellation

curl --request PUT
  --url https://api.cabcard.services/v1/intents/:id/cancellation
  --header 'Accept: application/json'

Delete a payment link

If you need to delete a previously cancelled payment link, use this operation. This operation is only available if the payment link status is cancelled.

DELETE

https://api.cabcard.services/v1/intents/:id

curl --request PUT
  --url https://api.cabcard.services/v1/intents/:id/cancellation
  --header 'Accept: application/json'

Capture payment link authorization

Used for intents with manual capture mode

PUT

https://api.cabcard.services/v1/intents/:id/authorization/capture

var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");

var requestOptions = {
   method: 'PUT',
   headers: myHeaders,
   redirect: 'follow'
};

fetch("https://api.cabcard.services/v1/intents/:id/authorization/capture/{id}", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));