Payment Method

Payment Method Resource

The Payment Method resource represents a payment method associated with a customer Account. There are two parts to the state associated with this resource, a first generic set of attributes kept by the Kill Bill core subsystem, and another set of attributes kept at the (payment) plugin level.

The payment method resource captures the core Kill Bill attributes. These attributes mostly track the associated payment plugin that is used to interact with the payment gateway as explained below:

Name Type Generated by Description
paymentMethodId string system UUID for this payment method
externalKey string user Optional external key provided by the client
accountId string system UUID for the associated account
isDefault boolean user Indicates whether this is the default payment method
pluginName string user Name of the associated payment plugin.
pluginInfo string user Plugin specific information (see below)
auditLogs array system Array of audit log records for this payment method

All payment operations associated with this payment method will be delegated to the plugin specified by pluginName.

Plugin Details Resource

The Plugin Details Resource object captures plugin specific information. In the case of a credit card for instance, the plugin would keep track of things like name, address, last4, and token. Not only are such attributes dependent on the payment method, but they are also dependent on the third party payment gateway, and on the tokenization model, which is why they are kept by the plugin (internal tables), and not by the Kill Bill core payment subsystem. Thus, it is up to a payment plugin to populate this object correctly via the getPaymentMethodDetail method.

The attributes contained in this resource are the following:

Name Type Generated by Description
externalPaymentMethodId string system UUID for this payment method
isDefaultPaymentMethod boolean system Indicates whether this is the default payment method
properties Array of key-value pairs system Key-value pairs specific to the plugin

Payment Methods

Basic operations to retrieve, list, search and delete payment methods.

Note that the creation of a payment method needs to be done at the Account level using the Add a payment method endpoint.

Retrieve a payment method by id

This API retrieves a payment method resource object based on its payment method ID.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}

Example Request:

curl \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Accept: application/json' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("3c449da6-7ec4-4c74-813f-f5055739a0b9");
Boolean includedDeleted = false; // Will not include deleted
Boolean withPluginInfo = true; // Will include plugin info
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

PaymentMethod paymentMethod = paymentMethodApi.getPaymentMethod(paymentMethodId, 
                                                                    includedDeleted, 
                                                                    withPluginInfo, 
                                                                    NULL_PLUGIN_PROPERTIES, 
                                                                    AuditLevel.NONE, 
                                                                    requestOptions);

payment_method_id = "6a0bf13e-d57f-4f79-84bd-3690135f1923"
included_deleted = false
with_plugin_info = false
audit = "NONE"
plugin_properties = ["key%3Dvalue"]

payment_method = KillBillClient::Model::PaymentMethod.find_by_id(payment_method_id,
                                                                 included_deleted,
                                                                 with_plugin_info,
                                                                 plugin_properties,
                                                                 audit,
                                                                 options)

paymentMethodApi = killbill.api.PaymentMethodApi()

payment_method_id = '83fc2425-ede3-4fbd-b117-2eff4c660cfe'

payment_method = paymentMethodApi.get_payment_method(payment_method_id)

const api: killbill.PaymentMethodApi = new killbill.PaymentMethodApi(config);

const paymentMethodId = '83fc2425-ede3-4fbd-b117-2eff4c660cfe';

const response: AxiosResponse<killbill.PaymentMethod, any> = await api.getPaymentMethod(paymentMethodId, 'NONE');

$apiInstance = $client->getPaymentMethodApi();

$paymentMethodId = "283bae70-a711-47ed-b7d4-040e3ecf8862";
$includedDeleted = false;
$withPluginInfo = false;
$pluginProperty = array("pluginProperty_example");
$audit = "NONE";

$result = $apiInstance->getPaymentMethod($paymentMethodId, $includedDeleted, $withPluginInfo, $pluginProperty, $audit);

Example Response:

