Swisscom Easypay

From txtNation Wiki
Jump to: navigation, search

Introduction

Easypay is the simple and secure direct billing solution from Swisscom enabling web and mobile web payments.

Easypay allows your customers to pay for content without any personal mobile subscriber details other than the MSISDN being disclosed. It is not necessary for the customer to register.


Contents


Implementation

In order to implement our COP gateway you will need:

  • Good programming knowledge to create a script that can send and respond to HTTP GET/POST requests.
  • A server to which will act as a start and end point for your users.


Note: The request can be sent to us as a HTTP GET and we will respond in JSON based on the standards outlined at http://jsonapi.org/format/.


We will also need the following information from you:

  • "Payment Info" - the name of the service which will be printed on the bill of the customer.
  • "merchantName" the name of your store or merchant account


User Process

The Easypay user process


Getting Started

You need to contact txtNation Support to ensure that Easypay is available on your account.

You will need to provide the following information in your support request:

  • What payment information you would like to appear on the bill of an end user
  • Your store name (if you would like to brand you Easypay window with something different to your txtNation account name)

Generating a Window

To display a payment link on your site, you will first need to generate the link. A payment URL can be generated by initiating an HTTP POST or GET request to the URL: http://client.txtnation.com/swisscom/

Below are the variables that we expect from you when making an Easypay request.


Variable Name Example Description
cc test The account name you use for our services (found in My.txtnation.com)
ekey d41d8cd98f00b204e9800998ecf8427e The ekey you were assigned by txtNation during your set up
name My First Product The name of the product being purchased by the end user. This appears on the Easypay window.
description The test description for my first product A short description of what is being purchased by the end user. This appears on the Easypay window.
value 2.00 The amount you wish to charge the end user for the product (in CHF)
success_url http://my.url/success Where the end user should be redirected after making a successful purchase, usually a "Thank You" page or restricted area
cancel_url http://my.url/cancel Where the end user should be redirected after cancelling the transaction
error_url http://my.url/error When the end user cannot be charged they will be redirected to this page


Optional Parameters

Variable Name Example Description
callback_url http://my.url/receive Use this parameter to enable our server to send you notifications of payment when they happen via HTTP
cp_service_id 12345 Your internal identifier for this service
cp_subscription_id GB-123 Your internal identifier for the end user's subscription
cp_user_id adf61b4f8ad6b4a8bfa489179adf6199 Your internal identifier for the end user
is_adult_content 1 Either 1 or 0 -- if the service is of an adult nature then the age of the end user will be confirmed before payment
is_roaming false Either true or false -- if the customer has roaming and the flag was set to true, then the payment will be blocked. If the customer has roaming and the flag was set to false, then the payment will not be blocked. If the customer has NO roaming the flag will be ignored.

Subscription Parameters

Variable Name Example Description
duration 1 The unit of time separating subscription rebilling
duration_unit WEEK Either WEEK or MONTH -- the unit of time associated with the duration parameter

Example Window Request

To generate a standard window (don't forget to use your own cc/ekey credentials!):

http://client.txtnation.com/swisscom/?cc=test&ekey=0aa5bb1086cc847812e7140923d57bff&name=My+first+item&description=This%20is%20my%20description&value=2.00&success_url=http%3A%2F%2Fmy.url%2Fsuccess&error_url=http%3A%2F%2Fmy.url%2Ferror&cancel_url=http%3A%2F%2Fmy.url%2Fcancel&callback_url=http%3A%2F%2Fmy.url%2Freceive


Example JSON Response

The following is an example of what will be returned by our API.

{
    data: [
        {
            id: "54b7aeee468dc",
            url: "https://easypay.swisscom.ch/charging-engine-checkout/authorize.jsf?signature=DU8zqI3KGZSjSbaAy%2FPPVlUfYaw%3D&checkoutRequestItem=eyJwYXltZW50SW5mbyI6IlBheW1lbnQgVGVzdCIsIm1lcmNoYW50TmFtZSI6IlRlc3QgTWVyY2hhbnQiLCJ0aXRsZSI6Ik1hcmMiLCJkZXNjcmlwdGlvbiI6IlRoaXMgaXMgbXkgZGVzY3JpcHRpb24iLCJhbW91bnQiOiIyLjAwIiwiY2FuY2VsVXJsIjoiaHR0cDpcL1wvY2xpZW50LnR4dG5hdGlvbi5jb21cL3N3aXNzY29tXC9jYW5jZWwucGhwP3Rva2VuPTU0YjdhZWVlNDY4ZGMiLCJlcnJvclVybCI6Imh0dHA6XC9cL2NsaWVudC50eHRuYXRpb24uY29tXC9zd2lzc2NvbVwvZXJyb3IucGhwP3Rva2VuPTU0YjdhZWVlNDY4ZGMiLCJzdWNjZXNzVXJsIjoiaHR0cDpcL1wvY2xpZW50LnR4dG5hdGlvbi5jb21cL3N3aXNzY29tXC9zdWNjZXNzLnBocD90b2tlbj01NGI3YWVlZTQ2OGRjIiwibWVyY2hhbnRJZCI6IlRYVDAxIn0%3D"
        }
    ]
}

Upon getting a result you should take the URL returned and redirect the end user to this location to complete the payment.


Common Error Messages

Code Description
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
500 Internal Error


Delivery Reports

If you include a callback_url in your window generation, we will send you updates regarding the transaction. The following table outlines the parameters we will send you via HTTP GET.

Variable Name Example Description
token 54afba65fb4a6aad The ID originally returned to you upon window creation
status Success The result of the payment (see Delivery Status Codes)
payment_id BFCD789-CA3878-246D6C-BFCD789-CA3878 The ID of the payment with Swisscom
cp_service_id 12345 The service ID passed to us when the window was generated
cp_subscription_id GB-12345 The subscription ID passed to us when the window was generated
cp_user_id adf61b4f8ad6b4a8bfa489179adf6199 The user ID passed to us when the window was generated


Delivery Status Codes

Code Description
Success The payment was successfully made
Failed The payment failed when billing was attempted
Cancelled The end user clicked the cancel button on the payment window
Error There was an error during the billing process


Renewing and Cancelling

You are responsible for renewing subscriptions by making the following API call according to your subscription period (every week, every month, etc):

   http://client.txtnation.com/swisscom/renewSubscription.php?cc={cc}&ekey={ekey}&token={token}


To opt-out an end user who no longer wishes to be part of your service you will need to call the following cancel API:

   http://client.txtnation.com/swisscom/cancelSubscription.php?cc={cc}&ekey={ekey}&token={token}


The token used in these examples is returned to you once an end user has subscribed in the delivery report. These calls will return a JSON string containing OK or ERROR, depending on the status of the call. For example:

   {
       data: "OK"
   }

Mobile Web White listing URL(s)

For Mobile Web Billing please view our FAQ. We will white list your URL for 'Single-Click': (found in Mobile Web Billing FAQs)

Live Example

View a live example of Mobile Web Billing (found in Mobile Web Billing Live Example)

Personal tools