Payment Button Integration Guide · GoPayToo – Payment Button Integration Guide 2 5 Hash sum / Checksum ..... 18

Payment Button Integration Guide

Confidential - for professional use only

Revision 0.2

1Preface.......................................................................................................................................................31.1Aboutthisdocument....................................................................................................................................31.2Revisions...........................................................................................................................................................31.3SystemOverview............................................................................................................................................31.4Definitions........................................................................................................................................................31.5RequestVSTransaction...............................................................................................................................31.6DocumentationProblems...........................................................................................................................4

2PaymentButtonIntegration...............................................................................................................52.1InterfaceLocation..........................................................................................................................................52.2Testing/Sandbox..........................................................................................................................................52.3AQuickStart....................................................................................................................................................52.4Parameterslist................................................................................................................................................6

3Globalsettings.........................................................................................................................................73.1Customization.................................................................................................................................................73.2CustomerSupport..........................................................................................................................................73.3ReturnURLs.....................................................................................................................................................83.4Automaticnotifications...............................................................................................................................93.5Hashkey............................................................................................................................................................9

4.PostbackandIPN..................................................................................................................................94.1Definitions........................................................................................................................................................94.1.1Postback.........................................................................................................................................................................94.1.2InstantPaymentNotification(IPN)................................................................................................................10

4.2«WhenIwillreceivewhatandwhere?»...........................................................................................104.3DatasentinthepostbackandtheIPN................................................................................................124.4MerchantApiResponse..............................................................................................................................144.4.1Rootdata.....................................................................................................................................................................144.4.2PaytooTransactionType.......................................................................................................................................154.4.3PaytooAccountType...............................................................................................................................................164.4.4PaytooRequestType...............................................................................................................................................17

GoPayToo – Payment Button Integration Guide 2

5Hashsum/Checksum.......................................................................................................................185.1Purpose..........................................................................................................................................................185.2Keyandsettings..........................................................................................................................................185.3Formulaforthe«Hash»inthePaymentButtonrequest.............................................................185.3.1Singlepayment(orinitialpaymentforsubscription).............................................................................185.3.2Recurringpayment/Subscription..................................................................................................................19

5.4Formulaforthe«Hash»inthePostbackandintheIPN...............................................................196CodeSamples........................................................................................................................................216.1HTML...............................................................................................................................................................21

7SpecialNotes.........................................................................................................................................227.1Mandatoryfieldsforcustomeraccountonthegateway................................................................227.2Restrictions...................................................................................................................................................227.3eSignature.....................................................................................................................................................227.4Recurringpayment/Subscription.......................................................................................................22

8Thirdpartiesmodules.......................................................................................................................23LimeLightCRM...................................................................................................................................................23Magento.................................................................................................................................................................23OpenCart...............................................................................................................................................................23OpenCartSettings..............................................................................................................................................................23GoPayTooSettings.............................................................................................................................................................24

9Administration.....................................................................................................................................2610Disclaimer...........................................................................................................................................27


1 Preface

1.1 About this document You can use your Go.PayToo account to receive payments for single and subscription items. This document gives an explanation on how to create Payment Buttons and the parameters that the IPN system posts back to your server.

1.2 Revisions Changes in revision 0.2

• OpenCart Module Changes in revision 0.1

• Initial document

1.3 System Overview Go.PayToo is a payment system that allows you to do quick, efficient and secure online transaction processing through an electronic wallet and also a number of third party and bank payments processing systems. PayToo uses real time processing with customer specified payment gateways to verify wallets details. PayToo stores the transactions details in an internal database. With the PayToo Administration interface you are able to overview user transactions. It also allows you to manage accounts and to view and analyze declined payments.

1.4 Definitions merchant – Refers to the merchant of Go.PayToo who is processing transactions for its customers customer – Refers to the party attempting to process a transaction – Any state or “event” with regards to a processing via the system (i.e. sale transaction, refund transaction, void transaction, etc.) OTP – One Time Password, also known as confirmation code: a 6 digits code received by the customer, which he must give to confirm a pending transaction. request – Every call to the Go PayToo system will generate a request, identified by a unique ID. transaction – A transaction is an act of payment. It is always associated to a request. gateway – Refer to the Go.PayToo payment page on which the customer will be redirected when he clicks on the Payment Button.

