Payment

A Payment in Kill Bill is an amount paid or payable on a specific account due to an invoice or independent of any invoice.

A Payment may be associated with a series of PaymentTransactions, such as authorization, payment attempt, chargeback, etc. each of which may succeed or fail.

A Payment Transaction takes place using a PaymentMethod such as a credit card. The transaction is processed by a plugin, which provides access to the appropriate payment gateway. The payment gateway processes the transaction, using the Payment Method provided in the request.

A Payment Attempt is an attempt to perform a Payment Transaction. A Payment Attempt may succeed or fail, and a Payment Transaction may have more than one Payment Attempt. In some cases a Payment Transaction may be in a PENDING state waiting for completion of its processing by the plugin.

Please refer to the payment manual for more details.

Payment Resource

A Payment is represented by a Payment resource object. The attributes for the Payment resource are as follows:

Name Type Generated by Description
paymentId string system UUID for the payment
accountId string system UUID for the account
paymentNumber number user or system User's ID number for the payment
paymentExternalKey string user or system Optional external key
authAmount string system Total amount authorized (see below)
capturedAmount string system Total amount captured (see below)
purchasedAmount string system Total amount purchased (see below)
refundedAmount string system Total amount refunded (see below)
creditedAmount string system Total amount credited (see below)
currency string user or system Currency associated with the account
paymentMethodId string system UUID for the payment method
transactions list system PaymentTransactions associated with this payment (see below)
paymentAttempts list system Payment retries (see below)

The attributes for a PaymentTransaction are described here.

Payments

These endpoints initiate transactions on an existing Payment. To begin a new Payment, see Trigger a Payment in the Account API.

Capture an existing authorization [using paymentId]

Attempts to capture a payment amount based on a prior authorization. (A prior authorization may be created via the Trigger a Payment endpoint). The Payment is identified by its paymentId provided as a path parameter.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments/{paymentId}

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
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("33eae7eb-0ad4-45d6-a12a-940e0b460be4");

PaymentTransaction captureTransaction = new PaymentTransaction();
captureTransaction.setPaymentId(paymentId);
captureTransaction.setAmount(BigDecimal.ONE);
captureTransaction.setCurrency(Currency.USD);

List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment capturedPayment = paymentApi.captureAuthorization(paymentId, 
                                                          captureTransaction, 
                                                          NULL_PLUGIN_NAMES, 
                                                          NULL_PLUGIN_PROPERTIES, 
                                                          requestOptions);

transaction            = KillBillClient::Model::Transaction.new
transaction.payment_id = "b2a187b8-0028-4de8-b349-0ebe4e714a5a"
transaction.amount     = "483.22"
transaction.currency   = "BTC"

transaction.capture(user, 
                    reason, 
                    comment, 
                    options)

paymentApi = killbill.api.PaymentApi()
payment_id = 'b2a187b8-0028-4de8-b349-0ebe4e714a5a'
body = PaymentTransaction(payment_id=payment_id, 
                          amount=50.0, 
                          currency='USD')

paymentApi.capture_authorization(payment_id,
                                 body,
                                 created_by,
                                 api_key,
                                 api_secret)

Request Body

A PaymentTransaction object containing, as a minimum, the amount to be captured.

Query Parameters

None.

Response

If successful, returns a status code of 201 and an empty body. A Location header containing the payment id is also included in the response. A PaymentTransaction of type CAPTURE is created.

Capture an existing authorization [using paymentExternalKey]

Requests a payment amount based on a prior authorization.(A prior authorization may be created via the Trigger a Payment endpoint).The payment is identified by its external key given in the request body.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments

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 '{
          "paymentExternalKey": "paymentExternalKey",
          "amount": 1
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments'     

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

PaymentTransaction captureTransaction = new PaymentTransaction();
captureTransaction.setAmount(BigDecimal.ONE);
captureTransaction.setCurrency(Currency.USD);
captureTransaction.setPaymentExternalKey("8e0c507a-05f9-4572-a57d-3f742cdc040d"); //payment external key
captureTransaction.setTransactionExternalKey("9b4dbbe7-749d-4c96-a2e7-57b8bff3bf05"); //external key to be set on the newly created CAPTURE transaction

List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment capturedPayment2 = paymentApi.captureAuthorizationByExternalKey(captureTransaction, 
                                                                        NULL_PLUGIN_NAMES, 
                                                                        NULL_PLUGIN_PROPERTIES, 
                                                                        requestOptions);

transaction                          = KillBillClient::Model::Transaction.new
transaction.amount                   = "483.22"
transaction.currency                 = "BTC"
transaction.transaction_external_key = "payment1-323475"

transaction.capture(user, 
                    reason, 
                    comment, 
                    options)

paymentApi = killbill.api.PaymentApi()
payment_external_key = 'sample_external_key'
body = PaymentTransaction(payment_external_key=payment_external_key,
                          amount=50.0,
                          currency='USD')

paymentApi.capture_authorization_by_external_key(body, 
                                                 created_by, 
                                                 api_key, 
                                                 api_secret)

Request Body

A PaymentTransaction object containing, as a minimum, the paymentExternalKey and theamount to be captured.

Query Parameters

None.

Response

If successful, returns a status code of 201 and an empty body. A Location header containing the payment id is also included in the response. A PaymentTransaction of type CAPTURE is created.

Retrieve a payment [using paymentId]

Retrieves a Payment object based on its paymentId given as a path parameter.

