Kartra Documentation TECHNICAL DOCUMENTATION

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 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:

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 in dollars deducted from the original price
transaction_shipping The shipping price
transaction_tax The sales tax or VAT in dollars
transaction_date The date of the transaction
transaction_type ‘sale’ – if successful transaction
‘refund’ – if transaction is a refund
‘partial_refund’ – if transaction is a refund
‘chargeback’ – if transaction is a chargeback
transaction_parent_id 0 if it’s a sale. Otherwise, the actual order ID of the original transaction if it’s a refund or chargeback.
transaction_affiliate The username of the affiliate (empty if no
affiliate)
transaction_jv The username of the jv broker (empty if no jv)
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_payment 0
trial_amount N/A
trial_period N/A
price The price point of the purchase in dollars
payments_left 0
buyer_id Buyer’s unique identifier id
buyer_first_name Buyer’s first name
buyer_last_name Buyer’s last name
buyer_email Buyer’s email
buyer_username Buyer’s username
buyer_billing_phone_country_code Buyer’s phone country code
buyer_billing_phone_number Buyer’s phone number
buyer_billing_address Buyer’s billing address
buyer_billing_city Buyer’s billing city
buyer_billing_zip Buyer’s billing ZIP
buyer_billing_state Buyer’s billing state
buyer_billing_country Buyer’s billing country
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”

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 in dollars deducted from the original price
transaction_shipping The shipping price
transaction_tax The sales tax or VAT in dollars
transaction_date The date of the transaction
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 (empty if no
affiliate)
transaction_jv The username of the jv broker (empty if no jv)
transaction_subscription_id The id of the subscription
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.
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_payment 1 or 0, depending on whether it is activated or not
trial_amount The trial amount in dollars
trial_period The trial period in days
buyer_id Buyer’s unique identifier id
buyer_first_name Buyer’s first name
buyer_last_name Buyer’s last name
buyer_email Buyer’s email
buyer_username Buyer’s username
buyer_billing_phone_country_code Buyer’s phone country code
buyer_billing_phone_number Buyer’s phone number
buyer_billing_address Buyer’s billing address
buyer_billing_city Buyer’s billing city
buyer_billing_zip Buyer’s billing ZIP
buyer_billing_state Buyer’s billing state
buyer_billing_country Buyer’s billing country
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”

 

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:

price The price of the transaction in dollar
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 (“yearly”)

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 in dollars deducted from the original price
transaction_shipping The shipping price
transaction_tax The sales tax or VAT in dollars
transaction_date The date of the transaction
transaction_type ‘rebill’
transaction_parent_id The actual order ID of the original transaction if it’s a refund or chargeback.
transaction_affiliate The username of the affiliate (empty if no
affiliate)
transaction_jv The username of the jv broker (empty if no jv)
transaction_subscription_id The id of the subscription
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.
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
buyer_id Buyer’s unique identifier id
buyer_first_name Buyer’s first name
buyer_last_name Buyer’s last name
buyer_email Buyer’s email
buyer_username Buyer’s username
buyer_billing_phone_country_code Buyer’s phone country code
buyer_billing_phone_number Buyer’s phone number
buyer_billing_address Buyer’s billing address
buyer_billing_city Buyer’s billing city
buyer_billing_zip Buyer’s billing ZIP
buyer_billing_state Buyer’s billing state
buyer_billing_country Buyer’s billing country
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”

 

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 (“yearly”)

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

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 in dollars deducted from the original price
transaction_shipping The shipping price
transaction_tax The sales tax or VAT in dollars
transaction_date The date of the transaction
transaction_type ‘refund’ – if transaction is a refund
‘partial_refund’ – if transaction is a partial refund
‘chargeback’ – if transaction is a chargeback
‘failed’ – if transaction rebill failed (due to card expiration, lack of funds, etc)
transaction_parent_id 0 if it’s a sale. Otherwise, the actual order ID of the original transaction if it’s a refund, partial refund or chargeback.
transaction_affiliate The username of the affiliate (empty if no
affiliate)
transaction_jv The username of the JV broker (empty if no JV)
transaction_subscription_id The id of the subscription
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.
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_payment 1 or 0, depending on whether it is activated or not
trial_amount The trial amount in dollars
trial_period The trial period in days
buyer_id Buyer’s unique identifier id
buyer_first_name Buyer’s first name
buyer_last_name Buyer’s last name
buyer_email Buyer’s email
buyer_username Buyer’s username
buyer_billing_phone_country_code Buyer’s phone country code
buyer_billing_phone_number Buyer’s phone number
buyer_billing_address Buyer’s billing address
buyer_billing_city Buyer’s billing city
buyer_billing_zip Buyer’s billing ZIP
buyer_billing_state Buyer’s billing state
buyer_billing_country Buyer’s billing country
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, not sent on refunds and chargebacks)
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”

Cancellation of a recurring payment subscription

transaction_id Kartra order id
transaction_date The date of the transaction
transaction_type ‘cancellation’
transaction_subscription_id The ID of the subscription being cancelled
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
buyer_id Buyer’s unique identifier id
buyer_first_name Buyer’s first name
buyer_last_name Buyer’s last name
buyer_email Buyer’s email
buyer_username Buyer’s username
buyer_billing_phone_country_code Buyer’s phone country code
buyer_billing_phone_number Buyer’s phone number
buyer_billing_address Buyer’s billing address
buyer_billing_city Buyer’s billing city
buyer_billing_zip Buyer’s billing ZIP
buyer_billing_state Buyer’s billing state
buyer_billing_country Buyer’s billing 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”

© 2020 Kartra All Rights Reserved