org.killbill.billing.payment.api

Interface PaymentApi

All Superinterfaces:

KillbillApi

public interface PaymentApi
extends KillbillApi

Method Summary

Methods

Modifier and Type	Method and Description
UUID	addPaymentMethod(Account account, String paymentMethodExternalKey, String pluginName, boolean setDefault, PaymentMethodPlugin paymentMethodInfo, Iterable<PluginProperty> properties, CallContext context)
Payment	createAuthorization(Account account, UUID paymentMethodId, UUID paymentId, BigDecimal amount, Currency currency, String paymentExternalKey, String paymentTransactionExternalKey, Iterable<PluginProperty> properties, CallContext context) Authorize a payment.
Payment	createCapture(Account account, UUID paymentId, BigDecimal amount, Currency currency, String paymentTransactionExternalKey, Iterable<PluginProperty> properties, CallContext context) Capture a previously authorized payment.
Payment	createChargeback(Account account, UUID paymentId, BigDecimal amount, Currency currency, String paymentTransactionExternalKey, CallContext context) Record a chargeback
Payment	createChargebackWithPaymentControl(Account account, UUID paymentId, BigDecimal amount, Currency currency, String paymentTransactionExternalKey, PaymentOptions paymentOptions, CallContext context) Record a chargeback
Payment	createCredit(Account account, UUID paymentMethodId, UUID paymentId, BigDecimal amount, Currency currency, String paymentExternalKey, String paymentTransactionExternalKey, Iterable<PluginProperty> properties, CallContext context) Credit a payment method.
Payment	createPurchase(Account account, UUID paymentMethodId, UUID paymentId, BigDecimal amount, Currency currency, String paymentExternalKey, String paymentTransactionExternalKey, Iterable<PluginProperty> properties, CallContext context) Combine an authorize and capture payment.
Payment	createPurchaseWithPaymentControl(Account account, UUID paymentMethodId, UUID paymentId, BigDecimal amount, Currency currency, String paymentExternalKey, String paymentTransactionExternalKey, Iterable<PluginProperty> properties, PaymentOptions paymentOptions, CallContext context) Combine an authorize and capture payment.
Payment	createRefund(Account account, UUID paymentId, BigDecimal amount, Currency currency, String paymentTransactionExternalKey, Iterable<PluginProperty> properties, CallContext context) Refund a previously captured payment.
Payment	createRefundWithPaymentControl(Account account, UUID paymentId, BigDecimal amount, Currency currency, String paymentTransactionExternalKey, Iterable<PluginProperty> properties, PaymentOptions paymentOptions, CallContext context) Refund a previously captured payment.
Payment	createVoid(Account account, UUID paymentId, String paymentTransactionExternalKey, Iterable<PluginProperty> properties, CallContext context) Void a previously authorized payment.
void	deletePaymentMethod(Account account, UUID paymentMethodId, boolean deleteDefaultPaymentMethodWithAutoPayOff, Iterable<PluginProperty> properties, CallContext context)
List<PaymentMethod>	getAccountPaymentMethods(UUID accountId, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context)
List<Payment>	getAccountPayments(UUID accountId, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context)
Payment	getPayment(UUID paymentId, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context)
Payment	getPaymentByExternalKey(String paymentExternalKey, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context)
PaymentMethod	getPaymentMethodByExternalKey(String paymentMethodExternalKey, boolean includedInactive, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context)
PaymentMethod	getPaymentMethodById(UUID paymentMethodId, boolean includedInactive, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context)
Pagination<PaymentMethod>	getPaymentMethods(Long offset, Long limit, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context) Find all payment methods across all plugins
Pagination<PaymentMethod>	getPaymentMethods(Long offset, Long limit, String pluginName, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context) Find all payment methods in a given plugin
Pagination<Payment>	getPayments(Long offset, Long limit, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context) Find all payments across all plugins
Pagination<Payment>	getPayments(Long offset, Long limit, String pluginName, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context) Find all payments in a given plugin
Payment	notifyPendingTransactionOfStateChanged(Account account, UUID paymentTransactionId, boolean isSuccess, CallContext context) Transition a currently PENDING transaction into either a SUCCESS or a FAILURE
Payment	notifyPendingTransactionOfStateChangedWithPaymentControl(Account account, UUID paymentTransactionId, boolean isSuccess, PaymentOptions paymentOptions, CallContext context) Transition a currently PENDING transaction into either a SUCCESS or a FAILURE
List<PaymentMethod>	refreshPaymentMethods(Account account, Iterable<PluginProperty> properties, CallContext context) Refresh all payment methods across all plugins This call is not atomic.
List<PaymentMethod>	refreshPaymentMethods(Account account, String pluginName, Iterable<PluginProperty> properties, CallContext context)
Pagination<PaymentMethod>	searchPaymentMethods(String searchKey, Long offset, Long limit, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context) Find all payment methods matching the search key across all plugins The match will be plugin specific: for instance some plugins will try to match the key against the last 4 credit cards digits, agreement ids, etc.
Pagination<PaymentMethod>	searchPaymentMethods(String searchKey, Long offset, Long limit, String pluginName, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context) Find all payment methods matching the search key in a given plugin The match will be plugin specific: for instance some plugins will try to match the key against the last 4 credit cards digits, agreement ids, etc.
Pagination<Payment>	searchPayments(String searchKey, Long offset, Long limit, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context) Find all payments matching the search key across all plugins The match will be plugin specific: for instance some plugins will try to match the key against the transaction ids, etc.
Pagination<Payment>	searchPayments(String searchKey, Long offset, Long limit, String pluginName, boolean withPluginInfo, Iterable<PluginProperty> properties, TenantContext context) Find all payments matching the search key in a given plugin The match will be plugin specific: for instance some plugins will try to match the key against the transaction ids, etc.
void	setDefaultPaymentMethod(Account account, UUID paymentMethodId, Iterable<PluginProperty> properties, CallContext context)

