Order management

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

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


Refund a payment

A refund goes through the same payment method as the original payment. Build the request as you would a payment, then call refund() with the transaction key of the original payment:

response = payments.create_payment(
    "ideal",
    {
        "currency": "EUR",
        "amount": 10.00,
        "invoice": "INV-1001",  # invoice of the original payment
        "description": "Refund for order #1001",
        "return_url": "https://example.com/buckaroo/return",
        "return_url_cancel": "https://example.com/buckaroo/cancel",
        "return_url_error": "https://example.com/buckaroo/error",
        "return_url_reject": "https://example.com/buckaroo/reject",
    },
).refund("ORIGINAL_TX_KEY")
  • Without a second argument, refund() refunds the amount in the request
  • For a partial refund, pass the amount: .refund("ORIGINAL_TX_KEY", 4.00)
  • For a card payment, also pass the same brand as the original payment
  • A refund is a transaction of its own, with its own transaction key and its own push message

The SDK checks the same required fields for a refund as for a payment, so the description and the four return URLs have to be present even though a refund does not redirect anyone.

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 and In3 use authorize() and capture():

order = {
    "brand": "visa",
    "currency": "EUR",
    "amount": 50.00,
    "invoice": "INV-1003",
    "description": "Order #1003",
    "return_url": "https://example.com/buckaroo/return",
    "return_url_cancel": "https://example.com/buckaroo/cancel",
    "return_url_error": "https://example.com/buckaroo/error",
    "return_url_reject": "https://example.com/buckaroo/reject",
}

auth = payments.create_payment("creditcard", order).authorize()

# Later, for example when the order ships
capture = payments.create_payment("creditcard", order).capture(auth.key)

To capture part of the amount, pass it as the second argument: .capture(auth.key, 20.00).

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


Cancel an authorization

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

response = payments.create_payment("creditcard", order).cancelAuthorize(auth.key)

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


Check a transaction

The push message tells you the status of every transaction, so store the latest status with your order when you handle it. For reconciliation and support, look up the transaction in Plaza with its transaction key.



Did this page help you?