1.5 Request VS Transaction In the PayToo system, every call to the system will generate a request, identified by a unique ID. This ID must be used as a reference to communicate with PayToo. In the other side, a transaction is a reference to a payment. So, every transaction is associated to a request, but a request has not necessarily a transaction associated. For example, if a request is rejected because of some invalid parameters, no transaction will be created.


So it is important to always refer to the request id, rather than the transaction id. The full request will always be returned in the posts back.

1.6 Documentation Problems If you discover any errors or have any problems with this documentation, please e-mail us by following the instructions below. Please submit a detailed description of the error or problem you experienced. Please include your account user name and submit via email to: [email protected]


2 Payment Button Integration

2.1 Interface Location All the requests should go to the following URL: - for the sandbox https://go.paytoo.info/gateway/ - for the live environment https://go.paytoo.com/gateway/

2.2 Testing / Sandbox At the beginning of the integration process, a test account will be provided on a “sandbox”. You will be plugged on the live environment only after several successful tests on the sandbox. On the sandbox, the OTP to validate wallet transactions is always 888888.

2.3 A Quick Start For the payment button to work you must create a form using the POST method and all the parameters you send should use hidden fields. Here is an example: <form action="https://go.paytoo.info/gateway" method="post"> <input type="hidden" name="merchant_id" value="12345678" /> <input type="hidden" name="amount" value="5.00" /> <input type="hidden" name="currency" value="USD" /> <input type="hidden" name="order_ref" value="1234" /> <input type="hidden" name="order_description" value="Order number 1234" /> <input type="image" name="submit" value="Pay with PayToo" src="https://go.paytoo.info/files/paytoo/images/button/gateway/S1_1.png" /> </form> The example above is the shortest version of the payment button that you can use. The item name is " Order number 1234" and its price is 5.00. The payment will go to your account if you replace 12345678 above with your Go.PayToo Merchant ID. Go.PayToo offers many more options that you can send in this form. Please see the list of parameters below for advanced usage.


2.4 Parameters list Below you can see an explanation of all the parameters that can be used for payment buttons:

Parameter Name Required Description merchant_id YES Your 8 digits Go.PayToo Merchant ID

amount YES The total amount requested

currency YES The currency of the transaction (always the same currency as your Go.PayToo Merchant Account).

order_ref YES A unique reference for this transaction

order_description NO The transaction description (will be echo to the customer)

sub_account_id NO An optional sub account ID to group your transactions

hash NO Checksum of the request (see chapter 5)

user[email] NO Customer’s email address

user[firstname] NO Customer’s first name

user[lastname] NO Customer’s last name

user[address] NO Customer’s address

user[zipcode] NO Customer’s postal code

user[city] NO Customer’s city

user[country] NO Customer’s country

user[state] NO Customer’s state (for US resident only)

user[cellphone] NO Customer’s cell phone (with international prefix)

recurring[enabled] NO Enable recurring payment/subscription. Must be set to 'yes' in order to enable recurring payment.

recurring[amount] NO The total amount requested for all recurring payments.

recurring[cycles] NO Number of cycles/periods (>1 or 0 for unlimited)

recurring[periodicity] NO Recurring period (weeks, months, years)

recurring[start date] NO Date of the first transaction (format is YYYY-MM-DD)

recurring[hash] NO Checksum of the recurring request (see chapter 5)

completed_url NO The URL where the user will be redirected to after he completes the payment. On the last step of the payment there is a button labeled "Return" and when the user clicks this button he is redirected to this URL. If provided, this parameter override the value set in your settings (see chapter 3.3).

cancelled_url NO The URL where the user will be redirected to after he cancels the payment. On the cancel step of the payment there is a button labeled "Return" and when the user clicks this button he is redirected to this URL. If provided, this parameter override the value set in your settings (see chapter 3.3).


Parameter Name Required Description rejected_url NO The URL where the user will be redirected to after the

payment has been rejected. On the rejection page of the payment there is a button labeled "Return" and when the user clicks this button he is redirected to this URL. If provided, this parameter override the value set in your settings (see chapter 3.3).

esign_url NO The URL where the user will be redirected to when his payment is pending for signature (see chapter 7.3). On the last step of the payment there is a button labeled "Return" and when the user clicks this button he is redirected to this URL. If provided, this parameter override the value set in your settings (see chapter 3.3).

