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}

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.

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'

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

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.

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'

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}

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.

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'

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": []
}

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

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.

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'

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": []
}

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}

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.

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'

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

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.

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'

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}

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.

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'

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

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.

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'

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

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.

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'

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

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.

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'

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

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.

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'

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

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.

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'

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

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.

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'

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

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.

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'

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

Query Parameters

None.

Response

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

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'

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

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.

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'

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

Request Body

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

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.

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' 

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

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

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.

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'

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

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.

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'

Example Response:

[
  {
    "customFieldId": "e4bac228-872d-4966-8072-2c3ac06442ed",
    "objectId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
    "objectType": "PAYMENT",
    "name": "Test Custom Field",
    "value": "test_value",
    "auditLogs": []
  }
]

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

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.

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'

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

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.

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'

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

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.

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'

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

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.

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'

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": []
  }
]

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

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.

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'

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

Query Parameters

None.

Response

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

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'

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"
    }
  },
]

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

Query Parameters

None.

Response

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

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'

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"
    }
  }
]

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

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.

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'

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": []
  }
]

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:

  • field: The name of the field you want to filter by. Possible values are:
    • id
    • account_id
    • payment_method_id
    • external_key
    • state_name
    • last_success_state_name
    • created_by
    • created_date
    • updated_by
    • updated_date
  • <operator>: The comparison operator. This is optional and defaults to the equal to (=) operator if not specified. Possible values are:
    • and
    • eq
    • gte
    • gt
    • like
    • lte
    • lt
    • neq
    • or
  • value: The value to be used for filtering.

Some advanced search key examples:

  • _q=1&payment_method_id=876aa7a2-e94a-4787-b193-71b6c882ae2d - Returns payments where payment_method_id is 876aa7a2-e94a-4787-b193-71b6c882ae2d
  • _q=1&state_name%5Blike%5D=%25SUCCESS - Returns payments where state_name ends with SUCCESS

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}

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.

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

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": []
  }
]