Maintenance operations
Creating the initial transaction is just the start of a transaction's life cycle. Following-up on existing transactions (i.e. by capturing an authorisation or performing a refund) is part of your daily business routine.
Use our dedicated endpoints or the Merchant Portal to perform maintenance operations on existing transactions for any given scenario.
- Depending on the transaction's status, different maintenance operations are possible. Refer to the transaction’s status to learn which options you have.
- All samples feature the bare minimum of mandatory/strongly recommended parameters. Find detailed information about these objects and properties in our API reference.
- You can perform all maintenance operations described below also both via the Merchant Portal and integration method Batch. Read the dedicated chapters in the respective guides to learn more:
Capture payments
If you have initially processed your transactions as authorisations (which have status.Output.statusCode=5), you need to capture them eventually to receive the funds. To do so, send a request to our dedicated CapturePayment endpoint:
CapturePaymentRequest capturePaymentRequest = new CapturePaymentRequest()
.withAmount(1000L)
.withIsFinal(false);CapturePaymentRequest capturePaymentRequest = new CapturePaymentRequest {
Amount = 1000,
IsFinal = false
};const capturePaymentRequest = {
amount: 1000,
isFinal: false
};$capturePaymentRequest = new CapturePaymentRequest();
$capturePaymentRequest->setAmount(1000);
$capturePaymentRequest->setIsFinal(false);capture_payment_request = CapturePaymentRequest()
capture_payment_request.amount = 1000
capture_payment_request.is_final = Falsecapture_payment_request = CapturePaymentRequest.new
capture_payment_request.amount = 1000
capture_payment_request.is_final = false| Property | Description |
|---|---|
| {merchantId} | Your account on our platform through which the initial transaction was processed. Add it as a path parameter to the CapturePayment endpoint Url. |
| {paymentId} | The payment.Id of the initial transaction which our platform returned in the CreatePayment/GetHostedCheckout request. Add it as a path parameter to the CapturePayment endpoint Url. |
| amount | The gross amount you want to capture for the original authorisation. If left empty, our platform will capture the full original amount. |
| isFinal |
Define whether to close the transaction for subsequent captures if you only partially capture the amount.
If left empty, the default value is "false". |
Cancel payments
If you have initially processed your transactions as authorisations (which have status.Output.statusCode=5), you can cancel them to unblock the funds. To do so, send a request to our dedicated CancelPayment endpoint:
CancelPaymentRequest cancelPaymentRequest = new CancelPaymentRequest()
.withAmountOfMoney(new AmountOfMoney()
.withAmount(1000L)
.withCurrencyCode("EUR")
)
.withIsFinal(false);CancelPaymentRequest cancelPaymentRequest = new CancelPaymentRequest {
AmountOfMoney = new AmountOfMoney {
Amount = 1000,
CurrencyCode = "EUR"
},
IsFinal = false
};const cancelPaymentRequest = {
amountOfMoney: {
amount: 1000,
currencyCode: "EUR"
},
isFinal: false
};$cancelPaymentRequest = new CancelPaymentRequest();
$amountOfMoney = new AmountOfMoney();
$amountOfMoney->setAmount(1000);
$amountOfMoney->setCurrencyCode("EUR");
$cancelPaymentRequest->setAmountOfMoney($amountOfMoney);
$cancelPaymentRequest->setIsFinal(false);cancel_payment_request = CancelPaymentRequest()
amount_of_money = AmountOfMoney()
amount_of_money.amount = 1000
amount_of_money.currency_code = "EUR"
cancel_payment_request.amount_of_money = amount_of_money
cancel_payment_request.is_final = Falsecancel_payment_request = CancelPaymentRequest.new
amount_of_money = AmountOfMoney.new
amount_of_money.amount = 1000
amount_of_money.currency_code = "EUR"
cancel_payment_request.amount_of_money = amount_of_money
cancel_payment_request.is_final = false| Property | Description |
|---|---|
| {merchantId} | Your account on our platform through which the initial transaction was processed. Add it as a path parameter to the CancelPayment endpoint Url. |
| {paymentId} | The payment.Id of the initial transaction which our platform returned in the CreatePayment/GetHostedCheckout request. Add it as a path parameter to the CancelPayment endpoint Url. |
| order.amountOfMoney amount currencyCode |
amount: The gross amount you want to cancel for the original authorisation. currencyCode: The ISO 4217 currency code for this amount. If left empty, our platform will cancel the full original amount. |
| isFinal |
Define whether to close the transaction for subsequent cancellations if you only partially cancel the amount.
If left empty, the default value is "false". |
Refund payments
You can reimburse successfully processed payments (which have status.Output.statusCode=9). To do so, send a request to our dedicated RefundPayment endpoint:
RefundRequest refundRequest = new RefundRequest()
.withAmountOfMoney(new AmountOfMoney()
.withAmount(1000L)
.withCurrencyCode("EUR")
);RefundRequest refundRequest = new RefundRequest {
AmountOfMoney = new AmountOfMoney {
Amount = 1000,
CurrencyCode = "EUR"
}
};const refundRequest = {
amountOfMoney: {
amount: 1000,
currencyCode: "EUR"
}
};$refundRequest = new RefundRequest();
$amountOfMoney = new AmountOfMoney();
$amountOfMoney->setAmount(1000);
$amountOfMoney->setCurrencyCode("EUR");
$refundRequest->setAmountOfMoney($amountOfMoney);refund_request = RefundRequest()
amount_of_money = AmountOfMoney()
amount_of_money.amount = 1000
amount_of_money.currency_code = "EUR"
refund_request.amount_of_money = amount_of_moneyrefund_request = RefundRequest.new
amount_of_money = AmountOfMoney.new
amount_of_money.amount = 1000
amount_of_money.currency_code = "EUR"
refund_request.amount_of_money = amount_of_money| Property | Description |
|---|---|
| {merchantId} | Your account on our platform through which the initial transaction was processed. Add it as a path parameter to the RefundPayment endpoint Url. |
| {paymentId} | The payment.Id of the initial transaction which our platform returned in the CreatePayment/GetHostedCheckout request. Add it as a path parameter to the RefundPayment endpoint Url. |
| order.amountOfMoney amount currencyCode |
amount: The gross amount you want to refund for the original authorisation. currencyCode: The ISO 4217 currency code for this amount. If left empty, our platform will refund the full original amount. |
Operation limits
Our platform implements limitations for maintenance operations that you can perform per individual transaction. This is a security measure that can help you identify issues in your server architecture, such as infinite loops or other flaws in your integration logic.
We distinguish between two types of limits:
- Soft limit: You can still process maintenance operations, but limited to one every 30 minutes. If you make more requests within these 30 minutes, our platform will reject it, resulting in errors.errorCode=50000429. This error indicates an unusual amount of maintenance operations for standard business use cases, possibly due to unintended infinite loops such as repeated refund retries.
- Hard limit: Your request is rejected as the transaction has reached the maximum number of allowed operations, resulting in errors.errorCode=50000430.
To avoid either limit, we recommend following these guidelines:
- Check your integration with our platform: For errors.errorCode=50000429, review your mechanism for requesting maintenance operations. Verify that retry requests have proper exit conditions and no infinite loops.
- Monitor operation counts: Send GetPaymentDetails requests to keep an eye on the number of performed maintenance operations per transactions. An unusually high number might indicate unintended workflows within your integration.
- Report exceptional business cases: Contact us if you require to exceed the soft/hard limit for specific scenarios.
We strongly recommend building your mechanism for requesting maintenance operations around the error codes 50000429 / 50000430, and not around the number of operations performed. By soft-coding the number of performed maintenance operations, you ensure your system receives always correct information about the rejection reason.