9019
Introduction
Postback notifications ensure that important data is shared with you after events such as signups, purchases, etc. You can store and use this data for member management, or to pass variables to SegPay that can be displayed to a consumer later. To specify which data should be included in postbacks that you receive after various events, login to the SegPay Merchant portal at: https://mp.segpay.com, then point your mouse at the My Websites menu and select Postbacks.
Types of Postbacks
Member Management Postbacks
Inquiry: Triggered when a username and password is entered on the Segpay payment page, or is passed to Segpay from your system during checkout. The Inquiry postback checks if the username already exists in your system. If so, we default the username to the member’s email (please verify that your system supports email addresses as usernames).
Enable: Triggered after an approved purchase, where a username and password were entered on the Segpay payment page, or passed to Segpay from your system. After the Inquiry postback verifies the username is available (or assigns the consumer’s email address as the username) the Enable postback alerts your system to grant access to the member for the service(s) purchased.
Disable: Triggered when a subscription reaches its expiration date (or when expiration is requested via chargeback or a refund/cancel request). The Disable postback is a notification to remove access for that member.
Cancellation: Triggered when an account cancellation or refund is requested – either by you, Segpay or the consumer.
Reactivation: Triggered when an inactive account (previously cancelled or expired) is reactivated.
Transactional Postbacks
Transpost (enter up to 4): Triggered by any transaction (payment, refund, void, chargeback, etc.) to update your database with the transaction details. Set up as many as four of these postbacks, if you need to send data to multiple locations after each transaction. For example, if you use the Segpay Affiliate Master product, two transaction postbacks have to go to affiliate.segpay.com, so you'll still have two remaining postbacks to go anywhere else you like.
For each type of postback, you can specify a URL on your system that is requested when that specific type of event occurs, along with parameters that specify which data is passed back to you.
Add Postback
To add a new postback configuration, just click the Add Postback button and follow these steps:
- Select the merchant associated with this set of postbacks (assuming you have more than one merchant account). Notice the search box, which comes in handy if you have a long list of merchants to scroll through. Note that you are only able to select merchant accounts that are assigned to you by your company administrator.
- In the “Description” field enter a name for this postback configuration. For example, use the name of your website associated with these postbacks, e.g. “Site 1 Postbacks.” (Required field).
Note: When you edit a postback after saving, the postback ID is automatically pre-pended to the description to help you identify the specific postback you are editing. For ex, “2607 – Site 1 Postbacks.”
- Click the blue header to display the input fields for the type of postback(s) you want to set up. Click the blue header again to collapse/hide the fields:
Postback Specs
Note the following when creating postbacks in the sections that follow:
- No need to enter Https in the URL fields; it is pre-pended to your URL automatically (all postback notifications use SSL by default).
-Data strings can include upper and lower-case characters, so your validations should not be set up to require case-sensitivity.
-When entering text for response codes, use a simple data string such as OK. Avoid html, spaces, line breaks, etc., which can break the post back.
-The following postback types are synchronous – they will wait for a response from your system and timeout if nothing is received:
-
- Inquiry
- Enable
- Disable
- Cancellation
- Reactivation
-Transaction postbacks are asynchronous – they do not wait for a response; they use conventional http response codes to indicate success or failure of a request. (For details, see: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).
Postback Input Fields
The input fields are the same for each type of postback. Descriptions for each field are below. To view specific input examples for each field, please refer to the Postback section of Segpay’s Processing API for Merchants Guide, starting on page 18.
URL: The URL where Segpay sends the postback (required).
Expected Response: Enter text that is passed back to Segpay to indicate success; e.g., GOOD or OK.
Error Response: Enter text that is passed back to Segpay if the action requested was not successful; e.g., NOT_SUCCESSFUL.
Failed Postback Notification Options:
- Notification Email: Enter an email address to be notified when a postback fails. This field is required if you select the “Retry Postback” option. The following information is included in the email: {TBD}.
- Retry postback: Select this checkbox to retry failed postbacks. Member Management postbacks are retried every 5 minutes, for up to one hour. Transaction postbacks are retried every hour, for up to 12 hours. Note that if you select this option, you must enter a notification email (see above)
Password-Protected Scripts:
- Domain: Enter the location of the script you entered in the URL section, if the domain is behind a password-protected area.
- Username/Password: Enter the username and password needed to access the protected domain above.
4. Save your changes by clicking one of the following:
Save and Exit: Save your changes and view your list of postback configurations.
Save and Add Another: Save your changes and reload the “Add Postbacks” form so you can begin adding the next one.
Save and Clone: Save your changes and easily create a copy of the postback(s) you just created. The “Add postbacks” form will reload, pre-populated with the data you just saved. Make whatever changes you like before saving.
Cancel: Exit the “Add postbacks” form and discard any data you entered in the fields above.
View all Postback Configurations
After you’ve created at least one postback configuration, you can see your list of postbacks anytime by clicking My Websites/Manage Postbacks.
Each row displays the postback ID and description; and shows which postback types were configured for that ID.
If you have more than one merchant, select the merchant whose postbacks you want to see.
If you have a long list of postbacks, you can use the search box near the top-right of the page. Just enter the first few letters of the postback description until it appears in the table.
If you have more than 25 postbacks, you will see the first 25 on the page by default. Click the Items per Page menu below the report to increase the results per page to 50, 100 or “All” (to see all postback IDs on one page). If you have more than one page, use the arrows to move back and forth between pages in your list.
Make Changes
As you see in the image above, two links appear to the right of each postback in your list:
- Edit: Make changes to any of the options you selected when creating the postback (see Add Postbacks section above).
- Clone: Create a copy of the postback. See Save and Clone option in the previous section.
Full List of Postback Parameters
The following chart defines all of the parameters you can add to postback URLs, and specifies the types of postbacks where each parameter can be used. You can add specific parameters to the postback URL in the order you want or, if you add none, all available parameters for the specific postback are passed to you.
|
Parameter |
Definition and Values |
Inquiry |
Access Enable |
Access Disable |
Cancel-lation |
Re-activation |
Trans-action |
|
<Action> |
The action that generated this postback. Default values are:
Inquiry Postbacks: “Probe” – A username and/or password was collected during payment. Segpay is making sure the username is available in your system. If it isn’t, we will assign the consumer's email address as the username.
Access Enable Postbacks: “Enable” – Access to your system has been granted, following a purchase.
Access Disable Postbacks: “Disable” – Access to your system has been removed, following an account cancellation/expiration.
Cancellation Postbacks: “Cancel” – A member has requested a cancellation or a refund/cancellation.
Reactivation Postbacks: “Reactivation” – A cancelled or expired subscription has been reactivated.
Transaction Postbacks: |
X |
X |
X |
X |
X |
X |
|
<stage> |
The type of transaction that triggered the event. Supported values are: |
X |
X |
|
|
|
X |
|
<approved> |
“yes” – Authorized transaction. |
X |
X |
|
|
|
X |
|
<trantype> |
Type of transaction. Either: “sale” – Sale. |
X |
X |
|
|
|
X |
|
<purchaseid> |
PurchaseID of transaction. |
X |
X |
X |
X |
X |
X |
|
<tranid> |
TransactionID of transaction. |
X |
X |
|
|
|
X |
|
<price> |
Transaction amount. For currency type, see <currencycode> |
X |
X |
|
|
|
X |
|
<currencycode> |
The currency used for the transaction. Either: “USD” – US dollar “EUR” – Euro “GBP” – British pound |
X |
X |
|
|
X |
X |
|
<paymentaccountid> |
Secure ID string used to uniquely identify the credit card used in a transaction. |
|
|
|
|
|
X |
|
<ipaddress> |
Consumer’s IP address. |
X |
X |
|
|
|
X |
|
<relatedtranid> |
Transaction ID of the original sale. Only available for refund, void, chargeback and revoke transactions. |
|
|
|
|
|
X |
|
<eticketid> |
PackageID:BillConfigID (Signup and Stand-In only). |
X |
X |
|
|
X |
X |
|
<ival> |
Initial transaction amount authorized for the sale. |
X |
X |
|
|
|
X |
|
<iint> |
Length, in days, of the Initial billing period (trial). |
X |
X |
|
|
|
X |
|
<rval> |
Recurring billing amount. 0 if no recurring amount. |
X |
X |
|
|
X |
X |
|
<rint> |
Length, in days, of the recurring billing period. |
X |
X |
|
|
|
X |
|
<desc> |
Bill configuration description. |
X |
X |
|
|
|
X |
|
<extra username> |
Username collected on the pay page. |
X |
X |
X |
X |
X |
X |
|
<extra password> |
Password collected on the pay page. |
X |
X |
X |
X |
X |
X |
|
<billname> |
Consumer’s first and last name. |
X |
X |
|
|
X |
X |
|
<billnamefirst> |
Consumer’s first name |
X |
X |
|
|
X |
X |
|
<billnamelast> |
Consumer’s last name |
X |
X |
|
|
X |
X |
|
<billemail> |
Consumer’s e-mail address. |
X |
X |
|
|
|
X |
|
<billphone> |
Consumer’s phone number. Collected on the pay page or passed to Segpay from you. Only collected on check transactions. |
X |
X |
|
|
|
X |
|
<billaddr> |
Consumer’s billing street address. Collected on the pay page or passed to Segpay from you. |
X |
X |
|
|
|
X |
|
<billcity> |
Consumer’s billing city. Collected on the pay page or passed to Segpay from you. |
X |
X |
|
|
|
X |
|
<billstate> |
Consumer’s billing state. Collected on the pay page or passed to Segpay from you. |
X |
X |
|
|
|
X |
|
<billzip> |
Consumer’s billing zip code. Collected on the pay page or passed to Segpay from you. |
X |
X |
|
|
|
X |
|
<billcntry> |
Consumer’s billing country, represented by a two-character ISO code. Collected on the pay page or passed to Segpay from you. |
X |
X |
|
|
|
X |
|
<extra merchantpartnerid> |
Affiliate ID passed to Segpay from you when the transaction executed. Useful if you use your own affiliate program and want to track sales through Segpay. |
X |
X |
|
|
|
X |
|
<transguid> |
The transaction Global Unique Identifier (GUID) assigned to the transaction by Segpay. Used for instant conversions. |
X |
X |
|
|
|
X |
|
<standin> |
-1 = Stand-In not supported. |
X |
X |
|
|
|
X |
|
<xsellnum> |
0 = Main transaction. |
X |
X |
|
|
|
X |
|
<transtime> |
Date and Time (in GMT) the transaction occurred. Sent URL-encoded. Example:
7%2f28%2f2008+3%3a38%3a43+PM+(GMT+STANDARD+TIME) |
X |
X |
|
|
|
X |
|
<reactivationtimestamp> |
Date and Time (in GMT) the reactivation occurred. Sent URL-encoded. Example:
7%2f28%2f2008+3%3a38%3a43+PM+(GMT+STANDARD+TIME) |
|
|
|
|
X |
|
|
<nextbilldate> |
Next rebill date for re-activated subscription: mm/dd/yyyy |
|
|
|
|
X |
|
|
<lastbilldate> |
The last date the re-activated subscription was billed: mm/dd/yyyy |
|
|
|
|
X |
|
|
<extra ref1> through <extra ref10> |
Ref Variables are merchant reference variables. Segpay will store these variables along with the transaction, and they can be retrieved at a later time. Unlike user-defined variables, Ref values are encrypted in our database and passed back in all reports. |
X |
X |
|
|
|
X |
|
<extra xxxx> |
All variables that are passed in on the pay page request via GET or POST variables will be matched to any “extra” variables and returned.
|
X |
X |
|
|
|
X |
|
<ccfirst6> |
First 6 digits of the card number (the BIN number).
The merchant needs to be configured to be able to receive this variable. |
|
|
|
|
|
X |
|
<cclast4> |
Last 4 digits of the card number.
The merchant needs to be configured to be able to receive this variable. |
|
|
|
|
|
X |
|
<authcode> |
Represents the response code for a transaction. Should use the normalized bank response table to return the appropriate decline message to the merchant. |
|
|
|
|
|
X |
|
<ccbincountry> |
Two-character ISO code representing the country associated with the credit card BIN value. |
|
|
|
|
|
X |
|
<refundreasoncode> |
Reason code the user chose when refunding the transaction. Only passed back for refund and void transactions. |
|
|
X |
|
|
X |
|
<refundcomment> |
The additional comment entered when a refund or void is processed. Only passed back for refund and void transactions. |
|
|
X |
|
|
X |
|
<refundedby> |
Name of the consumer that refunded the transaction. Only passed back for refund and void transactions. |
|
|
X |
|
|
X |
|
<cancelreasoncode> |
Reason code the consumer chose when refunding the transaction. Only passed back for refund and void transactions. |
|
|
|
X |
|
X |
|
<cancelcomment> |
The additional comment entered when a cancellation is processed. Only available in the cancellation postback. |
|
|
|
X |
|
X |
|
<cancelledby> |
Name of the consumer that cancelled the transaction. Only available in the cancellation postback. |
|
|
|
X |
|
X |
|
<cardtype> |
Available values are: Visa, MasterCard, JCB, Discover, eCheck and DirectDebit. |
|
|
|
|
|
X |
|
<extra browsertype> |
Browser type identified at the time of the transaction. Can include a variety of values as there are many different browser types. |
X |
X |
|
|
|
X |
|
<extra browserversion> |
Browser version identified at the time of the transaction. Example: Mozilla%2f5.0+(Windows+NT+6.3%3b+WOW64)+AppleWebKit%2f53 |
X |
X |
|
|
|
X |
|
<extra ipcountry> |
Two-character ISO country code associated with the IP address for the transaction. |
X |
X |
|
|
|
X |
|
<extra ismobiledevice> |
Values are: True or False, to indicate if transaction originated on a mobile device. |
X |
X |
|
|
|
X |
|
<extra platform> |
The platform identified at the time of the transaction. |
X |
X |
|
|
|
X |
|
<extra template> |
Paypage template associated with the package for the transaction. |
X |
X |
|
|
|
X |
|
<prepaidindicator> |
Values are: Y or N, to indicate if payment was made via a prepaid card. |
X |
X |
|
|
|
X |
|
<urlid> |
Numeric value representing the website ID in the Segpay system. |
X |
X |
X |
|
X |
X |
|
<singleusepromo> |
Values are: Yes or No, to indicate whether a sale is associated with a single-use promotion. NOTE: This parameter is programmatically added to a postback for all single use promo transactions. |
X | |||||
|
<SCArequired> |
Values are: Yes or No, to indicate if transaction required Strong Customer Authentication, via 3-D Secure, in accordance with PSD2 regulations (NOT CURRENTLY BEING ENFORCED). |
X | |||||
| <3DSauthenticated> |
Values are: Yes or No, to indicate if customer was authenticated via 3-D Secure. NOTE: The 3DSauthenticated parameter is added to custom postbacks even if not specified in the URL string. |
X | |||||
| <3DSauthenticationtype> | NOT CURRENTLY USED. Will include type of 3-D Secure authentication used. | X | |||||
| <authprice> | Converted amount, in an Amount Verification transaction, according to your base currency and the exchange rate on the day of the transaction. | X | |||||
| <authcurrency> | Currency used for Amount Verification transaction, based on consumer’s selection. | X | |||||
| X |
If you ever need help with your postbacks, or if you have thoughts or suggestions on this or any other Segpay feature, please contact us at [email protected].