{
  "paymentMethodId": "19398506-e8f0-4c60-b504-99f53c3e148d",
  "externalKey": "19398506-e8f0-4c60-b504-99f53c3e148d",
  "accountId": "f271e44f-651c-49b9-bc20-5d54e117b570",
  "isDefault": false,
  "pluginName": "killbill-braintree",
  "pluginInfo": {
    "externalPaymentMethodId": "19398506-e8f0-4c60-b504-99f53c3e148d",
    "isDefaultPaymentMethod": false,
    "properties": [
      {
        "key": "last4",
        "value": "1881",
        "isUpdatable": false
      },
      {
        "key": "commercial",
        "value": "Unknown",
        "isUpdatable": false
      },
      {
        "key": "bin",
        "value": "401288",
        "isUpdatable": false
      },
      {
        "key": "created_at",
        "value": "2023-08-29T11:43:13Z",
        "isUpdatable": false
      },
      {
        "key": "cart_type",
        "value": "Visa",
        "isUpdatable": false
      },
      {
        "key": "verification_status",
        "value": "VERIFIED",
        "isUpdatable": false
      },
      {
        "key": "healthcare",
        "value": "Unknown",
        "isUpdatable": false
      },
      {
        "key": "unique_number_identifier",
        "value": "1d5c9ba24194d854b6c78160160189a0",
        "isUpdatable": false
      },
      {
        "key": "updated_at",
        "value": "2023-08-29T11:43:13Z",
        "isUpdatable": false
      },
      {
        "key": "is_venmo_sdk",
        "value": "false",
        "isUpdatable": false
      },
      {
        "key": "product_id",
        "value": "Unknown",
        "isUpdatable": false
      },
      {
        "key": "issuing_bank",
        "value": "Unknown",
        "isUpdatable": false
      },
      {
        "key": "expiration_month",
        "value": "12",
        "isUpdatable": false
      },
      {
        "key": "debit",
        "value": "Unknown",
        "isUpdatable": false
      },
      {
        "key": "image_url",
        "value": "https://assets.braintreegateway.com/payment_method_logo/visa.png?environment=sandbox",
        "isUpdatable": false
      },
      {
        "key": "prepaid",
        "value": "No",
        "isUpdatable": false
      },
      {
        "key": "is_default",
        "value": "false",
        "isUpdatable": false
      },
      {
        "key": "durbin_regulated",
        "value": "Unknown",
        "isUpdatable": false
      },
      {
        "key": "country_of_issuance",
        "value": "Unknown",
        "isUpdatable": false
      },
      {
        "key": "token",
        "value": "19398506-e8f0-4c60-b504-99f53c3e148d",
        "isUpdatable": false
      },
      {
        "key": "expiration_year",
        "value": "2024",
        "isUpdatable": false
      },
      {
        "key": "is_expired",
        "value": "false",
        "isUpdatable": false
      },
      {
        "key": "customer_location",
        "value": "US",
        "isUpdatable": false
      },
      {
        "key": "is_network_tokenized",
        "value": "false",
        "isUpdatable": false
      },
      {
        "key": "payroll",
        "value": "Unknown",
        "isUpdatable": false
      },
      {
        "key": "customer_id",
        "value": "53223532849",
        "isUpdatable": false
      },
      {
        "key": "bt_customer_id",
        "value": "53223532849",
        "isUpdatable": false
      }
    ]
  },
  "auditLogs": []
}

Query Parameters

Name Type Required Default Description
includedDeleted boolean no false If true, include deleted payment methods
withPluginInfo boolean no false If true, include plugin details (see below)
pluginProperty array of strings no omit list of plugin properties, if any. Should be in the format key%3Dvalue
audit string no "NONE" Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL"

Response

If successful, returns a status code of 200 and a payment method resource object.

Retrieve a payment method by external key

This API retrieves a payment method resource object based on its external key.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentMethods

Example Request:

curl \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Accept: application/json' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/?externalKey=coolPaymentMethod' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

String externalKey = "sample_external_key";
Boolean includedDeleted = false; // Will not include deleted
Boolean withPluginInfo = false; // Will not reflect plugin info
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

PaymentMethod paymentMethod = paymentMethodApi.getPaymentMethodByKey(externalKey, 
                                                                     includedDeleted,
                                                                     withPluginInfo,
                                                                     NULL_PLUGIN_PROPERTIES, 
                                                                     AuditLevel.NONE,
                                                                     requestOptions);

payment_method_key = "sample_external_key"
included_deleted = false
with_plugin_info = false
plugin_properties = ["key%3Dvalue"]
audit = 'NONE'

