Payment Actions

Perform post-payment operations - capture authorised funds, issue refunds, and send digital receipts.

Required scopes

Include the relevant scopes when requesting your OAuth access token:

ActionScope
Capturecaptures/create
Refundrefunds/create
Digital Receipttransactions/id/receipts/create

What are payment actions?

Payment actions are operations you can perform on a payment after it has been authorised. While a standard payment completes in a single step, many real-world payment flows require additional steps - such as capturing funds after fulfilling an order, returning money to a shopper, or sending them a record of their purchase.

Teya supports three payment actions:

  • Capture - Collect funds that have been authorised but not yet captured.
  • Refund - Return funds to a shopper for a payment that has been captured.
  • Digital Receipts - Send a shopper a digital receipt for a completed payment via email.

Capture

By default, payments are captured immediately after authorisation. In some cases you may want to capture the payment separately - this is known as a manual capture.

A common use case is order fulfilment. After a payment is authorised, you ship the goods. If delivered successfully, you capture the payment. If delivery fails, you cancel the payment instead.

One capture per payment
Each authorised payment can only be captured once. You may capture any amount up to the full authorised amount, but once a capture request is made, no further captures are possible. For example, if a payment was authorised for £100.00 and you capture £10.00, the remaining £90.00 cannot be captured and will be released back to the shopper.

Capture a payment

To capture a payment, make a POST request using the payment ID returned when the payment was authorised:

Node.js example — staging
// 1. Get an access token
const tokenRes = await fetch('https://id.teya.xyz/oauth/v2/oauth-token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'User-Agent': 'Teya-JS-Client/1.0',
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: process.env.TEYA_CLIENT_ID,
    client_secret: process.env.TEYA_CLIENT_SECRET,
    scope: 'captures/create',
  }),
});
const { access_token } = await tokenRes.json();

// 2. Capture
const apiRes = await fetch('https://api.teya.xyz/v1/transactions/{id}/capture', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'User-Agent': 'Teya-JS-Client/1.0',
    Authorization: `Bearer ${access_token}`,
  },
  body: JSON.stringify({
      "amount": 5000
    }),
});
const data = await apiRes.json();
API Reference
POST /v1/transactions/{id}/capture - Capture an authorised payment

Refunds

To return funds to your shopper, you can refund a payment after it has been captured.

A refund does one of the following:

  • If the payment has not been captured, it reverses the payment.
  • If the payment has been captured, it refunds the payment.

You can issue multiple refunds against a single payment. The combined total of all refunds cannot exceed the original payment amount. For example, if a shopper paid £50.00, you could issue two separate refunds of £25.00 each, but not a third.

Refund a payment

To issue a refund, make a POST request with the ID of the payment you want to refund:

Node.js example — staging
// 1. Get an access token
const tokenRes = await fetch('https://id.teya.xyz/oauth/v2/oauth-token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'User-Agent': 'Teya-JS-Client/1.0',
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: process.env.TEYA_CLIENT_ID,
    client_secret: process.env.TEYA_CLIENT_SECRET,
    scope: 'refunds/create',
  }),
});
const { access_token } = await tokenRes.json();

// 2. Refund
const apiRes = await fetch('https://api.teya.xyz/v3/refunds', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'User-Agent': 'Teya-JS-Client/1.0',
    Authorization: `Bearer ${access_token}`,
  },
  body: JSON.stringify({
      "transaction_id": "tr_01999eea-03f5-78ae-962b-97ff946aad4d",
      "amount": 500
    }),
});
const data = await apiRes.json();
API Reference
POST /v3/refunds - Refund a payment

Digital Receipts

Send a digital receipt to a shopper for a completed payment via email.

Send a receipt

To send a digital receipt, make a POST request with the payment ID and the shopper's email address:

Node.js example — staging
// 1. Get an access token
const tokenRes = await fetch('https://id.teya.xyz/oauth/v2/oauth-token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'User-Agent': 'Teya-JS-Client/1.0',
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: process.env.TEYA_CLIENT_ID,
    client_secret: process.env.TEYA_CLIENT_SECRET,
    scope: 'transactions/id/receipts/create',
  }),
});
const { access_token } = await tokenRes.json();

// 2. Send receipt
const apiRes = await fetch('https://api.teya.xyz/v1/transactions/{transaction_id}/receipts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'User-Agent': 'Teya-JS-Client/1.0',
    Authorization: `Bearer ${access_token}`,
  },
  body: JSON.stringify({
      "recipient_emails": [
        "customer@example.com"
      ],
      "country_code": "GB",
      "language": "en-GB"
    }),
});
const data = await apiRes.json();
API Reference
POST /v1/transactions/{id}/receipts - Send a digital receipt