Payment Transaction

Payment transactions belong to a Payment object.

They represent a particular payment operation, such as authorization, chargeback, refund, etc. Most operations happen at the Payment level, but there are a few endpoints that work directly at the transaction level.

Payment Transaction Resource

A PaymentTransaction is represented by a PaymentTransaction resource object. The attributes for this resource object are as follows:

Name Type Generated by Description
transactionId string system UUID for the transaction
transactionExternalKey string user or system Optional external key
paymentId string system UUID for the payment
paymentExternalKey string user or system Optional external key
transactionType string user Transaction type (see below)
amount number system Total amount of the transaction
currency string user or system Currency associated with the account
effectiveDate string user Effective date of the transaction
processedAmount number system The amount processed by the gateway (see below)
processedCurrency string system The currency processed by the gateay (see below)
status string system Transaction status (see below)
gatewayErrorCode string system Error code returned by the payment gateway
gatewayErrorMsg string system Error message returned by the payment gateway
firstPaymentReferenceId string system Payment gateway reference
secondPaymentReferenceId string system see below
properties string user see below
auditlogs array system Array of audit log records for this invoice

Payment Transactions

Endpoints to retrieve a PaymentTransaction object or to set the status of a pending transaction. Note that endpoints to generate payment transactions are provided with the Payment APIs.

Retrieve a payment by transaction id

Retrieves a Payment resource object based on a PaymentTransaction id.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}

Example Request:

curl -v \
    -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/paymentTransactions/07655b3c-7f17-4172-b193-ece48e5741ad"

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("41f4d299-4371-4876-96b4-0b3cc81b246b");
Map<String, String> NULL_PLUGIN_PROPERTIES = null;
Payment payment = paymentTransactionApi.getPaymentByTransactionId(paymentTransactionId, NULL_PLUGIN_PROPERTIES, requestOptions);

payment_transaction_id = "e5f000f7-0733-4828-a887-3a4a58d27596"
with_attempts = false
with_plugin_info = false
plugin_properties = ["key%3Dvalue"]
audit = "NONE"

payment = KillBillClient::Model::Payment.find_by_transaction_id(payment_transaction_id, with_attempts, with_plugin_info, plugin_properties, audit, options)

paymentTransactionApi = killbill.PaymentTransactionApi()

payment_transaction_id = 'edb52a56-f5d2-4285-9a23-ccafb6f1ae1f'

payment = paymentTransactionApi.get_payment_by_transaction_id(payment_transaction_id)

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

const paymentTransactionId = '37b95fef-f5be-4771-80e4-d41af8e528cb';

const response: AxiosResponse<killbill.Payment, any> = await api.getPaymentByTransactionId(paymentTransactionId, 'NONE');

$apiInstance = $client->getPaymentTransactionApi();

$transactionId = "37b95fef-f5be-4771-80e4-d41af8e528cb";
$withPluginInfo = false;
$withAttempts = false;
$pluginProperty = array("pluginProperty_example");
$audit = "NONE";

$result = $apiInstance->getPaymentByTransactionId($transactionId, $withPluginInfo, $withAttempts, $pluginProperty, $audit);

Example Response:

{
  "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
  "paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
  "paymentNumber": "47",
  "paymentExternalKey": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
  "authAmount": 0,
  "capturedAmount": 0,
  "purchasedAmount": 0,
  "refundedAmount": 0,
  "creditedAmount": 0,
  "currency": "USD",
  "paymentMethodId": "c02fa9b0-ae95-42ae-9010-bc11cb160947",
  "transactions": [
    {
      "transactionId": "07655b3c-7f17-4172-b193-ece48e5741ad",
      "transactionExternalKey": "07655b3c-7f17-4172-b193-ece48e5741ad",
      "paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
      "paymentExternalKey": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
      "transactionType": "AUTHORIZE",
      "amount": 0,
      "currency": "USD",
      "effectiveDate": "2018-07-18T18:58:11.000Z",
      "processedAmount": 0,
      "processedCurrency": "USD",
      "status": "SUCCESS",
      "gatewayErrorCode": null,
      "gatewayErrorMsg": null,
      "firstPaymentReferenceId": null,
      "secondPaymentReferenceId": null,
      "properties": null,
      "auditLogs": []
    }
  ],
  "paymentAttempts": null,
  "auditLogs": []
}