payment_method = KillBillClient::Model::PaymentMethod.find_by_external_key(payment_method_key,
                                                          included_deleted,
                                                          with_plugin_info,
                                                          plugin_properties,
                                                          audit,
                                                          options)

paymentMethodApi = killbill.api.PaymentMethodApi()

external_key = 'sample_external_key'

payment_method = paymentMethodApi.get_payment_method_by_key(external_key)

const api: killbill.PaymentMethodApi = new killbill.PaymentMethodApi(config);

const key= 'sample_external_key';

const response: AxiosResponse<killbill.PaymentMethod, any> = await api.getPaymentMethodByKey(key,'NONE');

$apiInstance = $client->getPaymentMethodApi();

$externalKey = "sample_external_key";
$includedDeleted = false;
$withPluginInfo = false;
$pluginProperty = array("pluginProperty_example");
$audit = "NONE";

$result = $apiInstance->getPaymentMethodByKey($externalKey, $includedDeleted, $withPluginInfo, $pluginProperty, $audit);

Example Response:

{
    "paymentMethodId":"916619a4-02bb-4d3d-b3da-2584ac897b19",
    "externalKey":"coolPaymentMethod",
    "accountId":"84c7e0d4-a5ed-405f-a655-3ed16ae19997",
    "isDefault":false,
    "pluginName":"__EXTERNAL_PAYMENT__",
    "pluginInfo":null,
    "auditLogs":[]
}

Query Parameters

Name Type Required Default Description
externalKey string yes none External key
includedDeleted boolean no false If true, include deleted payment methods
withPluginInfo boolean no false If true, include plugin details (see below)
pluginProperty array of strings no omit list of plugin properties, if any. Should be in the format key%3Dvalue
audit string no "NONE" Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL"

Response

If successful, returns a status code of 200 and a payment method resource object.

Delete a payment method

This API deletes a payment method. The default payment method may not be deleted, depending on the query parameters.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'X-Killbill-CreatedBy: demo' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19'  

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("3c449da6-7ec4-4c74-813f-f5055739a0b9");
Boolean deleteDefaultPmWithAutoPayOff = true; // Will delete default payment method with auto pay off
Boolean forceDefaultPmDeletion = true; // Will force default payment method deletion
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

paymentMethodApi.deletePaymentMethod(paymentMethodId, 
                                     deleteDefaultPmWithAutoPayOff, 
                                     forceDefaultPmDeletion, 
                                     NULL_PLUGIN_PROPERTIES, 
                                     requestOptions);

user = "demo"
reason = nil
comment = nil

payment_method_id = "71d9c12a-2ace-41e6-84bc-a8b11ff807b8"
set_auto_pay_off = false
force_default_deletion = false
KillBillClient::Model::PaymentMethod.destroy(payment_method_id,
                                             set_auto_pay_off,
                                             force_default_deletion,
                                             user,
                                             reason,
                                             comment,
                                             options)

paymentMethodApi = killbill.api.PaymentMethodApi()

payment_method_id = '0052cddd-0f61-4f68-b653-ca49b5d7f915'

paymentMethodApi.delete_payment_method(payment_method_id,
                                       created_by='demo',
                                       reason='reason',
                                       comment='comment')

const api: killbill.PaymentMethodApi = new killbill.PaymentMethodApi(config);

const paymentMethodId = 'dab6464d-13eb-4702-864c-3d7297bbcf23';

api.deletePaymentMethod(paymentMethodId, 'created_by');

$apiInstance = $client->getPaymentMethodApi();

$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";

$paymentMethodId = "43baa5e3-d300-46ea-91ef-b242d14a4d13";
$deleteDefaultPmWithAutoPayOff = false;
$forceDefaultPmDeletion = false;
$pluginProperty = array("pluginProperty_example");

$apiInstance->deletePaymentMethod($paymentMethodId, $xKillbillCreatedBy, $deleteDefaultPmWithAutoPayOff, $forceDefaultPmDeletion, $pluginProperty, $xKillbillReason, $xKillbillComment);

Query Parameters