HTTP Request

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

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
Boolean withPluginInfo = false; // Will not reflect plugin info
Boolean withAttempts = true; // Will reflect payment attempts
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment payment = paymentApi.getPayment(paymentId, 
                                        withPluginInfo, 
                                        withAttempts, 
                                        NULL_PLUGIN_PROPERTIES, 
                                        AuditLevel.NONE, 
                                        requestOptions);

payment_id = "12c70604-cede-4df3-a321-38be4d176e9a"
with_plugin_info = false
with_attempts = false

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

paymentApi = killbill.api.PaymentApi()
payment_id = 'ce88ae5b-7ec0-4e14-9ea1-fffe4411278e'

paymentApi.get_payment(payment_id, api_key, api_secret)

Example Response:

{
  "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
  "paymentId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
  "paymentNumber": "14",
  "paymentExternalKey": "paymentExternalKey",
  "authAmount": 1,
  "capturedAmount": 6,
  "purchasedAmount": 0,
  "refundedAmount": 0,
  "creditedAmount": 0,
  "currency": "USD",
  "paymentMethodId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
  "transactions": [
    {
      "transactionId": "208d38df-8d5a-4e20-89df-15db4b3516b4",
      "transactionExternalKey": "208d38df-8d5a-4e20-89df-15db4b3516b4",
      "paymentId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
      "paymentExternalKey": "paymentExternalKey",
      "transactionType": "AUTHORIZE",
      "amount": 1,
      "currency": "USD",
      "effectiveDate": "2018-07-19T16:39:00.000Z",
      "processedAmount": 1,
      "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
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 Payment object.

Note: The effectiveDate of the last payment attempt in SCHEDULED state corresponds to the next scheduled payment retry date and can be used as such.

Retrieve a payment [using paymentExternalKey]

Retrieves a Payment object based on its external key given as a query parameter.

HTTP Request

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

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/payments?externalKey=paymentExternalKey' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

String externalPaymentKey = "11b28b2e-a377-4b95-b712-d71cbcb28f80";
Boolean withPluginInfo = false; // Will not reflect plugin info
Boolean withAttempts = false; // Will not reflect payment attempts
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment payment = paymentApi.getPaymentByExternalKey(externalPaymentKey,
                                                     withPluginInfo, 
                                                     withAttempts, 
                                                     NULL_PLUGIN_PROPERTIES, 
                                                     AuditLevel.NONE, 
                                                     requestOptions);

external_key = "example_payment_external_key"
with_plugin_info = false
with_attempts = false

KillBillClient::Model::Payment.find_by_external_key(external_key, 
                                                    with_plugin_info, 
                                                    with_attempts, 
                                                    options)

paymentApi = killbill.api.PaymentApi()
payment_external_key = 'sample_external_key' 

paymentApi.get_payment_by_external_key(payment_external_key,
                                       api_key,
                                       api_secret)

Example Response:

{
  "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
  "paymentId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
  "paymentNumber": "14",
  "paymentExternalKey": "paymentExternalKey",
  "authAmount": 1,
  "capturedAmount": 6,
  "purchasedAmount": 0,
  "refundedAmount": 0,
  "creditedAmount": 0,
  "currency": "USD",
  "paymentMethodId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
  "transactions": [
    {
      "transactionId": "208d38df-8d5a-4e20-89df-15db4b3516b4",
      "transactionExternalKey": "208d38df-8d5a-4e20-89df-15db4b3516b4",
      "paymentId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
      "paymentExternalKey": "paymentExternalKey",
      "transactionType": "AUTHORIZE",
      "amount": 1,
      "currency": "USD",
      "effectiveDate": "2018-07-19T16:39:00.000Z",
      "processedAmount": 1,
      "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
externalKey string yes none Payment external key
withPluginInfo boolean no false If true, include plugin info
withAttempts boolean no false If true, include payment attempts
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 Payment object.

Complete an existing transaction [using paymentId]

Completes any existing PaymentTransaction 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/payments/{paymentId}

Example Request:

curl \
    -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": "8fe697d4-2c25-482c-aa45-f6cd5a48186d"
      }' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
PaymentTransaction body = new PaymentTransaction();
body.setPaymentId(paymentId);

List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

paymentApi.completeTransaction(paymentId, 
                               body, 
                               NULL_PLUGIN_NAMES, 
                               NULL_PLUGIN_PROPERTIES, 
                               requestOptions);

transaction            = KillBillClient::Model::Transaction.new
transaction.payment_id = "7dcda896-808b-414c-aad4-74ddc98e3dcb"
refresh_options        = nil

transaction.complete_initial_transaction(user, 
                                         reason, 
                                         comment, 
                                         options, 
                                         refresh_options)

paymentApi = killbill.api.PaymentApi()
payment_id = '7dcda896-808b-414c-aad4-74ddc98e3dcb'
body = PaymentTransaction(payment_id=payment_id)

paymentApi.complete_transaction(payment_id,
                                body,
                                created_by,
                                api_key,
                                api_secret)

Request Body

A PaymentTransaction object containing, at least, the paymentId

Query Parameters

None.

Returns

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

Complete an existing transaction [using paymentExternalKey]

Completes any existing PaymentTransaction that is in a PENDING state, based on its paymentExternalKey given in the request body.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/payments

Example Request:

curl \
    -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 '{
          "paymentExternalKey": "paymentExternalKey"
      }' \
    'http://127.0.0.1:8080/1.0/kb/payments' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

String externalPaymentKey = "11b28b2e-a377-4b95-b712-d71cbcb28f80";
List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

PaymentTransaction body = new PaymentTransaction();
body.setPaymentExternalKey(externalPaymentKey);

paymentApi.completeTransactionByExternalKey(body, 
                                            NULL_PLUGIN_NAMES, 
                                            NULL_PLUGIN_PROPERTIES, 
                                            requestOptions);

transaction                      = KillBillClient::Model::Transaction.new
transaction.payment_external_key = "example_payment_external_key"
refresh_options                  = nil

transaction.complete_initial_transaction(user, 
                                         reason, 
                                         comment, 
                                         options, 
                                         refresh_options)

paymentApi = killbill.api.PaymentApi()
payment_external_key = 'sample_external_key'
body = PaymentTransaction(payment_external_key=payment_external_key)

paymentApi.complete_transaction_by_external_key(body,
                                                created_by,
                                                api_key,
                                                api_secret)

Request Body

A PaymentTransaction object containing, at least, the paymentExternalKey

Query Parameters

None.

Returns

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

Void an existing payment [using paymentId]

Voids a Payment, providing it is in a voidable state. For example, a Payment with only an AUTHORIZE transaction can be voided. No further transactions are possible on a voided Payment. The Payment is identified by its paymentId, which is given as a path parameter.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/payments/{paymentId}

Example Request:

curl -v \
    -X DELETE \
    -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": "8fe697d4-2c25-482c-aa45-f6cd5a48186d"
      }' \    
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d'    

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
PaymentTransaction body = new PaymentTransaction();
body.setPaymentId(paymentId);

List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

paymentApi.voidPayment(paymentId, 
                       body, 
                       NULL_PLUGIN_NAMES, 
                       NULL_PLUGIN_PROPERTIES, 
                       requestOptions);

transaction             = KillBillClient::Model::Transaction.new
transaction.payment_id  = "29b34a3d-d301-4e57-8fc2-2c0a201c4fd0"

transaction.void(user, 
                 reason, 
                 comment, 
                 options)

paymentApi = killbill.api.PaymentApi()
payment_id = '29b34a3d-d301-4e57-8fc2-2c0a201c4fd0'
body = PaymentTransaction(payment_id=payment_id)

paymentApi.void_payment(payment_id,
                        body,
                        created_by,
                        api_key,
                        api_secret)

Request Body

A PaymentTransaction object containing, at least, the paymentId

Query Parameters

None.

Returns

If successful, returns a status code of 204 and an empty body. a PaymentTransaction of type VOID is created.

Void an existing payment [using paymentExternalKey]

Voids a Payment, providing it is in a voidable state. For example, a Payment with only an AUTHORIZE transaction can be voided. can be voided. No further transactions are possible on a voided payment. The payment is identified by its paymentExternalKey, which is given as a query parameter.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/payments

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Content-Type: application/json' \
    -H 'X-Killbill-CreatedBy: demo' \
    -d '{
          "paymentExternalKey": "paymentExternalKey"
      }' \
    'http://127.0.0.1:8080/1.0/kb/payments'     

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

String paymentExternalKey = "cca08349-8b26-41c7-bfcc-2e3cf70a0f28";
PaymentTransaction body = new PaymentTransaction();
body.setPaymentExternalKey(paymentExternalKey);

List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

paymentApi.voidPaymentByExternalKey(body, 
                                    NULL_PLUGIN_NAMES, 
                                    NULL_PLUGIN_PROPERTIES, 
                                    requestOptions);

transaction                          = KillBillClient::Model::Transaction.new
transaction.transaction_external_key = "payment2-121268-void"

transaction.void(user, 
                 reason, 
                 comment, 
                 options)

paymentApi = killbill.api.PaymentApi()
payment_external_key = 'sample_external_key'
body = PaymentTransaction(payment_external_key=payment_external_key)

paymentApi.void_payment_by_external_key(body,
                                        created_by,
                                        api_key,
                                        api_secret)

Request Body

A Payment object containing, at least, the paymentExternalKey.

Query Parameters

None.

Returns

If successful, returns a status code of 204 and an empty body. A PaymentTransaction of type VOID is created.

Record a chargeback [using paymentId]

Creates a CHARGEBACK PaymentTransaction for a specified Payment. The Payment is identified by its paymentId given as a path parameter. The captured amount is reduced by the chargeback amount.

HTTP Request

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

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("8a096f10-1591-4546-880d-f6d4f7ea818c");
PaymentTransaction body = new PaymentTransaction();
body.setAmount(new BigDecimal(5));

List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment payment = paymentApi.chargebackPayment(paymentId, body, NULL_PLUGIN_NAMES, NULL_PLUGIN_PROPERTIES, requestOptions);

transaction                = KillBillClient::Model::Transaction.new
transaction.payment_id     = "42ab1653-051f-416c-8c70-bf5d4061d4fa"
transaction.amount         = '50.0'
transaction.currency       = 'USD'
transaction.effective_date = nil
refresh_options            = nil

transaction.chargeback(user, 
                       reason, 
                       comment, 
                       options, 
                       refresh_options)

paymentApi = killbill.api.PaymentApi()
payment_id = '42ab1653-051f-416c-8c70-bf5d4061d4fa'
body = PaymentTransaction(payment_id=payment_id,
                          amount=50.0,
                          currency='USD',
                          effective_date=None)

paymentApi.chargeback_payment(payment_id,
                              body,
                              created_by,
                              api_key,
                              api_secret)

Request Body

A Payment Transaction object containing, at least, the amount.

Query Parameters

None.

Returns

If successful, returns a status code of 204 and an empty body. A Payment Transaction is created with type CHARGEBACK.

Record a chargeback [using paymentExternalKey]

Creates a CHARGEBACK PaymentTransaction for a specified Payment. The Payment is identified by its paymentExternalKey given in the request body. The captured amount is reduced by the chargeback amount.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments/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 '{
          "paymentExternalKey": "a187746f-841a-481c-8d6c-4497080ed968",
          "amount": 5,
          "currency": "USD"
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/chargebacks' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

PaymentTransaction body = new PaymentTransaction();
body.setPaymentExternalKey("a975f7b8-1e59-4801-91c9-fcce1526b019");
body.setAmount(new BigDecimal(5));

List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment payment = paymentApi.chargebackPaymentByExternalKey(body, NULL_PLUGIN_NAMES, NULL_PLUGIN_PROPERTIES, requestOptions);


transaction                      = KillBillClient::Model::Transaction.new
transaction.payment_external_key = "example_payment_external_key"
transaction.amount               = '50.0'
transaction.currency             = 'USD'
transaction.effective_date       = nil
refresh_options                  = nil

transaction.chargeback(user, 
                       reason, 
                       comment, 
                       options, 
                       refresh_options)

paymentApi = killbill.api.PaymentApi()
payment_external_key = 'sample_external_key'
body = PaymentTransaction(payment_external_key=payment_external_key,
                          amount=50.0,
                          currency='USD',
                          effective_date=None)

paymentApi.chargeback_payment_by_external_key(body,
                                              created_by,
                                              api_key,
                                              api_secret)

Request Body

A PaymentTransaction object containing, at least, the paymentExternalKey and the amount.

Query Parameters

None.

Returns

If successful, returns a status code of 204 and an empty body. A PaymentTransaction is created with type CHARGEBACK.

Record a chargeback reversal [using paymentId]

Reverses a CHARGEBACK PaymentTransaction, 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. The CHARGEBACK transaction is identified by its transactionExternalKey which is given in the request body.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments/{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": "7ff346e8-24cc-4437-acfa-c79d96d54ee2"
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/chargebackReversals' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

PaymentTransaction body = new PaymentTransaction();
body.setPaymentExternalKey("a975f7b8-1e59-4801-91c9-fcce1526b019");
body.setAmount(new BigDecimal(5));

List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment payment = paymentApi.chargebackPaymentByExternalKey(body, NULL_PLUGIN_NAMES, NULL_PLUGIN_PROPERTIES, requestOptions);

transaction                          = KillBillClient::Model::Transaction.new
transaction.transaction_external_key = "9ceb96a2-5407-482b-8847-7b08cc64213f"
transaction.payment_id               = "74a82e25-120a-4a39-a7f7-7b5c2b4ac05d"

transaction.chargeback_reversals(user, 
                                 reason, 
                                 comment, 
                                 options)

paymentApi = killbill.api.PaymentApi()
payment_id = '74a82e25-120a-4a39-a7f7-7b5c2b4ac05d'
transaction_external_key = '9ceb96a2-5407-482b-8847-7b08cc64213f'
body = PaymentTransaction(payment_id=payment_id,
                          transaction_external_key=transaction_external_key)

paymentApi.chargeback_reversal_payment(payment_id,
                                       body,
                                       created_by,
                                       api_key,
                                       api_secret)

Request Body

A PaymentTransaction object containing, at least, the transactionExternalKey.

Query Parameters

None.

Response

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

Record a chargeback reversal [using paymentExternalKey]

Reverses a CHARGEBACK PaymentTransaction, if permitted by the Payment plugin. The chargeback amount is added back to the captured amount. The Payment is identified by its paymentExternalKey which is given in the request body. The CHARGEBACK transaction is identified by its transactionExternalKey which is also given in the request body.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments/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": "7ff346e8-24cc-4437-acfa-c79d96d54ee2",
          "paymentExternalKey": "paymentExternalKey"
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/chargebackReversals' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

PaymentTransaction body = new PaymentTransaction();
body.setPaymentExternalKey("631ec4ac-d745-4457-939d-d761badbf0ad");
body.setTransactionExternalKey("72789509-2b94-43b6-b889-42c5ec5d27f3");
body.setAmount(new BigDecimal(10));

List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment payment = paymentApi.chargebackPaymentByExternalKey(body, NULL_PLUGIN_NAMES, NULL_PLUGIN_PROPERTIES, requestOptions);

transaction                      = KillBillClient::Model::Transaction.new
transaction.payment_external_key = "example_payment_external_key"

transaction.chargeback_reversals(user, 
                                 reason, 
                                 comment, 
                                 options)

paymentApi = killbill.api.PaymentApi()
body = PaymentTransaction(payment_external_key=payment_external_key,
                          transaction_external_key=transaction_external_key)

paymentApi.chargeback_reversal_payment_by_external_key(body,
                                                       created_by,
                                                       api_key,
                                                       api_secret)

Request Body

A PaymentTransaction object containing, at least, the paymentExternalKey and the TransactionExternalKey.

Query Parameters

None.

Response

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

Refund an existing payment [using paymentId]

Refunds part or all of the balance of an existing Payment. 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/payments/{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": 5
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/refunds' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("89614849-9bd6-43ba-93d0-e9deb1acf575");

PaymentTransaction body = new PaymentTransaction();
body.setPaymentId(paymentId);
body.setAmount(BigDecimal.TEN);
body.setCurrency(Currency.USD);
body.setPaymentExternalKey("de924e98-2c76-4e90-b9d6-2ced262bc251");

List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment refundPayment = paymentApi.refundPayment(paymentId, 
                                                 body, 
                                                 NULL_PLUGIN_NAMES, 
                                                 NULL_PLUGIN_PROPERTIES, 
                                                 requestOptions);

transaction            = KillBillClient::Model::Transaction.new
transaction.payment_id = "dce5b2a0-0f0f-430b-9427-545ba4be5c7f"
transaction.amount     = '50.0'
refresh_options        = nil

transaction.refund(user, 
                   reason, 
                   comment, 
                   options, 
                   refresh_options)

paymentApi = killbill.api.PaymentApi()
payment_id = 'dce5b2a0-0f0f-430b-9427-545ba4be5c7f' 
body = PaymentTransaction(payment_id=payment_id,
                          amount=50.0)

paymentApi.refund_payment(payment_id,
                          body,
                          created_by,
                          api_key,
                          api_secret)

Request Body

A PaymentTransaction object including, as a minimum, the amount to be refunded.

Query Parameters

None.

Returns

If successful, returns a status code of 201 and an empty body. In addition, a Location header containing the payment id is returned. A new PaymentTransaction of type REFUND is created.

Refund an existing payment [using paymentExternalKey]

Refunds part or all of the balance of an existing payment. The payment is identified by its paymentExternalKey, which is given in the request body.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments/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 '{
          "paymentExternalKey": "paymentExternalKey",
          "amount": 5,
          "currency": "USD"
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/refunds' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

PaymentTransaction body = new PaymentTransaction();
body.setAmount(new BigDecimal(2));
body.setCurrency(Currency.USD);
body.setPaymentExternalKey("da96999c-b1ac-470f-8c48-c4ecf386cd89");

List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment refundPayment = paymentApi.refundPaymentByExternalKey(body, NULL_PLUGIN_NAMES, NULL_PLUGIN_PROPERTIES, requestOptions);


transaction                      = KillBillClient::Model::Transaction.new
transaction.payment_external_key = "example_payment_external_key"
transaction.amount               = '50.0'
refresh_options                  = nil

transaction.refund_by_external_key(user, 
                                   reason, 
                                   comment, 
                                   options, 
                                   refresh_options)

paymentApi = killbill.api.PaymentApi()
payment_external_key = 'example_payment_external_key'
body = PaymentTransaction(payment_external_key=payment_external_key,
                          amount=50.0)

paymentApi.refund_payment_by_external_key(body,
                                          created_by,
                                          api_key,
                                          api_secret)

Request Body

A PaymentTransaction object including, as a minimum, the paymentExternalKey and the amount to be refunded.

Query Parameters

None.

Returns

If successful, returns a status code of 201 and an empty body. In addition, a Location header containing the payment id is returned. A new PaymentTransaction of type REFUND is created.

Cancel a scheduled payment attempt retry [using transactionId]

Cancels a scheduled attempt to retry a PaymentTransaction. The transaction is identified by its transactionId, which is provided as a path parameter.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/payments/{paymentTransactionId}/cancelScheduledPaymentTransaction

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/payments/208d38df-8d5a-4e20-89df-15db4b3516b4/cancelScheduledPaymentTransaction'  

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentTransactionId = UUID.fromString("54aed1ed-f8dc-4445-a19f-3a2519c1a334");
paymentApi.cancelScheduledPaymentTransactionById(paymentTransactionId, requestOptions);


transaction                = KillBillClient::Model::Transaction.new
transaction.transaction_id = "231d2bbc-7ce3-4946-b6d9-f24f9a25ff6c"

transaction.cancel_scheduled_payment(user, 
                                     reason, 
                                     comment, 
                                     options)

paymentApi = killbill.api.PaymentApi()
payment_transaction_id = '231d2bbc-7ce3-4946-b6d9-f24f9a25ff6c'

paymentApi.cancel_scheduled_payment_transaction_by_id(payment_transaction_id,
                                                      created_by,
                                                      api_key,
                                                      api_secret)

Query Parameters

None.

Response

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

Cancel a scheduled payment attempt retry [using transactionExternalKey]

Cancels a scheduled attempt to retry a PaymentTransaction. The transaction is identified by its transactionExternalKey, which is provided as a query parameter.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/payments/cancelScheduledPaymentTransaction

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/payments/cancelScheduledPaymentTransaction?transactionExternalKey=transaction'    

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

String transactionExternalKey = "example_payment_external_key";

paymentApi.cancelScheduledPaymentTransactionByExternalKey(transactionExternalKey, inputOptions);

transaction                          = KillBillClient::Model::Transaction.new
transaction.transaction_external_key = "example_payment_external_key"

transaction.cancel_scheduled_payment(user, 
                                     reason, 
                                     comment, 
                                     options)

paymentApi = killbill.api.PaymentApi()
transaction_external_key = 'example_payment_external_key'

paymentApi.cancel_scheduled_payment_transaction_by_external_key(transaction_external_key,
                                                                created_by,
                                                                api_key,
                                                                api_secret)

Query Parameters

Name Type Required Default Description
transactionExternalKey string yes none Transaction external key

Response

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

Combo api to create a new payment transaction on a existing (or not) account

This API creates a PaymentTransaction of type AUTHORIZE, PURCHASE, or CREDIT. This is the same as the API Trigger a Payment described with the Account endpoints. However, this API can optionally create a new Account and register a new PaymentMethod at the same time.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments/combo

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 '{
            "account": 
            {
                "name": "John Doe"
            },
            "paymentMethod": 
            {
                "pluginName": "__EXTERNAL_PAYMENT__"
            },
            "transaction":
            {
                "transactionType": "AUTHORIZE",
                "amount": 5,
                "currency": "USD"
            }
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/combo' 

import org.killbill.billing.client.api.gen.AccountApi;
import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

Account account = new Account();
account.setName("Jane Doe");
account.setExternalKey("JaneDoe");

PaymentMethod paymentMethod = new PaymentMethod();
paymentMethod.setPluginName("__EXTERNAL_PAYMENT__");

PaymentTransaction paymentTransaction = new PaymentTransaction();
paymentTransaction.setAmount(BigDecimal.TEN);
paymentTransaction.setCurrency(Currency.USD);
paymentTransaction.setTransactionType(TransactionType.AUTHORIZE);

ComboPaymentTransaction body = new ComboPaymentTransaction();
body.setAccount(account);
body.setPaymentMethod(paymentMethod);
body.setTransaction(paymentTransaction);

List<String> NULL_PLUGIN_NAMES = null;

Payment result = paymentApi.createComboPayment(body,  NULL_PLUGIN_NAMES, requestOptions);

combo_transaction = KillBillClient::Model::ComboTransaction.new
combo_transaction.account = account_obj
combo_transaction.payment_method = payment_method_obj
combo_transaction.transaction = transaction_obj

refresh_options = nil

# Authorization
combo_transaction.auth(user, 
                       reason, 
                       comment, 
                       options, 
                       refresh_options)

# Purchase
combo_transaction.purchase(user, 
                           reason, 
                           comment, 
                           options, 
                           refresh_options)

# Credit
combo_transaction.credit(user, 
                         reason, 
                         comment, 
                         options, 
                         refresh_options)

paymentApi = killbill.api.PaymentApi()
body = ComboPaymentTransaction(account_obj, payment_method_obj, payment_transaction_obj)

paymentApi.create_combo_payment(body,
                                created_by,
                                api_key,
                                api_secret)

Request Body

The request body is a JSON string that represents three distinct objects: account, paymentMethod, and transaction. For example:

{
  "account": {
  },
  "paymentMethod": {
    "pluginName": "__EXTERNAL_PAYMENT__"
  "transaction": {
    "transactionType": "AUTHORIZE",
    "amount": 500,
    "currency": "USD"
  }
}

This example assumes that a new Account is to be created.

  1. No attributes are required for the account; however if the currency attribute is not given here it must be given for the transaction.

  2. If a new account is created, a new paymentMethod must be registered for that account. The only attribute required here is the pluginName.

  3. The transaction object contains, as a minimum, the transaction type, the amount, and the currency, unless given with the account.

Query Parameters

None.

Returns

If successful, returns a status code of 201 and an empty body. In addition, a Location header containing the paymentId is returned.

Custom Fields

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

Add custom fields to payment

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

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments/{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 Field",
            "value": "test_value"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/customFields' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

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

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

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

paymentApi.createPaymentCustomFields(paymentId, 
                                     customFields, 
                                     requestOptions);

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

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

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

paymentApi.create_payment_custom_fields(payment_id,
                                        [body],
                                        created_by,
                                        api_key,
                                        api_secret)

Request Body

A list of Custom Field objects. Each object should specify at least the the name and value attribute. For example:

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

Query Parameters

None.

Response

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

Retrieve payment custom fields

Retrieves the custom fields associated with a payment

HTTP Request

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

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

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

List<CustomField> customFields = paymentApi.getPaymentCustomFields(paymentId,
                                                                   AuditLevel.NONE,
                                                                   requestOptions);

audit = 'NONE'

payment.custom_fields(audit, options)

paymentApi = killbill.api.PaymentApi()

paymentApi.get_payment_custom_fields(payment_id, api_key, api_secret)

Example Response:

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

Modifies the custom fields associated with a payment object

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/payments/{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": "e4bac228-872d-4966-8072-2c3ac06442ed",
            "value": "NewValue"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/customFields' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

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

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

paymentApi.modifyPaymentCustomFields(paymentId, 
                                     customFieldModified, 
                                     requestOptions);

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

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

paymentApi = killbill.api.PaymentApi()
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')

paymentApi.modify_payment_custom_fields(payment_id,
                                        [body],
                                        created_by,
                                        api_key,
                                        api_secret)

Requst Body

A list of Custom Field objects representing the fields to substitute for existing ones. Each object should specify at least the the customFieldId and value attribute. For example:

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

Query Parameters

None.

Response

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

Remove custom fields from a payment

Removes a specified set of custom fields from a payment object

HTTP Request

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

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

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

paymentApi.deletePaymentCustomFields(paymentId, 
                                     customFieldsId, 
                                     requestOptions);

custom_field_id = custom_field.custom_field_id

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

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

paymentApi.delete_payment_custom_fields(payment_id,
                                        created_by,
                                        api_key,
                                        api_secret)

Query Parameters

Name Type Required Default Description
customField string yes none CCustom field object 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 Account Tags for an introduction.

The are no system tags applicable to a Payment.

Add tags to a payment

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

HTTP Request

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

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

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

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

Tags result = paymentApi.createPaymentTags(paymentId, 
                                           List.of(tagDefinitionId), 
                                           requestOptions);

tag_name = 'foo'

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

paymentApi = killbill.api.PaymentApi()
tag = ["353752dd-9041-4450-b782-a8bb03a923c8"]

paymentApi.create_payment_tags(payment_id,
                               tag,
                               created_by,
                               api_key,
                               api_secret)

Request Body

A JSON array containing one or more tag definition ids to be added as tags.

Query Parameters

None.

Response

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

Retrieve payment tags

Retrieves all tags attached to this payment.

HTTP Request

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

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

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

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

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

included_deleted = false
audit = 'NONE'

payment.tags(included_deleted,
             audit,
             options)

paymentApi = killbill.api.PaymentApi()
payment_id = '28af3cb9-275b-4ac4-a55d-a0536e479069'

paymentApi.get_payment_tags(payment_id, api_key, api_secret)

Example Response:

[
  {
    "tagId": "890e3b13-3114-478b-9365-50f1a2682143",
    "objectType": "PAYMENT",
    "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", or "FULL"

Response

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

Remove tags from a payment

Removes a list of tags attached to a payment.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/payments/{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/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/tags?tagDef=353752dd-9041-4450-b782-a8bb03a923c8'   

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

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

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

paymentApi.deletePaymentTags(paymentId, 
                             List.of(tagDefinitionId), 
                             requestOptions);

tag_name = 'TEST'

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

paymentApi = killbill.api.PaymentApi()
payment_id = 'dce5b2a0-0f0f-430b-9427-545ba4be5c7f'
tag = ["353752dd-9041-4450-b782-a8bb03a923c8"] 

paymentApi.delete_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 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.

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

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

HTTP Request

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

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

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

List<AuditLog> paymentAuditLogWithHistory = paymentApi.getPaymentAuditLogsWithHistory(paymentId, 
                                                                                      requestOptions);

accountApi = killbill.api.AccountApi()
account_id = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda'

accountApi.get_account_audit_logs_with_history(account_id, api_key, api_secret)

account.audit_logs_with_history(options)

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 payment audit logs with history.

Retrieve payment attempt audit logs with history by id

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

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/payments/attempts/{payment_attempt_id}/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/payments/attempts/<payment_attempt_id>/auditLogsWithHistory'  

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentAttemptId = UUID.fromString("2706b8c6-97f2-41b7-b9c5-de23726bb399");
AuditLogs logs = paymentApi.getPaymentAttemptAuditLogsWithHistory(paymentAttemptId, requestOptions);

Example Response:

[  
  {
    "changeType": "INSERT",
    "changeDate": "2022-05-02T11:15:52.000Z",
    "objectType": "PAYMENT_ATTEMPT",
    "objectId": "2706b8c6-97f2-41b7-b9c5-de23726bb399",
    "changedBy": "admin",
    "reasonCode": null,
    "comments": null,
    "userToken": "b65afb87-9e43-4ffe-a492-84ac5d5f10a9",
    "history": 
    {
      "id": null,
      "createdDate": "2022-05-02T11:15:52.000Z",
      "updatedDate": "2022-05-02T11:15:52.000Z",
      "recordId": 11214,
      "accountRecordId": 2306,
      "tenantRecordId": 1,
      "accountId": "bdcd8ed0-ffc6-42db-88eb-cf1ee504b9a8",
      "paymentMethodId": "82e375db-4aff-413e-9b52-f70803ea3bc5",
      "paymentExternalKey": "1833cad4-4b10-432e-959b-01dbf3ca0596",
      "transactionId": null,
      "transactionExternalKey": "92f17f72-c03f-427b-95eb-a959451c37b8",
      "transactionType": "PURCHASE",
      "stateName": "INIT",
      "amount": 10,
      "currency": "USD",
      "pluginName": "__INVOICE_PAYMENT_CONTROL_PLUGIN__",
      "pluginProperties": "WlYAAAJbXQ==",
      "historyTableName": "PAYMENT_ATTEMPT_HISTORY",
      "tableName": "PAYMENT_ATTEMPTS"
    }
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2022-05-02T11:15:52.000Z",
    "objectType": "PAYMENT_ATTEMPT",
    "objectId": "2706b8c6-97f2-41b7-b9c5-de23726bb399",
    "changedBy": "admin",
    "reasonCode": null,
    "comments": null,
    "userToken": "b65afb87-9e43-4ffe-a492-84ac5d5f10a9",
    "history": {
      "id": null,
      "createdDate": "2022-05-02T11:15:52.000Z",
      "updatedDate": "2022-05-02T11:15:52.000Z",
      "recordId": 11214,
      "accountRecordId": 2306,
      "tenantRecordId": 1,
      "accountId": "bdcd8ed0-ffc6-42db-88eb-cf1ee504b9a8",
      "paymentMethodId": "82e375db-4aff-413e-9b52-f70803ea3bc5",
      "paymentExternalKey": "1833cad4-4b10-432e-959b-01dbf3ca0596",
      "transactionId": "92f17f72-c03f-427b-95eb-a959451c37b8",
      "transactionExternalKey": "92f17f72-c03f-427b-95eb-a959451c37b8",
      "transactionType": "PURCHASE",
      "stateName": "SUCCESS",
      "amount": 10,
      "currency": "USD",
      "pluginName": "__INVOICE_PAYMENT_CONTROL_PLUGIN__",
      "pluginProperties": "WlYAADxbeyJJUENEX0lOVk9JQ0VfSUQiOiI3MzdmNDRhMi1iYTljLTRjNjQtOTQzYi04NWRlMjEyODMxYWMifV0=",
      "historyTableName": "PAYMENT_ATTEMPT_HISTORY",
      "tableName": "PAYMENT_ATTEMPTS"
    }
  }
]

Query Parameters

None.

Response

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

These endpoints allow you to list all payments or to search for a specific payment.

Get payments

Retrieve a list of all payments for this tenant.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/payments/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/payments/pagination' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

Long offset = 0L;
Long limit = 100L;
String pluginName = null;
Boolean withPluginInfo = false; // Will not fetch plugin info
Boolean withAttempts = true; // Will reflect payment attempts
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payments payments = paymentApi.getPayments(offset, 
                                           limit, 
                                           pluginName, 
                                           withPluginInfo, 
                                           withAttempts, 
                                           NULL_PLUGIN_PROPERTIES, 
                                           AuditLevel.NONE, 
                                           requestOptions);

offset = 0
limit = 100
payment.find_in_batches(offset, 
                        limit, 
                        options)

paymentApi = killbill.api.PaymentApi()

paymentApi.get_payments(api_key, api_secret)

Example Response:

[
  {
    "accountId": "ca15adc4-1061-4e54-a9a0-15e773b3b154",
    "paymentId": "4634b2ae-5263-4139-99b2-e2005f09a9fd",
    "paymentNumber": "7",
    "paymentExternalKey": "4634b2ae-5263-4139-99b2-e2005f09a9fd",
    "authAmount": 0,
    "capturedAmount": 0,
    "purchasedAmount": 0,
    "refundedAmount": 0,
    "creditedAmount": 0,
    "currency": "USD",
    "paymentMethodId": "dc89832d-18a3-42fd-b3be-cac074fddb36",
    "transactions": [
      {
        "transactionId": "92935e84-fd79-4672-98bf-df84566153c6",
        "transactionExternalKey": "92935e84-fd79-4672-98bf-df84566153c6",
        "paymentId": "4634b2ae-5263-4139-99b2-e2005f09a9fd",
        "paymentExternalKey": "4634b2ae-5263-4139-99b2-e2005f09a9fd",
        "transactionType": "PURCHASE",
        "amount": 1,
        "currency": "USD",
        "effectiveDate": "2018-07-18T15:04:05.000Z",
        "processedAmount": 0,
        "processedCurrency": "USD",
        "status": "PLUGIN_FAILURE",
        "gatewayErrorCode": "RuntimeError",
        "gatewayErrorMsg": "Could not retrieve the payer info: the token is missing",
        "firstPaymentReferenceId": null,
        "secondPaymentReferenceId": null,
        "properties": null,
        "auditLogs": []
      }
    ],
    "paymentAttempts": null,
    "auditLogs": []
  }
]

Query Parameters

Name Type Required Default Description
offset long no 0 Starting index for items listed
limit long no 100 Maximum number of items to be listed
withPluginInfo boolean no false if true, include plugin info
withAttempts boolean no false if true, include payment attempts
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 all payments for this tenant.

Search payments

Search for a payment by a specified search string. Search operation can be of two types as follows:

Basic:

The search string is compared against the paymentNumber, paymentId, accountId, or transactionType attributes. An exact match is required.

Advanced:

Advanced search allows filtering on the specified fields. The prefix marker _q=1 needs to be specified at the beginning of the search key to indicate this is an advanced query.

The search key should be in the following format: <field>[<operator>]=value. Here:

Some advanced search key examples:

Note: The symbols [,],% need to be URL encoded while using cURL/Postman as follows:

Symbol Encoding
[ %5B
] %5D
% %25

HTTP Request

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

Example Request:

## Basic Search
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/payments/search/8fe697d4-2c25-482c-aa45-f6cd5a48186d' 

## Advanced Search (search by state_name) 
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/payments/search/_q=1&state_name%5Blike%5D=%25SUCCESS' | jq 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

String searchKey = "ccbc67f5-91cb-4b9a-9648-fa6aedaf0890";
Long offset = 0L;
Long limit = 100L;
Boolean withPluginInfo = false; // Will not reflect plugin info
Boolean withAttempts = true;  // Will reflect payment attempts
String pluginName = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payments payments = paymentApi.searchPayments(searchKey, 
                                              offset, 
                                              limit, 
                                              withPluginInfo, 
                                              withAttempts, 
                                              pluginName, 
                                              NULL_PLUGIN_PROPERTIES, 
                                              AuditLevel.NONE, 
                                              requestOptions);

search_key = 'PURCHASE'
offset = 0
limit = 100

payment.find_in_batches_by_search_key(search_key,
                                      offset,
                                      limit,
                                      options)

paymentApi = killbill.api.PaymentApi()
search_key = 'SUCCESS'

paymentApi.search_payments(search_key, api_key, api_secret)

Example Response:

[
  {
    "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
    "paymentId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
    "paymentNumber": "14",
    "paymentExternalKey": "paymentExternalKey",
    "authAmount": 1,
    "capturedAmount": 6,
    "purchasedAmount": 0,
    "refundedAmount": 10,
    "creditedAmount": 0,
    "currency": "USD",
    "paymentMethodId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
    "transactions": [
      {
        "transactionId": "208d38df-8d5a-4e20-89df-15db4b3516b4",
        "transactionExternalKey": "208d38df-8d5a-4e20-89df-15db4b3516b4",
        "paymentId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
        "paymentExternalKey": "paymentExternalKey",
        "transactionType": "AUTHORIZE",
        "amount": 1,
        "currency": "USD",
        "effectiveDate": "2018-07-19T16:39:00.000Z",
        "processedAmount": 1,
        "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
offset long no 0 Starting index for items listed
limit long no 100 Maximum number of items to be listed
withPluginInfo boolean no false if true, include plugin info
withAttempts boolean no false if true, include payment attempts
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 all payments matched with the search key entered.