3 Global settings You can define some global settings of the payment page in your Go.PayToo account. Once logged, go into “Account Settings”.

3.1 Customization Here you can personalize the name and URL of your website, and you can also provide the logo of your website/company, as an URL. We heavily recommend using an https URL for the logo in order to avoid a security warning from the browser.

3.2 Customer Support After a payment, and in the emails that we send to the customer, we always include a way to contact our customer support. If you prefer to use your own customer support, you can set your own info here.


3.3 Return URLs The default URLs where the user will be redirected to after payment, if not provided in the request parameters. On the last step of the payment there is a button labeled "Return" and when the user clicks this button he is redirected to this URL.

Meaning of these URLs:

- success: when payment has been accepted - cancelled: when the customer has cancelled the payment by himself - rejected: when the payment has been rejected - pending: when the payment is pending for manual action (signature or verification)


3.4 Automatic notifications You can specify an URL and an email address on which you want to receive automatic notifications when the status of your transaction is updated.

Please see chapter 4 for more details of IPN.

3.5 Hash key The hash key is used to calculate the hash tag, you can define your hash key here and choose if PayToo must check the hash tag for all incoming request from you.

Please see chapter 5 for more details.

4. Post back and IPN

4.1 Definitions

4.1.1 Postback A Postback is the term to refer to data that has been posted back by the client to the server. For example when you submit data on an HTML form via your web browser (which is the client here), when you submit that form, a Postback to the server occurs. Effectively, the web browser, with its HTTP request for the specified file, will also have the Postback data. If you have a PHP application, by using the $_POST (or $_REQUEST to refer to $_POST, $_GET and $_COOKIE in one), you can retrieve the Postback data within your PHP applications.


It is important to understand that the Postback will only occurs if you provide an URL for the corresponding event AND if the customer click on the « Return » button when he is on the Go.PayToo Payment Gateway page.

4.1.2 Instant Payment Notification (IPN) Instant Payment Notification (IPN) is a message service that notifies you of events related to PayToo transactions. You can use it to automate back-office and administrative functions, such as fulfilling orders, tracking customers, and providing status and other information related to a transaction. IPN notifies you when an event occurs that affects a transaction. Typically, these events represent various kinds of payments; however, the events may also represent authorizations, Fraud Management Filter actions and other actions, such as refunds, disputes, and chargebacks. IPN is a message service that PayToo uses to notify you about events. These events include the following:

- Payments, including Micro Payment and recurring or indirect payments - Refunds - Rejected request/transaction

In many cases, the action that causes the event, such as a payment, occurs on your website; however, your website is not the only source of events. In many cases, events can be generated by the PayToo Gateway, the PayToo API, PayToo agents or by the customer itself. You detect and process IPN messages with a listener, sometimes called a handler, which is a script or program that you write. It waits for messages and passes them to various back-end or administrative processes that respond the messages. The actions to take when your listener is notified of an event are specific to your needs. Examples of the kinds of actions you might take when your listener receives an IPN message include the following:

- Trigger order fulfillment or enable media downloads when a check clears or a payment is made

- Update your list of customers - Update accounting records - Create specialized “to do” lists based on the kind of event

The difference with the Postback is that you will “always” receive the IPN, no matter what the customer does after the transaction. This way IPN enables you to automate your response to events.

4.2 « When I will receive what and where ? » The most frequently asked question when a merchant integrates Go.PayToo Payment Button is « When and where I will receive the post back and when I will receive the IPN ?».

The answer is « For the ‘where’, it depends on your global settings and the parameters sent with the payment button, for the ‘when’, post back is sent on customer action, IPN is sent automatically. ».


More generally, the post back is sent when the customer clicks on the "Return" button once the payment is completed, rejected or pending. And the IPN is sent automatically on the URL specified in your settings (this cannot be overridden in the request), when the status of your transaction is updated (it can be accepted, rejected, pending or refunded).

There is no IPN for pending transaction, and no Postback, neither IPN, for cancelled transactions. It is important to understand that the IPN is a server-to-server communication, and that it does not require an action made by the customer, and it cannot be altered. This way, the IPN is more reliable than the post back. Further more, you will always receive the IPN but the post back depends of the customer, as he must click on a button. So, if you have to process automatically the transactions, we encourage you to use the IPN in order to do so, and to only use the post back for informational usage. Also note that, depending of the network and of the customer, you can sometime receive the post back before the IPN, and vice versa.