Name Type Required Default Description
deleteDefaultPmWithAutoPayOff boolean no false if true, delete default payment method and set AUTO_PAY_OFF if not already set
forceDefaultPmDeletion boolean no false if true, force default payment method deletion
pluginProperty array of strings no omit list of plugin properties, if any. Should be in the format key%3Dvalue

The query parameters determine the behavior if the payment method specified is the default method: If forceDefaultPmDeletion is true, the payment method will be deleted unconditionally. If deleteDefaultPmWithAutoPayOff is true, the payment method will also be deleted, and AUTO_PAY_OFF will be set (if not already). If neither parameter is true, the default payment method will not be deleted (the call will fail).

Response

If successful, returns a status code of 204 and an empty body. If the payment method is the default and cannot be deleted, an error code of 500 and a suitable message will be returned.

These endpoints provide the ability to list and search for payment methods for a specific tenant

List payment methods

List all payment methods stored for the accounts maintained by this tenant

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentMethods/pagination

Example Request:

curl \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Accept: application/json' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/pagination' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

Long offset = 0L;
Long limit = 1L;
String pluginName = null;
Boolean withPluginInfo = false;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;


PaymentMethods allPaymentMethods = paymentMethodApi.getPaymentMethods(offset,
                                                                      limit,
                                                                      pluginName,
                                                                      withPluginInfo,
                                                                      NULL_PLUGIN_PROPERTIES,
                                                                      AuditLevel.NONE,
                                                                      requestOptions);

offset = 0
limit = 100

payment_methods = KillBillClient::Model::PaymentMethod.find_in_batches(offset,
                               limit,
                               options)

paymentMethodApi = killbill.api.PaymentMethodApi()

payment_methods = paymentMethodApi.get_payment_methods()

const api: killbill.PaymentMethodApi = new killbill.PaymentMethodApi(config);

const response: AxiosResponse<killbill.PaymentMethod[], any> = await api.getPaymentMethods();

$apiInstance = $client->getPaymentMethodApi();

$offset = 0;
$limit = 100;
$pluginName = null;
$withPluginInfo = false;
$pluginProperty = array("pluginProperty_example");
$audit = "NONE";

$result = $apiInstance->getPaymentMethods($offset, $limit, $pluginName, $withPluginInfo, $pluginProperty, $audit);

Example Response:

[
  {
    "paymentMethodId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
    "externalKey": "coolPaymentMethod",
    "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
    "isDefault": false,
    "pluginName": "__EXTERNAL_PAYMENT__",
    "pluginInfo": null,
    "auditLogs": []
  },
  {
    "paymentMethodId": "dc89832d-18a3-42fd-b3be-cac074fddb36",
    "externalKey": "paypal",
    "accountId": "ca15adc4-1061-4e54-a9a0-15e773b3b154",
    "isDefault": false,
    "pluginName": "killbill-paypal-express",
    "pluginInfo": null,
    "auditLogs": []
  }
]

Query Parameters

Name Type Required Default Description
offset long no 0 Starting position in list
limit long no 100 Max number of items to return
withPluginInfo boolean no false If true, include plugin details (see below)
pluginName string no all plugins If present, list only payment methods that use this plugin
pluginProperty array of strings no no properties return these properties for this plugin
audit string no "NONE" Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL"

Response

If successful, returns a status code of 200 and a list of payment method resource objects.

Search payment methods

This API searches all payment methods for a specified search string. The search string is compared to the following attributes: externalKey, pluginName. In addition, if the pluginName query parameter is specified, this method can also search plugin specific fields. It is up to a payment plugin to implement the search correctly via the searchPaymentMethods method.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentMethods/search/{searchKey}

Example Request:

curl \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Accept: application/json' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/search/coolPaymentMethod' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

String searchKey = "4365";
Long offset = 0L;
Long limit = 100L;
String pluginName = null;
Boolean withPluginInfo = false;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

List<PaymentMethod> results = paymentMethodApi.searchPaymentMethods(searchKey, 
                                                                    offset, 
                                                                    limit, 
                                                                    pluginName, 
                                                                    withPluginInfo, 
                                                                    NULL_PLUGIN_PROPERTIES,  
                                                                    AuditLevel.NONE,  
                                                                    requestOptions);

search_key = 'example'
offset = 0
limit = 100