Method Detail

createAuthorization

Payment createAuthorization(Account account,
                          UUID paymentMethodId,
                          UUID paymentId,
                          BigDecimal amount,
                          Currency currency,
                          String paymentExternalKey,
                          String paymentTransactionExternalKey,
                          Iterable<PluginProperty> properties,
                          CallContext context)
                            throws PaymentApiException

Authorize a payment.

Parameters:

account - the account

paymentMethodId - the payment method id to use

paymentId - the payment id (non-null for multi-steps flows, such as 3D Secure)

amount - the amount to pay

currency - the amount currency

paymentExternalKey - the payment external key

paymentTransactionExternalKey - the payment transaction external key

properties - plugin specific properties

context - the call context

Returns:

the payment

Throws:

PaymentApiException

createCapture

Payment createCapture(Account account,
                    UUID paymentId,
                    BigDecimal amount,
                    Currency currency,
                    String paymentTransactionExternalKey,
                    Iterable<PluginProperty> properties,
                    CallContext context)
                      throws PaymentApiException

Capture a previously authorized payment.

Parameters:

account - the account

amount - the amount to pay

currency - the amount currency

paymentTransactionExternalKey - the payment transaction external key

properties - plugin specific properties

context - the call context

Returns:

the payment

Throws:

PaymentApiException

createPurchase

Payment createPurchase(Account account,
                     UUID paymentMethodId,
                     UUID paymentId,
                     BigDecimal amount,
                     Currency currency,
                     String paymentExternalKey,
                     String paymentTransactionExternalKey,
                     Iterable<PluginProperty> properties,
                     CallContext context)
                       throws PaymentApiException

Combine an authorize and capture payment.

Parameters:

account - the account

paymentMethodId - the payment method id to use

paymentId - the payment id (non-null for multi-steps flows, such as 3D Secure)

amount - the amount to pay

currency - the amount currency

paymentExternalKey - the payment external key