4.3 Data sent in the post back and the IPN The data sent are the same in the post back and in the IPN. This data are sent in a POST array. In PHP, for example, you will access these data using $_POST[‘MerchantApiResponse’]. For a better understanding, we can represent these data as an HTML form, like the one below. <form method="post"> <input type="hidden" name="MerchantApiResponse[status]" value="OK"> <input type="hidden" name="MerchantApiResponse[request_id]" value="11122"> <input type="hidden" name="MerchantApiResponse[request_status]" value="completed"> <input type="hidden" name="MerchantApiResponse[tr_id]" value="22782"> <input type="hidden" name="MerchantApiResponse[sub_account_id]" value="8888"> <input type="hidden" name="MerchantApiResponse[ref_id]" value="1234"> <input type="hidden" name="MerchantApiResponse[msg]" value=""> <input type="hidden" name="MerchantApiResponse[info]" value=""> <input type="hidden" name="MerchantApiResponse[phone_number]" value="[email protected]"> <input type="hidden" name="MerchantApiResponse[w_number]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][request_id]" value="11122"> <input type="hidden" name="MerchantApiResponse[PaytooRequest][tr_id]" value="22782"> <input type="hidden" name="MerchantApiResponse[PaytooRequest][user_id]" value="6095"> <input type="hidden" name="MerchantApiResponse[PaytooRequest][ref_id]" value="1234"> <input type="hidden" name="MerchantApiResponse[PaytooRequest][sub_account_id]" value="8888"> <input type="hidden" name="MerchantApiResponse[PaytooRequest][date]" value="2014-03-27 13:19:35"> <input type="hidden" name="MerchantApiResponse[PaytooRequest][refund_date]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][expiration]" value="2014-03-28 01:19:35"> <input type="hidden" name="MerchantApiResponse[PaytooRequest][statement_id]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][refund_statement_id]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][method]" value="gateway"> <input type="hidden" name="MerchantApiResponse[PaytooRequest][type]" value="small"> <input type="hidden" name="MerchantApiResponse[PaytooRequest][is_pre_auth]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][is_recurring]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][is_a_cycle]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][recurring_id]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][currency]" value="USD"> <input type="hidden" name="MerchantApiResponse[PaytooRequest][amount]" value="5.00"> <input type="hidden" name="MerchantApiResponse[PaytooRequest][description]" value="Order number 1234"> <input type="hidden" name="MerchantApiResponse[PaytooRequest][addinfo]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][status]" value="completed"> <input type="hidden" name="MerchantApiResponse[PaytooRequest][status_infos]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][recurring_amount]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][recurring_cycles]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][recurring_period]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][recurring_start]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][recurring_end]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][recurring_status]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][recurring_info]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][transaction]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][card_present]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][employee_id]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][location_id]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][firstname]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][lastname]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooRequest][email]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_id]" value="22782"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_type]" value="wallet2merchant"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_from_type]" value="yackie"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_from_id]" value="01208100"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_from_currency]" value="USD"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_to_type]" value="merchant">