payment_methods = KillBillClient::Model::PaymentMethod.find_in_batches_by_search_key(search_key,
                                             offset,
                                             limit,
                                             options)

paymentMethodApi = killbill.api.PaymentMethodApi()

search_key = '__EXTERNAL_PAYMENT__'

payment_methods = paymentMethodApi.search_payment_methods(search_key)

const api: killbill.PaymentMethodApi = new killbill.PaymentMethodApi(config);

const key= 'braintree';

const response: AxiosResponse<killbill.PaymentMethod[], any> = await api.searchPaymentMethods(key);

$apiInstance = $client->getPaymentMethodApi();

$searchKey = "braintree";
$offset = 0;
$limit = 100;
$pluginName = null;
$withPluginInfo = false;
$pluginProperty = array("pluginProperty_example");
$audit = "NONE";

$result = $apiInstance->searchPaymentMethods($searchKey, $offset, $limit, $pluginName, $withPluginInfo, $pluginProperty, $audit);

Example Response:

[
  {
    "paymentMethodId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
    "externalKey": "coolPaymentMethod",
    "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
    "isDefault": false,
    "pluginName": "__EXTERNAL_PAYMENT__",
    "pluginInfo": null,
    "auditLogs": []
  }
]

Query Parameters

Name Type Required Default Description
offset long no 0 Starting position in list
limit long no 100 Max number of items to return
withPluginInfo boolean no false If true, include plugin details (see below)
pluginName string no all plugins If present, list only payment methods that use this plugin
pluginProperty array of strings no no properties return these properties for this plugin
audit string no "NONE" Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL"

Response

If successful, returns a status code of 200 and a list of payment method resource objects that match the search key.

Custom Fields

Custom fields are {key, value} attributes that can be attached to any customer resources. For more on custom fields see Custom Fields. These endpoints manage custom fields associated with PaymentMethod objects.

Add custom fields to a payment method

