Sign Up Sign in Blog Support

Instant Payment Notification (IPN)

Events that trigger an IPN
Setting up the CashSender IPN
The IPN listener script
Resending Failed IPNs
IPN Variables Reference (General Variables)
IPN Variables Reference (Balance Transfer)
IPN Variables Reference (Currency Conversion)
IPN Variables Reference (Buy Now Button/Shopping Cart/Invoice)

Overview

Instant Payment Notification (IPN) is a message service that sends notification to your server about your transaction, allowing you website backend to tracking payment and automate tasks like fulfilling orders and providing status information of orders.

Events that trigger an IPN

  1. Your CashSender account has received a payment.
  2. A payment you received has changed status (for example, pending payments is cancelled, accepted or rejected, or a completed payment is refunded)
  3. You have issued a refund.

Setting up the CashSender IPN

To enable IPN, login to your account and go to Seller Tools => Settings => IPN Settings (under preferences).

In the IPN Settings page:

Notification URL: Enter the URL of your listener script (described below)
Enable IPN: Select the button "Enable: Receive IPN messages".

Click "Submit" to save your settings.

The IPN listener script

The IPN listener script is a script that runs on your webserver and handle the IPN message sent be CashSender, it performs the following task (see sample code):

  1. Wait for an HTTP post from CashSender.
  2. Validate the IPN message following the IPN protocol (described below).
  3. After the IPN message is verified, confirm that the payment status is completed.
  4. Confirm that the receiver ID and receiver email is registered to your CashSender account.
  5. Confirm that the transaction has not been processed using the transaction ID (variable txn_id).
  6. Verify the price, item description or other information about the transaction, and ensure that it matches the transaction on your website.
  7. Process the payment

