1.7. M2_Payment

1.7. M2_Payment
Prev	1. Applications (Apps)	Next

Accepting payments in a Moski2.net driven Web site is terribly simple. You get a payment driver and run the magical payment wizard - here's an example for clearing a payment of GBP 465.25:

<?php

$opts = array(
              'language' => 'en',
              'ordernumber' => 1234,
              'amount' => '465.25',
              'currency' => 'GBP',
              'okmsg' => 'Thanks for your order. Your order number is
                          %%ORDER_NUMBER%% and your transaction reference is
                          %%TRANSACTION_ID%%.',
              'errormsg' => 'An error ocurred when processing your payment.
                             Please go back and try again.',
              'submitButtonLabel' => 'Go to payment'
             );

$driver = M2_Payment_Client::getDriver();
echo $driver->getPaymentWizard($opts);

?>

The code above will take the user through these steps:

A button saying 'Go to payment' is displayed.
When clicked, the user is redirected to a payment gateway.
At the payment gateway he enters his card data and the card is validated against a clearing house.
The payment gateway talks to the Moski2Engine handing over the result from the clearing house, and Moski2.net updates the payment status in the administrative pages.
The user is now redirected back to your page.
Depending on how the transaction went, okmsg or errormsg is displayed.

Here is a walk through of the API:

$driver->getPaymentWizard($options)

The payment wizard is a self contained widget that handles the complete payment flow, displays messages to the customer, redirects him back and forth between your Web site and the payment gateway, sends email confirmations and maintains the payment status in the administrative pages.

$options is an associative array - below are the available keys for the array:

Table 16. Parameters for the payment wizard

Key	Description	Required	Default
`language`	The language used in the payment form at the gateway. Currently supported languages are available at http://doc.quickpay.dk/form.html#appendix-language.	No	The current language of your site or 'en'
`ordernumber`	Your order number. Must be at least four characters long.	No	The next sequential order number on your site. Moski2.net automatically handles this.
`amount`	The amount you wish to charge the customer's card. Use a period to separate decimals.	Yes
`currency`	Currency code. See http://www.xe.com/iso4217.php for a complete list.	Yes
`cardtypelock`	A comma separated list of card types that you wish to limit the customer to choose from. See the complete list of card types at http://doc.quickpay.dk/form.html#appendix-cardtypelock	No
`autocapture`	Whether or not the amount should be withdrawn from the card immediately. Please note that you can only capture the payment for an order when you have shipped the goods - not when the order is placed. Set to 1 to autocapture or 0 not to.	No	`0`
`okmsg`	The message displayed to the customer when the payment is cleared ok. You must provide either this parameter or the `okpage` parameter. You can use two placeholders in your message that will be replaced with corresponding values: `%%ORDER_NUMBER%%` will be replaced with the order number. `%%TRANSACTION_ID%%` will be replaced with the transaction reference from the payment gateway. You must provide either `okmsg` or `okpage`.	Yes/No
`okpage`	A page to redirect to when the customer payment is cleared ok. In this page you will have to parameters available from the query string: `ordernumber`: The order number `token`: A token needed in order to call `getPaymentDetails() and learn the details about the payment.`	Yes/No
`errormsg`	Message to display to the customer if the transaction fails. You can use the same placeholders as in `okmsg`. You must provide either `errormsg` or `errorpage`.	Yes/No
`errorpage`	A page to redirect people to if the transaction fails. You will have available the same parameters in the query string as in an `okpage`.	Yes/No
`cancelmsg`	Message to display to the customer if the user presses the Cancel button in the payment gateway. You can use the same placeholders as in `okmsg`.	No	If neither cancelmsg or cancelpage is supplied, the user will simply be taken back to the payment wizard.
`cancelpage`	A page to redirect people to if the user presses the Cancel button in the payment gateway. You will have available the same parameters in the query string as in an `okpage`.	No
`extraParams`	Any extra parameters you wish to pass to the result pages in the query string, whether it is the same page (using `okmsg` and `errmsg`) or other pages, using `okpage` and `errorpage`. Extra parameters must be passed as an associative array.	No
`customData`	Custom data to store with this payment. This information will not be displayed anywhere in the page, but will be available to you in the administrative pages when browsing payments. You pass the custom data as an associative array. Please do not use multidimensional arrays as the will not be displayed nicely in the administration.	No
`submitButtonLabel`	The text to show on the button taking the customer on to the payment gateway.	No	"Go to payment"
`terms`	The payment terms, shown in a `<textarea>` below the button taking the customer on the payment gateway. Legally you must provide payment terms on the page, so if you don't supply them to this wizard, it is your responsibility to place them elsewhere in the page.	No
`emailNotifications`	An array of emails to send upon successful authorization of the payment. This allows you to automagically send different emails to different recipients when the payment is processed successfully. Each element in the array is itself an array holding at least the required fields from the table below.	No
`callbackUrl`	A URL where you wish to be notified when the payment is processed successfully. Please see Section 1.7.1, “Getting callback” for details.	No
`callbackParams`	Any parameters you wish to send along to the `callbackUrl` when it is notified of a successful payment. The parameters are passed as an associative array.	No

