To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Records one attempt to take a payment through a payment provider, successful or not. A transaction is created before the payment is attempted, with a UUID that identifies the operation even if the provider never responds, and is then updated with the provider's authorisation code, response code and message. The status flag is the provider's own success or failure verdict and is null until it answers, so a row with a null status is an attempt whose outcome is unknown rather than a failure. Rows are kept for failed attempts too, so a cart can have several. Billing details captured with the payment are stored on the row, and if the payment set up a subscription the resulting RecurringTransaction points back at it.
Group: Database Entities
Implements: Serializable, Relational
Properties
| Property | Returns | Description |
|---|---|---|
| addressLine1 | String | First line of the billing address supplied with the payment. |
| addressLine2 | String | Second line of the billing address supplied with the payment, often blank. |
| amount | BigDecimal | The amount charged, in the transaction's currency. Held as a decimal rather than as cents, and it does not include the transaction fee. |
| authorisationCode | String | Authorisation code returned by the payment provider when it approved the payment. Null for an attempt that was declined or that never got a response. |
| cardName | String | Name on the payment card, as entered by the shopper. Only the name is kept; no card number is ever stored on this row. |
| cart | Cart | The cart this payment was taken for, or null if the payment was not raised from a store purchase. A cart can have several transactions when earlier attempts failed. |
| city | String | City or town from the billing address supplied with the payment. |
| countryCode | String | Country from the billing address supplied with the payment, as a country code rather than a country name. |
| createdBy | Profile | The profile the payment was taken from, which is normally the person who checked out. Required. |
| createdDate | Date | When the payment attempt was created, which is before the provider was called rather than when it responded. Mandatory, and the field transaction listings sort on, newest first. |
| currencyCode | String | Currency the amount is expressed in, as a three letter ISO 4217 code such as NZD. The amount alone is meaningless without it. |
String | Email address supplied with the payment, used for the receipt. This is what the shopper typed at checkout, so it may differ from the paying profile's email address. | |
| errors | String | Error detail captured while attempting the payment, for example an exception raised talking to the provider. Null for an attempt that completed cleanly, whether it was approved or declined. |
| firstName | String | First name from the billing details supplied with the payment. |
| id | long | Database generated primary key for this payment attempt. The uuid, not the id, is what identifies the attempt to the payment provider. |
| invoiceDesc | String | Description passed to the payment provider for the invoice or statement line, up to 2000 characters. This is often what the shopper sees on their card statement. |
| invoiceNum | String | Invoice number passed to the payment provider, up to 200 characters. Used to tie the payment back to an invoice in an external accounting system. |
| org | Organisation | The organisation the payment was taken for. Required, and every transaction lookup is scoped to it, so a transaction cannot be read from another account. |
| phone | String | Contact phone number supplied with the payment, or null if none was given. |
| postCode | String | Postcode or ZIP code from the billing address supplied with the payment. Stored as text, since postcodes are not always numeric. |
| provider | String | Name of the payment provider app that handled this payment, for example the app implementing the gateway integration. Response codes and transaction identifiers only make sense in the context of this provider. |
| responseCode | String | Raw response code returned by the payment provider. The codes are provider specific, so do not compare them across providers; use the status flag for a portable success test. |
| responseMessage | String | Human readable message returned by the payment provider, typically the reason a payment was declined. Safe to log, but it is written by the provider so review it before showing it to a shopper. |
| state | String | State, province or region from the billing address supplied with the payment. Often blank in countries that do not use one. |
| status | Boolean | The success or failure verdict returned by the payment provider. Null until the provider has responded, so a null status means the outcome is unknown rather than that the payment failed. Always check for null before treating a transaction as failed. |
| surName | String | Surname from the billing details supplied with the payment. |
| transactionFee | BigDecimal | The fee the payment provider charged for processing this payment, in the transaction's currency. Separate from the amount, and null when the provider does not report a fee. |
| transactionID | String | The provider's own identifier for this payment, used when reconciling against the provider or requesting a refund. Null until the provider has responded. |
| uuid | String | Random UUID generated when the attempt was created, used to identify the operation with the provider if the call fails or times out. Mandatory, and it is what makes a retry safe to reconcile. |
| website | Website | The website the payment was made through, or null for a payment taken outside a website. |
Methods
getId() · getCreatedDate() · setCreatedDate(Date createdDate) · getCreatedBy() · setCreatedBy(Profile createdBy) · getOrg() · setOrg(Organisation org) · getAuthorisationCode() · setAuthorisationCode(String authorisationCode) · getResponseCode() · setResponseCode(String responseCode) · getResponseMessage() · setResponseMessage(String responseMessage) · getTransactionID() · setTransactionID(String transactionID) · getErrors() · setErrors(String errors) · getCurrencyCode() · setCurrencyCode(String currencyCode) · getAmount() · setAmount(BigDecimal amount) · getTransactionFee() · setTransactionFee(BigDecimal transactionFee) · getWebsite() · setWebsite(Website website) · getUuid() · setUuid(String uuid) · getStatus() · setStatus(Boolean status) · getProvider() · setProvider(String provider) · getInvoiceDesc() · setInvoiceDesc(String invoiceDesc) · getInvoiceNum() · setInvoiceNum(String invoiceNum) · getCardName() · setCardName(String cardName) · getPhone() · setPhone(String phone) · getEmail() · setEmail(String email) · getFirstName() · setFirstName(String firstName) · getSurName() · setSurName(String surName) · getAddressLine1() · setAddressLine1(String addressLine1) · getAddressLine2() · setAddressLine2(String addressLine2) · getCity() · setCity(String city) · getState() · setState(String state) · getPostCode() · setPostCode(String postCode) · getCountryCode() · setCountryCode(String countryCode) · getCart() · setCart(Cart cart) · findRecurringTx() · findRecurringTxs()
getId()
Returns: long
Database generated primary key for this payment attempt. The uuid, not the id, is what identifies the attempt to the payment provider.
getCreatedDate()
Returns: Date
When the payment attempt was created, which is before the provider was called rather than when it responded. Mandatory, and the field transaction listings sort on, newest first.
setCreatedDate(Date createdDate)
Returns: void
Sets the date this payment attempt was created. Required.
| Parameter | Description |
|---|---|
createdDate | the creation date |
getCreatedBy()
Returns: Profile
The profile the payment was taken from, which is normally the person who checked out. Required.
setCreatedBy(Profile createdBy)
Returns: void
Sets the profile the payment was taken from. Required.
| Parameter | Description |
|---|---|
createdBy | the paying profile |
getOrg()
Returns: Organisation
The organisation the payment was taken for. Required, and every transaction lookup is scoped to it, so a transaction cannot be read from another account.
setOrg(Organisation org)
Returns: void
Sets the organisation the payment is taken for. Required.
| Parameter | Description |
|---|---|
org | the owning organisation |
getAuthorisationCode()
Returns: String
Authorisation code returned by the payment provider when it approved the payment. Null for an attempt that was declined or that never got a response.
setAuthorisationCode(String authorisationCode)
Returns: void
Stores the authorisation code returned by the payment provider.
| Parameter | Description |
|---|---|
authorisationCode | the provider's authorisation code, or null |
getResponseCode()
Returns: String
Raw response code returned by the payment provider. The codes are provider specific, so do not compare them across providers; use the status flag for a portable success test.
setResponseCode(String responseCode)
Returns: void
Stores the raw response code returned by the payment provider.
| Parameter | Description |
|---|---|
responseCode | the provider's response code, or null |
getResponseMessage()
Returns: String
Human readable message returned by the payment provider, typically the reason a payment was declined. Safe to log, but it is written by the provider so review it before showing it to a shopper.
setResponseMessage(String responseMessage)
Returns: void
Stores the human readable message returned by the payment provider.
| Parameter | Description |
|---|---|
responseMessage | the provider's response message, or null |
getTransactionID()
Returns: String
The provider's own identifier for this payment, used when reconciling against the provider or requesting a refund. Null until the provider has responded.
setTransactionID(String transactionID)
Returns: void
Stores the provider's own identifier for this payment.
| Parameter | Description |
|---|---|
transactionID | the provider's transaction identifier, or null |
getErrors()
Returns: String
Error detail captured while attempting the payment, for example an exception raised talking to the provider. Null for an attempt that completed cleanly, whether it was approved or declined.
setErrors(String errors)
Returns: void
Records error detail captured while attempting the payment.
| Parameter | Description |
|---|---|
errors | the error detail to record, or null |
getCurrencyCode()
Returns: String
Currency the amount is expressed in, as a three letter ISO 4217 code such as NZD. The amount alone is meaningless without it.
setCurrencyCode(String currencyCode)
Returns: void
Sets the currency the amount is expressed in.
| Parameter | Description |
|---|---|
currencyCode | a three letter ISO 4217 currency code |
getAmount()
Returns: BigDecimal
The amount charged, in the transaction's currency. Held as a decimal rather than as cents, and it does not include the transaction fee.
setAmount(BigDecimal amount)
Returns: void
Sets the amount charged, in the transaction's currency.
| Parameter | Description |
|---|---|
amount | the amount charged |
getTransactionFee()
Returns: BigDecimal
The fee the payment provider charged for processing this payment, in the transaction's currency. Separate from the amount, and null when the provider does not report a fee.
setTransactionFee(BigDecimal transactionFee)
Returns: void
Sets the fee the payment provider charged for processing this payment.
| Parameter | Description |
|---|---|
transactionFee | the processing fee, or null |
getWebsite()
Returns: Website
The website the payment was made through, or null for a payment taken outside a website.
setWebsite(Website website)
Returns: void
Sets the website the payment was made through.
| Parameter | Description |
|---|---|
website | the website, or null |
getUuid()
Returns: String
Random UUID generated when the attempt was created, used to identify the operation with the provider if the call fails or times out. Mandatory, and it is what makes a retry safe to reconcile.
setUuid(String uuid)
Returns: void
Sets the UUID identifying this payment operation. Required, and should be an unguessable random value.
| Parameter | Description |
|---|---|
uuid | the operation UUID |
getStatus()
Returns: Boolean
The success or failure verdict returned by the payment provider. Null until the provider has responded, so a null status means the outcome is unknown rather than that the payment failed. Always check for null before treating a transaction as failed.
setStatus(Boolean status)
Returns: void
Records the provider's success or failure verdict.
| Parameter | Description |
|---|---|
status | true for success, false for failure, or null while the outcome is unknown |
getProvider()
Returns: String
Name of the payment provider app that handled this payment, for example the app implementing the gateway integration. Response codes and transaction identifiers only make sense in the context of this provider.
setProvider(String provider)
Returns: void
Sets the name of the payment provider app handling this payment.
| Parameter | Description |
|---|---|
provider | the name of the provider app |
getInvoiceDesc()
Returns: String
Description passed to the payment provider for the invoice or statement line, up to 2000 characters. This is often what the shopper sees on their card statement.
setInvoiceDesc(String invoiceDesc)
Returns: void
Sets the invoice or statement description sent to the payment provider.
| Parameter | Description |
|---|---|
invoiceDesc | the description, up to 2000 characters |
getInvoiceNum()
Returns: String
Invoice number passed to the payment provider, up to 200 characters. Used to tie the payment back to an invoice in an external accounting system.
setInvoiceNum(String invoiceNum)
Returns: void
Sets the invoice number sent to the payment provider.
| Parameter | Description |
|---|---|
invoiceNum | the invoice number, up to 200 characters |
getCardName()
Returns: String
Name on the payment card, as entered by the shopper. Only the name is kept; no card number is ever stored on this row.
setCardName(String cardName)
Returns: void
Sets the cardholder name captured with the payment.
| Parameter | Description |
|---|---|
cardName | the name on the card, or null |
getPhone()
Returns: String
Contact phone number supplied with the payment, or null if none was given.
setPhone(String phone)
Returns: void
Sets the contact phone number captured with the payment.
| Parameter | Description |
|---|---|
phone | the phone number, or null |
getEmail()
Returns: String
Email address supplied with the payment, used for the receipt. This is what the shopper typed at checkout, so it may differ from the paying profile's email address.
setEmail(String email)
Returns: void
Sets the contact email address captured with the payment.
| Parameter | Description |
|---|---|
email | the email address, or null |
getFirstName()
Returns: String
First name from the billing details supplied with the payment.
setFirstName(String firstName)
Returns: void
Sets the billing first name captured with the payment.
| Parameter | Description |
|---|---|
firstName | the first name, or null |
getSurName()
Returns: String
Surname from the billing details supplied with the payment.
setSurName(String surName)
Returns: void
Sets the billing surname captured with the payment.
| Parameter | Description |
|---|---|
surName | the surname, or null |
getAddressLine1()
Returns: String
First line of the billing address supplied with the payment.
setAddressLine1(String addressLine1)
Returns: void
Sets the first line of the billing address captured with the payment.
| Parameter | Description |
|---|---|
addressLine1 | the first address line, or null |
getAddressLine2()
Returns: String
Second line of the billing address supplied with the payment, often blank.
setAddressLine2(String addressLine2)
Returns: void
Sets the second line of the billing address captured with the payment.
| Parameter | Description |
|---|---|
addressLine2 | the second address line, or null |
getCity()
Returns: String
City or town from the billing address supplied with the payment.
setCity(String city)
Returns: void
Sets the billing city captured with the payment.
| Parameter | Description |
|---|---|
city | the city or town, or null |
getState()
Returns: String
State, province or region from the billing address supplied with the payment. Often blank in countries that do not use one.
setState(String state)
Returns: void
Sets the billing state or region captured with the payment.
| Parameter | Description |
|---|---|
state | the state, province or region, or null |
getPostCode()
Returns: String
Postcode or ZIP code from the billing address supplied with the payment. Stored as text, since postcodes are not always numeric.
setPostCode(String postCode)
Returns: void
Sets the billing postcode captured with the payment.
| Parameter | Description |
|---|---|
postCode | the postcode or ZIP code, or null |
getCountryCode()
Returns: String
Country from the billing address supplied with the payment, as a country code rather than a country name.
setCountryCode(String countryCode)
Returns: void
Sets the billing country code captured with the payment.
| Parameter | Description |
|---|---|
countryCode | the country code, or null |
getCart()
Returns: Cart
The cart this payment was taken for, or null if the payment was not raised from a store purchase. A cart can have several transactions when earlier attempts failed.
setCart(Cart cart)
Returns: void
Links this payment attempt to the cart it was taken for.
| Parameter | Description |
|---|---|
cart | the cart being paid for, or null |
findRecurringTx()
Returns: RecurringTransaction
The subscription this payment started, or null if it did not start one. Hits the database, and returns the first match when a payment has somehow produced more than one; use findRecurringTxs if you need them all.
findRecurringTxs()
Returns: List<RecurringTransaction>
All subscriptions started by this payment. Hits the database. Normally empty or a single entry, since a payment usually sets up at most one subscription.
© 2025 Kademi Ltd