Invoice Payment

An InvoicePayment is a Payment that is made against a specific invoice.

By default the system will always attempt to make a full payment against an invoice, but Kill Bill also allows multiple partial payments. Partial payments can be made against unpaid - or partially paid - invoices by triggerring a payment against the Invoice resource. The reverse is not true; a single payment across multiple invoices is not (yet) supported.

See Payment for further information.

Invoice Payment Resource

The InvoicePayment resource represents a payment associated with a given invoice. It is identical to the Payment resource except for the inclusion of the targetInvoiceId attribute.

Name Type Generated by Description
targetInvoiceId string system UUID for the invoice to be paid
accountId string system UUID for the account to be paid
paymentId string system UUID for the payment
paymentNumber number user User's ID number for the payment
paymentExternalKey string user optional external key
authAmonunt number user or system Total authorized amount (see below)
capturedAmonunt number user or system Total captured amount (see below)
purchasedAmonunt number user or system Total purchased amount (see below)
refundedAmount number user or system Total refunded amount (see below)
creditedAmount number user or system Total credited amount (see below)
currency string user currency to be used
paymentMethod string system UUID for the payment method used
transactions list system list of paymentTransactions, if any (see below)
paymentAttempts list system list of paymentAttempts, if any (see below)

Invoice Payment Transaction Resource

The InvoicePaymentTransaction resource represents a payment transaction associated with a given InvoicePayment. It is identical to the PaymentTransaction resource except for the inclusion of the isAdjusted and adjustments attributes. The attributes for this resource object are:

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 transaction
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
isAdjusted boolean system true if this object includes one or more InvoiceItem adjustments
adjustments list system List of adjusted InvoiceItem resources showing adjusted amounts

Invoice Payment

These endpoints initiate transactions on an existing InvoicePayment. Many other applicable transactions are given in the Payment section. To begin a new Payment, see Trigger a Payment in the Account API.

Retrieve a payment by id

Retrieves an invoice payment by its payment Id, which is given as a path parameter

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}

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/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("80f5bfca-e142-4320-b8f2-ae4530ca7172");
Boolean withPluginInfo = false; // Will not reflect plugin info
Boolean withAttempts = false; // Will not reflect payment attempts
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

InvoicePayment invoicePayment = invoicePaymentApi.getInvoicePayment(paymentId, 
                                                                    withPluginInfo,
                                                                    withAttempts,
                                                                    NULL_PLUGIN_PROPERTIES,
                                                                    AuditLevel.NONE,
                                                                    requestOptions);

payment_id = '28aef37a-7655-4351-985a-02b961ae4ac7'
with_plugin_info = false
with_attempts = false

