Capture, refund and void existing transactions

Manage a transaction

Capture Refund Void

CAPTURE on a AUTHORIZE transaction

Collects funds from a previously authorized transaction. Supports partial or full capture up to the original authorized amount.

Request rules

Field	Description
`reference`	The original order reference.
`amount`	Less than or equal to the original transaction amount.
`currency`	Same as the original transaction.
`parent_transaction_id`	Optional. Runs the operation against this specific transaction.
`options`	Optional, for example `final_capture`.

cURLNode.js

POST /api/transactions/manage

curl -X POST https://api.finrelay.io/api/transactions/manage \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "terminal_id": "TERM001",
    "reference": "ORDER-123456",
    "transaction_type": "CAPTURE",
    "amount": 4990,
    "currency": "EUR"
  }'

POST /api/transactions/manage

const res = await fetch('https://api.finrelay.io/api/transactions/manage', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    terminal_id: 'TERM001',
    reference: 'ORDER-123456', // original order reference
    transaction_type: 'CAPTURE',
    amount: 4990, // full capture
    currency: 'EUR',
  }),
});

const { status, approved } = await res.json();

REFUND on a PURCHASE transaction

Returns funds to the customer for a completed or captured transaction. Supports partial or full refund amounts.

Request rules

Field	Description
`reference`	The original order reference.
`amount`	Less than or equal to the original transaction amount.
`currency`	Same as the original transaction.
`parent_transaction_id`	Optional. Runs the operation against this specific transaction.
`options`	Optional, for example `final_capture`.

cURLNode.js

POST /api/transactions/manage

curl -X POST https://api.finrelay.io/api/transactions/manage \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "terminal_id": "TERM001",
    "reference": "ORDER-123456",
    "transaction_type": "REFUND",
    "amount": 2000,
    "currency": "EUR"
  }'

POST /api/transactions/manage

const res = await fetch('https://api.finrelay.io/api/transactions/manage', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    terminal_id: 'TERM001',
    reference: 'ORDER-123456', // original order reference
    transaction_type: 'REFUND',
    amount: 2000, // partial refund
    currency: 'EUR',
  }),
});

const { status, approved } = await res.json();

VOID on a AUTHORIZE transaction

Cancels an authorized or pending transaction before capture, releasing the held funds back to the customer.

Request rules

Field	Description
`reference`	The original order reference.
`amount`	Less than or equal to the original transaction amount.
`currency`	Same as the original transaction.
`parent_transaction_id`	Optional. Runs the operation against this specific transaction.
`options`	Optional, for example `final_capture`.

cURLNode.js

POST /api/transactions/manage

curl -X POST https://api.finrelay.io/api/transactions/manage \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "terminal_id": "TERM001",
    "reference": "ORDER-123456",
    "transaction_type": "VOID",
    "amount": 4990,
    "currency": "EUR"
  }'

POST /api/transactions/manage

const res = await fetch('https://api.finrelay.io/api/transactions/manage', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    terminal_id: 'TERM001',
    reference: 'ORDER-123456', // original order reference
    transaction_type: 'VOID',
    amount: 4990, // original amount
    currency: 'EUR',
  }),
});

const { status, approved } = await res.json();

Receive webhooks

Finrelay sends an HTTP POST to your endpoint when a transaction is processed. Every request is signed with a JWT.

Register your endpoint

Webhook setup is not self-service. Send your endpoint URL to the support team; contact details are in your client portal.

Verify the signature

Hash the raw body with SHA-512 and compare it to SHA512 in the JWT data claim. Then verify the JWT with the merchant’s public key.

Respond quickly

Return a 2xx status, ideally within 2 seconds. Reject invalid requests with 401.

Handle retries

Failed deliveries retry with exponential backoff for up to 24 hours. Make processing idempotent.

Node.js

webhook.js · your server

app.post('/webhooks/payments', (req, res) => {
  const token = req.headers.authorization.split(' ')[1];
  const { data } = jwt.decode(token);

  const digest = crypto.createHash('sha512')
    .update(req.rawBody).digest('hex');
  if (digest !== data.SHA512) return res.sendStatus(401);

  try { jwt.verify(token, merchantPublicKey); }
  catch { return res.sendStatus(401); }

  res.sendStatus(200);
  handleEvent(req.body); // idempotent
});

Transaction Manage API Documentation

Welcome to the Transaction Manage API, part of the Finrelay payment platform. This API enables merchants and integrators to manage existing transactions by initiating follow-up actions such as captures, refunds, and voids based on original transaction references.

This is a general transaction management API and may support additional management operations in the future, allowing for expanded flexibility as integration needs evolve.

Use Cases

The API supports a variety of transaction management operations, including:

Partial or full capture of previously authorized transactions
Partial or full refunds of completed purchases or captured transactions
Void operations on authorized or pending transactions

Note: Availability of specific transaction types (e.g., capture, void, refund) depends on:

The underlying integration with the payment service provider (PSP)

The type of credentials issued by the third-party PSP to your merchant account

Supported Transaction Types

The gateway supports two categories of transaction types: management transaction types used to perform follow-up operations on existing transactions via this API, and initial transaction types used when creating a new transaction.

Management Transaction Types

These transaction types are submitted to /api/transactions/manage to perform follow-up operations on an existing transaction:

Transaction Type	Description
`CAPTURE`	Collects funds from a previously authorized (`AUTHORIZE`) transaction. Supports partial or full capture up to the original authorized amount.
`REFUND`	Returns funds to the customer for a completed or captured transaction. Supports partial or full refund amounts.
`VOID`	Cancels an authorized or pending transaction before capture, releasing the held funds back to the customer.

Note: Availability of specific management transaction types depends on the underlying integration with the payment service provider (PSP) and the credentials issued to your merchant account.

Initial Transaction Types

These transaction types are submitted at the point of authorization to create a new transaction:

Transaction Type	Endpoint	Description
`PURCHASE`	`/api/transactions/authorize`	Combined authorization and immediate capture in a single step. Funds are reserved and collected at once. The most common type for standard card payments.
`AUTHORIZE`	`/api/transactions/authorize`	Reserves (holds) funds on the customer's card without capturing them immediately. A separate `CAPTURE` management operation must follow to collect the funds. Use when the final charge amount may change (e.g. hotel reservations, car rentals).
`OCT`	`/api/transactions/authorize`	Original Credit Transaction — pushes funds directly to a cardholder's card. Used for payouts, disbursements, and marketplace seller payments.
`PAYOUT`	`/api/transactions/authorize`	Sends funds to a card recipient via a payout flow.
`PAYMENT`	`/api/transactions/payment`	Alternative payment methods such as Open Banking, UPI, wallets, bank transfer, or QR code. The `transaction_type` is fixed to `PAYMENT` automatically for this endpoint.