Payforit 4 API

From txtNation Wiki
Jump to: navigation, search
Payforit Logo

Please note: this is now Payforit VERSION 5.

Payforit is the UK mobile micropayment scheme, created and supported by all of the UK mobile network operators (MNOs), enabling consumers to use their mobile phone account or prepaid balance to transact securely and safely when purchasing content and services on the internet.

Through txtNation's Payforit API, you can securely create ad hoc Payforit campaigns with dynamic price points.

This option may be useful to clients who would like to charge for hundreds of different products or clients that have their own clients and may not necessarily know what price points they need in advance.

IMPORTANT INFORMATION

Any country connection problems or interruptions to txtNation services will be announced in our Zendesk forum article. Please login to your Zendesk account and subscribe to these updates now. They will be very important for your services. If you are a temporary developer on a project, please advise your manager to do the same. You can also subscribe to maintenance notices.

Contents


Useful information

To connect to the Payforit API you should use the following details:

Transaction flow

The below flow diagram details how a Payforit transaction will happen.


The Payforit message flow

One-time charges

To call the API you should send an HTTP POST or GET request.

Required parameters (All Requests)

The following parameters must be sent through with each API call you make.

Variable Name Example Description Restrictions
company joebloggs Your company name in our platform Between 2 and 30 alphanumeric characters
password 88C3CF364123A25BBAB687D4FE8EC628 Your password in our platform Will be provided on setup and is linked to your control panel login.
value 1.00 The amount of money to charge the end user. See available price points, below. One or two digits, optionally followed by the decimal places, if required.
currency GBP The currency in which to charge the end user. This must always be GBP in upper case.
name Access to my secret page The name of the product for which you are charging. This will be visible on the Payforit window. Max length: 35 characters
description Provides access to the secret members only page. A short description of what the end user is purchasing. Max length: 200 characters.
Optional parameters callback_url, success_url, cancel_url. These optional parameters should be included in every case, see the following table.

Optional parameters (All Requests)

The following parameters can be sent through with each API call you make, depending on what you want to achieve.

Variable Name Example Description Restrictions Default
id JB-123 A unique identifier (generated by you) of the transaction from your platform. This ID will be sent to you on subsequent post backs, under the variable 'key' (see wiki page txtNation PayforIt Notifications). Max length: 150 characters. null
brand Joe Bloggs Ltd The trading name of the company who will be making the charge. This must be pre-approved and arranged through the txtNation support team. Max length: 30 characters. txtNation
window large The type of Payforit window to render for the consumer. See Payforit windows, below. One of: large, small, embed_large, embed_small small
msisdn 44744665537 If you know the MSISDN of the consumer you can pre-populate the MSISDN field of the Payforit window using this parameter. null
marketing 1 Ask the consumer whether they would like to be included on marketing information from your company Can be either 1 or 0. 1
confirmation 1 When the purchase is made, should the consumer see the confirmation page including the marketing (above) checkbox? Can be either 1 or 0. 0
callback_url http://yourserver.com/ When the consumer has confirmed or declined the purchase, we can notify a URL of your choosing with the status of the transaction. Must be URL encoded null
success_url http://yourserver.com/success/ When the consumer has confirmed purchase, this is the page they will be redirected to by Payforit.

Additionally, the transaction id will be appended to the parameters returned (parameter: t)

Must be URL encoded null
cancel_url http://yourserver.com/error/ When the consumer has declined purchase, this is the page they will be redirected to by Payforit.

Additionally, the transaction id will be appended to the parameters returned (parameter: t)

Must be URL encoded null
terms http://yourserver.com/terms/terms.html Displayed to end users in the small print at the bottom of each window generated. Must be URL encoded http://www.txtnation.com/pfi/terms.html
logo http://yourserver.com/images/logo.png Use your brand logo instead of text. This must be your merchant logo NOT a logo of the product. For best results, images should be 440px x 40px. Must be URL encoded null

Examples

Each of the following examples will create a different Payforit window. Please note that you must replace the company and password parameters with your own details to pass validation.

  • Create a large Payforit window to charge the end user 5.00 GBP
 https://payforit.txtnation.com/api/?company=mycompany&password=XXXXX&value=5.00&currency=GBP&name=My+first+Payforit+product&description=My+first+Payforit+test+dislogue&window=large&success_url=http%3A%2F%2Fwww.txtnation.com%2F&cancel_url=http%3A%2F%2Fwww.mfusion.com%2F&callback_url=http%3A%2F%2Ftxtnation.com
  • Create a small Payforit window to charge the end user 1.00 GBP
 https://payforit.txtnation.com/api/?company=mycompany&password=XXXXX&value=1.00&currency=GBP&name=My+redirecting+Payforit+window&description=Another+test+from+my+Payforit+dislogue&window=small&success_url=http%3A%2F%2Fwww.txtnation.com%2F&cancel_url=http%3A%2F%2Fwww.mfusion.com%2F&callback_url=http%3A%2F%2Ftxtnation.com

