Transaction Modification API

The Transaction Modification API feature makes it possible to remotely edit the affiliate's payout, merchant's revenue, and/or the transaction approval status. You can also grant access to a merchant and allow them to edit their own transactions.

Because you are using a feature that is outside the secure environment of the LinkTrust app, LinkTrust has enhanced the layers of security for this feature. That means that you must enable external transaction modification for each campaign separately and provide a custom password. You can also restrict changes to come from only specific white listed IP addresses.

NOTE: LinkTrust highly recommends using HTTPS for all transaction edit API calls to ensure secure communications. This requires your inbound URL to be configured for HTTPS. You must have a secure certificate setup with LinkTrust to do this.

To adjust a transaction, you need the updated affiliate payout, merchant revenue, or approval status with a valid click ID, transaction ID or a combination of merchant reference ID and campaign ID with the security password. The ability to use the merchant reference ID and campaign ID combination requires you to enforce a unique merchant reference ID for each transaction in the campaign settings.

Merchants can also modify transactions within LinkTrust by passing their own ID from their back office CRM or shopping cart instead of needing to record and use LinkTrust identifiers.

In this help page, you learn the following:

  • Enable External Transaction Modifications
  • Identify Posting Parameters
  • Identify Posting Transaction Server Responses
  • Identify Error Response Messages
  • Create a Tab Delimited (*.TXT) File
  • Use Lead Poster

Enable External Transaction Modifications

To enable external transaction modifications, do the following:

  1. From the menu, select Campaigns > View All.
  2. Browse to and select the campaign you wish to enable external transaction modifications for.
  3. Open the campaign settings by selecting the Edit Campaign icon.
  4. Under Tracking Options, mark Allow External Transaction Modifications.
  5. In the Custom Password field, enter a password.
  6. If you want these externally modified transactions to ONLY come from a known IP address, select Only Allow Modifications from White Listed IPs.

If you plan to use the white list, make sure you add the IP address to the white list. The white list is located under Account > Domains.

Identify Posting Parameters

The posting URL used for all transaction modification is the following:

http://[TrackingURL.com]/transaction.edit

You must have one of the following three parameters to modify these transactions:

  1. LinkTrust transaction ID (Transactionid=value)
  2. Click ID (Clickid=value)
  3. Merchant reference ID and campaign ID (Merchantreferenceid=value&CID=xxxxxxx)

NOTE: Only one method can be used at a time per transaction. For the posting transaction format, select sample CVS files

After the transaction is located, you can modify the transaction in the following ways:

  1. Affiliate Payout (AP=0.00)
  2. Merchant Payout (MP=0.00)
  3. Transaction Approval status (A=yes or A=no) (Yes is for an approved transaction and No is for an unapproved transaction.)
  4. Execute the Affiliate's Server Side Post Back URL (executeaffiliatepixel=Yes)

For added security, the password you placed in LinkTrust when enabling the transaction modification feature must be passed in for each modification. Use the following parameter:

Password (Password=value)

Sample Transaction Modification URLs

To modify a transaction externally, you must have one of the following URLs to perform this action:

  • Transaction ID URL:

http://[TrackingURL.com]/transaction.edit?Password=value&Transactionid=value&A=no&AP=0.00&MP=0.00&executeaffiliatepixel=Yes

  • Click ID URL:

http://[TrackingURL.com]/transaction.edit?Password=value&ClickID=value&A=no&AP=0.00&MP=0.00&executeaffiliatepixel=Yes

  • Merchant Reference ID and Campaign ID URL:

http://[TrackingURL.com]/transaction.edit?Password=value&Merchantreferenceid=value&CID=xxxxxx&A=no&AP=0.00&MP=0.00&executeaffiliatepixel=Yes

As you can see, each modification URL has all of the following four components:

  1. Posting URL
  2. Password
  3. Identifier
  4. Modification parameters

There is no required order for these name-value pairs when posting in a modification.

Transaction Modification Server Responses

When a transaction modification is done from an external source, LinkTrust responds with the following server responses:

Sample Success Response:

<?xml version="1.0" encoding="UTF-8"?>
<LinkTrust><ApiResponse action="ModifyTransaction">
<Succeeded>True</Succeeded>
<SuppliedValues>
<TransactionId></TransactionId>
<ClickId></ClickId>
<MerchantReferenceId></MerchantReferenceId>
<CID></CID>
<AP>0.00</AP>
<MP>0.00</MP>
<A>no</A>
<REASON></REASON>
</SuppliedValues>
</ApiResponse></LinkTrust>

Sample Failure Response:

<?xml version="1.0" encoding="UTF-8"?>
<LinkTrust><ApiResponse action="ModifyTransaction">
<Succeeded>False</Succeeded>
<Error><Type>permanent</Type>
<Message>Permanent Failure: Invalid authentication credentials.</Message>
</Error><SuppliedValues>
<TransactionId></TransactionId>
<ClickId></ClickId>
<MerchantReferenceId></MerchantReferenceId>
<CID><CID>
<AP></AP>
<MP></MP>
<A></A>
<REASON></REASON>
</SuppliedValues>
</ApiResponse></LinkTrust>

Identify Error Response Messages

The following table lists possible error messages and their results:

Error Result
Error message for invalid parameters Permanent failure: Invalid parameter value for [=PARAMETER_NAME=]
Error message when multiple transaction identifiers are supplied Permanent failure: Multiple transaction identifiers provided
Error message for temporary failures: [=FAILURE_TYPE=] LinkTrust API was unable to complete the request
Error message for system failures System level error
Error message for when transaction cannot be found Permanent failure: Invalid transaction specified
Error message for when the campaign does not allow external transaction modification Permanent failure: Campaign does not allow external transaction modification
Error message for when the password does not match Permanent failure: Invalid authentication credentials
Error message for when the IP address is not on the white list and the white list is enforced Permanent failure: Invalid authentication credentials
Error message if nightly processing is in progress Temporary failure: Nightly processing in progress
Error message if not yet rolled up to the hour Temporary failure: Hourly processing not completed

Create a Tab Delimited (*.TXT) File

Using a text file allows you to modify a large quantity of transactions quickly. For example, you want to unapprove 150 transactions given to you by your merchant and you do not want to make these changes one by one. After understanding the information needed to make these changes remotely, you can create a spreadsheet in Excel and then have the lead poster post these modifications for you.

The tab delimited (*.TXT) file format is a format used to store table data where numbers and text are stored in plain textual form that can be read in a text editor. You must first create a spreadsheet and save it as a TXT file for the creative import to work. For your convenience, download the sample .CSV files to get started.

To create a spreadsheet file, do the following:

  1. Download the sample spreadsheet fileNote: The downloadable file is compressed for easier downloading.
  2. Save the file to your desktop.
  3. Open the file in Excel.
  4. Make the following column headers:
    • Transaction ID - Password, TransactionID, AP, MP, A
    • Click ID - Password, ClickID, AP, MP, A
    • Merchant Reference ID + Campaign ID - Password, MerchantreferenceID, CID, AP, MP, A, executeaffiliatepixel
  5. Import the appropriate transaction modification information.
  6. When you are finished, save the file into a Tab Delimited (*.TXT) File.
  7. Select Save as.
  8. Select Other Formats.
  9. Select Text (Tab Delimited).
  10. Import a Tab Delimited (*.TXT) File.

Use Lead Poster

Now that your file is complete, you are ready to use the lead poster to modify your transactions. You must use the GET method in the lead poster to post the modifications into the system.  To learn more, select lead poster.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.