<input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_to_id]" value="12345678"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_to_currency]" value="USD"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_requested_original]" value="5.0000"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_requested_currency]" value="USD"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_amount_requested]" value="5.0000"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_amount_transfered]" value="5.0000"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_amount_total_cost]" value="5.0000"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_amount_refunded]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_change_rate]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_fees]" value="0.0000"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_fees_currency]" value="USD"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_fees_type]" value="fixed"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_fees_rate_fixed]" value="0.0000"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_fees_rate_percent]" value="0.0000"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_fees_level]" value="2"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_date_created]" value="2014-03-27 13:19:35"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_date_updated]" value="2014-03-27 13:19:42"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_date_completed]" value="2014-03-27 13:19:42"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_date_refunded]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_notif_sender]" value="email"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_notif_receiver]" value="none"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_status]" value="completed"> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][tr_status_msg]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooTransaction][pay_infos]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooAccount][user_id]" value="6095"> <input type="hidden" name="MerchantApiResponse[PaytooAccount][wallet]" value="01208100"> <input type="hidden" name="MerchantApiResponse[PaytooAccount][currency]" value="USD"> <input type="hidden" name="MerchantApiResponse[PaytooAccount][registered_phone]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooAccount][max_pin]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooAccount][sim_phonenumber]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooAccount][prepaidcard]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooAccount][email]" value="[email protected]"> <input type="hidden" name="MerchantApiResponse[PaytooAccount][gender]" value="m"> <input type="hidden" name="MerchantApiResponse[PaytooAccount][firstname]" value="Cedric"> <input type="hidden" name="MerchantApiResponse[PaytooAccount][middlename]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooAccount][lastname]" value="Mayol"> <input type="hidden" name="MerchantApiResponse[PaytooAccount][address]" value="Some street "> <input type="hidden" name="MerchantApiResponse[PaytooAccount][city]" value="Fort Lauderdale"> <input type="hidden" name="MerchantApiResponse[PaytooAccount][zipcode]" value="33301"> <input type="hidden" name="MerchantApiResponse[PaytooAccount][country]" value="US"> <input type="hidden" name="MerchantApiResponse[PaytooAccount][state]" value="FL"> <input type="hidden" name="MerchantApiResponse[PaytooAccount][phone]" value="33679555985"> <input type="hidden" name="MerchantApiResponse[PaytooAccount][level]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooAccount][question1]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooAccount][answer1]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooAccount][question2]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooAccount][answer2]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooAccount][question3]" value=""> <input type="hidden" name="MerchantApiResponse[PaytooAccount][answer3]" value=""> <input type="hidden" name="MerchantApiResponse[hash]" value="def2e614513fc7cf0d85c97167fb10ab"> </form>


4.4 MerchantApiResponse Below are all the parameters of the post back and IPN explained

4.4.1 Root data

Propertie Type Description status string Has the value "OK" for successful, "PENDING" for pending

transaction or "ERROR" for failure request_id int Request ID is the unique ID of the request

request_status string Request status, it can be 'pending', 'accepted', 'rejected', 'cancelled', 'completed', 'refunded'

tr_id int Transaction ID is the unique ID of transaction associated to the request

sub_account_id string Sub Account ID for which you have associated this request

ref_id string Reference ID is the unique ID you've passed for this request

msg string Message

info string Additional information

phone_number string * The phone number reserved for a micro payment in case of a Micropayment response * The customer registered phone number or simcard phone number in all other case

w_number string Wallet number of the associated PayToo account

PaytooTransaction PaytooTransactionType PayToo Transaction information associated to a request/transaction

PaytooAccount PaytooAccountType PayToo Account information associated to a request/transaction

PaytooRequest PaytooRequestType PayToo Request with full information

hash string Hash code to check the authenticity of the IPN response – not filled with the API


4.4.2 PaytooTransactionType Propertie Type Description tr_id int Internal unique ID in the PayToo system for this transaction

tr_type string Transaction type. Possible values are: "wallet2partner" or "partner2wallet"

tr_from_type string Transaction source type. Usually "wallet"

tr_from_id string Transaction source id. Usually the wallet number

tr_from_currency string The main currency of the source account

tr_to_type string Transaction destination type. Usually "merchant"

tr_to_id string Transaction destination id.

tr_to_currency string Transaction destination currency.

tr_requested_original float Transaction original requested amount

tr_requested_currency string Transaction original requested currency

tr_amount_requested float Transaction converted requested amount (used currency is defined in $tr_from_currency)

tr_amount_transfered float Transaction converted transferred amount (used currency is defined in $tr_to_currency)

tr_amount_total_cost float Transaction total cost including fees (used currency is defined in $tr_from_currency)

tr_amount_refunded float Transaction refunded amount (used currency is defined in $tr_from_currency)

tr_change_rate float Transaction change rate from $tr_requested_currency and the $tr_from_currency if not the same

tr_fees float Transaction fees that generally apply to the sender ($tr_from_id)

tr_fees_currency string Transaction fees currency (generally the same as $tr_from_currency)

tr_fees_type string Type of fees ('fixed', 'percent', 'both')

tr_fees_rate_fixed float Fixed part of the fees

tr_fees_rate_percent float Variable part of the fees

tr_fees_level int User level applied to the fees and limits (only apply when 'from' is a PayToo wallet)

tr_date_created string Transaction creation date

tr_date_updated string Transaction last update