paymentTransactionExternalKey - the payment transaction external key

properties - plugin specific properties

context - the call context

Returns:

the payment

Throws:

PaymentApiException

createPurchaseWithPaymentControl

Payment createPurchaseWithPaymentControl(Account account,
                                       UUID paymentMethodId,
                                       UUID paymentId,
                                       BigDecimal amount,
                                       Currency currency,
                                       String paymentExternalKey,
                                       String paymentTransactionExternalKey,
                                       Iterable<PluginProperty> properties,
                                       PaymentOptions paymentOptions,
                                       CallContext context)
                                         throws PaymentApiException

Combine an authorize and capture payment.

Parameters:

account - the account

paymentMethodId - the payment method id to use

paymentId - the payment id (non-null for multi-steps flows, such as 3D Secure)

amount - the amount to pay

currency - the amount currency

paymentExternalKey - the payment external key

paymentTransactionExternalKey - the payment transaction external key

properties - plugin specific properties

paymentOptions - options to control payment behavior

context - the call context

Returns:

the payment

Throws:

PaymentApiException

createVoid

Payment createVoid(Account account,
                 UUID paymentId,
                 String paymentTransactionExternalKey,
                 Iterable<PluginProperty> properties,
                 CallContext context)
                   throws PaymentApiException

Void a previously authorized payment.

Parameters:

account - the account

paymentId - the payment id

paymentTransactionExternalKey - the payment transaction external key

properties - plugin specific properties

context - the call context

Returns:

the payment

Throws:

PaymentApiException

createRefund

Payment createRefund(Account account,
                   UUID paymentId,
                   BigDecimal amount,
                   Currency currency,
                   String paymentTransactionExternalKey,
                   Iterable<PluginProperty> properties,
                   CallContext context)
                     throws PaymentApiException

Refund a previously captured payment.

Parameters:

account - the account

paymentId - the payment id

amount - the amount to refund

currency - the amount currency

paymentTransactionExternalKey - the payment transaction external key

properties - plugin specific properties

context - the call context

Returns:

the payment

Throws:

PaymentApiException

createRefundWithPaymentControl

Payment createRefundWithPaymentControl(Account account,
                                     UUID paymentId,
                                     BigDecimal amount,
                                     Currency currency,
                                     String paymentTransactionExternalKey,
                                     Iterable<PluginProperty> properties,
                                     PaymentOptions paymentOptions,
                                     CallContext context)
                                       throws PaymentApiException

Refund a previously captured payment.

Parameters:

account - the account

paymentId - the payment id

amount - the amount to refund

currency - the amount currency

paymentTransactionExternalKey - the payment transaction external key

properties - plugin specific properties

paymentOptions - options to control payment behavior

context - the call context

Returns:

the payment

Throws:

PaymentApiException

createCredit

Payment createCredit(Account account,
                   UUID paymentMethodId,
                   UUID paymentId,
                   BigDecimal amount,
                   Currency currency,
                   String paymentExternalKey,
                   String paymentTransactionExternalKey,
                   Iterable<PluginProperty> properties,
                   CallContext context)
                     throws PaymentApiException

Credit a payment method.

This is also known as payment in reverse.

Parameters:

account - the account

paymentMethodId - the payment method id to use

paymentId - the payment id (non-null for multi-steps flows)

amount - the amount to credit

currency - the amount currency

paymentExternalKey - the payment external key

paymentTransactionExternalKey - the payment transaction external key

properties - plugin specific properties

context - the call context

Returns:

the payment

Throws:

PaymentApiException

createChargeback

Payment createChargeback(Account account,
                       UUID paymentId,
                       BigDecimal amount,
                       Currency currency,
                       String paymentTransactionExternalKey,
                       CallContext context)
                         throws PaymentApiException

Record a chargeback

Parameters:

account - the account

paymentId - the payment id

paymentTransactionExternalKey - the chargeback external key

amount - the amount to chargeback

currency - the amount currency

context - the call context

Returns:

