Pingbacks

When user pays or completes an offer, we will send a pingback which will notify your server regarding the transactions.

Pingback request is sent from our servers to your Pingback listener script where we communicate to your server regarding the details about payment transactions so that your server can process the pingback automatically and deliver the goods to the according users.

In your project settings, please input the Pingback URL which is the URL address of your script that processes the pingbacks.


Pingback Security

Please add following IP Addresses as authorized IP addresses to access the script:


Pingback Return Value

If you are able to process the requests, please respond back to the Pingback request with OK. If we don’t receive a confirmation message or if the response status code is different from 200, we will send Pingbacks again within 30 minutes and the subsequent retries will happen at 30 minute increments after that.


Pingback Parameters

Below are the parameters which are included for both Digital Goods API and Virtual Currency API. Let’s study each necessary parameters one by one.

Name Format
uid eg: pwuser
Unique identifier of the user. The value of parameter “uid” from Widget call.
type eg: 0 / 2
Type of pingback.
Please refer Pingback Type for detailed information.
ref eg: b1493096790
Unique transaction reference id generated by Terminal3 Payments.
Please refer Pingback Reference for detailed information.
sign_version eg: 2 / 3
Version of signature calculation.
sig eg: d94b23ba8585f29978706dd1b153ead9
Signature value calculated from pingback parameters.
Please refer Signature Calculation for detailed information.
is_test eg: 1
Value defined as 1.
Note: This parameter is not present unless pingback is sent via Test Pingback Tool or payment is done with Test Payment method.

For Digital Goods API, the default pingback would include following parameters:

Name Format
goodsid eg: gold_membership
Id of product. The value of parameter “ag_external_id” from Widget call.
Note: with Stored Product Widget call, “Product ID” column in ‘Products’ section will be the value of this parameter.
slength eg: positive whole number such as 1 / 3
Subscription length. Will be only filled up when your service is subscription plan.
speriod eg: day / week / month / year
Subscription period. Will be only filled up when your service is subscription plan.

For Virtual Currency API, the default pingback would include following parameters:

Name Format
currency eg: positive whole number such as 200
Currency amount of virtual money that user purchased.

Pingback Type

By default, Pingback has two default types:

type Description
0 When product is purchased. Please check whether the reference ID is unique and deliver the goods.
2 When user issued chargeback or refund. Please take the delivered goods out from user’s account.

For Brick, please be aware of the following pingback types:

type Description
200 Pending status. In case a payment is currently under risk review by Terminal3 Payments. Please do not deliver the goods yet.
201 Review is done and payment is accepted. Please check whether the reference ID is unique and deliver the goods.
202 Review is done and payment is declined. Please do not deliver the goods since the user will get his money back.
203 Authorization has been voided due to no capture request received on time.

Additionally, the following pingback types can be activated by request for recurring payments.

type Description
12 When user cancels subscription plan. Sent immediately upon cancellation, e.g. in the middle of current premium month.
13 When subscription expired.
14 When renewal subscription payment failed. Subscription stopped due to failing payments e.g. due to insufficient funds.

Pingback Reference

Each pingback has its own reference id which can be identified as the parameter name “ref”.
Reference id is used to track payment transactions. To prevent double crediting and fraudulent users or transactions, we need you to store reference ids to check before you process pingbacks. Please note when you receive pingback :

  • With type=0 : Make sure the reference value is unique. If you have history of same reference id, please do not deliver goods to user twice.
  • With type=2 : Make sure you have a record of reference value with type=0 pingback and take the exact product from user. Please refer Chargeback Pingback for detailed information.

Chargeback Pingback

For cases of fraud, corrections etc, Terminal3 Payments sends request to Pingback URL and communicates to take goods from specific user. Requested method and Parameters are the same as for common pingback except :

  • type=2
  • “reason” parameter - Chargeback reason with code numbers. Below is possible reason codes.
Code Reason Recommendation
1 Chargeback  
2 Credit Card fraud Ban User
3 Other fraud Ban User
4 Bad data entry  
5 Fake / Proxy user  
6 Rejected by advertiser  
7 Duplicate conversions  
8 Goodwill credit taken back  
9 Canceled order, e.g. refund  
10 Partially reversed transaction  
11 PayPal e-check fail  

Relate topic