KillBillClient::Model::InvoicePayment.find_by_id(payment_id, 
                                                 with_plugin_info, 
                                                 with_attempts, 
                                                 @options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '5e9d8b82-2664-4a36-85a1-37471a0b618a'

invoicePaymentApi.get_invoice_payment(payment_id, api_key, api_secret)

Example Response:

{
  "targetInvoiceId": "4be34fe4-5845-4a35-afd8-632ad04cccf9",
  "accountId": "8b66b9f9-bfb4-463a-86c7-e267128a294a",
  "paymentId": "cc7fcd4d-e701-4679-9741-41289103db83",
  "paymentNumber": "19",
  "paymentExternalKey": "cc7fcd4d-e701-4679-9741-41289103db83",
  "authAmount": 0,
  "capturedAmount": 0,
  "purchasedAmount": 500,
  "refundedAmount": 0,
  "creditedAmount": 0,
  "currency": "USD",
  "paymentMethodId": "39f3461c-5357-42f7-a8a9-ec79502fdb6b",
  "transactions": [
    {
      "transactionId": "6787dc2d-4f5e-49b5-9764-0070fd1238c2",
      "transactionExternalKey": "6787dc2d-4f5e-49b5-9764-0070fd1238c2",
      "paymentId": "cc7fcd4d-e701-4679-9741-41289103db83",
      "paymentExternalKey": "cc7fcd4d-e701-4679-9741-41289103db83",
      "transactionType": "PURCHASE",
      "amount": 500,
      "currency": "USD",
      "effectiveDate": "2018-07-19T20:48:34.000Z",
      "processedAmount": 500,
      "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
withAttempts boolean no false if true, include payment attempts

Returns

If successful, returns a status code of 200 and an InvoicePayment object.

Refund a payment, and adjust the invoice if needed

Refunds a payment, and optionally adds the amount to one or more invoice items

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/refunds

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 '{
          "amount": 50,
          "isAdjusted": false
        }' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/refunds' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("45d6f4c5-21be-49b1-99c5-7b0c3c985bf0");

InvoicePaymentTransaction refund = new InvoicePaymentTransaction();
refund.setPaymentId(paymentId);
refund.setAmount(BigDecimal.ONE);

UUID paymentMethodId = UUID.fromString("28a3ed1a-7a58-4ac2-b864-2ca723abb864");

Map<String, String> NULL_PLUGIN_PROPERTIES = null;

invoicePaymentApi.createRefundWithAdjustments(paymentId, 
                                              refund, 
                                              paymentMethodId, 
                                              NULL_PLUGIN_PROPERTIES, 
                                              requestOptions);

payment_id = '8d85a8e8-c94b-438f-aac1-e8cb436b2c05'
amount ='50.0'
adjustments = nil
KillBillClient::Model::InvoicePayment.refund(payment_id, 
                                             amount, 
                                             adjustments, 
                                             user, 
                                             reason, 
                                             comment, 
                                             options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '8d85a8e8-c94b-438f-aac1-e8cb436b2c05'
body = PaymentTransaction(amount=50.0)

invoicePaymentApi.create_refund_with_adjustments(payment_id,
                                                 body,
                                                 created_by,
                                                 api_key,
                                                 api_secret)

Request Body

An InvoicePaymentTransaction object, including at least the amount attribute and the isAdjusted attribute. If isAdjusted is true, then the object must also include the attribute adjustments which is a list of InvoiceItem objects giving the invoiceItemId, the invoiceId, and the adjusted amount for each of the adjustments to be made.

Query Parameters

Name Type Required Default Description
externalPayment boolean no false choose true if the payment method is external
paymentMethodId string yes none paymentMethod id

Response

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

Record a chargeback

Creates a CHARGEBACK InvoicePaymentTransaction for a specified InvoicePayment. The InvoicePayment is identified by its paymentId given as a path parameter. The captured amount is reduced by the chargeback amount. If appropriate this amount will be added back to one or more invoice items.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/chargebacks

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 '{
          "amount": 5,
          "isAdjusted": false
        }' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/chargebacks' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("96930ff3-82e1-4556-888a-0cb07ec120d6");

InvoicePaymentTransaction body = new InvoicePaymentTransaction();
body.setPaymentId(paymentId);
body.setAmount(new BigDecimal("50.00"));

InvoicePayment result = invoicePaymentApi.createChargeback(paymentId, 
                                                           body, 
                                                           requestOptions);

payment_id = '2276b3c9-4e51-41b2-b5bf-9ddc11582ee4'
amount = '50.0'
currency = 'USD'
effective_date = "2013-08-01"

KillBillClient::Model::InvoicePayment.chargeback(payment_id, 
                                                 amount,
                                                 currency,
                                                 effective_date,
                                                 user, 
                                                 reason,
                                                 comment, 
                                                 options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '2276b3c9-4e51-41b2-b5bf-9ddc11582ee4'
body = PaymentTransaction(amount=50.0, currency='USD')

invoicePaymentApi.create_chargeback(payment_id, 
                                    body, 
                                    created_by, 
                                    api_key, 
                                    api_secret)

Request Body

An InvoicePaymentTransaction object, including at least the amount attribute and the isAdjusted attribute. If isAdjusted is true, then the object must also include the attribute adjustments which is a list of InvoiceItem objects giving the invoiceItemId, the invoiceId, and the adjusted amount for each of the adjustments to be made.

Query Parameters

None.

Response

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

Record a chargeback reversal

Reverses a CHARGEBACK InvoicePaymentTransaction, if permitted by the Payment plugin. The chargeback amount is added back to the captured amount. The payment is identified by its paymentId which is given as a path parameter.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/chargebackReversals

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 '{
          "transactionExternalKey": "a335f7d2-e115-436f-8c63-2b0114d974de",
          "paymentId": "cc7fcd4d-e701-4679-9741-41289103db83",
          "effectiveDate": "2018-07-20T15:05:36.853Z"        
        }' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/chargebackReversals' 

TODO

payment_id = '7a5d4997-5d44-4a82-8371-a410ea5615f4'
chargeback_transaction_external_key = '99c45d07-abe4-4bc7-a207-0524548c1b08'
effective_date = "2013-08-01"

KillBillClient::Model::InvoicePayment.chargeback_reversal(payment_id,
                                                          chargeback_transaction_external_key, 
                                                          effective_date, 
                                                          user, 
                                                          reason, 
                                                          comment, 
                                                          options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '7a5d4997-5d44-4a82-8371-a410ea5615f4'
transaction_external_key = '99c45d07-abe4-4bc7-a207-0524548c1b08'
body = PaymentTransaction(amount=50.0, 
                          currency='USD', 
                          transaction_external_key=transaction_external_key)

invoicePaymentApi.create_chargeback_reversal(payment_id, 
                                             body, 
                                             created_by, 
                                             api_key, 
                                             api_secret)

Request Body

An InvoicePaymentTransaction object, including at least the amount attribute and the isAdjusted attribute. If isAdjusted is true, then the object must also include the attribute adjustments which is a list of InvoiceItem objects giving the invoiceItemId, the invoiceId, and the adjusted amount for each of the adjustments to be made.

Query Parameters

None.

Response

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

Complete an existing transaction

Completes any existing InvoicePaymentTransaction that is in a PENDING state, based on its paymentId given as a path parameter.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}

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 '{
            "paymentId": "cc7fcd4d-e701-4679-9741-41289103db83"
        }' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("80f5bfca-e142-4320-b8f2-ae4530ca7172");
PaymentTransaction body = new PaymentTransaction();
List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

invoicePaymentApi.completeInvoicePaymentTransaction(paymentId, 
                                                    body, 
                                                    NULL_PLUGIN_NAMES, 
                                                    NULL_PLUGIN_PROPERTIES, 
                                                    requestOptions);

payment_id = '2276b3c9-4e51-41b2-b5bf-9ddc11582ee4'

KillBillClient::Model::InvoicePayment.complete_invoice_payment_transaction(payment_id, 
                                                                           user, 
                                                                           reason, 
                                                                           comment, 
                                                                           options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
body = PaymentTransaction(payment_id=payment_id)

invoicePaymentApi.complete_invoice_payment_transaction(payment_id, 
                                                       body, 
                                                       created_by, 
                                                       api_key, 
                                                       api_secret)

Query Parameters

None.

Response

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

Custom Fields

Custom fields are {key, value} attributes that can be attached to any customer resource. In particular they can be added to InvoicePayment objects. For details on Custom Fields see Custom Field.

Add custom fields to invoice payment

Adds one or more custom fields to an InvoicePayment object. Existing custom fields are not modified.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/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 Fields",
            "value": "test_value"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/2495e35e-2b96-434c-8877-62dbbf20f7e9/customFields' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("59860a0d-c032-456d-a35e-3a48fe8579e5");
final List<AuditLog> EMPTY_AUDIT_LOGS = Collections.emptyList();

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

invoicePaymentApi.createInvoicePaymentCustomFields(paymentId, 
                                                   customFields, 
                                                   requestOptions);

custom_field = KillBillClient::Model::CustomFieldAttributes.new
custom_field.object_type = 'INVOICE_PAYMENT'
custom_field.name = 'Test Custom Field'
custom_field.value = 'test_value'

invoice_payment.add_custom_field(custom_field, 
                                 user,
                                 reason,
                                 comment,
                                 options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
body = CustomField(name='Test Custom Field', value='test_value')

invoicePaymentApi.create_invoice_payment_custom_fields(payment_id,
                                                       [body],
                                                       created_by,
                                                       api_key,
                                                       api_secret)

Request Body

A JSON string representing the custom field object or objects to be added.

Query Parameters

None.

Response

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

Retrieve invoice payment custom fields

Retrieves the custom fields associated with an InvoicePayment object

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/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/invoicePayments/2495e35e-2b96-434c-8877-62dbbf20f7e9/customFields' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("59860a0d-c032-456d-a35e-3a48fe8579e5");

List<CustomField> customFields = invoicePaymentApi.getInvoicePaymentCustomFields(paymentId,
                                                                                 AuditLevel.NONE,
                                                                                 requestOptions);

audit = 'NONE'

invoice_payment.custom_fields(audit, options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = 'f33e0adc-78df-438a-b920-aaacd7f8597a'

invoicePaymentApi.get_invoice_payment_custom_fields(payment_id, api_key, api_secret)

Example Response:

[
  {
    "customFieldId": "3fbf75aa-6f22-4a02-974b-55eeded2cf6b",
    "objectId": "2495e35e-2b96-434c-8877-62dbbf20f7e9",
    "objectType": "PAYMENT",
    "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

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and a list of custom field objects

Modify custom fields for an invoice payment

Modifies the custom fields associated with an InvoicePayment object

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/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": "e2408cac-931b-43eb-855b-9f2902615c39",
            "value": "NewValue"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/2495e35e-2b96-434c-8877-62dbbf20f7e9/customFields' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("59860a0d-c032-456d-a35e-3a48fe8579e5");
UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");

CustomField customFieldModified = new CustomField();
customFieldModified.setCustomFieldId(customFieldsId);
customFieldModified.setValue("NewValue");

invoicePaymentApi.modifyInvoicePaymentCustomFields(paymentId, 
                                                   customFieldModified, 
                                                   requestOptions);

custom_field.custom_field_id = '7fb3dde7-0911-4477-99e3-69d142509bb9'
custom_field.name = 'Test Modify'
custom_field.value = 'test_modify_value'

invoice_payment.modify_custom_field(custom_field,                                                                                            
                                    user, 
                                    reason,
                                    comment, 
                                    options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = 'f33e0adc-78df-438a-b920-aaacd7f8597a'
custom_field_id = '9913e0f6-b5ef-498b-ac47-60e1626eba8f'
body = CustomField(custom_field_id=custom_field_id, name='Test Modify', value='test_modify_value')

invoicePaymentApi.modify_invoice_payment_custom_fields(payment_id,
                                                       [body],
                                                       created_by,
                                                       api_key,
                                                       api_secret)

Requst Body

A JSON string representing a list of custom fields to substitute for the existing ones.

Query Parameters

None.

Response

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

Remove custom fields from an invoice payment

Removes a specified set of custom fields from an InvoicePayment object

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/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/invoicePayments/2495e35e-2b96-434c-8877-62dbbf20f7e9/customFields?customField=e2408cac-931b-43eb-855b-9f2902615c39' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("59860a0d-c032-456d-a35e-3a48fe8579e5");
UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");

invoicePaymentApi.deleteInvoicePaymentCustomFields(paymentId, 
                                                   customFieldsId, 
                                                   requestOptions);

custom_field_id = custom_field.custom_field_id

invoice_payment.remove_custom_field(custom_field_id,                                                                                            
                                    user, 
                                    reason,
                                    comment, 
                                    options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = 'f33e0adc-78df-438a-b920-aaacd7f8597a'
custom_field_id = '9913e0f6-b5ef-498b-ac47-60e1626eba8f'
custom_field = [custom_field_id]
invoicePaymentApi.delete_invoice_payment_custom_fields(payment_id,
                                                       created_by,
                                                       api_key,
                                                       api_secret,
                                                       custom_field=custom_field)

Query Parameters

Name Type Required Default Description
customField string yes none Comma separated list of custom field object IDs that should be deleted.

Response

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

Tags

See Account Tags for an introduction.

The are no system tags applicable to an InvoicePayment.

Add tags to an invoice payment

Adds one or more tags to an invoice payment object. The tag definitions must already exist.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/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/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/tags' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("45d6f4c5-21be-49b1-99c5-7b0c3c985bf0");

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

Tags result = invoicePaymentApi.createInvoicePaymentTags(paymentId, 
                                                         List.of(tagDefinitionId), 
                                                         requestOptions);

tag_name = 'foo'

invoice_payment.add_tag(tag_name,
                        user,
                        reason,
                        comment,
                        options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '8d85a8e8-c94b-438f-aac1-e8cb436b2c05'
tag = ["353752dd-9041-4450-b782-a8bb03a923c8"]

invoicePaymentApi.create_invoice_payment_tags(payment_id,
                                              tag,
                                              created_by,
                                              api_key,
                                              api_secret)

Request Body

Provides a list of tag definition Ids in JSON format

Query Parameters

None.

Response

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

Retrieve invoice payment tags

Retrieves all tags attached to this InvoicePayment.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/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/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/tags' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

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

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

List<Tag> tags = invoicePaymentApi.getInvoicePaymentTags(paymentId, 
                                                         includedDeleted, 
                                                         AuditLevel.FULL, 
                                                         requestOptions);

included_deleted = false
audit = 'NONE'

invoice_payment.tags(included_deleted,
                     audit,
                     options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '2a1ffd2c-0de1-4f5c-b2a9-27d8deebe596'

invoicePaymentApi.get_invoice_payment_tags(payment_id, api_key, api_secret)

Example Response:

[
  {
    "tagId": "e7f68cab-3b9a-4150-909a-5f1c17f1fb2b",
    "objectType": "PAYMENT",
    "objectId": "cc7fcd4d-e701-4679-9741-41289103db83",
    "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

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and a list of tag objects.

Remove tags from an invoice payment

Removes a list of tags attached to an InvoicePayment.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/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/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/tags?tagDef=00000000-0000-0000-0000-000000000001'    

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

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

UUID autoPayOffId = UUID.fromString("00000000-0000-0000-0000-000000000001");

invoicePaymentApi.deleteInvoicePaymentTags(paymentId, 
                                           List.of(autoPayOffId), 
                                           requestOptions);

tag_name = 'TEST'

invoice_payment.remove_tag(tag_name,
                           user,
                           reason,
                           comment,
                           options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '8d85a8e8-c94b-438f-aac1-e8cb436b2c05'
tag = ["00000000-0000-0000-0000-000000000002"]

invoicePaymentApi.delete_invoice_payment_tags(payment_id, 
                                              created_by, 
                                              api_key, 
                                              api_secret, 
                                              tag_def=tag)

Query Parameters

Name Type Required Default Description
tagDef array of string yes none List of tag definition IDs identifying the tags that should be removed.

Response

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

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 invoice payment audit logs with history by id

Retrieves a list of audit log records showing events that occurred involving changes to a specified invoice payment. History information is included with each record.

HTTP Request

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

                                                                                      requestOptions);

Example Response:

[
  {
    "changeType": "INSERT",
    "changeDate": "2018-07-19T16:39:00.000Z",
    "objectType": "PAYMENT",
    "objectId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
    "changedBy": "demo",
    "reasonCode": null,
    "comments": null,
    "userToken": "5d32d0ab-3c08-47b2-8c6d-bb9d2a7fd62c",
    "history": 
    {
      "id": null,
      "createdDate": "2018-07-19T16:39:00.000Z",
      "updatedDate": "2018-07-19T16:39:00.000Z",
      "recordId": 14,
      "accountRecordId": 35,
      "tenantRecordId": 1,
      "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
      "paymentNumber": null,
      "paymentMethodId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
      "externalKey": "paymentExternalKey",
      "stateName": null,
      "lastSuccessStateName": null,
      "tableName": "PAYMENTS",
      "historyTableName": "PAYMENT_HISTORY"
    }
  },
]

**Query Parameters**

None.

**Response**

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