Charge, capture, refund and cancel Transactions

July 30, 2026

Charge tokenized payments, capture reservations, refund fully or partially and cancel waiting transactions with the FlowAlp Pay API.

Once a transaction exists in FlowAlp Pay you can keep working with it: charge a stored payment method, collect a reserved amount, issue full or partial refunds, cancel a payment that never completed, and maintain the data stored on a tokenization. All calls below use API version v1.16 and the x-api-key header described in Authentication.

Charge a tokenized or reserved Transaction

Two flows produce chargeable transactions. A tokenization (Gateway created with preAuthorization) leaves a transaction with status authorized: you can charge it as often as you like, with a different amount each time, and the token does not expire — but a successful charge is not guaranteed. A pre-authorization (Gateway created with reservation) leaves a transaction with status reserved: it can be charged exactly once, with an amount up to the reserved amount, and the reservation typically holds for about five days depending on the card issuer.

POSThttps://api.pay.flowalp.com/v1.16/Transaction/{id}/v1.14 · v1.15 · v1.16

Request

Parameter	Type	Description
id	integer (required)	Path parameter: ID of the transaction to charge — its status must be `authorized` or `reserved`.
instance	string (required)	Query parameter: name of your instance (tenant).
amount	integer	Amount to charge in minor units (`4500` = CHF 45.00).
purpose	string	What the customer is paying for.
referenceId	string	Your own reference for the charged transaction; it is included in the transaction webhook.
payoutDescriptor	string	Text added to the payout statement, maximum 80 characters. Applies only to payments collected by FlowAlp Pay that are paid out as single-transaction payouts.

Charge a transactionbash

curl -X POST "https://api.pay.flowalp.com/v1.16/Transaction/9034/?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4500,
    "purpose": "Monthly plan July",
    "referenceId": "SUB-2026-07-042"
  }'

Charge a transaction (PHP SDK)PHP

<?php
use FlowAlpPay\FlowAlpPay;
use FlowAlpPay\Models\Request\Transaction;

$client = new FlowAlpPay(
    getenv('FLOWALP_TENANT'),
    getenv('FLOWALP_API_SECRET'),
    FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER,
    'pay.flowalp.com',
    '1.16'
);

$charge = new Transaction();
$charge->setId(9034);
$charge->setAmount(4500);
$charge->setPurpose('Monthly plan July');
$charge->setReferenceId('SUB-2026-07-042');

try {
    $transaction = $client->charge($charge);
    echo $transaction->getStatus();
} catch (Exception $e) {
    error_log('Charge failed: ' . $e->getMessage());
}

Response

Sample responseJSON

{
  "status": "success",
  "data": [
    {
      "id": 9107,
      "uuid": "b32a7620",
      "referenceId": "SUB-2026-07-042",
      "time": "2026-07-15 08:03:11",
      "status": "confirmed",
      "lang": "de",
      "psp": "Native_PSP",
      "amount": 4500,
      "contact": {
        "id": 23,
        "uuid": "1a2b3c",
        "firstname": "Anna",
        "lastname": "Keller",
        "email": "anna.keller@example.com"
      }
    }
  ]
}

Capture a pre-authorized Transaction

Capture collects a previously approved amount without changing it. The call takes no documented body parameters beyond the path ID and your instance.

POSThttps://api.pay.flowalp.com/v1.16/Transaction/{id}/capturev1.14 · v1.15 · v1.16

Capture a transactionbash

curl -X POST "https://api.pay.flowalp.com/v1.16/Transaction/9034/capture?instance=<tenant>" \
  -H "x-api-key: <api-secret>"

Capture a transaction (PHP SDK)PHP

<?php
use FlowAlpPay\Models\Request\Transaction;

// $client: same constructor as in the charge example above
$capture = new Transaction();
$capture->setId(9034);

try {
    $client->capture($capture);
} catch (Exception $e) {
    error_log('Capture failed: ' . $e->getMessage());
}

To collect a lower amount than the reserved one, do not capture — charge the reservation with an explicit amount instead. A reserved transaction can only be collected once.

Refund a Transaction

A refund returns money to the customer. Omit amount to refund the full transaction, or pass an amount in minor units for a partial refund. Whether a refund is currently possible depends on the payment method and the transaction state — check the refundable and partiallyRefundable flags returned by List and retrieve Transactions. Refund progress shows up in the statuses refund_pending, refunded and partially-refunded.