Callback URL

For a simple one time payment, the Callback URL will receive the following variables by HTTP POST from the txtNation Gateway server, which represent the progress/status each payment attempt.

   [key] => da787950b76abXXXX2fdeee4d3ac7427da046bc429
   [billed] => 1
   [transactionId] => 1481485429996291
   [status] => OK
   [msisdn] => 447777777777
   [network] => ORANGEUK

These variables should be extracted from the HTTP $_POST variable and stored to a database for your own records and further processing.

For full details of the notifications see PayforIt Notifications

Success URL

Upon successful payment the consumer will be re-directed to URL defined for this variable

Cancel URL

When the consumer selects cancel during the payment process they will be re-directed to URL defined for this variable

Subscription charges

Subscription charges enable you to add your end users to a managed subscription service, where you can define how much and how often someone should be billed. All subsequent billing messages are handled by Payforit, as are STOP / STOP ALL requests.

Required parameters

In addition to the required parameters, above, the following extra parameters are required for subscriptions:

Variable Name Example Description Restrictions
sub_repeat 7 How many times should the end user be billed in total? Either a positive integer, or zero (never ending subscription).
sub_period 1 In conjunction with sub_period_units, how often should the end user be charged? A positive integer
sub_period_units days The units of sub_period to use One of: hours, days, weeks, months

Optional parameters

The following parameters are not required for most subscription services but have been included for completeness.

Variable Name Example Description Restrictions
sub_free_period 1 Together with the sub_free_period_units, this defines how long the end user has free at the beginning of the subscription. This parameter is the number of units (days, weeks, etc) that the free period lasts for.

The value must be a positive integer. If there is no free period, do not include the parameter. The maximum free period you can set is 45 days. Required: Only when subscriptionFreePeriodUnits is also specified.

A positive integer Default: 1 day
sub_free_period_units days The units of sub_free_period to use. This must be one of: Hours, Days, Weeks or Months (these are case sensitive). If there is no free period, do not include the parameter. The maximum free period you can set is 45 days. Required: Only when subscriptionFreePeriod is also specified.

Deprecated parameters

The following parameters are no longer supported.

Variable Name Example Description Restrictions
sub_grace_period 1 Together with the sub_grace_period_units, if the subscription charge fails this defines how long we will continue to attempt billing before suspending the subscription A positive integer With a Default and maximum: 45 days.
sub_grace_period_units days The units of sub_grace_period to use One of: hours, days, weeks, months.
sub_suspend_period 1 Together with the sub_suspend_period_units, this determines how long we will attempt to charge an end user that is suspended. After this time has elapsed, the end user is unsubscribed A positive integer With a Default and maximum: 45 days.
sub_suspend_period_units days The units of sub_suspend_period to use One of: hours, days, weeks, months.

Grace and Suspend periods work as follows: Grace and Suspend periods are calculated as (Suspend period minus Grace period).

Therefore if Suspend Period = 30 Days and Grace Period = 7 Days, The suspend period will be (30-7) = 7 days Grace and 23 Days suspended, before the user is unsubscribed.

Retries

Retries are handled automatically via the Payforit subscription management system.

The time between retries depends on the subscription period; each action is retried three times according to the following scheme:

sub_period_units Retry interval
hours 15 minutes
days 6 hours
weeks 2 days
months 1 week

For example, on a monthly subscription started on 2014/10/01 00:00:00 with a failed initial billing attempt, the retry will be attempted at 2014/10/08 00:00:00, then 2014/10/15 00:00:00, then 2014/10/22 00:00:00 before being opted out. If a billing request is successful at any stage the message is removed from the retry scheme.

Examples

The following Payforit windows each show a different style of subscription. Please note that you must replace the company and password values with your own details.

  • Create a subscription that will charge an end user 4.50 GBP per week, for four weeks.
 https://payforit.txtnation.com/api/?company=mycompany&password=XXXXX&value=4.50&currency=GBP&name=My+first+subscription&description=My+first+subscription+Payforit+test+window&sub_repeat=4&sub_period=1&sub_period_units=weeks

Stopping subscriptions

If you need to STOP a subscription on behalf of an end user you should make a call to the following API:

 https://payforit.txtnation.com/api/stop/?company=mycompany&password=XXXXX&transactionId=12345678901234567890

Where transactionId is the transactionId returned to you as part of the Subscription initiated post.

