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:
- 216.127.71.0/24 - New IP effective from November 2018
- 174.36.92.186
- 174.36.92.187
- 174.36.92.192
- 174.36.96.66
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 |