TransXpress ForumTransXpress Comments (1)

Automated Payment API Documentation

Overview

TransXpress' Automated Payment API allows you to use TransXpress as a payment gateway for your own shopping cart or e-commerce site, provided the purchaser has an account on this site.

The process is initiated by sending a POST request to https://trans-xpress.com/auto_payments/new with specific parameters (detailed below), and TransXpress steps the user through making the payment. Once it is completed, the user is sent back to your website by given URLs.

Parameters

account_number

Required. This is your account number that will be accepting the funds that are transferred. Example: 'TX-123'

amount

Required. The amount that should be transferred (excluding TransXpress fees). Any currency symbols are not required. Example: '100.00'

currency

Required. The currency that the transfer should be conducted with. Example: 'USD'

internal_id

Your own transaction identifier. This will not be shown to the user. Example: 'TR1001'

comment

Your own transaction memo. This will not be shown to the user. Example: 'Automated Transaction 1001'

description

A description of the transaction. This will be displayed to the user. Example: 'The Moon'

success_url

Required. The URL that the user should be directed to once the transaction has been completed. See documentation below for details on what information is sent through. Example: 'http://domain.tld/success'

success_method

How the user will be directed to success_url. Allowed values are POST and GET. POST is the default if none is supplied.

failure_url

Required. The URL that the user should be directed to if they cancel the transaction, or are unable to continue with should they not have sufficient funds for the given currency. See documentation below for details on what information is sent through. Example: 'http://domain.tld/failure'

failure_method

How the user will be directed to failure_url. Allowed values are POST and GET. POST is the default if none is supplied.

notify_url

The URL or email address that will receive notification when a transaction is marked as completed or invalid. If sending to an email address, ensure notify_method is set to MAIL. See documentation below for details on what information is sent through. Example: 'http://domain.tld/notify'

notify_method

How the completion/invalidation notification (using notify_url) will be sent. Allowed values are POST, GET and MAIL. POST is the default if none is supplied. MAIL should only be used if notify_url is an email address.

extra

Any extra information you would like to send through. You could use this as a container for additional fields the above options don't cover. Example: 'shipping=air,country=Australia'

An example form:

<form action="https://trans-xpress.com/auto_payments/new" method="post">
  <input type="hidden" name="account_number" value="TX-123" />
  <input type="hidden" name="amount" value="100.00" />
  <input type="hidden" name="currency" value="USD" />
  <input type="hidden" name="internal_id" value="TR1001" />
  <input type="hidden" name="comment" value="Automated Transaction TR1001" />
  <input type="hidden" name="description" value="The Moon" />
  <input type="hidden" name="success_url" value="http://domain.tld/success" />
  <input type="hidden" name="success_method" value="POST" />
  <input type="hidden" name="failure_url" value="http://domain.tld/failure" />
  <input type="hidden" name="failure_method" value="GET" />
  <input type="hidden" name="notify_url" value="auto@domain.tld" />
  <input type="hidden" name="notify_method" value="MAIL" />
  <input type="hidden" name="extra" value="shipping=air,country=Australia" />
  <input type="submit" value="Transfer via TransXpress" />
</form>

Responses

At various stages in the transaction process, the user may be sent back to your site by supplied URLs. In all cases, data, as outlined below, will be sent via POST or GET requests.

Success

Once the transaction is completed on the TransXpress website, the user will be directed to the success_url using a POST or GET request. In both situations, all the initial parameters will be sent along as well:

• account_number
• amount
• currency
• internal_id
• comment
• description
• success_url
• success_method
• failure_url
• failure_method
• notify_url
• notify_method
• extra

Failure

If at any point the user cancels the transaction process, or if it's found that they do not have sufficient funds once they have logged in to finalise the payment, they will be directed to the failure_url using a POST or GET request. In both situations, all the initial parameters will be sent along as well:

• account_number
• amount
• currency
• internal_id
• comment
• description
• success_url
• success_method
• failure_url
• failure_method
• notify_url
• notify_method
• extra

Notification

When the transaction is completed or invalidated, TransXpress will send notification to the URL or email address provided for notify_url. The following data will be included, either in the email or as POST or GET parameters:

sender

The account number of the user who completed the transaction. Example: 'TX-3214'

recipient

The account number of the user who received the payment - that is, what was provided as account_number at the start of the process. Example: 'TX-123'

amount

The amount transferred. Example: '100.00'

currency

The currency that the payment was conducted with. Example: 'AUD'

receipt

The unique identifier for the transaction, from the perspective of TransXpress. Example: 'TX-401-227'

internal_id

The internal reference that was supplied at the start of the process. Example: 'TR1001'

timestamp

The exact time of the transaction, in RFC822 format. Example: 'Mon, 06 Apr 2009 17:14:04 +1000'

status

The status of the transaction. This will either be 'completed' or 'invalid' - do not forget to track this value, as notifications may be sent more than once for any given transaction, as its status changes.

extra

Any additional information you provided in the field of the same name at the beginning of the process. Example: 'shipping=air,country=Australia'

hash

A unique verification hash generated for each transaction. This will allow you to guarantee that the notification has come from TransXpress.

Verification

Using the notification parameters and your account password, you can generate a matching verification hash by joining the values of the following fields (in the given order) with colons (':'), and then finding the MD5 hash of the corresponding string.

1. sender
2. recipient
3. amount
4. currency
5. receipt
6. internal_id
7. timestamp
8. MD5 hash of account password

An pseudo-code example, where your account password is 'automation':

password_hash = hash('automation');
string = "TX-123:TX-456:100.00:USD:TX-789-999:TR1001:" +
         "Mon, 06 Apr 2009 17:14:04 +1000:" + password_hash;
print hash(string);
# => "58af05803c3950e4bd35329f223105df"