Query Parameters

Name Type Required Default Description
withPluginInfo boolean no false If true, include plugin info. This results in the PaymentPluginApi.getPaymentInfo method being invoked for the underlying payment plugin. See Payment Plugin Tutorial.
withAttempts boolean no false if true, include payment attempts
pluginProperty array of strings false omit list of plugin properties, if any
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 object including the specified transaction.

Retrieve a payment transaction by external key

Retrieves a Payment resource object based on a PaymentTransaction external key.

HTTP Request

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

Example Request:

curl -v \
    -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/paymentTransactions?transactionExternalKey=07655b3c-7f17-4172-b193-ece48e5741ad"

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

String transactionExternalKey = "41f4d299-4371-4876-96b4-0b3cc81b246b";
Map<String, String> NULL_PLUGIN_PROPERTIES = null;
Payment payment = paymentTransactionApi.getPaymentByTransactionExternalKey(transactionExternalKey, NULL_PLUGIN_PROPERTIES, requestOptions);


external_key = "e5f000f7-0733-4828-a887-3a4a58d27596"
with_plugin_info = false
with_attempts = false
plugin_properties = ["key%3Dvalue"]
audit = 'NONE'

payment = KillBillClient::Model::Payment.find_by_transaction_external_key(external_key, with_plugin_info, with_attempts, plugin_properties, audit, options)

paymentTransactionApi = killbill.PaymentTransactionApi()

payment_transaction_key = 'edb52a56-f5d2-4285-9a23-ccafb6f1ae1f'

payment = paymentTransactionApi.get_payment_by_transaction_external_key(payment_transaction_key)

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

const key = '37b95fef-f5be-4771-80e4-d41af8e528cb';

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

$apiInstance = $client->getPaymentTransactionApi();

$transactionExternalKey = "37b95fef-f5be-4771-80e4-d41af8e528cb";
$withPluginInfo = false;
$withAttempts = false;
$pluginProperty = array("pluginProperty_example");
$audit = "NONE";

$result = $apiInstance->getPaymentByTransactionExternalKey($transactionExternalKey, $withPluginInfo, $withAttempts, $pluginProperty, $audit);

Example Response:

{
  "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
  "paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
  "paymentNumber": "47",
  "paymentExternalKey": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
  "authAmount": 0,
  "capturedAmount": 0,
  "purchasedAmount": 0,
  "refundedAmount": 0,
  "creditedAmount": 0,
  "currency": "USD",
  "paymentMethodId": "c02fa9b0-ae95-42ae-9010-bc11cb160947",
  "transactions": [
    {
      "transactionId": "07655b3c-7f17-4172-b193-ece48e5741ad",
      "transactionExternalKey": "07655b3c-7f17-4172-b193-ece48e5741ad",
      "paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
      "paymentExternalKey": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
      "transactionType": "AUTHORIZE",
      "amount": 0,
      "currency": "USD",
      "effectiveDate": "2018-07-18T18:58:11.000Z",
      "processedAmount": 0,
      "processedCurrency": "USD",
      "status": "SUCCESS",
      "gatewayErrorCode": null,
      "gatewayErrorMsg": null,
      "firstPaymentReferenceId": null,
      "secondPaymentReferenceId": null,
      "properties": null,
      "auditLogs": []
    }
  ],
  "paymentAttempts": null,
  "auditLogs": []
}

Query Parameters

Name Type Required Default Description
transactionExternalKey string yes none Transaction external key
withPluginInfo boolean no false If true, include plugin info. This results in the PaymentPluginApi.getPaymentInfo method being invoked for the underlying payment plugin. See Payment Plugin Tutorial.
withAttempts boolean no false If true, include payment attempts
pluginProperty array of strings false omit list of plugin properties, if any
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 object including the specified transaction.

Mark a pending payment transaction as succeeded or failed

Sets the status of a PENDING PaymentTransaction to SUCCESS or PAYMENT_FAILURE

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}

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 "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '{"paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82", "status": "SUCCESS"}' \
    "http://127.0.0.1:8080/1.0/kb/paymentTransactions/07655b3c-7f17-4172-b193-ece48e5741ad"

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("37d15a2f-55ac-40ab-a873-08faae78f213");
PaymentTransaction paymentTransaction = new PaymentTransaction();
paymentTransaction.setStatus(TransactionStatus.SUCCESS);
paymentTransaction.setPaymentId(UUID.fromString("27d15e39-b25c-4dc1-92cf-5487397a48a6");

Payment payment = paymentTransactionApi.notifyStateChanged(paymentTransactionId, 
                                         paymentTransaction, 
                                         null, 
                                         requestOptions));