tr_date_completed string Transaction processing date

tr_date_refunded string Transaction refund date

tr_notif_sender string Type of notification sent to the sender

tr_notif_receiver string Type of notification sent to the receiver

tr_status string Transaction status ('waiting', 'rejected', 'played', 'refunded', 'loaded', 'confirmed', 'completed', 'cancelled')

tr_status_msg string Transaction status additional information


4.4.3 PaytooAccountType Properties Type Mandatory Description user_id int Internal unique ID in the PayToo system

wallet string PayToo Wallet number

currency string Wallet currency.

registered_phone string Yes, if no email

PayToo registered phone number.

max_pin string PayToo Max PIN. PIN used for the cellphone registration (read-only).

email string Yes, if no cellphone

Email address – UNIQUE per customer.

gender string Gender: 'M' for Male / 'F' for Female.

firstname string Yes First name

middlename string Middle name

lastname string Yes Last name

address string Yes Address

city string Yes City

zipcode string Yes Zip/Postal code

country string Yes Country code (2 chars)

state string Yes, for US State code (2 chars / for US citizen only)

phone string Phone number. Used for contact purpose only.

birthday string Birthday. Format: YYYY-MM-DD

question1 int First security question (cf. documentation for possible values).

answer1 string Answer for the first security question (max 60 chars).

question2 int Second security question (cf. documentation for possible values).

answer2 string Answer for the second security question (max 60 chars).

question3 int Third security question (cf. documentation for possible values).

answer3 string Answer for the third security question (max 60 chars).

level int User wallet level


4.4.4 PaytooRequestType Propertie Type Description request_id integer Internal unique ID in the PayToo system for this request

tr_id integer Internal unique ID in the PayToo system for the associated transaction

user_id integer Internal unique ID of a customer in the PayToo system

ref_id string Your reference ID

sub_account_id string Sub Account ID

date string Date of the request (format: YYYY-MM-DD HH:MM:SS)

refund_date string Refund date of the request (format: YYYY-MM-DD HH:MM:SS)

expiration string Expiration date (format: YYYY-MM-DD HH:MM:SS)

statement_id integer Statement ID (if transaction has been settled to the merchant)

refund_statement_id integer Refund statement ID (if transaction has been refunded on a statement)

method string Request method (api, gateway, terminal)

type string Transaction type. Possible values are: "micro", "small", "regular", "credit card"

is_pre_auth boolean True if the request has been initiated as a pre-auth transaction

is_recurring boolean True if the request has been initiated as a recurring transaction

is_a_cycle boolean True if the request is part of a recurring cycle

recurring_id integer Main/parent recurring request ID (filled if $is_a_cycle is true)

currency string Request currency

amount float Original requested amount or Initial amount for recurring request

description string Description

addinfo string Additional info that you have provided

status string Request status

status_infos string Additional info’s on the status

recurring_amount float Recurring amount

recurring_cycles integer Number of recurring cycles

recurring_period string Recurring period ('days', 'weeks', 'months', 'years')

recurring_start string Recurring payment start date (format: YYYY-MM-DD HH:MM:SS)

recurring_end string Recurring payment end date (format: YYYY-MM-DD HH:MM:SS)

recurring_status string Recurring status. Possible values are: "pending", "open", "stopped", "terminated"

recurring_info string Recurring additional info

transaction PaytooTransactionType Associated transaction - Only filled with function GetRequests()


5 Hash sum / Checksum

5.1 Purpose A checksum or hash sum is a small-size datum computed from an arbitrary block of digital data for the purpose of detecting errors or modifications that may have been introduced during its transmission. To secure your payments, Go.PayToo offers 2 different checksums:

- one for the Payment Button request : you will have to calculate this hash and send it into your Payment Button.

- Another one in the Postback and the IPN: you will have to calculate it, and to compare with the one provided in the response.

Even if it is not mandatory to calculate and verify the checksums, PayToo heavily encourage you to use them.

5.2 Key and settings In order to have and to calculate the checksum, you must first define a hash key in your settings (see chapter 3.5). This hash key is like a password and must never be communicated in clear text.

Please use only alphanumeric characters in your key, special characters may produce invalid hashes.

For the Payment Button requests, if you want that Go.PayToo checks your hash, you must activate this function in your settings (see chapter 3.5). If this setting is not set to « Yes », Go.PayToo will ignore the « hash » parameter, even if it is present.

