Merge pull request #31 from paynow/feature/add-test-tokens

add zimswitch and visa mastercard  test tokens

docs/express_checkout_transactions.md

@@ -4,26 +4,30 @@ title: Express Checkout Transactions
 sidebar_label: Express Checkout Transactions
 ---
 
-An express checkout transaction allows the integrator to capture the customers payment method and details inside their application and initiate payment without redirecting the user to Paynow. This is ideal for mobile applications; however, integrators should be aware of PCI DSS requirements for capturing Visa/Mastercard details within their applications.
+An express checkout transaction allows a merchant to capture their customer's payment method and details inside their application and complete payment without redirecting the customer to Paynow.
 
-Express checkout transactions currently support EcoCash, OneMoney, InnBucks, PayGo and Visa/Mastercard payment methods.
-
-For EcoCash and OneMoney, the mobile subscriber specified in the initiate message will have a USSD session pushed to their handset prompting them to enter their mobile wallet PIN number to authorize the transaction (or to cancel the transaction).
+Express checkout transactions currently support the following payment methods:
+- Visa/Mastercard (via tokenized card details)
+- Zimswitch (via tokenized card details)
+- EcoCash
+- OneMoney
+- InnBucks
+- PayGo (e.g. Omari)
 
 ## Initiate an Express Checkout Transaction
 
 To initiate an express checkout transaction, an HTTP POST request should be made to the URL:
 
 [https://www.paynow.co.zw/interface/remotetransaction](https://www.paynow.co.zw/interface/remotetransaction)
 
-The fields below are required in addition to those specified in the [Initiate a Transaction](/docs/initiate_transaction.html) section
+The fields below are required **in addition to those specified in the [Initiate a Transaction](/docs/initiate_transaction.html) section**
 
-| Required For | Field | Data Type | Description |
+| Field | Required For | Data Type | Description |
 | --- | --- | --- | --- |
-| All | method | String | ecocash = Ecocash mobile money **OR** onemoney = OneMoney mobile money  **OR** vmc = Visa Mastercard **OR** innbucks = InnBucks **OR** paygo = PayGo |
-| Mobile Money | phone | String | The subscriber number of the mobile money wallet to be debited |
-| Visa/Mastercard | token | String | A token returned by a previous tokenized transaction. Used to carry out recurring payments without requiring further input from the card holder |
-| Visa/Mastercard | merchanttrace | String | A unique merchanttrace is required for each request to ensure that no duplicate debits are processed in the event of a request timeout or network interruption |
+| method | All | String | The payment method to be used. One of the following:<ul><li>zimswitch</li><li>vmc (Visa Mastercard)</li><li>ecocash</li><li>onemoney</li><li>innbucks</li><li>paygo</li></ul>
+| phone | Mobile Money | String | The subscriber number of the mobile money wallet to be debited |
+| token | Visa/Mastercard/Zimswitch | String | A token returned by a previous tokenized transaction. Used to carry out recurring payments without requiring further input from the card holder |
+| merchanttrace | Visa/Mastercard/Zimswitch | String | A unique merchanttrace is required for each request to ensure that no duplicate debits are processed in the event of a request timeout or network interruption |
 
 ## Important Notes
 ### Integration
@@ -46,6 +50,10 @@ An express checkout request for PayGo will return the following additional value
 - **authorizationqr** - a URL to the QR code for the PayGo transaction (display to customer)
 - **authorizationexpires** - the date and time at which the authorization code will expire in the format d-MMM-yyyy HH:mm (display to customer)
 
-### Visa/Mastercard
+### Visa/Mastercard & Zimswitch
+
+For Visa/Mastercard & Zimswitch **token** transactions, the **merchanttrace** field is required. These transactions will be automatically re-tokenized during the payment and the new token returned in the status update callback message
 
-For Visa/Mastercard **token** transactions, the **merchanttrace** field is required. These transactions will be automatically re-tokenized during the payment and the new token returned in the status update callback message
+> In order to initially get a token for a customer's payment instrument (card) which can be used repeatedly here, the merchant must redirect the customer to Paynow to complete a transaction where `tokenize=true` is specified in the initiate transaction request (see [Initiate Transaction](initiate_transaction.md#tokenize) for more information)
+>
+>The token is returned following a successful card payment (in the Status Update from Paynow) and can be stored by the merchant for future payments for the customer

docs/initiate_transaction.md

@@ -22,7 +22,7 @@ resulturl|String|The URL on the merchant website Paynow will post transaction re
 authemail|String|(*optional*) If the field is present and set to an email address Paynow will attempt to auto login the customers email address as an anonymous user.  If the email address has a registered account the user will be prompted to login to that account.<br/><br/>**N.B. This field is required when initiating [Express Checkout Transactions](express_checkout_transactions.md#initiate-an-express-checkout-transaction)**
 authphone|String|(*optional*) If the field is present and set to a valid mobile phone number, Paynow will attempt to use it as the customers mobile number for the duration of their session
 authname|String|(*optional*) If the field is present, Paynow will attempt to use it as the customers name for the duration of their session
-tokenize|Boolean|(*optional*) If set to true and the customer uses Visa/Mastercard to complete the transaction, the tokenized payment instrument will be returned in the **status update** which can be used for recurring payments without requiring further input from the card holder.<br/><br/> **N.B.** *A merchant may only use this field if permitted to tokenize payment instruments. Contact support@paynow.co.zw to apply for this functionality.*
+<a name="tokenize">tokenize</a>|Boolean|(*optional*) If set to true and the customer uses Visa/Mastercard/Zimswitch card to complete the transaction, the tokenized payment instrument (card) will be returned in the **status update** which can be used for recurring payments without requiring further input from the card holder.<br/><br/> **N.B. A merchant may only use this field if permitted to tokenize payment instruments. Contact support@paynow.co.zw to apply for this functionality.**
 merchanttrace|String|*(optional)* Must be unique per merchant if specified. Can be up to 32 characters in length. Used to check the status of a transaction in the event of a timeout or network error
 status|String|Should be set to “Message” at this stage of the transaction.
 hash|String|Details of Hash generation are provided in the [Generating Hash](generating_hash.md) section.

docs/test_mode.md

@@ -11,7 +11,9 @@ When making payment in test mode select [TESTING: Faked Success] and click [Make
 
 When you are happy that you have completed integration go back to the Integration Keys section and click [Request to be Set Live].  Paynow support will check you have performed at least one successful test transaction and set you to live.  Once you are set live you will begin receive payment from your select Payment Methods.
 
-## Express Checkout (Mobile Money)
+## Express Checkout
+
+### Mobile Money (ecocash, onemoney)
 To use mobile money Express Checkout in test mode, there are four pre-configured mobile numbers that can be used to simulate various results: 
 
 *N.B. The `authemail` field supplied during test mode should match one of the login email addresses for the merchant account being tested.*
@@ -30,4 +32,48 @@ Paynow will send a FAILED status update message 30 seconds after the transaction
 
 > Insufficient Balance – 0774444444
 
-Paynow will immediately fail the transaction during initiation and return an “Insufficient balance” error message.
+Paynow will immediately fail the transaction during initiation and return an “Insufficient balance” error message.
+
+### Visa / MasterCard (vmc)
+
+Using one of the tokens below during a test mode express checkout transaction with *method=vmc*, will yield the associated transaction result:
+
+> Success: {11111111-1111-1111-1111-111111111111}
+
+Paynow will send a SUCCESS status update message 5 seconds after the transaction is initiated.
+
+> Pending: {22222222-2222-2222-2222-222222222222}
+
+Paynow will send a SUCCESS status update message 30 seconds after the transaction is initiated. This simulates the user taking a longer than normal amount of time to authorize the transaction from their handset
+
+> Cancelled: {33333333-3333-3333-3333-333333333333}
+
+Paynow will send a FAILED status update message 30 seconds after the transaction is initiated. This simulates the user cancelling the mobile money transaction.
+
+> Insufficient Balance: {44444444-4444-4444-4444-444444444444}
+
+Paynow will immediately fail the transaction during initiation and return an “Insufficient balance” error message.
+
+The token should be specified as *token=xxxxxxx* in the request to the */interface/remotetransaction* API endpoint, along with any other required fields
+
+### Zimswitch (zimswitch)
+
+Using one of the tokens below during a test mode express checkout transaction with *method=zimswitch*, will yield the associated transaction result:
+
+> Success: 11111111111111111111111111111111
+
+Paynow will send a SUCCESS status update message 5 seconds after the transaction is initiated.
+
+> Pending: 22222222222222222222222222222222
+
+Paynow will send a SUCCESS status update message 30 seconds after the transaction is initiated. This simulates the user taking a longer than normal amount of time to authorize the transaction from their handset
+
+> Cancelled: 33333333333333333333333333333333
+
+Paynow will send a FAILED status update message 30 seconds after the transaction is initiated. This simulates the user cancelling the mobile money transaction.
+
+> Insufficient Balance: 44444444444444444444444444444444
+
+Paynow will immediately fail the transaction during initiation and return an “Insufficient balance” error message.
+
+The token should be specified as *token=xxxxxxx* in the request to the */interface/remotetransaction* API endpoint, along with any other required fields