user = "demo"
reason = nil
comment = nil

payment_transaction = KillBillClient::Model::Transaction.new
payment_transaction.payment_id = "caced2e2-717e-4cf7-a8fd-f760b5d2deb8"
payment_transaction.transaction_id = "029d7d7b-d5fa-4a29-93f5-7f927d79f3f3"

status = 'PAYMENT_FAILURE'
control_plugin_name = []

payment_transaction.update_transaction_state(status,
                                control_plugin_name,
                                user,
                                reason,
                                comment,
                                options)

paymentTransactionApi = killbill.PaymentTransactionApi()

payment_transaction_id = '02acb6b2-8139-40d3-816c-8b7ec858d350'
body = PaymentTransaction(payment_id='8cc963a6-786a-4dd1-bcfb-5edc266c01b9', status='SUCCESS')

paymentTransactionApi.notify_state_changed(payment_transaction_id, body,
                                           created_by='demo',
                                           reason='reason',
                                           comment='comment')

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

const payment_transaction: PaymentTransaction = {paymentId: "e129a8fc-c244-425f-b1eb-68d3aac7054e", status: "SUCCESS"};
const paymentTransactionId = '8dabaa02-c926-4ec3-b0bb-47fe2271b62f';

api.notifyStateChanged(payment_transaction, paymentTransactionId, 'created_by');

$apiInstance = $client->getPaymentTransactionApi();

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

$transactionId = "1f7002b3-d1a5-458d-97d4-46b6b86499ac";
$controlPluginName = array("controlPluginName_example");

$body = new \Killbill\Client\Swagger\Model\PaymentTransaction();
$body -> setPaymentId("2ad112db-cf4b-497d-9a0d-c0e41fa6070b");
$body -> setStatus("SUCCESS");

$result = $apiInstance->notifyStateChanged($body, $xKillbillCreatedBy, $transactionId, $xKillbillReason, $xKillbillComment, $controlPluginName);

Request Body

A PaymentTransaction object including, at least, a paymentId and a status (SUCCESS or PAYMENT_FAILURE)

Query Parameters

Name Type Required Default Description
controlPluginName array of strings false omit List of control plugin names, if any

Response

If successful, returns a status code of 201 and an empty body. In addition, a Location header is returned which contains the payment id.

Audit Logs

Audit logs provide a record of events that occur involving various specific resources. For details on audit logs see Audit and History.

Retrieve payment transaction audit logs with history by id

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

Some examples:

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/auditLogsWithHistory

Example Request:

curl -v \
    -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/paymentTransactions/07655b3c-7f17-4172-b193-ece48e5741ad/auditLogsWithHistory"

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("41f4d299-4371-4876-96b4-0b3cc81b246b");

List<AuditLog> auditLogs = paymentTransactionApi.getTransactionAuditLogsWithHistory(paymentTransactionId, 
                                                                                 requestOptions);

payment_transaction = KillBillClient::Model::Transaction.new
payment_transaction.transaction_id = "e5f000f7-0733-4828-a887-3a4a58d27596"

audit_logs = payment_transaction.audit_logs_with_history(options)

paymentTransactionApi = killbill.PaymentTransactionApi()

payment_transaction_id = '02acb6b2-8139-40d3-816c-8b7ec858d350'
audit_logs = paymentTransactionApi.get_transaction_audit_logs_with_history(payment_transaction_id)

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

const paymentTransactionId = '8dabaa02-c926-4ec3-b0bb-47fe2271b62f';

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

$apiInstance = $client->getPaymentTransactionApi();

$transactionId = "1f7002b3-d1a5-458d-97d4-46b6b86499ac";

$result = $apiInstance->getTransactionAuditLogsWithHistory($transactionId);

Example Response:

[
  {
    "changeType": "INSERT",
    "changeDate": "2018-07-18T18:58:11.000Z",
    "objectType": "TRANSACTION",
    "objectId": "07655b3c-7f17-4172-b193-ece48e5741ad",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "84ac4088-dc76-4fde-9ff0-63e228b5e6fc",
    "history": {
      "id": null,
      "createdDate": "2018-07-18T18:58:11.000Z",
      "updatedDate": "2018-07-18T18:58:11.000Z",
      "recordId": 63,
      "accountRecordId": 120,
      "tenantRecordId": 101,
      "attemptId": null,
      "paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
      "transactionExternalKey": "07655b3c-7f17-4172-b193-ece48e5741ad",
      "transactionType": "AUTHORIZE",
      "effectiveDate": "2018-07-18T18:58:11.000Z",
      "transactionStatus": "UNKNOWN",
      "amount": 0,
      "currency": "USD",
      "processedAmount": null,
      "processedCurrency": null,
      "gatewayErrorCode": null,
      "gatewayErrorMsg": null,
      "tableName": "PAYMENT_TRANSACTIONS",
      "historyTableName": "PAYMENT_TRANSACTION_HISTORY"
    }
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2018-07-18T18:58:11.000Z",
    "objectType": "TRANSACTION",
    "objectId": "07655b3c-7f17-4172-b193-ece48e5741ad",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "84ac4088-dc76-4fde-9ff0-63e228b5e6fc",
    "history": {
      "id": null,
      "createdDate": "2018-07-18T18:58:11.000Z",
      "updatedDate": "2018-07-18T18:58:11.000Z",
      "recordId": 63,
      "accountRecordId": 120,
      "tenantRecordId": 101,
      "attemptId": null,
      "paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
      "transactionExternalKey": "07655b3c-7f17-4172-b193-ece48e5741ad",
      "transactionType": "AUTHORIZE",
      "effectiveDate": "2018-07-18T18:58:11.000Z",
      "transactionStatus": "SUCCESS",
      "amount": 0,
      "currency": "USD",
      "processedAmount": 0,
      "processedCurrency": "USD",
      "gatewayErrorCode": null,
      "gatewayErrorMsg": null,
      "tableName": "PAYMENT_TRANSACTIONS",
      "historyTableName": "PAYMENT_TRANSACTION_HISTORY"
    }
  }
]

Query Parameters

None.

Response

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

Custom Fields

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

Add custom fields to payment transaction

Adds one or more custom fields to a PaymentTransaction object. Existing custom fields are not modified.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/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/paymentTransactions/8fe697d4-2c25-482c-aa45-f6cd5a48186d/customFields' 

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");

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

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

paymentTransactionApi.createTransactionCustomFields(paymentTransactionId, 
                                                    customFields, 
                                                    requestOptions);

user = "demo"
reason = nil
comment = nil

payment_transaction = KillBillClient::Model::Transaction.new
payment_transaction.transaction_id = "e5f000f7-0733-4828-a887-3a4a58d27596"

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_transaction.add_custom_field(custom_fields,
                                user,
                                reason,
                                comment,
                                options)

paymentTransactionApi = killbill.api.PaymentTransactionApi()

payment_transaction_id = '02acb6b2-8139-40d3-816c-8b7ec858d350'
body = CustomField(name='Test Custom Field', value='test_value')

paymentTransactionApi.create_transaction_custom_fields(payment_transaction_id,
                                                       [body],
                                                       created_by='demo',
                                                       reason='reason',
                                                       comment='comment')

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

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

const paymentTransactionId = '8dabaa02-c926-4ec3-b0bb-47fe2271b62f';

api.createTransactionCustomFields(customFields, paymentTransactionId, 'created_by');

$apiInstance = $client->getPaymentTransactionApi();

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

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

$transactionId = "1f7002b3-d1a5-458d-97d4-46b6b86499ac";