Table 17. Associative array keys when describing emails sent by M2_Payment

Key	Description	Required	Default
`trigger`	The event that will trigger sending this email. Possible values are: `AUTHORIZE` - will send the email when the payment is authorized. `CAPTURE` - will send the email when the payment is captured. `CANCEL` - will send the email if the payment is cancelled. `CREDIT` - will send the email if the payment is credited after being captured. Note If you use autocapture there is obviously little difference between using `AUTHORIZE` and `CAPTURE` as the trigger. Partial capture does not provide a trigger for sending email, whereas partial refund will trigger the sending of any emails with the `CREDIT` trigger.	No	`AUTHORIZE`
`emailTo`	The email address to send a confirmation email to.	Yes
`emailFrom`	The sender address.	No	`[email protected]`
`emailFromName`	The sender name.	No	`[email protected]`
`emailSubject`	The subject of the email. You can use the same placeholders as described in `emailBody` below.	No	'Payment @ yourdomain.tld'
`emailBody`	The body of the confirmation email. You can use these three placeholders in the text: `%%ORDER_NUMBER%%` will be replaced with the order number. `%%TRANSACTION_ID%%` will be replaced with the transaction reference from the payment gateway. In addition, any keys from your `customData` parameter encapsulated in double percentage signs will be replaced with their values. So, if you have a `customData` array looking like this: array( 'customerName' => 'Bill Hanson', 'shippingAddress' => 'Somewhere' ); You can then set `emailBody` to something like this: $options['emailBody'] = "Hi there, %%customerName%%. We will ship your order number %%ORDER_NUMBER%% to this address: %%shippingAddress%%."; Note If your `emailBody` starts with `<html>` the email will be treated as an HTML mail.	Yes

$driver->getPaymentDetails($orderNumber, $token)

This method lets you retrieve the details about a payment. You will typically use this if you implement your own okpage and errorpage (see above), as both parameters are available directly in such pages.

<?php

$driver = M2_Payment_Client::getDriver();
$details = $driver->getPaymentDetails($_GET['ordernumber'], $_GET['token']);

...do stuff with the $details array...

?>

The method returns an associative arrays with the following keys:

Table 18. Return data from getPaymentDetails

Key	Description
`user_id`
`order_number`
`custom_data`
`state`
`auth_time`
`reference_id`
`card_type`
`amount`
`currency`

$driver->getRequestType()

When you add the payment wizard to a Web page, the payment gateway will return to that page after processing the payment. The customer might then be redirected to a different page (if you provided the okpage or errorpage parameters). If this is the case you may not want to run certain parts of the code sitting before the payment wizard, and with this method you can detect whether the request is the gateway returning, and if so, i which mode it is returning.

Possible return values are:

Table 19. Return values from getRequestType

Key	Description
`normal`	The request is not from the payment gateway - most likely this is just your visitor accessing the wizard for the first time.
`success`	The gateway is returning after a successful transaction.
`failure`	The gateway is returning after a failed transaction.
`cancel`	The user pressed the Cancel button in the payment gateway.
`result`	This request stems from the payment gateway, but for some reason Moski2.net could not determine the result of the transaction. In theory this should never happen, but that's only theory ;)

Prev	Up	Next
1.6. M2_Order	Home	1.7.1. Getting callback

1.7. M2_Payment

Note

Note