POSThttps://api.pay.flowalp.com/v1.16/Transaction/{id}/refundv1.14 · v1.15 · v1.16

Parameter	Type	Description
id	integer (required)	Path parameter: ID of the transaction to refund.
instance	string (required)	Query parameter: name of your instance (tenant).
amount	integer	Optional. Partial refund amount in minor units; omit it to refund the full amount.

Partial refund of CHF 15.00bash

curl -X POST "https://api.pay.flowalp.com/v1.16/Transaction/4712/refund?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1500}'

Refund a transaction (PHP SDK)PHP

<?php
use FlowAlpPay\Models\Request\Transaction;

// $client: same constructor as in the charge example above
$refund = new Transaction();
$refund->setId(4712);
$refund->setAmount(1500); // omit setAmount() for a full refund

try {
    $client->refund($refund);
} catch (Exception $e) {
    error_log('Refund failed: ' . $e->getMessage());
}

Cancel a waiting Transaction

A transaction that is still in status waiting — started but never completed — can be cancelled. The response returns the transaction with status cancelled. If the transaction exists but is no longer waiting, the API answers with 404.

PATCHhttps://api.pay.flowalp.com/v1.16/Transaction/{id}/cancelv1.14 · v1.15 · v1.16

Cancel a waiting transactionbash

curl -X PATCH "https://api.pay.flowalp.com/v1.16/Transaction/377/cancel?instance=<tenant>" \
  -H "x-api-key: <api-secret>"

Sample responseJSON

{
  "status": "success",
  "data": [
    {
      "id": 377,
      "uuid": "2639f2f9",
      "referenceId": "",
      "time": "2026-07-18 17:22:29",
      "status": "cancelled",
      "lang": "de",
      "psp": "Native_PSP",
      "amount": 10000
    }
  ]
}

Update contact details of a pre-authorization or tokenization

Tokenizations and pre-authorizations store contact data alongside the payment method. Update that data by sending a fields object in which every entry is an object with a value key.

PUThttps://api.pay.flowalp.com/v1.16/Transaction/{id}/v1.14 · v1.15 · v1.16

Contact fields: title, forename, surname, company, street, postcode, place, country, phone, email, date_of_birth — title accepts mister, miss or diverse.
Delivery address fields: delivery_title, delivery_forename, delivery_surname, delivery_company, delivery_street, delivery_postcode, delivery_place, delivery_country.
Custom fields: custom_field_1 … custom_field_5, each with name, value and export_name.
terms and privacy_policy: if you include these fields in the request, they must be accepted.

Update contact detailsbash

curl -X PUT "https://api.pay.flowalp.com/v1.16/Transaction/9034/?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "forename": {"value": "Anna"},
      "surname": {"value": "Keller"},
      "email": {"value": "anna.keller@example.com"}
    }
  }'

If you authenticate with ApiSignature instead of the API key header, the fields[...] parameters must keep a stable order when the signature is calculated.

Update a tokenization

Adjust the VAT rate stored on an existing tokenization. The response returns the tokenization with its updated vatRate.

PATCHhttps://api.pay.flowalp.com/v1.16/Transaction/{id}/updateTokenizationv1.14 · v1.15 · v1.16

Parameter	Type	Description
id	integer (required)	Path parameter: ID of the original tokenization.
instance	string (required)	Query parameter: name of your instance (tenant).
vatRate	integer (required)	New VAT rate as a percentage value.

Update a tokenizationbash

curl -X PATCH "https://api.pay.flowalp.com/v1.16/Transaction/9034/updateTokenization?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{"vatRate": 8}'

Errors

HTTP status	Meaning
400	Malformed request — the `message` field of the error body describes the exact problem.
404	No transaction with the given ID exists on this instance. For cancellations this also occurs when the transaction is not in status `waiting`.

To look up transaction states and IDs, use List and retrieve Transactions. The concepts behind these operations are explained in the Tokenization and Pre-authorization guides.

Charge, capture, refund and cancel Transactions

Charge a tokenized or reserved Transaction#

Request#

Response#

Capture a pre-authorized Transaction#

Refund a Transaction#

Cancel a waiting Transaction#

Update contact details of a pre-authorization or tokenization#

Update a tokenization#

Errors#