Adds one or more custom fields to a payment method object. Existing custom fields are not disturbed.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}/customFields

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Content-Type: application/json' \
    -H 'X-Killbill-CreatedBy: demo' \
    -d '[{ 
            "name": "Test Custom Field",
            "value": "test_value"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19/customFields' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("3c449da6-7ec4-4c74-813f-f5055739a0b9");

final List<AuditLog> EMPTY_AUDIT_LOGS = Collections.emptyList();

CustomFields customFields = new CustomFields();
customFields.add(new CustomField(null, 
                                 paymentMethodId, 
                                 ObjectType.PAYMENT_METHOD, 
                                 "Test Custom Field", 
                                 "test_value", 
                                 EMPTY_AUDIT_LOGS));

paymentMethodApi.createPaymentMethodCustomFields(paymentMethodId, 
                                                 customFields, 
                                                 requestOptions);

user = "demo"
reason = nil
comment = nil

payment_method = KillBillClient::Model::PaymentMethod.new
payment_method.payment_method_id = "06e5c871-3caf-41c2-9d7e-30c95f6e309c"

custom_fields = []
custom_field = KillBillClient::Model::CustomFieldAttributes.new
custom_field.name = 'Test Custom Field'
custom_field.value = 'test_value'
custom_fields.push custom_field

payment_method.add_custom_field(custom_fields,
                                user,
                                reason,
                                comment,
                                options)

paymentMethodApi = killbill.api.PaymentMethodApi()

payment_method_id = '34150e56-c1fe-4560-a177-2e1376662e20'
body = CustomField(name='Test Custom Field', value='test_value')

paymentMethodApi.create_payment_method_custom_fields(payment_method_id,
                                                     [body],
                                                     created_by='demo',
                                                     reason='reason',
                                                     comment='comment')

const api: killbill.PaymentMethodApi = new killbill.PaymentMethodApi(config);

const customField: CustomField = {name: "Test Custom Field", value: "test_value"};
const customFields = [customField];

const paymentMethodId = '06e5c871-3caf-41c2-9d7e-30c95f6e309c';

api.createPaymentMethodCustomFields(customFields, paymentMethodId, 'created_by');

$apiInstance = $client->getPaymentMethodApi();

$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";

$customField = new CustomField();
$customField -> setName('Test Custom Field');
$customField -> setValue('test_value');

$body = array($customField);

$paymentMethodId = "06e5c871-3caf-41c2-9d7e-30c95f6e309c";

$result = $apiInstance->createPaymentMethodCustomFields($body, $xKillbillCreatedBy, $paymentMethodId, $xKillbillReason, $xKillbillComment);

Request Body

A list of objects giving the name and value of the custom field, or fields, to be added. For example:

[ { "name": "CF1", "value": "123" } ]

Query Parameters

None.

Response

If successful, returns a 201 status code. In addition, a Location header is returned giving the URL to retrieve the custom fields associated with the payment method.

Retrieve payment method custom fields

Returns any custom field objects associated with the specified payment method

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}/customFields

Example Request:

curl \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Accept: application/json' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19/customFields' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("3c449da6-7ec4-4c74-813f-f5055739a0b9");

List<CustomField> customFields = paymentMethodApi.getPaymentMethodCustomFields(paymentMethodId,
                                                                               AuditLevel.NONE,
                                                                               requestOptions);

payment_method = KillBillClient::Model::PaymentMethod.new
payment_method.payment_method_id = "06e5c871-3caf-41c2-9d7e-30c95f6e309c"

audit = 'NONE'

fields = payment_method.custom_fields(audit, options)

paymentMethodApi = killbill.api.PaymentMethodApi()

payment_method_id = '34150e56-c1fe-4560-a177-2e1376662e20'

fields = paymentMethodApi.get_payment_method_custom_fields(payment_method_id)

const api: killbill.PaymentMethodApi = new killbill.PaymentMethodApi(config);

const paymentMethodId = '06e5c871-3caf-41c2-9d7e-30c95f6e309c';
const audit = 'NONE';

const response: AxiosResponse<killbill.CustomField[], any> = await api.getPaymentMethodCustomFields(paymentMethodId, audit, 'created_by');

$apiInstance = $client->getPaymentMethodApi();

$paymentMethodId = "06e5c871-3caf-41c2-9d7e-30c95f6e309c";
$audit = "NONE";

$result = $apiInstance->getPaymentMethodCustomFields($paymentMethodId, $audit);

Example Response:

[
  {
    "customFieldId": "6d4c073b-fd89-4e39-9802-eba65f42492f",
    "objectId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
    "objectType": "PAYMENT_METHOD",
    "name": "Test Custom Field",
    "value": "test_value",
    "auditLogs": []
  }
]

Query Parameters

Name Type Required Default Description
audit string no "NONE" Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL"

Response

If successful, returns a status code of 200 and a (possibly empty) list of custom field objects.

Modify custom fields for payment method

Modifies the value of one or more existing custom fields associated with a payment method object. Note that it is not possible to modify the name of a custom field, it is only possible to modify its value.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}/customFields

Example Request:

curl -v \
    -X PUT \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Content-Type: application/json' \
    -H 'X-Killbill-CreatedBy: demo' \
    -d '[{ 
            "customFieldId": "6d4c073b-fd89-4e39-9802-eba65f42492f",
            "value": "NewValue"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19/customFields' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("3c449da6-7ec4-4c74-813f-f5055739a0b9");

UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");

CustomField customFieldModified = new CustomField();
customFieldModified.setCustomFieldId(customFieldsId);
customFieldModified.setValue("NewValue");
CustomFields customFields = new CustomFields();
customFields.add(customFieldModified);
paymentMethodApi.modifyPaymentMethodCustomFields(paymentMethodId, 
                                                 customFields, 
                                                 requestOptions);


user = "demo"
reason = nil
comment = nil

payment_method = KillBillClient::Model::PaymentMethod.new
payment_method.payment_method_id = "06e5c871-3caf-41c2-9d7e-30c95f6e309c"

custom_fields = []
custom_field.custom_field_id = '7fb3dde7-0911-4477-99e3-69d142509bb9'
custom_field.value = 'new value'
custom_fields.push custom_field

payment_method.modify_custom_field(custom_fields,
                                   user,
                                   reason,
                                   comment,
                                   options)

paymentMethodApi = killbill.api.PaymentMethodApi()

payment_method_id = '34150e56-c1fe-4560-a177-2e1376662e20'
custom_field_id = '75d6449f-d012-42d8-a9bc-56261a63281f'
body = CustomField(custom_field_id=custom_field_id,
                   name='Test Custom Field',
                   value='new value')

paymentMethodApi.modify_payment_method_custom_fields(payment_method_id,
                                                     [body],
                                                     created_by='demo',
                                                     reason='reason',
                                                     comment='comment')

const api: killbill.PaymentMethodApi = new killbill.PaymentMethodApi(config);

const paymentMethodId = '06e5c871-3caf-41c2-9d7e-30c95f6e309c';

const customField: CustomField = {customFieldId: "8b8374b5-ef9b-4eb1-b820-1b9bde00d277", value: "new_value"};
const customFields = [customField];

api.modifyPaymentMethodCustomFields(customFields, paymentMethodId, 'created_by');

$apiInstance = $client->getPaymentMethodApi();

$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";

$customField = new CustomField();
$customField -> setCustomFieldId('bbfa081a-e7f9-4492-b30f-b77f9fa207da');
$customField -> setValue('new_value');

$body = array($customField);

$paymentMethodId = "06e5c871-3caf-41c2-9d7e-30c95f6e309c";

$apiInstance->modifyPaymentMethodCustomFields($body, $xKillbillCreatedBy, $paymentMethodId, $xKillbillReason, $xKillbillComment);

Request Body

A list of objects specifying the id and the new value for the custom fields to be modified. For example:

[ { "customFieldId": "6d4c073b-fd89-4e39-9802-eba65f42492f", "value": "123" } ]

Although the fieldName and objectType can be specified in the request body, these cannot be modified, only the field value can be modified.

Query Parameters

None.

Response

If successful, a status code of 204 and an empty body.

Remove custom fields from payment method

Delete one or more custom fields from a payment method. It accepts query parameters corresponding to the custom field ids to be deleted. If no query parameters are specified, it deletes all the custom fields corresponding to the payment method.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}/customFields

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'X-Killbill-CreatedBy: demo' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/77e23878-8b9d-403b-bf31-93003e125712/customFields?customField=439ed0f8-9b37-4688-bace-e2595b1d3801' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("3c449da6-7ec4-4c74-813f-f5055739a0b9");
UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");
List<UUID> customFieldsList = List.of(customFieldsId);
paymentMethodApi.deletePaymentMethodCustomFields(paymentMethodId, 
                                                 customFieldsList, 
                                                 requestOptions);

user = "demo"
reason = nil
comment = nil

payment_method = KillBillClient::Model::PaymentMethod.new
payment_method.payment_method_id = "06e5c871-3caf-41c2-9d7e-30c95f6e309c"

custom_field_ids = []
custom_field_id = 'cda969c3-1092-4702-b155-05d0ef899fa2'
custom_field_ids.push custom_field_id

payment_method.remove_custom_field(custom_field_ids,
                                   user,
                                   reason,
                                   comment,
                                   options)

paymentMethodApi = killbill.api.PaymentMethodApi()

payment_method_id = '34150e56-c1fe-4560-a177-2e1376662e20'

custom_fields = ['0ef3863d-1d3f-4b18-a795-9bb6b68cef83']

paymentMethodApi.delete_payment_method_custom_fields(payment_method_id,
                                                     custom_field=custom_fields,
                                                     created_by='demo',
                                                     reason='reason',
                                                     comment='comment')

const api: killbill.PaymentMethodApi = new killbill.PaymentMethodApi(config);

const paymentMethodId = '06e5c871-3caf-41c2-9d7e-30c95f6e309c';

const customField = '8b8374b5-ef9b-4eb1-b820-1b9bde00d277';
const customFields = [customField];

api.deletePaymentMethodCustomFields(paymentMethodId, 'created_by', customFields);

$apiInstance = $client->getPaymentMethodApi();

$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";

$paymentMethodId = "06e5c871-3caf-41c2-9d7e-30c95f6e309c";
$customFields = array("5319cbff-c348-44ae-af91-fb3a4f1ab117");

$apiInstance->deletePaymentMethodCustomFields($paymentMethodId, $xKillbillCreatedBy, $customFields, $xKillbillReason, $xKillbillComment);

Query Parameters

Name Type Required Default Description
customField string yes none Custom field ID that should be deleted. Multiple custom fields can be deleted by specifying a separate customField parameter corresponding to each field.

Response

If successful, returns a status code of 204 and an empty body.

Audit Logs

This endpoint enables access to payment method audit logs. For details on audit logs see Audit and History.

Retrieve payment method audit logs with history by id

Retrieve a list of audit log records showing changes to the payment method. History information (a copy of the full payment method object) is included with each record.

Some examples:

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}/auditLogsWithHistory