the payment

Throws:

PaymentApiException

createChargebackWithPaymentControl

Payment createChargebackWithPaymentControl(Account account,
                                         UUID paymentId,
                                         BigDecimal amount,
                                         Currency currency,
                                         String paymentTransactionExternalKey,
                                         PaymentOptions paymentOptions,
                                         CallContext context)
                                           throws PaymentApiException

Record a chargeback

Parameters:

account - the account

paymentId - the payment id

paymentTransactionExternalKey - the chargeback external key

amount - the amount to chargeback

currency - the amount currency

paymentOptions - options to control payment behavior

context - the call context

Returns:

the payment

Throws:

PaymentApiException

notifyPendingTransactionOfStateChanged

Payment notifyPendingTransactionOfStateChanged(Account account,
                                             UUID paymentTransactionId,
                                             boolean isSuccess,
                                             CallContext context)
                                               throws PaymentApiException

Transition a currently PENDING transaction into either a SUCCESS or a FAILURE

Parameters:

account - the account

paymentTransactionId - the transaction id

isSuccess - whether the transaction is successful or not

context - the call context

Returns:

the payment

Throws:

PaymentApiException

notifyPendingTransactionOfStateChangedWithPaymentControl

Payment notifyPendingTransactionOfStateChangedWithPaymentControl(Account account,
                                                               UUID paymentTransactionId,
                                                               boolean isSuccess,
                                                               PaymentOptions paymentOptions,
                                                               CallContext context)
                                                                 throws PaymentApiException

Transition a currently PENDING transaction into either a SUCCESS or a FAILURE

Parameters:

account - the account

paymentTransactionId - the transaction id

isSuccess - whether the transaction is successful or not

paymentOptions - options to control payment behavior

context - the call context

Returns:

the payment

Throws:

PaymentApiException

getAccountPayments

List<Payment> getAccountPayments(UUID accountId,
                               boolean withPluginInfo,
                               Iterable<PluginProperty> properties,
                               TenantContext context)
                                 throws PaymentApiException

Parameters:

accountId - the account id

withPluginInfo - whether to fetch plugin info

properties - plugin specific properties

context - the call context

Returns:

the list of payments on this account

Throws:

PaymentApiException

getPayment

Payment getPayment(UUID paymentId,
                 boolean withPluginInfo,
                 Iterable<PluginProperty> properties,
                 TenantContext context)
                   throws PaymentApiException

Parameters:

paymentId - the payment id

withPluginInfo - whether to fetch plugin info

properties - plugin specific properties

context - the call context

Returns:

the payment

Throws:

PaymentApiException

getPaymentByExternalKey

Payment getPaymentByExternalKey(String paymentExternalKey,
                              boolean withPluginInfo,
                              Iterable<PluginProperty> properties,
                              TenantContext context)
                                throws PaymentApiException

Parameters:

paymentExternalKey - the payment external key

withPluginInfo - whether to fetch plugin info

properties - plugin specific properties

context - the call context

Returns:

the payment

Throws:

PaymentApiException

getPayments

Pagination<Payment> getPayments(Long offset,
                              Long limit,
                              boolean withPluginInfo,
                              Iterable<PluginProperty> properties,
                              TenantContext context)

Find all payments across all plugins

Parameters:

offset - the offset of the first result

limit - the maximum number of results to retrieve

withPluginInfo - whether to fetch plugin info

properties - plugin specific properties

context - the user context

Returns:

the list of payments for that tenant

getPayments

Pagination<Payment> getPayments(Long offset,
                              Long limit,
                              String pluginName,
                              boolean withPluginInfo,
                              Iterable<PluginProperty> properties,
                              TenantContext context)
                                throws PaymentApiException

Find all payments in a given plugin

Parameters:

offset - the offset of the first result

limit - the maximum number of results to retrieve

pluginName - the payment plugin name

withPluginInfo - whether to fetch plugin info

properties - plugin specific properties

context - the user context

Returns:

