| Element | Details | Description | Active with |
|---|---|---|---|
ch.voev.nova.payment.servicemodel.RefundRequest | payer | deprecated since 3.0.0, removed NOVA-79474 , PI2025-06 | |
ch.voev.nova.payment.servicemodel.RefundRequest | authorizationAmount | The authorization amount will not be required in the future as it can be taken from several sources depending on the concrete payment case. Already now the value is optional in case of coupons that have a percentage discount. | |
ch.voev.nova.payment.servicemodel.RefundPayment | Renamed type CancellationPayment to RefundPayment | 0.3.21 / 1.0.21 | |
ch.voev.nova.payment.servicemodel.PaymentTransaction | refundedTransactionID | Renamed property canceledTransactionID to refundedTransactionID | 0.3.21 / 1.0.21 |
ch.voev.nova.payment.servicemodel.PaymentTransactionID | id | Changed type from long to String. | 1.0.22 / 0.3.22 |
ch.voev.nova.payment.servicemodel.PaymentContext | New technical header was introduced as a temporary solution in order to simplify integration on channel side. | 1.0.23 | |
ch.voev.nova.payment.servicemodel.Account | balance | Property will be optional as this operation was never implemented before. | 1.4.0 |
ch.voev.nova.payment.servicemodel.PaymentTransactionQuery | payer, transactionState, paymentInstrumentIdentifier, bookableItemID are removed as properties for querying transactions. accountID is now a mandatory field | PI 17 | |
ch.voev.nova.payment.servicemodel.PaymentRequest | shoppingCartElements | In the future it is required to provide at least 1 shopping cart element. | PI 19 |
ch.voev.nova.payment.servicemodel.PaymentAllocation | shoppingCartElementID | Property will be mandatory in the future. | PI 19 |
ch.voev.nova.payment.servicemodel.PaymentService.checkRefund | pRequest | Due to extended business requirements it is mandatory in the future to provide shopping cart elements when requesting a refund of a payment transaction. This will lead to the fact that this parameter here has to has to be passed in the future. | PI 22 |
ch.voev.nova.payment.servicemodel.RefundRequest | shoppingCartElementsToRefund | Due to extended business requirements it is mandatory in the future to provide information about shopping cart elements when requesting a refund of a payment transaction. This will lead to the fact that this property here has to contain at least one entry. | PI 22 |
| Artifact | Icon | Maturity Level | since |
|---|---|---|---|
| NOVA Payment Data Types | 🐦 | Early Bird | 2.0.0 |
| NOVA Payment Service Model | 🐦 | Early Bird | 2.0.0 |
| NOVA Payment Events | 🐦 | Early Bird | 2.0.0 |
| REST Path / Operation | Description |
|---|---|
/payments/transactions:checkPayment [POST] checkPayment(CheckPaymentRequest, PaymentContext, SalesContext) | Operation checks if the passed payment instrument is applicable for the passed shopping cart elements. This operation only does a very simple precheck e.g. it does not check the balance of an Halbtax PLUS or the status of a coupon. It only checks if the payment instrument is in general applicable for the shopping cart element. |
/payments/transactions/{transactionID}:checkRefund [POST] checkRefund(PaymentTransactionID, RefundRequest, PaymentContext, SalesContext) | Operation checks if a refund of the passed transaction is possible. This operation only does a very simple precheck for the refund. This means that when calling authorizePaymentRefund(...) it still might not be possible to refund a transaction even though checkRefund(...) was successful. |
/payments/transactions:resolveAuthorizationFlow [POST] resolveAuthorizationFlow(AuthorizationFlowRequest, PaymentContext, SalesContext) | NOVA Payment knows two different types of authorization flows. Depending on business rules either a direct authorization is possible or an authorization with a second factor (2FA) is required. This operation can be used to find out which authentication flow will be required for a payment transaction. The main purpose of this operation is to support a more customer friendly checkout process in case that no 2FA is required. If a client prefers to always use the same flow then it should implement the 2FA flow where the second factor will only be requested if really needed. |
/payments/transactions:preparePayment [POST] preparePayment(PaymentRequest, IdempotencyHeader, PaymentContext, SalesContext) | Operation prepares a payment transaction. This is the first call in the 2FA authorization flow. Depending on the returned "transactionState" of the payment transaction it is either possible to directly authorize the transaction (WAITING_FOR_AUTHORIZATION) or an explicit confirmation of the customer (2FA) is required (CUSTOMER_CONFIRMATION_REQUIRED). The operation is idempotent, which means that if a transaction was already created for the passed idempotence key then the response contains the original transaction along with the appropriate message. |
/payments/transactions/{transactionID}:authorizePayment2FAFlow [POST] authorizePayment2FAFlow(PaymentTransactionID, IdempotencyHeader, PaymentContext, SalesContext) | Operation authorizes a payment transaction. The payment transaction before needs to be prepared. This operation is part of 2FA authorization flow. The operation is idempotent, which means that if a transaction was already authorized for the passed idempotence key then the response contains the original transaction along with the appropriate message. |
/payments/transactions:authorizePaymentDirectFlow [POST] authorizePaymentDirectFlow(PaymentRequest, IdempotencyHeader, PaymentContext, SalesContext) | Operation authorizes a payment transaction. This is the first call in the direct authorization flow. If a direct authorization is possible the a payment transaction will be returned. If you want to make sure that a direct authorization of the payment transaction is possible then first call resolveAuthorizationFlow(...). The operation is idempotent, which means that if a transaction was already created for the passed idempotence key then the response contains the original transaction along with the appropriate message. |
/payments/transactions/{transactionID}:authorizeRefund [POST] authorizePaymentRefund(PaymentTransactionID, RefundRequest, IdempotencyHeader, PaymentContext, SalesContext) | Cancellation is requested for payments of the transaction with the specified id. If single payments are not set then the whole transaction will be canceled. Operation is required in cases where a payment transaction was already settled and now should be canceled. The operation is idempotent, which means that if a transaction was already canceled for the passed idempotence key then the response contains the original transaction along with the appropriate message. |
/payments/transactions/{transactionID}:settleTransaction [POST] settlePayment(PaymentTransactionID, IdempotencyHeader, PaymentContext, SalesContext) | Settlement is requested for the transaction with specified id. This can either be a regular payment transaction or a refund / cancellation of a transaction. This operation is independent of the authorization flow. The operation is idempotent, which means that if a transaction was already settled for the passed idempotence key then the response contains the original transaction along with the appropriate message. |
/payments/transactions/{transactionID}:cancel [POST] cancelPayment(PaymentTransactionID, IdempotencyHeader, PaymentContext, SalesContext) | Operation cancels a payment transaction. This operation is intended to be called in case that the payment was not yet settled. In order to cancel an already settled transaction "authorizePaymentCancellation" has to be used. The operation is idempotent, which means that if a transaction was already created for the passed idempotence key then the response contains the original transaction along with the appropriate message. |
/payments/transactions/{transactionID} [GET] getTransaction(PaymentTransactionID, PaymentContext, SalesContext) | Operation returns the payment transaction with the passed ID. |
/payments/accounts/{accountID} [GET] getAccount(AccountID, PaymentContext, SalesContext) | Operation returns the account with the passed account ID. |
/payments/accounts [POST] createAccount(CreateAccountRequest, PaymentContext, SalesContext) | |
/payments/accounts/{accountID}:update [POST] updateAccount(AccountID, UpdateAccountRequest, PaymentContext, SalesContext) | |
/payments/transactions [GET] queryTransactions(PaymentTransactionQuery, PagingParams, PaymentContext, SalesContext) | Operation executes a query for payment transactions that match with the passed query parameters. |
/payments/accounts/{accountID}/balances [GET] getBalances(AccountID, PaymentContext, SalesContext) | Operation returns the balances for the account with the passed ID. For every account there exists at least one type of balance (ACCOUNT_BALANCE). Depending on the account type and contract there might be additional balances available. |
/payments/accounts/{accountID}/payment-instrument [GET] getPaymentInstrument(AccountID, PaymentContext, SalesContext) | |
/payments/payment-instrument-authentications [POST] authenticatePaymentInstrument(PaymentInstrumentAuthenticationRequest, PaymentContext, SalesContext) | Operation can be used to authenticate the usage of a payment instrument. This operation does not authorize any transactions. Its purpose is only to offer a check if a payment instrument can be used. Besides a proper authentication it might also be required to provide a customer confirmation code (2FA). If this is the case then the returned payment instrument authentication state will be "WAITING_FOR_CUSTOMER_CONFIRMATION". |
/payments/payment-instrument-authentications/{authenticationID}/state [GET] getPaymentInstrumentAuthenticationState(PaymentInstrumentAuthenticationID, PaymentContext, SalesContext) | Operation returns the state of the payment instrument authentication with the passed ID. |
/payments/accounts/{accountID}/payment-instruments [POST] createPaymentInstrument(CreatePaymentInstrumentRequest, AccountID, SalesContext) | This operation creates a new payment instrument with the specified properties on an existing Account. Currently, only payment instruments of type IBAN can be created with this operation. The respective Account must be of type "SUBSCRIPTION_CONTRACT_ACCOUNT", but may be in any state. |
/payments/accounts/{accountID}/payment-instruments [GET] queryPaymentInstruments(PaymentInstrumentQuery, AccountID, NOVAContext) | Operation returns all payment instruments of the specified Account. |
/payments:validateIBAN [POST] validateIBAN(IBAN, SalesContext) | Operation validates the passed IBAN. Besides formal checks according to ISO 13616-1:2020 this might also contain further checks that verify if the IBAN might be used in the context of NOVA. |
/payments/accounts/{accountID}/payment-instruments/{paymentInstrumentID} [DELETE] removePaymentInstrument(String, AccountID, NOVAContext) | Operation removes the PaymentInstrument with the given ID from an existing Account. |
/payments/accounts/{accountID}:cancelLatestOpenDeposit [POST] cancelLatestOpenDeposit(AccountID, SalesContext) | This temporary operation cancels the latest open deposit transaction on an Account if there is any. This is an internal operation that only exists as a workaround to enable the implementation of the HTA+ contract refill case and will be removed as soon as possible. |
ch.voev.nova.payment.datatypesNo deprecations published.
ch.voev.nova.payment.servicemodelPaymentService| Operation | Parameter | Description | Deprecated since | Planned to be removed |
|---|---|---|---|---|
cancelLatestOpenDeposit(AccountID, SalesContext) | Will be removed as soon as possible when the workaround for the HTA+ contract refill is obsolete. | PI 2024-10 | PI 2025-04 | |
getAccount(AccountID, PaymentContext, SalesContext) | This endpoint was originally intended but was never used. | 1.1.0 | PI 20 | |
getPaymentInstrument(AccountID, PaymentContext, SalesContext) | Operation will be replaced by "getPaymentInstruments". | PI 20 |
| Type | Attribute | Description | Deprecated since | Planned to be removed |
|---|---|---|---|---|
AbstractPayment | ||||
paymentPositionID | Attribute is obsolete as it would only be required in case that a payment transaction could contain multiple payments. | 1.0.23 | PI 17 | |
AbstractPaymentRequest | ||||
authorizationAmount | The authorization amount will not be required in the future as it can be taken from several sources depending on the concrete payment case. Already now the value is optional in case of coupons that have a percentage discount. | 1.2.0 | PI 19 | |
Account | ||||
balance | Balance will no longer be supported directly on the account. Instead there is a explicit operation to request the balance of an account. Please use operation getBalances(...) / REST request "accounts/{accountID}/balances" instead. | 1.4.0 | PI 19 | |
PaymentTransaction | ||||
organizationCode | Please use information via novaSalesClient instead. | 2.0 | PI 22 | |
novaClientCode | Please use information via novaSalesClient instead. | 2.0 | PI 22 | |
transactionAmount | Please use Payment.paymentAmount instead. | 1.2.0 | PI 19 | |
canceledTransactionID | Please use refundedTransactionID instead. | 1.2.0 | PI 18 | |
PaymentTransactionOutput | ||||
balance | This feature is currently neither specified nor implemented. Even though it's considered to be bad design we already now put it on the interface. Meanwhile it was decided that this feature will never be implemented. | 1.0.22 / 0.3.22 | PI 17 | |
RefundRequest | ||||
payer | 3.0.0 | unused property see for details NOVA-77927 | ||
authorizationAmount | The authorization amount will not be required in the future as it can be taken from several sources depending on the concrete payment case. Already now the value is optional in case of coupons that have a percentage discount. | 1.2.0 | PI 19 | |
UpdateAccountRequest | ||||
startDate | For internal use only. Will be removed as soon as possible. | PI 19 | PI 19 |
| Enumeration | Literal | Description | Deprecated since | Planned to be removed |
|---|---|---|---|---|
PaymentType | ||||
DVF | As soon as we do not support NOVA 14 in parallel to NOVA REST this payment type will be removed. Replacement is type "ACCOUNT". | 0.3.19 | after transition phase to NOVA REST is closed. | |
DVP | As soon as we do not support NOVA 14 in parallel to NOVA REST this payment type will be removed. Replacement is type "ACCOUNT". | 0.3.19 | after transition phase to NOVA REST is closed. |
ch.voev.nova.payment.eventsNo deprecations published.