One of the following HTTP codes will be returned with each response.

  • 200 OK
  • 406 Not Acceptable
  • 403 Forbidden
  • 400 Bad Request

A JSON response in the body of the result will provide you with additional details.

All successful stop requests will have the body text: { status: 'OK' }

Error responses will have an error status along with a result parameter which will provide you with a reason for the failure. e.g. { status: 'ERROR', result: 'Invalid transactionId' }

Please note that this will also send a notification to your callback_url (if set) confirming the subscription conclusion (the user will also be notified by means of text message).

Return values explained

When you make a call to the API, the result of the call will be output into the body of the HTTP response. The response is split into two or three sections using the | (pipe) character. For example:

 OK|1268316443|http://pfi.me/0/XXXXXXX

A successful response will always begin with OK. Error responses will begin with ERROR.

The second section of the string reports the ID of the transaction in our platform. This will be posted to you with every subsequent HTTP POST callback. We recommend that you interpret this value as a 64-bit integer to avoid integer overflow issues.

The final section is the URL to which you must redirect your end user (HTTP 302).

Error messages

The following list details the possible error strings that you may experience. Please note that X is a place holder for more informative text.

  • You have forgotten to include a parameter that must be included for the transaction you want to create:
 Missing parameter X in request
  • A parameter does not conform to the requirements of the field:
 Parameter X is not in required format
  • The company and/or password values are incorrect:
 Invalid credentials
  • The amount you want to charge is not supported:
 Unsupported value
  • The currency must be GBP:
 The currency given was not recognised
  • There is a temporary problem retrieving your account details. Please try again later:
 Account not found
  • There is a temporary problem loading a Payforit window. Please try again later:
 Payforit unavailable for this transaction, errno: X
  • There is a temporary problem saving your transaction details. Please try again later:
 Payforit currently unavailable

Available price points

The following price points are available on both one-time and subscription charges. More tariffs may become available over time.

Please note that your service must receive specific approval for any price point over £10.00 (maximum: £30.00). Please contact our support team for more information.

Operator Price Points (In GBP, £)
Orange 0.25, 0.50, 0.75, 1.00, 1.50, 2.00, 2.50, 3.00, 3.50, 4.00, 4.50, 5.00, 6.00, 7.00, 8.00, 9.00, 10.00
T-Mobile 0.25, 0.50, 0.75, 1.00, 1.50, 2.00, 2.50, 3.00, 3.50, 4.00, 4.50, 5.00, 6.00, 7.00, 8.00, 9.00, 10.00
O2 0.25, 0.50, 0.75, 1.00, 1.50, 2.00, 2.50, 3.00, 3.50, 4.00, 4.50, 5.00, 6.00, 7.00, 8.00, 9.00, 10.00
Three 0.25, 0.50, 0.75, 1.00, 1.50, 2.00, 2.50, 3.00, 3.50, 4.00, 4.50, 5.00, 6.00, 7.00, 8.00, 9.00, 10.00
Vodafone 0.25, 0.50, 0.75, 1.00, 1.50, 2.00, 2.50, 3.00, 3.50, 4.00, 4.50, 5.00, 6.00, 7.00, 8.00, 9.00, 10.00
Virgin 0.25, 0.50, 0.75, 1.00, 1.50, 2.00, 2.50, 3.00, 3.50, 4.00, 4.50, 5.00, 6.00, 7.00, 8.00, 9.00, 10.00

Spending Limits

One Time Billing

  • Orange users are limited to spending £30 per month via Payforit.
  • All other networks are limited to spending £30 per day via Payforit.

Subscription Services

  • Subscription services are limited to £4.50 per week across all networks unless you have prior approval from PhonepayPlus.

txtNation's Server IP Addresses

You can validate all posts you receive from our server by validating against the following IP list.


  • 5.39.71.100
  • 149.202.136.48
  • 149.202.136.49
  • 149.202.136.50
  • 149.202.136.51
  • 149.202.136.52
  • 149.202.136.53
  • 149.202.136.54
  • 149.202.136.55
  • 162.13.59.148
  • 162.13.52.70
  • 162.13.104.239
  • 162.13.56.28


This is of course optional, but strongly recommended to prevent un-authorised requests. If you are unsure of what to do please contact our support team at http://sd.txtnation.com.

Payforit windows

There are four different types of window available in Payforit: large (default), embed_small, embed_large. Examples of each are shown below:


The following can be done on a per application basis

Please contact txtNation support team at http://clients.txtnation.com for more details. You may also make a number of small changes to the payment window to better tailor it to your service:

  • Add your company / service logo to the top of the payment page.
  • Amend the terms and conditions to better suit your service type.
  • Add your companies contact details / support information.
Personal tools