the list of payments for that tenant

Throws:

PaymentApiException

searchPayments

Pagination<Payment> searchPayments(String searchKey,
                                 Long offset,
                                 Long limit,
                                 boolean withPluginInfo,
                                 Iterable<PluginProperty> properties,
                                 TenantContext context)

Find all payments matching the search key across all plugins

The match will be plugin specific: for instance some plugins will try to match the key against the transaction ids, etc.

Parameters:

searchKey - the search key

offset - the offset of the first result

limit - the maximum number of results to retrieve

withPluginInfo - whether to fetch plugin info

properties - plugin specific properties

context - the user context

Returns:

the list of payments matching this search key for that tenant

searchPayments

Pagination<Payment> searchPayments(String searchKey,
                                 Long offset,
                                 Long limit,
                                 String pluginName,
                                 boolean withPluginInfo,
                                 Iterable<PluginProperty> properties,
                                 TenantContext context)
                                   throws PaymentApiException

Find all payments matching the search key in a given plugin

The match will be plugin specific: for instance some plugins will try to match the key against the transaction ids, etc.

Parameters:

searchKey - the search key

offset - the offset of the first result

limit - the maximum number of results to retrieve

pluginName - the payment plugin name

withPluginInfo - whether to fetch plugin info

properties - plugin specific properties

context - the user context

Returns:

the list of payments matching this search key for that tenant

Throws:

PaymentApiException

addPaymentMethod

UUID addPaymentMethod(Account account,
                    String paymentMethodExternalKey,
                    String pluginName,
                    boolean setDefault,
                    PaymentMethodPlugin paymentMethodInfo,
                    Iterable<PluginProperty> properties,
                    CallContext context)
                      throws PaymentApiException

Parameters:

account - the account

paymentMethodExternalKey - the external key

pluginName - the plugin name

setDefault - whether this should be set as a default payment method

paymentMethodInfo - the details for the payment method

properties - plugin specific properties

context - the call context

Returns:

the uuid of the payment method

Throws:

PaymentApiException

getAccountPaymentMethods

List<PaymentMethod> getAccountPaymentMethods(UUID accountId,
                                           boolean withPluginInfo,
                                           Iterable<PluginProperty> properties,
                                           TenantContext context)
                                             throws PaymentApiException

Parameters:

accountId - the account id

withPluginInfo - whether we want to retrieve the plugin info for that payment method

properties - plugin specific properties

context - the call context

Returns:

the list of payment methods

Throws:

PaymentApiException

getPaymentMethodById

PaymentMethod getPaymentMethodById(UUID paymentMethodId,
                                 boolean includedInactive,
                                 boolean withPluginInfo,
                                 Iterable<PluginProperty> properties,
                                 TenantContext context)
                                   throws PaymentApiException

Parameters:

paymentMethodId - the payment method id

includedInactive - returns the payment method even if this is not active

withPluginInfo - whether we want to retrieve the plugin info for that payment method

properties - plugin specific properties

context - the call context @return the payment method

Throws:

PaymentApiException

getPaymentMethodByExternalKey

PaymentMethod getPaymentMethodByExternalKey(String paymentMethodExternalKey,
                                          boolean includedInactive,
                                          boolean withPluginInfo,
                                          Iterable<PluginProperty> properties,
                                          TenantContext context)
                                            throws PaymentApiException

Parameters:

paymentMethodExternalKey - the payment method external key

includedInactive - returns the payment method even if this is not active

withPluginInfo - whether we want to retrieve the plugin info for that payment method

properties - plugin specific properties

context - the call context @return the payment method

Throws:

PaymentApiException

getPaymentMethods

Pagination<PaymentMethod> getPaymentMethods(Long offset,
                                          Long limit,
                                          boolean withPluginInfo,
                                          Iterable<PluginProperty> properties,
                                          TenantContext context)

Find all payment methods across all plugins

Parameters:

offset - the offset of the first result

limit - the maximum number of results to retrieve