5.3 Formula for the « Hash » in the Payment Button request

5.3.1 Single payment (or initial payment for subscription) The calculation of the Payment Button hash requires only 5 parameters. The hash can be found by a md5sum of a string formed by concatenating the following variables (in the given order and without any other characters or spaces):

- merchant_id - amount - currency - order_ref - your private key


For example, in PHP, you will use the following code:

$hash_key = ‘yourhashkey’ ; $hash = md5($merchant_id.$amount.$currency.$order_ref.$hash_key);

Once calculated, this hash should be placed in the ‘hash’ parameter.

<input type="hidden" name="hash" value="< ?pup echo hash ; ?>" />

5.3.2 Recurring payment / Subscription In addition to the « single payment »hash above, if you want to make a recurring payment, you’ve to calculate a second hash with the parameters specific to this subscription.

This specific hash can be found with the same method but with these parameters instead : - recurring amount - cycles - periodicity - start_date - your private key


$hash_key = ‘yourhashkey’ ; $hash = md5($recurring['amount'].$recurring['cycles'].$recurring['periodicity'].$recurring['start_date'].$hash_key);

Once calculated, this hash should be placed in the ‘recurring[hash]’ parameter.

<input type="hidden" name="recurring[hash]" value="< ?php echo hash ; ?>" />

5.4 Formula for the « Hash » in the Postback and in the IPN The hash is present in the root of the MerchantApiResponse ($_POST[‘MerchantApiResponse’][‘hash’] using PHP) The calculation of this hash requires only 5 parameters. The hash can be found by a md5sum of a string formed by concatenating the following variables (in the given order and without any other characters or spaces):

- request_id - amount - currency - status - your private key



$mykey = 'yourprivatekey-notyourpassword!'; $request = $_POST[‘MerchantApiResponse’’][‘PaytooRequest’];

$myhash = md5($request[‘request_id’]. $request[‘amount’]. $request[‘currency’]. $request[‘status’].$mykey);

if ($myhash == $_POST[‘MerchantApiResponse’’]['hash']) echo "The request is valid";


6 Code Samples

6.1 HTML The example below is the more complete version of the payment button that you can use, with all possible parameters. <form action="https://go.paytoo.info/gateway" method="post">

<input type="hidden" name="merchant_id" value="12345678" />

<input type="hidden" name="amount" value="5.00" />

<input type="hidden" name="currency" value="USD" />

<input type="hidden" name="order_ref" value="1234" />

<input type="hidden" name="sub_account_id" value="8888" />

<input type="hidden" name="order_description" value="Order number 1234" />

<input type="hidden" name="hash" value="" />

<input type="hidden" name="user[email]" value="[email protected]" />

<input type="hidden" name="user[firstname]" value="John" />

<input type="hidden" name="user[lastname]" value="Doe" />

<input type="hidden" name="user[address]" value="200 SW 1st Avenue" />

<input type="hidden" name="user[zipcode]" value="33301" />

<input type="hidden" name="user[city]" value="Fort Lauderdale" />

<input type="hidden" name="user[country]" value="US" />

<input type="hidden" name="user[state]" value="FL" />

<input type="hidden" name="user[cellphone]" value="" />

<input type="hidden" name="recurring[enabled]" value="yes" />

<input type="hidden" name="recurring[amount]" value="10.00" />

<input type="hidden" name="recurring[cycles]" value="12" />

<input type="hidden" name="recurring[periodicity]" value="months" />

<input type="hidden" name="recurring[start_date]" value="2014-03-28" />

<input type="hidden" name="recurring[hash]" value="" />

<input type="hidden" name="completed_url" value="https://demo.paytoo.com/success/" />

<input type="hidden" name="cancelled_url" value="https://demo.paytoo.com/cancelled/" />

<input type="hidden" name="rejected_url" value="https://demo.paytoo.com/rejected/" />

<input type="hidden" name="esign_url" value="https://demo.paytoo.com/esign/" />

<input type="image" name="submit" value="Pay with PayToo" src="https://go.paytoo.info/files/paytoo/images/button/gateway/S1_1.png" />

</form>


7 Special Notes

7.1 Mandatory fields for customer account on the gateway Due to regulation laws, the customer must provide his first name, last name and full address (city, zipcode, country and state for US customer).