$result = $apiInstance->createTransactionCustomFields($body, $xKillbillCreatedBy, $transactionId, $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 transaction.

Retrieve payment transaction custom fields

Retrieves the custom fields associated with the specified payment transaction.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/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/paymentTransactions/8fe697d4-2c25-482c-aa45-f6cd5a48186d/customFields' 

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");

List<CustomField> customFields = paymentTransactionApi.getTransactionCustomFields(paymentTransactionId,
                                                                                  AuditLevel.NONE,
                                                                                  requestOptions);

payment_transaction = KillBillClient::Model::Transaction.new
payment_transaction.transaction_id = "e5f000f7-0733-4828-a887-3a4a58d27596"

audit = 'NONE'

fields = payment_transaction.custom_fields(audit, options)

paymentTransactionApi = killbill.api.PaymentTransactionApi()

payment_transaction_id = '02acb6b2-8139-40d3-816c-8b7ec858d350'

fields = paymentTransactionApi.get_transaction_custom_fields(payment_transaction_id)

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

const paymentTransactionId = '8dabaa02-c926-4ec3-b0bb-47fe2271b62f';
const audit = 'NONE';

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

$apiInstance = $client->getPaymentTransactionApi();

$transactionId = "1f7002b3-d1a5-458d-97d4-46b6b86499ac";
$audit = "NONE";

$result = $apiInstance->getTransactionCustomFields($transactionId, $audit);

Example Response:

[
  {
    "customFieldId": "e4bac228-872d-4966-8072-2c3ac06442ed",
    "objectId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
    "objectType": "TRANSACTION",
    "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 a payment transaction

Modifies the value of one or more existing custom fields associated with a payment transaction 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/paymentTransactions/{transactionId}/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": "e4bac228-872d-4966-8072-2c3ac06442ed",
            "value": "NewValue"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/paymentTransactions/8fe697d4-2c25-482c-aa45-f6cd5a48186d/customFields' 

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
UUID customFieldId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");

CustomField customFieldModified = new CustomField();
customFieldModified.setCustomFieldId(customFieldId);
customFieldModified.setValue("NewValue");
CustomFields customFields = new CustomFields();
customFields.add(customFieldModified);
paymentTransactionApi.modifyTransactionCustomFields(paymentTransactionId, 
                                                    customFields, 
                                                    requestOptions);

user = "demo"
reason = nil
comment = nil

payment_transaction = KillBillClient::Model::Transaction.new
payment_transaction.transaction_id = "e5f000f7-0733-4828-a887-3a4a58d27596"

custom_fields = []
custom_field = KillBillClient::Model::CustomFieldAttributes.new
custom_field.custom_field_id = '7fb3dde7-0911-4477-99e3-69d142509bb9'
custom_field.name = 'Test Modify'
custom_field.value = 'test_modify_value'
custom_fields.push custom_field

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

paymentTransactionApi = killbill.api.PaymentTransactionApi()

payment_transaction_id = '02acb6b2-8139-40d3-816c-8b7ec858d350'
custom_field_id = 'eddc016c-0336-44d3-9383-a29962e276b7'
body = CustomField(custom_field_id=custom_field_id, value='new value')

paymentTransactionApi.modify_transaction_custom_fields(payment_transaction_id,
                                                       [body],
                                                       created_by='demo',
                                                       reason='reason',
                                                       comment='comment')

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

const paymentTransactionId = '8dabaa02-c926-4ec3-b0bb-47fe2271b62f';

const customField: CustomField = {customFieldId: "690b4723-5d54-4b89-afe0-dae0d146183c", value: "new_value"};
const customFields = [customField];

api.modifyTransactionCustomFields(customFields, paymentTransactionId, 'created_by');

$apiInstance = $client->getPaymentTransactionApi();

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

$customField = new CustomField();
$customField -> setCustomFieldId('cea1e5e0-87b9-40bf-8d46-b00e6f870c8f');
$customField -> setValue('new_value');
$body = array($customField);

$transactionId = "1f7002b3-d1a5-458d-97d4-46b6b86499ac";

$apiInstance->modifyTransactionCustomFields($body, $xKillbillCreatedBy, $transactionId, $xKillbillReason, $xKillbillComment);

Requst 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, returns a status code of 204 and an empty body.

Remove custom fields from a payment transaction

Delete one or more custom fields from a payment transaction. 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 transaction.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/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/paymentTransactions/77e23878-8b9d-403b-bf31-93003e125712/customFields?customField=e4bac228-872d-4966-8072-2c3ac06442ed' 

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");
List<UUID> customFieldsList = List.of(customFieldsId);
paymentTransactionApi.deleteTransactionCustomFields(paymentTransactionId, 
                                                    customFieldsList, 
                                                    requestOptions);

user = "demo"
reason = nil
comment = nil

payment_transaction = KillBillClient::Model::Transaction.new
payment_transaction.transaction_id = "e5f000f7-0733-4828-a887-3a4a58d27596"

custom_field_ids = []
custom_field_id = 'cda969c3-1092-4702-b155-05d0ef899fa2'
custom_field_ids.push custom_field_id
payment_transaction.remove_custom_field(custom_field_ids,
                                   user,
                                   reason,
                                   comment,
                                   options)

paymentTransactionApi = killbill.api.PaymentTransactionApi()

payment_transaction_id = '02acb6b2-8139-40d3-816c-8b7ec858d350'
custom_fields = ['494c8e9b-0840-4955-9e23-e84d4c353c25']

paymentTransactionApi.delete_transaction_custom_fields(payment_transaction_id,
                                                       custom_field=custom_fields,
                                                       created_by='demo',
                                                       reason='reason',
                                                       comment='comment')

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

const paymentTransactionId = '8dabaa02-c926-4ec3-b0bb-47fe2271b62f';

const customField = '690b4723-5d54-4b89-afe0-dae0d146183c';
const customFields = [customField];

api.deleteTransactionCustomFields(paymentTransactionId, 'created_by', customFields);

$apiInstance = $client->getPaymentTransactionApi();

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

$transactionId = "1f7002b3-d1a5-458d-97d4-46b6b86499ac";
$customFields = array("cea1e5e0-87b9-40bf-8d46-b00e6f870c8f");

$apiInstance->deleteTransactionCustomFields($transactionId, $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.

Tags

See section Tags for an introduction.

Note: None of the system tags are applicable for Payment Transactions, only a user tag can be associated with a payment transaction.

Add tags to a payment transaction

This API adds one or more tags to a PaymentTransaction. The tag definition corresponding to the tag to be added must already exist.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/tags

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 '[
            "353752dd-9041-4450-b782-a8bb03a923c8"
        ]' \
    'http://127.0.0.1:8080/1.0/kb/paymentTransactions/8fe697d4-2c25-482c-aa45-f6cd5a48186d/tags' 

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("917992d3-5f1f-4828-9fff-799cc4211aa9");

UUID tagDefinitionId = UUID.fromString("353752dd-9041-4450-b782-a8bb03a923c8");

Tags tags = paymentTransactionApi.createTransactionTags(paymentTransactionId, 
                                                          List.of(tagDefinitionId), 
                                                          requestOptions);

user = "demo"
reason = nil
comment = nil

payment_transaction = KillBillClient::Model::Transaction.new
payment_transaction.transaction_id = "e5f000f7-0733-4828-a887-3a4a58d27596"

tag_definition_ids = ['2c1f8309-24d7-437c-971b-7e68ff2d393a']

payment_transaction.add_tags_from_definition_ids(tag_definition_ids,
                     user,
                     reason,
                     comment,
                     options)

paymentTransactionApi = killbill.api.PaymentTransactionApi()

payment_transaction_id = '02acb6b2-8139-40d3-816c-8b7ec858d350'
tagDefIds  = ["3d70a355-8342-4042-8694-a2447f0f2b1e"]

paymentTransactionApi.create_transaction_tags(payment_transaction_id,
                                              tagDefIds,
                                              created_by='demo',
                                              reason='reason',
                                              comment='comment')

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

const paymentTransactionId = '8dabaa02-c926-4ec3-b0bb-47fe2271b62f';

const tagDefIds = ['3d70a355-8342-4042-8694-a2447f0f2b1e'];

api.createTransactionTags(tagDefIds, paymentTransactionId, 'created_by');

$apiInstance = $client->getPaymentTransactionApi();

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

$transactionId = "1f7002b3-d1a5-458d-97d4-46b6b86499ac";
$tagDefIds = array("3d70a355-8342-4042-8694-a2447f0f2b1e");

$apiInstance->createTransactionTags($tagDefIds, $xKillbillCreatedBy, $transactionId, $xKillbillReason, $xKillbillComment);

Request Body

A JSON array corresponding to the tag definition IDs to be added.

Query Parameters

None.

Response

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

Retrieve payment transaction tags

Retrieves all tags attached to this payment transaction.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/tags

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/paymentTransactions/8fe697d4-2c25-482c-aa45-f6cd5a48186d/tags' 

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("e659f0f3-745c-46d5-953c-28fe9282fc7d");

Boolean includedDeleted = false; // Will not include deleted tags

List<Tag> tags = paymentTransactionApi.getTransactionTags(paymentTransactionId, 
                                                          includedDeleted, 
                                                          AuditLevel.FULL, 
                                                          requestOptions);

payment_transaction = KillBillClient::Model::Transaction.new
payment_transaction.transaction_id = "e5f000f7-0733-4828-a887-3a4a58d27596"

included_deleted = false
audit = 'NONE'

tags = payment_transaction.tags(included_deleted,
                  audit,
                  options)

paymentTransactionApi = killbill.api.PaymentTransactionApi()

payment_transaction_id = '02acb6b2-8139-40d3-816c-8b7ec858d350'

tags = paymentTransactionApi.get_transaction_tags(payment_transaction_id)

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

const paymentTransactionId = '8dabaa02-c926-4ec3-b0bb-47fe2271b62f';
const includeDeleted = false;
const audit = 'NONE';

const response: AxiosResponse<killbill.Tag[], any> = await api.getTransactionTags(paymentTransactionId, includeDeleted, audit);

$apiInstance = $client->getPaymentTransactionApi();

$transactionId = "1f7002b3-d1a5-458d-97d4-46b6b86499ac";
$includedDeleted = false;
$audit = "NONE";

$result = $apiInstance->getTransactionTags($transactionId, $includedDeleted, $audit);

Example Response:

[
  {
    "tagId": "890e3b13-3114-478b-9365-50f1a2682143",
    "objectType": "TRANSACTION",
    "objectId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
    "tagDefinitionId": "353752dd-9041-4450-b782-a8bb03a923c8",
    "tagDefinitionName": "foo",
    "auditLogs": []
  }
]

Query Parameters

Name Type Required Default Description
includedDeleted boolean no false If true, include deleted tags
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 tag objects.

Remove tags from a payment transaction

This API deletes one or more tags attached to a payment transaction.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/tags

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/paymentTransactions/8fe697d4-2c25-482c-aa45-f6cd5a48186d/tags?tagDef=353752dd-9041-4450-b782-a8bb03a923c8'    

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("e659f0f3-745c-46d5-953c-28fe9282fc7d");

UUID tagDefinitionId = UUID.fromString("353752dd-9041-4450-b782-a8bb03a923c8");

paymentTransactionApi.deleteTransactionTags(paymentTransactionId, 
                                            List.of(tagDefinitionId), 
                                            requestOptions);

user = "demo"
reason = nil
comment = nil

payment_transaction = KillBillClient::Model::Transaction.new
payment_transaction.transaction_id = "e5f000f7-0733-4828-a887-3a4a58d27596"

tag_definition_ids = ['2c1f8309-24d7-437c-971b-7e68ff2d393a']

payment_transaction.remove_tags_from_definition_ids(tag_definition_ids,
                        user,
                        reason,
                        comment,
                        options)

paymentTransactionApi = killbill.api.PaymentTransactionApi()

payment_transaction_id = '02acb6b2-8139-40d3-816c-8b7ec858d350'
tagDefIds = ["3d70a355-8342-4042-8694-a2447f0f2b1e"]

paymentTransactionApi.delete_transaction_tags(payment_transaction_id,
                                              tag_def=tagDefIds,
                                              created_by='demo',
                                              reason='reason',
                                              comment='comment')

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

const paymentTransactionId = '8dabaa02-c926-4ec3-b0bb-47fe2271b62f';

const tagDefIds = ['3d70a355-8342-4042-8694-a2447f0f2b1e'];

api.deleteTransactionTags(paymentTransactionId, 'created_by', tagDefIds);

$apiInstance = $client->getPaymentTransactionApi();

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

$transactionId = "1f7002b3-d1a5-458d-97d4-46b6b86499ac";
$tagDefIds = array("3d70a355-8342-4042-8694-a2447f0f2b1e");

$apiInstance->deleteTransactionTags($transactionId, $xKillbillCreatedBy, $tagDefIds, $xKillbillReason, $xKillbillComment);

Query Parameters

Name Type Required Default Description
tagDef array of string yes none A tag definition ID identifying the tag that should be removed. Multiple tags can be deleted by specifying a separate tagDef parameter corresponding to each tag.

Response

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