withPluginInfo - whether to fetch plugin info

properties - plugin specific properties

context - the user context

Returns:

the list of payment methods for that tenant

getPaymentMethods

Pagination<PaymentMethod> getPaymentMethods(Long offset,
                                          Long limit,
                                          String pluginName,
                                          boolean withPluginInfo,
                                          Iterable<PluginProperty> properties,
                                          TenantContext context)
                                            throws PaymentApiException

Find all payment methods in a given plugin

Parameters:

offset - the offset of the first result

limit - the maximum number of results to retrieve

pluginName - the payment plugin name

withPluginInfo - whether to fetch plugin info

properties - plugin specific properties

context - the user context

Returns:

the list of payment methods for that tenant

Throws:

PaymentApiException

searchPaymentMethods

Pagination<PaymentMethod> searchPaymentMethods(String searchKey,
                                             Long offset,
                                             Long limit,
                                             boolean withPluginInfo,
                                             Iterable<PluginProperty> properties,
                                             TenantContext context)

Find all payment methods matching the search key across all plugins

The match will be plugin specific: for instance some plugins will try to match the key against the last 4 credit cards digits, agreement ids, etc.

Parameters:

searchKey - the search key

offset - the offset of the first result

limit - the maximum number of results to retrieve

withPluginInfo - whether to fetch plugin info

properties - plugin specific properties

context - the user context

Returns:

the list of payment methods matching this search key for that tenant

searchPaymentMethods

Pagination<PaymentMethod> searchPaymentMethods(String searchKey,
                                             Long offset,
                                             Long limit,
                                             String pluginName,
                                             boolean withPluginInfo,
                                             Iterable<PluginProperty> properties,
                                             TenantContext context)
                                               throws PaymentApiException

Find all payment methods matching the search key in a given plugin

The match will be plugin specific: for instance some plugins will try to match the key against the last 4 credit cards digits, agreement ids, etc.

Parameters:

searchKey - the search key

offset - the offset of the first result

limit - the maximum number of results to retrieve

pluginName - the payment plugin name

withPluginInfo - whether to fetch plugin info

properties - plugin specific properties

context - the user context

Returns:

the list of payment methods matching this search key for that tenant

Throws:

PaymentApiException

deletePaymentMethod

void deletePaymentMethod(Account account,
                       UUID paymentMethodId,
                       boolean deleteDefaultPaymentMethodWithAutoPayOff,
                       Iterable<PluginProperty> properties,
                       CallContext context)
                         throws PaymentApiException

Parameters:

account - the account

paymentMethodId - the id of the payment method

deleteDefaultPaymentMethodWithAutoPayOff - whether to allow deletion of default payment method and set account into AUTO_PAY_OFF

properties - plugin specific properties

context - the call context

Throws:

PaymentApiException

setDefaultPaymentMethod

void setDefaultPaymentMethod(Account account,
                           UUID paymentMethodId,
                           Iterable<PluginProperty> properties,
                           CallContext context)
                             throws PaymentApiException

Parameters:

account - the account

paymentMethodId - the payment method id

properties - plugin specific properties

context - the call context

Throws:

PaymentApiException

refreshPaymentMethods

List<PaymentMethod> refreshPaymentMethods(Account account,
                                        String pluginName,
                                        Iterable<PluginProperty> properties,
                                        CallContext context)
                                          throws PaymentApiException

Parameters:

account - the account

pluginName - the name of the plugin

properties - plugin specific properties

context - the call context

Returns:

the list of payment methods for that account

Throws:

PaymentApiException

refreshPaymentMethods

List<PaymentMethod> refreshPaymentMethods(Account account,
                                        Iterable<PluginProperty> properties,
                                        CallContext context)
                                          throws PaymentApiException

Refresh all payment methods across all plugins

This call is not atomic.

Parameters:

account - the account

properties - plugin specific properties

context - the call context

Returns:

the list of payment methods for that account

Throws:

PaymentApiException