Please also note that he must provide either his cell phone or his email address.

7.2 Restrictions - PO Boxes are not allowed. Transaction created with such address will be rejected.

- No more than 3 transactions of the same kind in one day, and 5 in one week, 10 in the month.

7.3 eSignature For some transactions, PayToo will ask the customer to sign his receipt. For security reason, this process is done apart of the Payment Button.

So when the customer will click on the “Return” button to go back on your shopping cart, his payment will not be completed, it will be “pending” (for signature).

It is why you have the possibility to specify a “pending URL” to redirect the customer on. On this page, you should encourage the customer to finish his Go.PayToo payment by following the process he has received by email and/or SMS. This process is very simple; he just has to click on a link provided in the email/sms and signs the ticket (preferably on a smartphone or a touch device, for a better signature). Once signed, Go.PayToo will review the transaction and if the signature is valid, the payment will be completed and you will receive the IPN. If you have specified a default “Success URL”, a “Return” button (with Postback data) will be proposed to the customer.

7.4 Recurring payment / Subscription If you propose subscriptions on your web site, you can use our recurring’s payments parameters (see parameters list in chapter 2.4). For this kind of payment, the initial payment amount can be different than the coming payments.

This is useful if you want to provide, for example, a trial period at 50% off, or, a first payment that include additional fees.

In order for the recurring payments to take place, the first initial payment must be accepted. It is why, for now, it is not possible to make a free initial payment.

Once the recurring payment is running, you will receive IPN for every payment, and you will have options in your account to cancel it.

To see these options, you will have to find the initial request ID in your transactions.


8 Third parties modules

Lime Light CRM Full documentation on how to configure the PayToo Gateway, click on the link below: http://help.limelightcrm.com/entries/21432858-configuring-paytoo-gateway

Magento Official extension from PayToo Corp. Utilizes Go.PayToo gateway, API and instant notifications to provide you with the ability to do all of your sales management from Magento. It has been extensively tested, is used by many Go.PayToo merchants and is updated with each Magneto community release. http://www.magentocommerce.com/magento-connect/catalog/product/view/id/17243/s/paytoo-payment-gateway-9250/?___store=mc_default_store

OpenCart Integrate OpenCart with GoPayToo Payment Gateway

OpenCart Settings 1. Download the GoPayToo payment module for Open Cart here:

http://www.paytoo.com/files/dist/opencart-gopay2-gateway.zip 2. Extract the ZIP file on your computer

3. Upload the files/folders at the root of your OpenCart installation using your FTP client.


4. Sign in to your OpenCart admin.

5. Click **Extensions** in the menu, and **Payments** submenu. 6. Under **GoPayToo** click **Install** and then click **Edit**.

7. Enter your **GoPayToo Merchant Account ID**.

8. Enter your **Hash Key**.

9. Select **No** under **Test Mode** (Unless you are testing in the GoPayToo Sandbox).

10. Select an option for **Order status while pending for signature** (usually 'Processing')

11. Select an option for **Order status when paid** (usually 'Processed')

12. Select **Enabled** under **Status**.

13. Save your changes.

GoPayToo Settings 1. Sign in to your GoPayToo account.

2. Click the **Account Settings** link.


3. Under **Transactions Notifications** enter your Hash Key. (Must be the same value entered in your OpenCart admin).

4. Set the **NOTIFICATION URL** to

http://www.yourstore.com/index.php?route=payment/gopaytoo/callback (Replace http://www.yourstore.com with the actual URL to your store).

5. Click **Save Changes**.

Please feel free to contact GoPayToo directly with any integration questions.


9 Administration The administrative merchant front end of PayToo is located at: http://go.paytoo.com/ (or http://go.paytoo.info for the sandbox). Just sign in with the merchant details you have obtained from us. The main features are:

− Transaction monitoring − Refunding transactions

− Viewing transaction details


− Manual processing via virtual terminal

− Request a payment from anyone

10 Disclaimer © 2009-2014 PayToo. All rights reserved. PayToo and the authors assume no liability for errors or omissions, or for damages, resulting from the use of this guide or the information contained in this guide.

Documents

Payment Button Integration Guide · GoPayToo – Payment Button Integration Guide 2 5 Hash sum / Checksum ..... 18