Example Request:

curl \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Accept: application/json' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19/auditLogsWithHistory' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("e9d95f16-a426-46d0-b76b-90814792fb36");

List<AuditLog> auditLog = paymentMethodApi.getPaymentMethodAuditLogsWithHistory(paymentMethodId, requestOptions);

paymentMethodApi = killbill.api.PaymentMethodApi()

payment_method_id = '34150e56-c1fe-4560-a177-2e1376662e20'

audit_logs = paymentMethodApi.get_payment_method_audit_logs_with_history(payment_method_id)

payment_method = KillBillClient::Model::PaymentMethod.new
payment_method.payment_method_id = "06e5c871-3caf-41c2-9d7e-30c95f6e309c"

audit_logs = payment_method.audit_logs_with_history(options)

const api: killbill.PaymentMethodApi = new killbill.PaymentMethodApi(config);

const paymentMethodId = '06e5c871-3caf-41c2-9d7e-30c95f6e309c';

const response: AxiosResponse<killbill.AuditLog[], any> = await api.getPaymentMethodAuditLogsWithHistory(paymentMethodId);

$apiInstance = $client->getPaymentMethodApi();

$paymentMethodId = "06e5c871-3caf-41c2-9d7e-30c95f6e309c";

$result = $apiInstance->getPaymentMethodAuditLogsWithHistory($paymentMethodId);

Example Response:

[
  {
    "changeType": "INSERT",
    "changeDate": "2023-09-30T09:22:48.000Z",
    "objectType": "PAYMENT_METHOD",
    "objectId": "d15679bd-527d-46e1-8141-e20d74572cdf",
    "changedBy": "admin",
    "reasonCode": null,
    "comments": null,
    "userToken": "fdb63796-38a6-4420-a94b-1dc479d75ad4",
    "history": {
      "id": null,
      "createdDate": "2023-09-30T09:22:48.000Z",
      "updatedDate": "2023-09-30T09:22:48.000Z",
      "recordId": 22,
      "accountRecordId": 2,
      "tenantRecordId": 1,
      "externalKey": "d15679bd-527d-46e1-8141-e20d74572cdf",
      "accountId": "544d269c-8a66-40c3-9abd-e3dddd4a016c",
      "pluginName": "__EXTERNAL_PAYMENT__",
      "isActive": true,
      "tableName": "PAYMENT_METHODS",
      "historyTableName": "PAYMENT_METHOD_HISTORY",
      "active": true
    }
  },
  {
    "changeType": "DELETE",
    "changeDate": "2023-09-30T09:25:49.000Z",
    "objectType": "PAYMENT_METHOD",
    "objectId": "d15679bd-527d-46e1-8141-e20d74572cdf",
    "changedBy": "admin",
    "reasonCode": null,
    "comments": null,
    "userToken": "e076ca73-1b25-4e9f-8a0b-2d58324cdd94",
    "history": {
      "id": null,
      "createdDate": "2023-09-30T09:25:49.000Z",
      "updatedDate": "2023-09-30T09:25:49.000Z",
      "recordId": 22,
      "accountRecordId": 2,
      "tenantRecordId": 1,
      "externalKey": "d15679bd-527d-46e1-8141-e20d74572cdf",
      "accountId": "544d269c-8a66-40c3-9abd-e3dddd4a016c",
      "pluginName": "__EXTERNAL_PAYMENT__",
      "isActive": false,
      "tableName": "PAYMENT_METHODS",
      "historyTableName": "PAYMENT_METHOD_HISTORY",
      "active": false
    }
  }
]

Query Parameters

None.

Returns

If successful, returns a status code of 200 and a list of payment method audit logs with history.