Order management

Once a transaction exists, you can refund it, capture or cancel it, and look it up with its transaction key.

Store the transaction key with your own order when you start the payment. Every later action needs it: refunds, captures, cancellations, lookups and support requests.


Refund a payment

A refund goes through the same payment method as the original payment, and refers to it with originalTransactionKey:

const response = await buckaroo
    .method('ideal')
    .refund({
        invoice: 'INV-1001',                       // invoice of the original payment
        originalTransactionKey: 'ORIGINAL_TX_KEY', // from response.getTransactionKey()
        amountCredit: 10.0,                        // full or partial amount
    })
    .request();

if (response.isSuccess()) {
    // refund accepted
}
  • For a partial refund, pass a lower amountCredit
  • For a card payment, use the same card brand as the service code, such as visa
  • A refund is a transaction of its own, with its own transaction key and its own push message

Whether and how long a payment can be refunded differs per payment method. See Refunds.


Authorize and capture

Some methods can reserve the amount first and collect it later, for example when the order ships. Credit cards, Riverty, In3 and Wero use authorize() and capture():

const auth = await buckaroo
    .method('visa')
    .authorize({
        invoice: 'INV-1003',
        amountDebit: 50.0,
    })
    .request();

// Later, for example when the order ships
const capture = await buckaroo
    .method('visa')
    .capture({
        invoice: 'INV-1003',
        originalTransactionKey: auth.getTransactionKey(),
        amountDebit: 50.0,
    })
    .request();

Klarna uses reserve() instead, followed by pay() to collect the reserved amount.

Riverty uses the service code afterpay in the SDK, which was the method's name before it was renamed.


Cancel an authorization

An amount that is reserved but not yet collected is cancelled, not refunded:

const response = await buckaroo
    .method('visa')
    .cancelAuthorize({
        invoice: 'INV-1003',
        originalTransactionKey: 'ORIGINAL_TX_KEY',
        amountCredit: 50.0,
    })
    .request();

Klarna reservations are cancelled with cancel(). The fields differ per method, so check the method's page under Payment methods.


Look up a transaction

const transaction = buckaroo.transaction('YOUR-TRANSACTION-KEY');

const status = await transaction.status(); // the current status, as a TransactionResponse
await transaction.refundInfo();            // what can still be refunded
await transaction.cancelInfo();            // whether the transaction can be cancelled

status() returns the same response object as a payment, so status.isSuccess() works as you would expect.

Use lookups for reconciliation and support, not to drive your order flow. The push message does that. Requests to the API are subject to rate limiting, so do not poll the status in a loop.



Did this page help you?