Kartra Documentation Technical Documentation for Kartra

The IPN system

Here you will find the specific variables our payment checkout system forwards via IPN immediately upon a transaction is processed. Note that the IPN system is for advanced users only and it requires programming skills on your end.

Some general notes to consider:

    1. Please configure your IPN pointing to a .php file (recommended to be hosted on a secure https:// domain) from where you can grab all the IPN variables we send from POST.

    2. Any variable with an empty value will be posted as “N/A”.

Sale, refund or chargeback for one-time payments without an initial payment (AKA trial) enabled

Below is the data that is being pinged by our IPN system when a customer processes a one-time payment order, as well as when a refund is issued.

The main difference between sale and refund or partial_refund is the transaction_type variable (see table below), which is for the sale, (refund) for the refund and partial_refund for the partial refund. Moreover, in case of a refund or partial refund, the system also sends the transaction_parent_id parameter, which is the original sale’s order ID. That will help you identify which original transaction is being refunded.

Here’s the full list of variables we send for sales :

transaction_id Kartra order id
transaction_full_amount The amount paid by the customer
transaction_base_amount The base price for the transaction
transaction_discount If any discount coupon was applied, the amount deducted from the original price
transaction_shipping The shipping price
transaction_tax The sales tax or VAT
transaction_date The date of the transaction. Format yyyy-mm-dd hh:mm:ss EST
transaction_type The transaction type. Possible values: ‘sale’
transaction_parent_id 0
transaction_affiliate The username of the affiliate (‘N/A’ if no
affiliate)
transaction_jv The username of the jv broker (‘N/A’ if no jv)
transaction_quantity Product units
transaction_subscription_id ‘N/A’
transaction_internal_subscription_id ‘N/A’
transaction_subscription_pay_number ‘N/A’
transaction_last_4_card_digits The last 4 digits of the used card (‘N/A’ if PayPal)
original_id 0
product_name The name of the purchased product
product_id The ID of the product
product_price_point The price point number. This is a number from 1 onwards
trial 0
trial_amount N/A
trial_period N/A
payments_left 0
lead_id Buyer’s unique identifier id
lead_first_name Buyer’s first name
lead_last_name Buyer’s last name
lead_email Buyer’s email
lead_username Buyer’s username
lead_phone_country_code Buyer’s phone country code
lead_phone_number Buyer’s phone number
lead_address Buyer’s billing address
lead_city Buyer’s billing city
lead_zip Buyer’s billing ZIP
lead_state Buyer’s billing state
lead_country Buyer’s billing country
lead_country_code_2 Buyer’s two letter country code
lead_country_code_3 Buyer’s three letter country code
lead_ip Buyer’s IP
shipping_address Buyer’s shipping address
shipping_city Buyer’s shipping city
shipping_zip Buyer’s shipping ZIP
shipping_state Buyer’s shipping state
shipping_country Buyer’s shipping country
secret_key The secret key you setup when you created the notification
vendor_tracking_id_1 Vendor’s tracking ID 1 if the sale was generated from a tracking link
vendor_tracking_id_2 Vendor’s tracking ID 2 if the sale was generated from a tracking link
vendor_tracking_link Vendor’s tracking link name
gdpr_lead_status integer, possible values:

0 – For GDPR status off – Your account has GDPR deactivated
1 – For GDPR status not subject – The lead’s IP is from a country not subject to GDPR
2 – For GDPR status accepted – The lead has accepted the GDPR terms
3 – For GDPR status not accepted – The lead hasn’t accepted the GDPR terms
4 – For GDPR status unknown – The lead’s location could not be determined
5 – For GDPR status pending

gdpr_lead_status_date string (DD Mmm YYYY HH:MM:SS)
gdpr_lead_status_ip string
gdpr_lead_communications
integer, possible values:

0 – Lead hasn’t agreed to be contacted
1 – Lead has agreed to be contacted

payment_processor_type

“PayPal”
“Braintree”
“Stripe”
Authorize.net”
kartra_reference_id Kartra internal reference id
lead_company Buyer’s company
lead_sales_tax_id Buyer’s sales tax id

 

Here’s the full list of variables we send for refunds, partial refunds and chargebacks:

transaction_id Kartra order id
transaction_full_amount The amount paid by the customer
transaction_base_amount The base price for the transaction
transaction_discount If any discount coupon was applied, the amount deducted from the original price
transaction_shipping The shipping price
transaction_tax The sales tax or VAT
transaction_date The date of the transaction. Format yyyy-mm-dd hh:mm:ss EST
transaction_type The transaction type. Possible values: ‘refund’, ‘partial_refund’, ‘chargeback’
transaction_parent_id The id of the parent transaction
transaction_affiliate The username of the affiliate (‘N/A’ if no
affiliate)
transaction_jv The username of the jv broker (‘N/A’ if no jv)
transaction_quantity Product units
transaction_subscription_id ‘N/A’
transaction_internal_subscription_id ‘N/A’
transaction_subscription_pay_number ‘N/A’
original_id 0
product_name The name of the purchased product
product_id The ID of the product
product_price_point The price point number. This is a number from 1 onwards
lead_id Buyer’s unique identifier id
lead_first_name Buyer’s first name
lead_last_name Buyer’s last name
lead_email Buyer’s email
lead_username Buyer’s username
lead_phone_country_code Buyer’s phone country code
lead_phone_number Buyer’s phone number
lead_address Buyer’s billing address
lead_city Buyer’s billing city
lead_zip Buyer’s billing ZIP
lead_state Buyer’s billing state
lead_country Buyer’s billing country
lead_country_code_2 Buyer’s two letter country code
lead_country_code_3 Buyer’s three letter country code
shipping_address Buyer’s shipping address
shipping _city Buyer’s shipping city
shipping _zip Buyer’s shipping ZIP
shipping _state Buyer’s shipping state
shipping _country Buyer’s shipping country
secret_key The secret key you setup when you created the notification
vendor_tracking_id_1 Vendor’s tracking ID 1 if the sale was generated from a tracking link
vendor_tracking_id_2 Vendor’s tracking ID 2 if the sale was generated from a tracking link
vendor_tracking_link Vendor’s tracking link name
gdpr_lead_status integer, possible values:

0 – For GDPR status off – Your account has GDPR deactivated
1 – For GDPR status not subject – The lead’s IP is from a country not subject to GDPR
2 – For GDPR status accepted – The lead has accepted the GDPR terms
3 – For GDPR status not accepted – The lead hasn’t accepted the GDPR terms
4 – For GDPR status unknown – The lead’s location could not be determined
5 – For GDPR status pending

gdpr_lead_status_date string (DD Mmm YYYY HH:MM:SS)
gdpr_lead_status_ip string
gdpr_lead_communications
integer, possible values:

0 – Lead hasn’t agreed to be contacted
1 – Lead has agreed to be contacted

payment_processor_type

“PayPal”
“Braintree”
“Stripe”
Authorize.net”
lead_company Buyer’s company
lead_sales_tax_id Buyer’s sales tax id

Sale for one-time payments with an initial payment (AKA trial) or sale for a subscription

Below is the data that is being pinged by our IPN system when a customer processes a sale for a one-time payment order with a trial, or a sale for a recurring payment plan.

transaction_id Kartra order id
transaction_full_amount The amount paid by the customer
transaction_base_amount The base price for the transaction (for trial this will be the base price of the initial transaction)
transaction_discount If any discount coupon was applied, the amount deducted from the original price
transaction_shipping The shipping price
transaction_tax The sales tax or VAT
transaction_date The date of the transaction.  Format yyyy-mm-dd hh:mm:ss EST
transaction_type ‘sale’ – if successful transaction
‘failed’ – if transaction rebill failed (due to card expiration, lack of funds, etc)
transaction_parent_id 0
transaction_affiliate The username of the affiliate (‘N/A’ if no
affiliate)
transaction_jv The username of the jv broker (‘N/A’  if no jv)
transaction_subscription_id The ID of the subscription being cancelled (PayPal transactions will return PayPal subscription id)
transaction_internal_subscription_id A unique numeric identifier for the subscription id
transaction_subscription_pay_number The number of payment within this rebill sequence: 1st installment, 2nd installment, etc. In this case, it will always be the 1st installment.
transaction_last_4_card_digits The last 4 digits of the used card (‘N/A’ if PayPal)
original_id The order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
transaction_quantity Product units
product_name The name of the purchased product
product_id The ID of the product
product_price_point The price point number. This is a number from 1 onwards
trial 1
trial_amount The trial amount
trial_period The trial period in days
lead_id Buyer’s unique identifier id
lead_first_name Buyer’s first name
lead_last_name Buyer’s last name
lead_email Buyer’s email
lead_username Buyer’s username
lead_phone_country_code Buyer’s phone country code
lead_phone_number Buyer’s phone number
lead_address Buyer’s billing address
lead_city Buyer’s billing city
lead_zip Buyer’s billing ZIP
lead_state Buyer’s billing state
lead_country Buyer’s billing country
lead_country_code_2 Buyer’s two letter country code
lead_country_code_3 Buyer’s three letter country code
lead_ip Buyer’s IP
shipping_address Buyer’s shipping address
shipping_city Buyer’s shipping city
shipping_zip Buyer’s shipping ZIP
shipping_state Buyer’s shipping state
shipping_country Buyer’s shipping country
shipping_cost Shipping cost
secret_key The secret key you setup when you created the notification
vendor_tracking_id_1 Vendor’s tracking ID 1 if the sale was generated from a tracking link
vendor_tracking_id_2 Vendor’s tracking ID 2 if the sale was generated from a tracking link
vendor_tracking_link Vendor’s tracking link name
gdpr_lead_status integer, possible values:

0 – For GDPR status off – Your account has GDPR deactivated
1 – For GDPR status not subject – The lead’s IP is from a country not subject to GDPR
2 – For GDPR status accepted – The lead has accepted the GDPR terms
3 – For GDPR status not accepted – The lead hasn’t accepted the GDPR terms
4 – For GDPR status unknown – The lead’s location could not be determined
5 – For GDPR status pending

gdpr_lead_status_date string (DD Mmm YYYY HH:MM:SS)
gdpr_lead_status_ip string
gdpr_lead_communications
integer, possible values:

0 – Lead hasn’t agreed to be contacted
1 – Lead has agreed to be contacted

payment_processor_type

“PayPal”
“Braintree”
“Stripe”
Authorize.net”
lead_company Buyer’s company
lead_sales_tax_id Buyer’s sales tax id

 

Depending on the type of pricing structure you have configured for your product, you will also get the following additional variables:

1. If the price point has been configured as a one time payment with an initial (trial) payment:

payments_left Number of upcoming payments until the end of the subscription

 

2. If the price point has been configured as unlimited recurring payments:

payments_left Number of upcoming payments until the end of the subscription. 9999 if “cancelled by customer”
rebill_circle Days left for the next payment

 

3. If the price point has been configured as limited number of installments:

payments_left Number of upcoming payments until the end of the subscription. 9999 if “cancelled by customer”
rebill_circle Days left for the next payment
installments Total number of installments

 

4. If the price point has been configured as recurring installments:

payments_left Number of upcoming payments until the end of the subscription. 9999 if “cancelled by customer”
rebill_circle Days left for the next payment
installments Total number of installments
frequency The frequency (‘every_year’, ‘every_2_years’)

Rebill for a subscription, or a follow up after a one-time payment initial payment (trial)

Below is the data that is being pinged by our IPN system when a customer processes a rebill payment within a subscription plan, or a follow up payment after a trial payment.

transaction_id Kartra order id
transaction_full_amount The amount paid by the customer
transaction_base_amount The base price for the recurring transaction
transaction_discount If any discount coupon was applied, the amount deducted from the original price
transaction_shipping The shipping price
transaction_tax The sales tax or VAT
transaction_date The date of the transaction. Format yyyy-mm-dd hh:mm:ss EST
transaction_type ‘rebill’
transaction_parent_id 0
transaction_affiliate The username of the affiliate (‘N/A’ if no
affiliate)
transaction_jv The username of the jv broker (‘N/A’ if no jv)
transaction_subscription_id The ID of the subscription being cancelled (PayPal transactions will return PayPal subscription id)
transaction_internal_subscription_id A unique numeric identifier for the subscription id
transaction_subscription_pay_number The number of payment within this rebill sequence: 1st installment, 2nd installment, etc. In this case, it will always be the 1st installment.
transaction_last_4_card_digits The last 4 digits of the used card (‘N/A’ if PayPal)
original_id The order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
transaction_quantity Product units
product_name The name of the purchased product
product_id The ID of the product
product_price_point The price point number. This is a number from 1 onwards
lead_id Buyer’s unique identifier id
lead_first_name Buyer’s first name
lead_last_name Buyer’s last name
lead_email Buyer’s email
lead_username Buyer’s username
lead_phone_country_code Buyer’s phone country code
lead_phone_number Buyer’s phone number
lead_address Buyer’s billing address
lead_city Buyer’s billing city
lead_zip Buyer’s billing ZIP
lead_state Buyer’s billing state
lead_country Buyer’s billing country
lead_country_code_2 Buyer’s two letter country code
lead_country_code_3 Buyer’s three letter country code
lead_ip Buyer’s IP
shipping_address Buyer’s shipping address
shipping_city Buyer’s shipping city
shipping_zip Buyer’s shipping ZIP
shipping_state Buyer’s shipping state
shipping_country Buyer’s shipping country
secret_key The secret key you setup when you created the notification
vendor_tracking_id_1 Vendor’s tracking ID 1 if the sale was generated from a tracking link
vendor_tracking_id_2 Vendor’s tracking ID 2 if the sale was generated from a tracking link
vendor_tracking_link Vendor’s tracking link name
failed_reattempt_number The reattempt number for a failed transaction (up to 3 attempts)
gdpr_lead_status integer, possible values:

0 – For GDPR status off – Your account has GDPR deactivated
1 – For GDPR status not subject – The lead’s IP is from a country not subject to GDPR
2 – For GDPR status accepted – The lead has accepted the GDPR terms
3 – For GDPR status not accepted – The lead hasn’t accepted the GDPR terms
4 – For GDPR status unknown – The lead’s location could not be determined
5 – For GDPR status pending

gdpr_lead_status_date string (DD Mmm YYYY HH:MM:SS)
gdpr_lead_status_ip string
gdpr_lead_communications
integer, possible values:

0 – Lead hasn’t agreed to be contacted
1 – Lead has agreed to be contacted

payment_processor_type
“PayPal”
“Braintree”
“Stripe”
Authorize.net”
lead_company Buyer’s company
lead_sales_tax_id Buyer’s sales tax id

 

Depending on the type of pricing structure you have configured for your product, you will also get the following additional variables:

1. If the price point has been configured as a one time payment with an initial (trial) payment:

payments_left Number of upcoming payments until the end of the subscription

 

2. If the price point has been configured as unlimited recurring payments:

payments_left Number of upcoming payments until the end of the subscription. 9999 if “cancelled by customer”
rebill_circle Days left for the next payment

 

3. If the price point has been configured as limited number of installments:

payments_left Number of upcoming payments until the end of the subscription. 9999 if “cancelled by customer”
rebill_circle Days left for the next payment
installments Total number of installments

 

4. If the price point has been configured as recurring installments:

payments_left Number of upcoming payments until the end of the subscription. 9999 if “cancelled by customer”
rebill_circle Days left for the next payment
installments Total number of installments
frequency The frequency (‘every_year’, ‘every_2_years’)

Refund, failed rebill or chargeback for a recurring subscription payment, or for a one time payment with a trial

Below is the data that is being pinged by our IPN system when there is a refund or a failed rebill for a one-time payment order with a trial, or a recurring payment plan.

Here’s the full list of variables we send for failed transaction:

transaction_id Kartra order id
transaction_full_amount The amount the customer had to pay
transaction_base_amount The base price for the transaction
transaction_discount If any discount coupon was applied, the amount in dollars deducted from the original price
transaction_shipping The shipping price
transaction_tax The sales tax or VAT
transaction_date The date of the transaction. Format yyyy-mm-dd hh:mm:ss EST
transaction_type ‘failed’ – if transaction rebill failed (due to card expiration, lack of funds, etc)
transaction_parent_id 0
transaction_affiliate The username of the affiliate (‘N/A’ if no
affiliate)
transaction_jv The username of the JV broker (‘N/A’ if no JV)
transaction_subscription_id The ID of the subscription being cancelled (PayPal transactions will return PayPal subscription id)
transaction_internal_subscription_id A unique numeric identifier for the subscription id
transaction_subscription_pay_number The number of payment within this rebill sequence: 1st installment, 2nd installment, etc. In this case, it will always be the 1st installment.
transaction_quantity Product units
transaction_last_4_card_digits The last 4 digits of the used card (N/A if PayPal)
original_id The order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
product_name The name of the purchased product
product_id The ID of the product
product_price_point The price point number. This is a number from 1 onwards
lead_id Buyer’s unique identifier id
lead_first_name Buyer’s first name
lead_last_name Buyer’s last name
lead_email Buyer’s email
lead_username Buyer’s username
lead_phone_country_code Buyer’s phone country code
lead_phone_number Buyer’s phone number
lead_address Buyer’s billing address
lead_city Buyer’s billing city
lead_zip Buyer’s billing ZIP
lead_state Buyer’s billing state
lead_country Buyer’s billing country
lead_country_code_2 Buyer’s two letter country code
lead_country_code_3 Buyer’s three letter country code
lead_ip Buyer’s IP
shipping_address Buyer’s shipping address
shipping_city Buyer’s shipping city
shipping_zip Buyer’s shipping ZIP
shipping_state Buyer’s shipping state
shipping_country Buyer’s shipping country
shipping_cost Shipping cost
secret_key The secret key you setup when you created the notification
vendor_tracking_id_1 Vendor’s tracking ID 1 if the sale was generated from a tracking link
vendor_tracking_id_2 Vendor’s tracking ID 2 if the sale was generated from a tracking link
vendor_tracking_link Vendor’s tracking link name
failed_reattempt_number The reattempt number for a failed transaction (up to 3 attempts)
gdpr_lead_status integer, possible values:

0 – For GDPR status off – Your account has GDPR deactivated
1 – For GDPR status not subject – The lead’s IP is from a country not subject to GDPR
2 – For GDPR status accepted – The lead has accepted the GDPR terms
3 – For GDPR status not accepted – The lead hasn’t accepted the GDPR terms
4 – For GDPR status unknown – The lead’s location could not be determined
5 – For GDPR status pending

gdpr_lead_status_date string (DD Mmm YYYY HH:MM:SS)
gdpr_lead_status_ip string
gdpr_lead_communications
integer, possible values:

0 – Lead hasn’t agreed to be contacted
1 – Lead has agreed to be contacted

payment_processor_type

“PayPal”
“Braintree”
“Stripe”
Authorize.net”
lead_company Buyer’s company
lead_sales_tax_id Buyer’s sales tax id

 

Here’s the full list of variables we send for refunds, partial refunds and chargebacks:

transaction_id Kartra order id
transaction_full_amount The amount paid by the customer
transaction_base_amount The base price for the transaction
transaction_discount If any discount coupon was applied, the amount deducted from the original price
transaction_shipping The shipping price
transaction_tax The sales tax or VAT
transaction_date The date of the transaction. Format yyyy-mm-dd hh:mm:ss EST
transaction_type The transaction type. Possible values: ‘refund’, ‘partial_refund’, ‘chargeback’
transaction_parent_id The id of the parent transaction
transaction_affiliate The username of the affiliate (‘N/A’ if no
affiliate)
transaction_jv The username of the jv broker (‘N/A’ if no jv)
transaction_quantity Product units
transaction_subscription_id The ID of the subscription being cancelled (PayPal transactions will return PayPal subscription id)
transaction_internal_subscription_id A unique numeric identifier for the subscription id
transaction_subscription_pay_number The number of payment within this rebill sequence: 1st installment, 2nd installment, etc. In this case, it will always be the 1st installment.
original_id The order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
product_name The name of the purchased product
product_id The ID of the product
product_price_point The price point number. This is a number from 1 onwards
lead_id Buyer’s unique identifier id
lead_first_name Buyer’s first name
lead_last_name Buyer’s last name
lead_email Buyer’s email
lead_username Buyer’s username
lead_phone_country_code Buyer’s phone country code
lead_phone_number Buyer’s phone number
lead_address Buyer’s billing address
lead_city Buyer’s billing city
lead_zip Buyer’s billing ZIP
lead_state Buyer’s billing state
lead_country Buyer’s billing country
lead_country_code_2 Buyer’s two letter country code
lead_country_code_3 Buyer’s three letter country code
lead_ip Buyer’s IP
shipping_address Buyer’s shipping address
shipping _city Buyer’s shipping city
shipping _zip Buyer’s shipping ZIP
shipping _state Buyer’s shipping state
shipping _country Buyer’s shipping country
secret_key The secret key you setup when you created the notification
vendor_tracking_id_1 Vendor’s tracking ID 1 if the sale was generated from a tracking link
vendor_tracking_id_2 Vendor’s tracking ID 2 if the sale was generated from a tracking link
vendor_tracking_link Vendor’s tracking link name
gdpr_lead_status integer, possible values:

0 – For GDPR status off – Your account has GDPR deactivated
1 – For GDPR status not subject – The lead’s IP is from a country not subject to GDPR
2 – For GDPR status accepted – The lead has accepted the GDPR terms
3 – For GDPR status not accepted – The lead hasn’t accepted the GDPR terms
4 – For GDPR status unknown – The lead’s location could not be determined
5 – For GDPR status pending

gdpr_lead_status_date string (DD Mmm YYYY HH:MM:SS)
gdpr_lead_status_ip string
gdpr_lead_communications
integer, possible values:

0 – Lead hasn’t agreed to be contacted
1 – Lead has agreed to be contacted

payment_processor_type

“PayPal”
“Braintree”
“Stripe”
Authorize.net”
lead_company Buyer’s company
lead_sales_tax_id Buyer’s sales tax id

Cancellation of a recurring payment subscription

Below is the data that is being pinged by our IPN system when there is a cancellation for a one-time payment order with a trial, or a recurring payment plan.

transaction_id Kartra order id
transaction_date The date of the transaction. Format yyyy-mm-dd hh:mm:ss EST
transaction_type ‘cancellation’
transaction_subscription_id The ID of the subscription being cancelled (PayPal transactions will return PayPal subscription id)
transaction_internal_subscription_id A unique numeric identifier for the subscription id
transaction_last_4_card_digits The last 4 digits of the used card (‘N/A’ if PayPal)
original_id The order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
product_name The name of the purchased product
product_id The ID of the product
product_price_point The price point number. This is a number from 1 onwards
lead_id Buyer’s unique identifier id
lead_first_name Buyer’s first name
lead_last_name Buyer’s last name
lead_email Buyer’s email
lead_username Buyer’s username
lead_phone_country_code Buyer’s phone country code
lead_phone_number Buyer’s phone number
lead_address Buyer’s billing address
lead_city Buyer’s billing city
lead_zip Buyer’s billing ZIP
lead_state Buyer’s billing state
lead_country Buyer’s billing country
lead_country_code_2 Buyer’s two letter country code
lead_country_code_3 Buyer’s three letter country code
lead_ip Buyer’s IP
secret_key The secret key you setup when you created the notification
vendor_tracking_id_1 Vendor’s tracking ID 1 if the sale was generated from a tracking link
vendor_tracking_id_2 Vendor’s tracking ID 2 if the sale was generated from a tracking link
vendor_tracking_link Vendor’s tracking link name
gdpr_lead_status integer, possible values:

0 – For GDPR status off – Your account has GDPR deactivated
1 – For GDPR status not subject – The lead’s IP is from a country not subject to GDPR
2 – For GDPR status accepted – The lead has accepted the GDPR terms
3 – For GDPR status not accepted – The lead hasn’t accepted the GDPR terms
4 – For GDPR status unknown – The lead’s location could not be determined
5 – For GDPR status pending

gdpr_lead_status_date string (DD Mmm YYYY HH:MM:SS)
gdpr_lead_status_ip string
gdpr_lead_communications
integer, possible values:

0 – Lead hasn’t agreed to be contacted
1 – Lead has agreed to be contacted

payment_processor_type
“PayPal”
“Braintree”
“Stripe”
Authorize.net”
lead_company Buyer’s company
lead_sales_tax_id Buyer’s sales tax id

© 2024 Kartra All Rights Reserved