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) |
authAmount: Total amount that is authorized for this payment. Often this is the amount authorized by a single AUTHORIZATION Payment Transaction.
capturedAmount: Total amount that has been captured (that is, successfully paid).
purchasedAmount: Total amount that has been purchased. A PURCHASE transaction combines authorization and capture.
refundedAmount: Total amount that has been refunded.
creditedAmount: Total amount that has been credited.
paymentAttempts: Number of payment attempts; this is only effective when the system has been configured to retry failed transactions.
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.
No attributes are required for the account; however if the
currencyattribute is not given here it must be given for the transaction.If a new account is created, a new paymentMethod must be registered for that account. The only attribute required here is the pluginName.
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.
List and Search
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. The search string is compared against the paymentNumber, paymentId, accountId, or transactionType attributes. An exact match is required.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/payments/search/{searchKey}
Example Request:
curl \
-u admin:password \
-H 'X-Killbill-ApiKey: bob' \
-H 'X-Killbill-ApiSecret: lazar' \
-H 'Accept: application/json' \
'http://127.0.0.1:8080/1.0/kb/payments/search/8fe697d4-2c25-482c-aa45-f6cd5a48186d'
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 |
|---|---|---|---|---|
| searchKey | string | yes | none | What you want to find |
| 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.