The IPN protocol - The IPN protocol is a mechanism for the listener script to check the validity of the IPN message, it should follow the steps below:

  1. CashSender sends a message to your listener script.
  2. Your listener creates a HTTP request with the same IPN variables and send the message to the URL https://www.cashsender.com/ipn_listen/ (For sandbox use https://sandbox.cashsender.com/ipn_listen/)
  3. Wait for a response from CashSender, which should be IPN_VERIFIED or IPN_INVALID
  4. Verify that the response status is 200.
  5. If the response is IPN_VERIFIED, the IPN message is valid, and your listener script can continue checking the details of the message and process it.
  6. If the response is IPN_INVALID or if the response status is not 200, the IPN is invalid and it should be logged for further investigation.
  7. Invalid IPNs will be sent again by CashSender, up to a maximum 10 times. (You can direct CashSender to resend a failed IPN using the IPN history tool (Under Seller Tools => IPN History)

Resending Failed IPNs

You can manually ask the CashSender System to resend IPN messages that were previously failed to reach your listen script by using the IPN history tool:

  • Go to the IPN History tool (Under Seller Tools => IPN History)
  • By default it shows all IPN in the previous 24 hours. You can search for the failed IPN by using date range and select "Fail" under status
  • If you know the transaction ID of the IPN, you can also enter the transaction ID
  • Check the checkboxes of the IPNs you want CashSender to resend, then click "Resend Selected IPN"

IPN Variables Reference (General Variables)

Below variables are relevant to all IPN messages

Variable name Description Specification
msg_id A unique ID of the IPN message 20 characters
test Whether this message is a test message sent from the sandbox 1 = Test message
0 = Message from live CashSender site
resend Whether this message was resent after previous failed attempts 1 = Yes, this is a resent message.
0 = No.
txn_id Unique ID of the transaction pertained to this notification 20 characters
parent_txn_id ID of the original transaction related to this transaction.
Only available for the following transaction type:
  • Refunds
20 characters
transaction_type Type of transaction pertained to this notification.
  • balance_transfer - Payment received
  • refund - Refund Issued
payment_type From where the payment was originated
(Only available for balance transfer)
  • send_money - initiated by the sender using "Send Money" page on the CashSender site
  • invoice - CashSender invoice / money request
  • cart - Shopping Cart /Buy Now Button
gross Gross amount of the transaction (exclude transaction fee) Decimal number
fee Transaction fee
(N/A if payment is pending)
Decimal number
net Net amount after transaction fee. Decimal number
currency Currency of the transaction ISO 4217 currency code (3 letters) or BTC for bitcoin
status Status of the transaction
  • complete
  • pending - Payment pending your acceptance
  • reject - Pending incoming payment rejected
  • cancel - Pending incoming payment cancelled by sender
  • refund - Refund has been issued to sender
timestamp Timestamp of the transaction in Unix Epoch time. Timestamp follows the time zone settings in your profile. Integer
update_timestamp The time when the transaction updated. Timestamp follows the time zone settings in your profile.
Only applies when the notification is initiated by a change of status of the transaction.
Integer
timezone Timezone of the timestamp Positive or negative number (+1 or -3, for example)
recipient_id User ID of the account Text (max 20 characters)
recipient_email Email addressed by this payment Valid email address
last_name Last name of payment sender Text (max 128 characters)
first_name First name of payment sender Text (max 128 characters)
business_name Business name of payment sender Text (max 128 characters)
country Country of residence of payment sender ISO 3166 country code (2 letters)
email Email address of payment sender Valid email address
address_verified Whether payment sender is address verified 1 = Address Verified.
0 = Address Unverified.
identity_verified Whether payment sender is identity verified 1 = Identity Verified.
0 = Identity Unverified.

IPN Variables Reference (Balance Transfer)

Below variables are relevant to balance transfer only

Variable name Description Specification
address_recipient Recipient listed in the shipping address
Different than sender&apos's name if this is a gift address
Text (max 128 characters)
address_1 Shipping Address Line 1 Text (max 256 characters)
address_2 Shipping Address Line 2 Text (max 256 characters)
address_city Shipping Address: City Text (max 64 characters)
address_state Shipping Address: State/Province Text
2 letters for Canadian or US
Max 64 letters for other countries
address_zip Shipping Address: Zip code/ Postal code Text (max 32 characters)
address_country Shipping Address: Country ISO 3166 country code (2 letters)
address_status Status of the shipping address confirmed / unconfirmed
auction_site Auction site (entered by sender) Text (max 255 characters)
auction_user_id Auction user ID (entered by sender) Text (max 255 characters)
auction_item_id Auction ID (entered by sender) Text (max 255 characters)

IPN Variables Reference (Currency Conversion)

Below variables are present when currency conversion took place for the transaction

Variable name Description Specification
original_amount Original amount Decimal Number
final_amount Converted amount Decimal Number
original_currency Original currency ISO 4217 currency code (3 letters) or BTC for bitcoin
final_currency Final currency ISO 4217 currency code (3 letters) or BTC for bitcoin
exchange_rate Exchange Rate Decimal Number

IPN Variables Reference (Buy Now Button/Shopping cart/Invoice)

Below variables are present in balance transfers originated from Buy Now Button, Shopping Cart, or CashSender Invoice

Variable name Description Specification
num_items Total number of items in shopping cart Integer
item_desc_n Item description Text (max 128 characters)
item_id_n Item ID Text (max 128 characters)
item_quan_n Item quantity Integer
item_price_n Item unit price
If "discount_ipn" is 1 - unit price before discount is applied.
If "discount_ipn" is 0 - unit price after discount is applied.
Decimal number
item_discount_n Item discount (in percentage)
Only shown if "discount_ipn" is 1
Integer (0 - 100)
item_amount_n Total cost of item (Unit price X Quantity)

If "discount_ipn" is 1:
Total cost before discount is applied:
(Unit price X Quantity X (100 - Discount) / 100)

If "discount_ipn" is 0:
Total cost after discount is applied
Decimcal number
item_taxable_n Is item taxable 1 = True
0 = False
item_on_1_n Name of item option field 1 Text (max 255 characters)
item_ov_1_n Value of item option field 1 Text (max 255 characters)
item_on_2_n Name of item option field 2 Text (max 255 characters)
item_ov_2_n Value of item option field 2 Text (max 255 characters)
item_on_3_n Name of item option field 3 Text (max 255 characters)
item_ov_4_n Value of item option field 4 Text (max 255 characters)
item_on_1_n Name of item option field 1 Text (max 255 characters)
subtotal Subtotal of all items (before shipping and tax) Decimal Number
shipping_total Total shipping cost Decimal Number
shipping_taxable Is shipping taxable? 1 = True
0 = False
tax_total Total amount of tax Deciaml Number
total Total amount (subtotal + tax + shipping) Alphanumeric
invoice_id Invoice ID Text (max 255 characters)
ref_1 Reference passback variable 1 Text (max 255 characters)
ref_2 Reference passback variable 2 Text (max 255 characters)