Back to top
 

Our innovative RaiseNow platform supports ambitious fundraisers to grow their online fundraising. Use solutions for all digital touch points – from SMS donations and mobile phone apps right up to peer-to-peer event fundraising and donation forms. We integrate your email and social media channels and make everything tightly work with your existing fundraising and donor database.

Within this product landscape the RaiseNow team develops a core component which provides a uniform Web service interface for various payment methods, including credit cards, Sofortüberweisung, SMS and PayPal. Furthermore, the interface allows a donor to initiate a credit card recurring donation where the card will be periodically charged.

On merchants’ side, this interface simplifies the integration with the desired payment interfaces, because their software developers only need to program against a single uniform interface and there are tools, support, and documentations available to help them. Through the use of RaiseNow Web Widgets (see chapter about Web Widgets) the integration with the payment interface is made much simpler, so that merchants only need to adapt the graphical look and the texts if necessary. The following services complete the core component of the RaiseNow platform with additional functionalities:

RaiseNow Manager / Widget Configurator

A Web-Administration interface is provided for a central access to our services. Thanks to filtering with faceted search and dashboard functions of the Manager, key characteristic numbers important to the merchants can be extracted and exported to an Excel or CSV file. Moreover, various important settings can be configured through the RaiseNow Manager.

Notification System using Email and Webhook

If needed, transaction details about donations can be made available to a third-party system via email or webhooks. To cope with temporary failures on the third-party system, security and retry mechanisms are in-place to guarantee the integrity of the data transferred. The required webhooks can be configured by the merchants themethselves through the RaiseNow Manager GUI. Go to webhooks section

Donation forms

Donate online simply and quickly with mobile, tablet or desktop computers. Right on your website. Monthly giving solutions available. Go to web widgets section

CRM integration

Fully automated data and process integration with your existing fundraising database. We are ready for Care, FunTrade, iInfo, OM and SextANT.

Social funding

Crowdfunding, peer-to-peer event and corporate fundraising solutions out of the box.

Getting Started 

How to use the Pay API

(this example is not meant to be used in production mode)

<form method="post" action="https://api.raisenow.com/epayment/api/step/pay/merchant/1234567890" >
    success_url<br/><input type="text" name="success_url" value="https://localhost/response.html"/><br/><br/>
    error_url<br/><input type="text" name="error_url" value="https://localhost/response.html"/><br/><br/>
    cancel_url<br/><input type="text" name="cancel_url" value="https://localhost/response.html"/><br/><br/>
    test_mode<br/><input type="text" name="test_mode" value="true"/><br/><br/>
    mobile_mode<br/><input type="text" name="mobile_mode"  value="false"/><br/><br/>
    amount<br/><input type="text" name="amount" value="500"/><br/><br/>
    currency<br/><input type="text" name="currency" value="chf"/><br/><br/>
    language<br/><input type="text" name="language" value="de"/><br/><br/>
    payment_method<br/><input type="text" name="payment_method" value="vis"/><br/><br/>
    <input type="submit"/>
</form>

Submitting the form will result in a redirect to a second form depending on the payment method. In the above snippet the form will be posted to the pay_api (aka API endpoint). This URL ends with your merchant config ID (aka api key). All fields in this form are mandatory and have to be sent to our service for initiating a successful transaction:

  • success_url, error_url, cancel_url define the redirect after a transaction was successful, incorrect or aborted by the user.

  • test_mode defines if a real payment is triggered or not

  • mobile_mode defines if the mobile optimized versions of the forms are returned or not

  • amount defines the amount in Rappen

  • currency defines currency in ISO 4217 Currency Codes

  • language defines the used language in ISO 6391 Codes

  • payment_method defines the payment method, e.g. sms (SMS), vis (Visa), pfc (PostFinance Card), ezs (Payment Slip)

Further details about each parameter can be found in the section parameter.

To finish a payment transaction, the form has to be sent to the payment provider. After the transaction is processed, the request will be redirected either to your success, error or cancel URL. When one of these URLs is called, payment specific parameters are added as query parameter. The most important parameter is the epp_transaction_id which identifies your transaction. Processing of a transaction or requesting the status of a transaction can be done using this epp_transaction_id. Please also visit the Webservice API section for further information. Another important parameter is called epayment_status which defines the status of the transaction (e.g. success, error).


Payment Process Overview

Image

In most cases you do not want to go to a new page to show the payment specific form. Therefore you have to post the infos of your payment within an iframe. The response (form) will then be rendered in this iframe. A javascript class called EPIK supports you to create the iframe and send the parameter to our API endpoint. The following sections explain how to use this javascript class and other tools.

Integrate Credit Card Form via iframe 

Table of Contents:


Introduction: Why integrating credit card form via iframe?

Dear Developer

This documentation is for implementation partners who want to keep the credit card form as part of their checkout or rather their donation form. Or in other words: you would like to have the credit card form visible as part of your form and don’t want to display the credit card form after submitting your own form to our API. If you are interessed in the latter scenario you can omit all credit card relavant fields. and just set the corrsponding payment_method (e.g. vis, eca or amx).

So now let’s start with some background information.

The Payment Card Industry Data Security Standard (PCI DSS) is a widely accepted set of policies and procedures intended to optimize the security of credit, debit and cash card transactions and protect cardholders against misuse of their personal information. The PCI DSS was created jointly in 2004 by four major credit-card companies: Visa, MasterCard, Discover and American Express.

The Payment Card Industry Security Standards Council requires that all companies, including third party service providers, that are involved in the transmission, processing or storage of credit and debit card data, must adhere to the PCI Data Security Standard on an ongoing basis and demonstrate compliance.

For merchants who fully outsourced all cardholder data functions can attest their compliance with a Self-Assessment Questionnaire called “PCI DSS SAQ A”. All cardholder data fully outsourced means that even the credit card form is not hosted on the own website. It has to be provided by RaiseNow within an iframe. The interaction between your form and the provided credit card form is based on Javascript’s postMessage

Don’t worry if you use one of our widgets this is already included.

The following sections explain how to interact with the credit card form if you don’t use a widget.


How to integrate the credit card form?

The credit card from can be added to your page via the following iframe tag

<iframe src="https://api.raisenow.com/epayment/api/step/select-card/merchant/1234567890"></iframe>

Whereas 1234567890 is the API key of the merchant. You can also set width and height of the iframe and provide some other styling to improve the user experience.

It is also possible to apply own styles to the credt card form. Add the query parameter css_url to the URL. The assigned value of the parameter css_url has to be an absolute URL.

<iframe src="https://api.raisenow.com/epayment/api/step/select-card/merchant/1234567890?css_url=https://mydomain.com/mystyles.css"></iframe>

The css will be fetched by via proxy. That means you don’t have to worry about providing your styles over https.

The donate button can be made hidden by adding the query parameter submit_button_visibility with the value false to the credit card URL

https://api.raisenow.com/epayment/api/step/select-card/merchant/1234567890?submit_button_visibility=false

The credit card form can be initiated via HTTP GET or POST. If you would like to integrate the credit card form in the existing checkout form, GET is the preferred HTTP method.

As mentioned above via Javascript’s postMessage we are able to interact with the credit card form.

Because we are not allowed the handle the credit card data we have to create a token from the credit card fields. This token can be submitted to our API without worrying about exposing sensitive data on the own website.

The following actions can be triggerd

  • rnw-creditcardform.create-token

  • rnw-creditcardform.validate-form

The following responses can be received

  • rnw-creditcardform.token-received

  • rnw-creditcardform.data-changed

  • rnw-creditcardform.form-not-valid

  • rnw-creditcardform.create-token-error

  • rnw-creditcardform.form-valid

The message in the postMessage is a json string defined as an object containing a topic string and a data object.

The following example shows the event object for rnw-creditcardform.create-token and how to send the message to the iframe.

event = {
    topic: 'rnw-creditcardform.create-token',
    data: {
        apiKey: '1234567890'
    }
};
document.getElementByTagName('iframe')[0].contentWindow.postMessage(JSON.stringify(event), '*');

Response of the request above can be retrieved as followed:

function receiveMessage(event) {
    if ( ! event.data || typeof event.data != 'string') {
        return;
    }

    var eventData = JSON.parse(event.data);
    var topic = eventData.topic || null;
    var data = eventData.data || {};

    if (topic == null) {
        return;
    }
        
    switch(topic) {
        case "rnw-creditcardform.token-received":
            //Two parameters are available: token and payment method
            console.log(data.paymentMethod);
            console.log(data.token);
            /*
               Add data.paymentMethod as input field 
            payment_method to your form and the token as 
            card_token to your form
            */
            break;
        case  "rnw-creditcardform.data-changed":
            //values of the credit card form have changed.
            console.log(data);
            console.log(data.paymentMethod)
            //if payment method is already defined it will be set
            break;
        case "rnw-creditcardform.form-not-valid":
            console.log("credit card form not valid");
            //data contains an array of input field names which are not valid.
            console.log(data);
            break;
        case "rnw-creditcardform.create-token-error":
            console.log("error while creating the token");
            break;
        case "rnw-creditcardform.form-valid":
            //Credit card form is valid. Go on and submit the form. 
            break;
    }
};
window.addEventListener("message", receiveMessage);

The received event object contains a property data which consists of a json string containing the topicand the corresponding data of the event. In the above example the events are handled within the switch statement. Values available in the event object are defined above.

We recommend to validate the form first and then create the credit card token and last submit your form with parameter payment_method (data.paymentMethod) and card_token (data.token) to our payment API.

Got it? Try it out yourself.


What do I have to do if I already have a credit card form on my page?

So if you already have a credit card form on your page, please remove all credit card related fields. These fields are: cardno, expy, expm, cvv.

Then follow the instructions above how to integrate the credit card form as iframe.

Important: you have to add the payment_method and card_token parameters to your form which will be provided by the event rnw-creditcardform.token-received.


Transaction Search API 

 

This section will show you how to use our Search API to search for transactions. To interact with the search API, we will use curl. Please note that our API only accepts secure communication over TLS 1.1 and TLS 1.2. Moreover, to access our services, you need to authenticate yourself to the site with a username and password using HTTP Basic Authentication.

The service path of the search API is:

/epayment/api/MERCHANTIDENTIFIER/transactions/search

The MERCHANTIDENTIFER is the identifier of the merchant, i.e., the organisation who receives payments made through our Payment API. You will get the API user and the merchant identifier during the onboarding process from RaiseNow.

In the following, we give some examples on how to sort and filter for specific transactions. So, let’s start!

Example 1

First, we try to fetch the latest transactions sorted by created date:

curl -u USERNAME:PASSWORD -g "https://api.raisenow.com/epayment/ \
api/MERCHANTIDENTIFIER/transactions/search? \
sort[0][field_name]=created&sort[0][order]=desc"

Note that the sorting conditions are provided as query parameters. The query parameter sort[0][field_name] with value created specifies the field name which will be used to sort the transactions. The second query parameter defines the sorting order. The values desc and asc are allowed here. You can have multiple dimensions to sort to: Add a new pair of sort[1][field_name] and sort[1][order] with your preferred secondary dimension (have you noticed that the index has to be incremented by one?).

The result for the request above may look like the example below:

{
"result" : {
    "transactions":[
            {
                    "epp_transaction_id": "c2x0f148mz2zw44",
                    "created": "1485844439",
                    "currency_identifier": "chf",
                    "amount": 500,
                    "payment_method_identifier": "EZS",
                    "last_status": "final_success",
            },
            {
                    "epp_transaction_id": "c2rl148sfc0836",
                    "created": "1485840836",
                    "currency_identifier": "chf",
                    "amount": 500,
                    "payment_method_identifier": "EZS",
                    "last_status": "final_success"
            },
            {
                    "epp_transaction_id": "c1y2w148yyfbw72",
                    "created": "1485837232",
                    "currency_identifier": "chf",
                    "amount": 500,
                    "payment_method_identifier": "EZS",
                    "last_status": "final_success"
                                                        
            }
    ],
    "sort": [
          ],
    "additional_info": {
                    "lang": "de",
                    "page": 1,
                    "total_pages": 13,
                    "search_time": "28.2662",
                    "records_per_page": "100",
                    "total_hits": 1321
               },
    "filters": [
            ],
    "facets": [
             ]
    }
}

The field created contains the creation date of the transaction as UNIX timestamp. Under additional_info you see meta information about your request. total_pages, records_per_page, and total_hits are important figures to fetch all remaining transactions.

There are 3 additional useful query parameters available to retrieve the relevant transactions.

  • records_per_page defines how many transactions per page.

  • If the result has more transactions than defined in records_per_page, you can jump to the next/previous page by incrementing/decrementing the current value of page.

  • displayed_fields defines which fields/parameters of the transactions should be returned. It is a comma-separated list, e.g. epp_transaction_id,amount,currency,created

So, try it out and request your own merchant parameters (starting with stored_).

Example 2

Returning all transactions without filtering is of limited use. In this example, we demonstrate how to retrieve transactions with the following filter criteria:

  • test_mode = production

  • last_status = final_success

curl -u USERNAME:PASSWORD -g "https://api.raisenow.com/epayment/api/ \
MERCHANTIDENTIFIER/transactions/search?sort[0][field_name]=created& \
sort[0][order]=desc&filters[0][field_name]=test_mode& \
filters[0][type]&term&filters[0][value]=production& \
filters[1][field_name]=last_status& \
filters[1][type]=term&filters[1][value]=final_success"

Each filter is defined by 3 to 5 query parameters:

  • filters[0][field_name] defines the field.

  • filters[0][type] defines the type of the field. Possible values are: term, range, date_range, and fulltext. term values are not analyzed.

  • filters[0][value] defines the value for term or fulltext filters. The character * and ~ are not allowed as first character of the value.

  • filters[0][from] defines the lower bound for range and date_range filter.

  • filters[0][to] defines the upper bound for range and date_range filter.

Example 3

The last example shows how to fetch transactions within a predefined date range.

curl -u USERNAME:PASSWORD -g "https://api.raisenow.com/epayment/api/ \
MERCHANTIDENTIFIER/transactions/search?sort[0][field_name]=created& \
sort[0][order]=desc&filters[0][field_name]=created& \
filters[0][type]=date_range& \
filters[0][from]=20160915000000&filters[0][to]=20160915235959"

The above request will fetch all transactions from 15th of September 2016 whereas filters[0][from] (e.g. 20160915000000) is defined as UTC timestamp in the format YYYYMMDDhhmmss (four-digit year, two-digit month, two-digit day, zero-padded hour between 00 and 24, zero-padded minute between 00 and 59, zero-padded second between 00 and 59).

E-Payment Integration Kit 

Table of Contents:


Introduction: What is the E-Payment Integration Kit, aka EPIK?

Dear Developer EPIK is a set of templates, code snippets and scripting libraries that make it easier for you to integrate raisenow’s e-payment functionality into a website. EPIK stands for E-Payment Integration Kit. This documentation explains step-by-step how to use it.

Download (not preconfigured version): https://raisenow.com/epik/downloads/. If you would like to have a preconfigured version of EPIK, please contact us via support@raisenow.com.


Requirements

  • jQuery, version > 1.3

  • PHP 5 or Coldfusion 8 (or higher) for SMS Count-Down widget and webhooks


Supported and Tested Browsers

  • Internet Explorer, versions > 7

  • Firefox, versions > 3

  • Opera, versions > 7

  • Safari, versions >= 4

  • Chrome, versions > 13


What does EPIK contain?

  • Configuration file in the config subfolder called parameters.ini

  • PHP demo: contains a lot of code snippets and templates. This should make it easier for you to integrate EPIK

  • A form template is available in the forms subfolder

  • Integration tools: Currently, JavaScript and PHP, Coldfusion are supported


What it is not

  • Off the shelf solution

Paramaters

The following section explains all used parameters in detail. All used parameters are defined in parameters.ini. These parameters are used in the JavaScript and/or PHP part of EPIK. The most important parameters are also available as constants in the JavaScript epik object named CONSTANTS. Parameters are grouped to have them better organized.


Parameter Group: credentials

This group specifies username and password for basic authentication to access the e-payment web services.

Name Value
username XXXXXX
password XXXXXX

Parameter Group: serverside

Parameters to access SMS poll status and recurring payment information from e-payment web services via PHP.

Name Value
transaction_api /epayment/api/transaction/status
This service returns a json object containing all available information about a transaction. Query parameter transaction-id (epp_transaction_id) and merchant-config (merchant_config_id) has to be added.
recurrentpayment_subscription_api /epayment/api/subscription/
authority api.raisenow.com
protocol https
merchant_config_id XXXXXXXXXXX
You will be assigned an id from raisenow.
pay_api /epayment/api/step/pay/merchant/

path to post the e-payment form (ends with merchant_config_id)

Parameter Group: urls

Redirect urls used in JavaScript: error_url, cancel_url and success_url. These are used to redirect the client request after calling raisenow’s e-payment service.

Name Value
error_url http://localhost/epik/demo/error.html
cancel_url http://localhost/epik/demo/cancel.html
success_url http://localhost/epik/demo/success.html
iframe_landing_url http://localhost/epik/demo/landing.html
If iframe_landing_url is defined, EPIK will redirect client to this url and afterwards call the success, error, or cancel url in the parent window from the client side.
pollstatus_url http://localhost/epik/demo/pollstatus.php

query parameters: merchant-config = (merchant_config_id), transaction-id (epp_transaction_id)

Parameter Group: parameters
Name Value
secure_cookie true | false
If true, keeps cookie communication limited to encrypted transmission, directing browsers to use cookies only via secure/encrypted connections.
test_mode true | false

Indicates if it is a real transaction or a transaction to test your implementation. In test mode only test credit card numbers are accepted.

true
Only test credit cards are permitted, no charges (see also Test Credit Cards in DataTrans Technical Implementation guide)

false
Only real credit cards, charged
method POST HTTP method. Currently only POST is supported
mobile_mode true | false

true, if the client is a mobile device
enable_jquery true | false
true if jQuery should be available outside of EPIK
iframe_container iframe_wrapper Indicates where the content of the response should be rendered. In some cases it may be necessary to render the credit card forms in an iframe in order to maintain context consistent with the containing website (see example implementation below).
trigger_event click

change Specifies the event to be triggered if a mandatory input field is manipulated
auto_submit true | false

Indicates if the form should be auto submitted to raisenow’s e-payment service when the submit button of the form is clicked.
language en | de | fr | it
Specifies the language of the labels of raisenow’s forms. Indicates the default language when specified in the parameters.ini file.
iframe_loading_page wait.html
Specifies the html page that is specified in the iframe tag as value of the src attribute. If not defined the current page is added as value of the src attribute.
INFO:

If you have decided to use client-side validation (e.g. jquery validate plugin) you have to set auto_submit to false and call (if form is valid) the following methods

epik.makeReadyToSubmit();

epik.createAndSubmitIFrame();


Parameter Group: PayPal
Name Value
popup true
Specifies if PayPal website will be opened in a popup. If not opened in a popup, the context of the website will be lost. Note: PayPal does not support iframes.

####How to integrate EPIK

Now you should be ready to create your own form and update the templates for your needs. We will now create a basic form. Start by copying the EPIK folder to a place where it can be accessed by your web server. Scripts should be executable. For each scripting/programming language a folder exists which contains utilities and tools for the integration. Please check the source code documentation for details. The folder demo contains examples in PHP and demonstrates how to use EPIK: index.html contains a pure html implementation of EPIK and step2.php shows how to load parameters dynamically via PHP and retrieve form fields from another html page (step1.html). If necessary, split the JavaScript part from the PHP part. Open your JavaScript console in the browser to get output from the EPIK logger. Also exceptions and further information will be displayed on this console. We recommend to use Firebug for Firefox or Developer Tools for Chrome or Safari to integrate EPIK into your website.

1. Update the merchant-specific parameters in the file parameters.ini. merchant_config_id has also to be updated.

2. Create a form or use the template step1.html or step2.php in the demo folder. The file step1.html contains a form for user to enter personal information, such as name, address etc., while step2.php contains the e-payment relevant form fields. The following list shows all e-payment parameters and attributes. If the attribute is required it has to be posted to API endpoint otherwise the transaction fails. The attribute visible/hidden means when you create the form via JavaScript EPIK object (e.g. updateForm) the corresponding fields will be rendered as visible (text) field or as hidden field.

Name Attributes/Description
currency visible, required
amount visible, required
error_url hidden, required
cancel_url hidden, required
success_url hidden, required
payment_method visible, required
sms | vis | eca | amx | din | ezs | es | pfc | pef | pex | dd

Specifies the payment method. In the glossary you find some further details about the acronyms above
test_mode hidden, required
pollstatus_url hidden, optional
mobile_mode hidden, required
language visible, required
transaction_id hidden, optional (deprecated)
msisdn visible, optional
keyword visible, optional
Which SMS keyword should be used for the payment
sid hidden, optional
Shortnumber of a SMS payment
css_url Absolute URL to a CSS file, which should be used to style the credit card form. The CSS file will be loaded via e-payment platform and not directly from the origin. This mechanism should prevent cross-domain problems. Be sure to use absolute URLs within the CSS. If you want to load the CSS directly from origin, add the query parameter use_proxy to the URL and set it to false.
recurring visible, optional
true | false

Indicates a recurring or one-time payment.
recurring_interval visible, optional
L * *
If the payment is a recurring payment, the interval has to be specified. The interval is defined as in crontab except that minutes and hours may not be specified. Additionally, argument L is allowed to specify the last day of a month.
stored_customer_email visible, optional
foo@raisenow.com
If the payment is a recurring payment the customer’s email address has to be defined

3. Create an instance of the EPIK JavaScript object : First argument of the constructor is the id of the form, the second parameter is the options parameter which are read from the parameters.ini. You can instantiate the PHP class EPIKDefaultImpl and call createJavascriptOptionObject to generate the JavaScript option object or add the parameters manually. The following PHP code snippet is an example for how to do this (add this snippet before the html end tag).

<script language="javascript" src="../js/jquery.min.js" type="text/javascript"></script>
<script language="javascript" src="../js/epik.js" type="text/javascript"></script>
<script language="javascript" type="text/javascript">
<?php$epayment = new EPIKDefaultImpl();

//use relative path to the parameters.ini from the location of this file
$params = $epayment-> getParameters("../config/parameters.ini");
echo $epayment-> createJavascriptOptionObject($params, array("urls", "parameters", "paypal"), "myOptions");?>
</script>

<script language="javascript" type="text/javascript">
var epik = new EPIK("epp", myOptions);
epik.beforeSubmit(function() {
    if(epik.getPaymentMethod() == "ezs") { epik.setRefNo((new Date()).getTime()); }
});
</script>

4. Call the updateForm method in order to add all defined parameters as input fields to the form and if available, add values to these input fields. If parameters are defined in parameters.ini and passed as argument to the constructor of the JavaScript EPIK object (see code snippet above), the updateForm method will apply them to the form. If auto_submit is true, updateForm will automatically be called when submitting the form.

5. To validate your form you can call the method validateForm which checks if all mandatory fields are correctly set. If not set, an exception will be thrown, or the logger returns some information about the validation process.

6. if the payment method is a payment slip (“ezs”) a reference number is necessary. There is an interface defined in EPIK.php to generate a reference number. To use this interface you can invoke the method createCompleteRefNo which creates a reference number based on the banking customer identification. The banking customer identification is unique and identifies the bank account to which the money should be transferred. createCompleteRefNo is also available in javascript. Usually, there will be subsequent requests to deliver required information for the payment method specified (e.g. card_holder_name for credit card or msisdn for the SMS payment method). A number of these parameters are required and can already be set at this stage.

Name Description
card_holder_name Card holder name
reqtype value := CAA
This field is necessary to process credit cards directly without using our credit card form.
Notice: Also card_holder_name, cardno, expm, expy, and cvv have to be set to process credit cards directly
cardno credit card number
expm expiry month, 2 digits, e.g. 02 for february
expy expiry year, 2 ditits, e.g. 13 for 2013
cvv Card Verification Code, also known as Security Code
refno Payment slip reference number
payer_line[1-4] Payer lines 1-4 are available. Represents the customer’s address on the payment slip
msisdn Mobile phone number of the customer. If set, SMS transactions can be processed directly.

In the demo, beforeSubmit is used to set the transaction_id (deprecated) and refno. beforeSubmit can be used to register a callback method which will be inserted before the submit is actually executed. If you don’t want to use auto_submit you can register your own submit_handler which will be called when the submit button is pressed or your event triggers the form submission.

7. Now you are ready to test your form. Submit the form and check the output in the console. Make sure that the API endpoint is set in the option object or via JavaScript setApiEndpoint. If the action attribute defined in the form is not equal to the result of getApiEndpoint, EPIK does not send the form to the e-payment service (this could be useful when implementing a multistep form across multiple pages). If you want to get the response from e-payment service in an iframe, you have to define the iframe_container in parameters.ini, which is the id of the DOM element. This DOM element will contain the response of the request.

8. The e-payment service processes the form and redirects either to the defined success, error or cancel url. All parameters are returned as query string parameters of this url. You can access them via PHP or also in JavaScript via getQueryParams or getQueryParamValueFromUrl. The values are also stored in a Cookie. You can access them via getter and setter when instantiating the JavaScript EPIK object and use the same id of the form as argument as above. It is also possible to access the parameters via PHP. Use the EPIKDefaultImpl readFormParameters or readFormMerchantParameters.

9. As said before, all returned values are sent to the error_url, success_url and cancel_url via a GET request (technically, a 302 Found HTTP Redirect Header with the corresponding URL is sent to the client). The exact number of parameters depends on the chosen payment method. Please check the corresponding section in the payment method descriptions for more information about the return values for specific payment methods. The returned values described below are the standard return parameters that apply to all payment methods.

Name Description
parameter_count The total number of return parameters. (including this one)
epayment_status A string defining the status of this transaction.
payment_method The payment method’s identifier used for this transaction.
payment_provider The payment provider identifier used for this transaction.
currency Transaction currency in ISO-Code
amount Amount in cents or smallest available unit of the currency.
epp_transaction_id System-wide unique id generated by the e-payment platform. Can be used to get details of a transaction or refund a transaction).
test_mode Indicating if this was a test only transaction. If datatrans is used as payment provider, datatrans test credit cards can be used (see section Payment Provider-Specific Return Parameters).
language The language used for this transaction
finalstatus_url The merchant’s final status URL for this transaction.

10. If the payment method is SMS, a Count-Down Widget can be displayed on the page. To get the status of the SMS payment you have to implement a web service in PHP that returns the current state. Check pollstatus.php for the server side code. In JavaScript, add the code below.

<script language="javascript" src="../js/jquery.min.js" type="text/javascript"></script>
<script language="javascript" src="../js/epik.js" type="text/javascript"></script>
<script language="javascript" type="text/javascript">
    var epik = new EPIK("epp"),
        trId = epik.getQueryParamValueFromUrl("epp_transaction_id");
    $("#successmessage").text( parseInt(epik.getAmount())/100 + " " + epik.getCurrency() + " via " + epik.getPaymentMethod());
    //show Count-Down-Widget if payment method was SMS
    if(epik.getPaymentMethod() === "sms") {
        epik.waitForConfirmation({
            start_minutes: 59,
            start_seconds : 59,
            container_id : "smscounter",
            epp_transaction_id : trId,
            timedout : function() { alert("time is up");},
            confirmed : function() { alert("confirmed");},
            declined : function() { alert("cancelled");},
            interval : 5
        });
    }
    // Retrieves the mobile number of the customer
    // returned as query parameter
    epik.getQueryParamValueFromUrl("smspayment_msisdn");
    // To delete all data from the processed transaction.
    epik.deleteData();
</script>

There is also the possibility to add your own parameters to the form. We call them merchant parameters. If you want to have these parameters available in the e-payment service, add the prefix “stored_” to the input field. There are predefined merchant parameters for your use. These parameters will be used amongst others in Datatrans transactions. In the following section predefined merchant parameters are shown:

  • stored_customer_title

  • stored_customer_firstname

  • stored_customer_lastname

  • stored_customer_street

  • stored_customer_street2

  • stored_customer_city

  • stored_customer_country (iso country code)

  • stored_customer_zip_code

  • stored_customer_phone

  • stored_customer_fax

  • stored_customer_email


This chapter lists parameters which are returned by a payment provider as a result of processing a payment transaction. These parameters and their possible values are shown below in a tabular form per payment provider respectively payment method.

Datatrans
Name Value
datatrans_upptransaction_id Datatrans unique transaction identifier.
datatrans_status The transaction status returned by Datatrans
datatrans_upp_msg_type The string constant “web”
datatrans_refno The e-payment internal reference number, returned by Datatrans
datatrans_amount The amount that was processed by Datatrans.
datatrans_currency The currency used by Datatrans.
datatrans_pmethod The payment method used for this transaction.
datatrans_reqtype The request type used for this transaction.
datatrans_authorization_code datatrans_authorization_code
datatrans_response_code The authorization response code sent by Datatrans
datatrans_response_message The Datatrans response message text.
datatrans_acq_authorization_code Authorization code returned by credit card issuing bank
datatrans_security_verification Security verification flag (pass/no pass). (Only if Datatrans Security Level 2 is enabled)
datatrans_acq_error_code Contains the error code sent by the acquirer
datatrans_error_code The error code sent by Datatrans
datatrans_error_message The error message sent by Datatrans
datatrans_error_detail A detailed description of the error sent by Datatrans

PayPal
Name Value
paypal_customer_id A unique string that identifies the PayPal buyer
paypal_customer_status The status of the buyer
paypal_customer_salutation The buyer’s salutation as reported by PayPal
paypal_customer_firstname The first name of the buyer as reported by PayPal
paypal_customer_lastname The last name of the buyer as reported by PayPal
paypal_customer_street The buyer’s first address line as reported by PayPal
paypal_customer_street2 The buyer’s second address line as reported by PayPal
paypal_customer_city The buyer’s place of residency as reported by PayPal
paypal_customer_zip_code The buyer’s place of residency zip code as reported by PayPal
paypal_customer_email The email address of the buyer as reported by PayPal
paypal_customer_country_cod The buyer’s country code as reported by PayPal
paypal_currency Currency ISO-Code
paypal_transaction_id A unique string identifying a transaction whithin the PayPal platform
paypal_amount Amount
paypal_transaction_type Type of transaction
paypal_payment_type Indicates whether the payment is instant or delayed
paypal_order_time The timestamp of the order, Date and time are in UTC/GMT format
paypal_payment_status The status of the transaction
paypal_reversal_reason Reason why a transaction has been reversed.
paypal_pending_reason Reason why the transaction is pending
paypal_hold_reason Reason why a transaction is held back

Postfinance Card or Postfinance E-Finance via Datatrans

Postfinance transactions via Datatrans work differently compared to credit-card transactions and require fewer parameters be sent. Instead of displaying a form to enter the credit card information, the e-payment platform will display an iframe containing the forms from Postfinance.


Payment Slip
Name Value
ezspayment_refno Merchant’s reference number, must be at least the banking customer identification number (6 digits)
ezspayment_pdflink
espayment_pdflink
Link to the genereated payment slip

SMS
Name Value
smspayment_status Transaction status sent by the SMS payment provider. A success status does not indicate that the transaction has been settled, but that the Double-Opt-In message has been sent. There is no means to determine at that point of time whether the consumer has received the SMS, or if he has already confirmed or declined the Double-Opt-In. But at the moment the SMS payment provider receives the confirmation or runs into a timeout waiting for a confirmation it calls the finalstatus_url.
smspayment_msisdn Mobile phone number that was used

###API Error Codes

General Errors
Code Description
010001 “Parameter %s missing”
010002 “Parameter %s invalid”
010003 “Url-Parameter step invalid”
010004 “invalid merchantConfigKey”
010005 “missing merchantConfigKey”
010006 “no access to transaction”
010007 “invalid transaction”
010008 “already processed”
010011 “Parameter missing”
010012 “Parameter invalid”
010013 “Parameter %s is not unique”
010021 “configuration error”
010031 “no access to payment_method”
010041 “recurring payment error”
010051 “Invalid refund amount”
010052 “Refund period expired”
010053 “NonRefundable transaction”
010054 “refund error”
010055 “refundToEmail error”
010101 “internal error”

SMS Errors
Code Description
020001 “Parameter %s missing”
020002 “invalid amount for sms payments”
020003 “sms payment error”

EZS Errors
Code Description
030001 “ezs payment error”

Datatrans Errors
Code Description
040999 “datatrans: General error”
040072 “datatrans: cannot be credited, amount not valid”
040098 “datatrans: external datatrans error”
041001 “datatrans: missing required parameter”
041002 “datatrans: not valid parameter format”
041003 “datatrans: value of parameter not found”
041004 “datatrans: invalid card number”
041006 "datatrans: card expired"v
041007 “datatrans: access denied by sign control”
041008 “datatrans: merchant disabled by Datatrans”
041009 “datatrans: payment method init error”
041201 “datatrans: system error”
041400 “datatrans: invalid card number”
041401 “datatrans: invalid expiration date”
041402 “datatrans: expired card”
041403 “datatrans: transaction declined by card issuer”
041404 “datatrans: card blocked”
041405 “datatrans: amount exceeded”
043000 “datatrans: denied by fraud management”
043001 “datatrans: ip denied by global fraud management”
043002 “datatrans: ip denied by merchant fraud management”
043003 “datatrans: CC number declined by global fraud management”
043004 “datatrans: CC number declined by merchant fraud management”
043005 “datatrans: denied by fraud management”
043006 “datatrans: denied by fraud management”
043011 “datatrans: denied by fraud management”
043012 “datatrans: denied by fraud management”
043013 “datatrans: denied by fraud management”
043014 “datatrans: denied by fraud management”
043015 “datatrans: denied by fraud management”
043016 “datatrans: denied by fraud management”
043021 “datatrans: declined by country filter”
043022 “datatrans: country declined by country filter”
043023 “datatrans: declined by country verification”
043024 “datatrans: declined by country verification”
043025 “datatrans: country declined by group country filter”
043031 “datatrans: declined due to response code 02”
043041 “datatrans: declined due to post error”
043051 “datatrans: declined due to country verification check”
043061 “datatrans: declined due to unique refno check”
043071 “datatrans: declined due to AVS check”
049999 "datatrans: undefined error

PayPal Errors
Code Description
0510001 “paypal internal error”
0510002 “Authentication/Authorization Failed”
0510004 “Transaction refused because of an invalid argument”
0510007 “Permission denied”
0510009 “Transaction refused”
0510011 “Invalid transaction id”
0510402 “Authorization only is not allowed for merchant.”
0510404 “Invalid transaction id”
0510405 “Invalid transaction id”
0510407 “Transaction refused because of an invalid argument”
0510408 “Express Checkout token is missing.”
0510409 “You’re not authorized to access this info.”
0510410 “Invalid token.”
0510411 “This Express Checkout session has expired.”
0510412 “Duplicate invoice”
0510413 “Transaction refused because of an invalid argument.”
0510414 “Transaction refused because of an invalid argument.”
0510415 “Transaction refused because of an invalid argument.”
0510416 “Transaction refused because of an invalid argument.”
0510417 “Transaction cannot complete.”
0510418 “Transaction refused because of an invalid argument.”
0510419 “Express Checkout PayerID is missing…”
0510420 “Transaction refused because of an invalid argument.”
0510425 “Express Checkout has been disabled for this merchant.”
0510432 “Transaction refused because of an invalid argument.”
0510433 “Transaction refused because of an invalid argument.”
0510434 “Transaction refused because of an invalid argument.”
0510436 “Transaction refused because of an invalid argument.”
0510437 “Transaction refused because of an invalid argument.”
0510438 “Transaction refused because of an invalid argument.”
0510439 “Transaction refused because of an invalid argument.”
0510440 “Transaction refused because of an invalid argument.”
0510471 “Transaction refused because of an invalid argument.”
0510472 “Transaction refused because of an invalid argument.”
0510537 “Risk Control Country Filter Failure.”
0510538 "Risk Control Max Amount Failure.

Recurring Payments 

 

Raisenow’s e-payment web services allow customers to set up recurring payments. To set up a recurring payment these parameters must be defined:

recurring (true|false)
recurring_interval (defined as a cron expression)
stored_customer_email

Currently only payments by credit cards are supported for recurring payments (verify that when recurring is true, the correct payment method is selected). The customer’s email address is used to send a confirmation email containing information about the customer’s recurring payment details such as information on how to unsubscribe, the payment interval, or the masked credit card number. Additionally, webhooks can be defined which will be invoked upon certain events that occur in the context of recurring payments. This allows merchants to create customized email notifications and information web pages about the recurring payment status of the customer. When raisenow configures your e-payment account, please inform raisenow if you want to use webhooks. Otherwise, the default raisenow email notifications will be sent. Read more about webhooks in the next chapter. The following list defines which webhook is called on which event.

  • subscription_subscribed_webhook will be called when a customer has subscribed, namely has set up a recurring payment

  • subscription_charged_webhook will be called each time a customer is charged

  • subscription_renewed_webhook will be called each time a customer has renewed the payment method details, such as credit card number

  • subscription_cancel_webhook Will be called when a customer cancels a recurring payment.

  • subscription_error_webhook will be called each time an error occurred during the recurring payment execution

To help you better understand recurring payments, an example is given below. Example: Charge monthly at end of month In addition to the mandatory parameters of a non-recurring payment, the following parameters have to be specified, for example by using input fields on a web form.

<input type="checkbox" name="recurring" value="true"/>
<input type="input" name="stored_customer_email" value=""/>
<input type="radio" name="recurring_interval" value="L * *"/>

The values of the field recurring_interval are based on cron expression parameters, but you only have to specify the day, month, and weekday parameter. Furthermore, raisenow e-payment platform supports an extra value L for specifying the day parameter. This value L means the last day of a month. You can either create your cron expression parameters manually, e.g. via rputils.js (see example in demo/recurrentpayment.html) or if you don’t want to use cron expression parameters at all, there are also a set of keywords, which can be used.

daily; means daily execution (* * *) weekly; means execution on every Monday (* * 1) monthly; means end of month execution (L * *) quarterly; means execution every three months at the end of March, June, September, and December (L */3 *) semestral; means half-yearly execution at the end of June and December (L */6 *) yearly; means once a year on 31st of December

To test your implementation, enter amount, select credit card as payment method (e.g. visa), enter a valid email address, and submit the form. In the background, the e-payment platform checks if the credit card is valid, and if it is possible to charge the specified amount of money. If yes, a subscription will be activated. In the next 10 minutes, you will receive an email from the e-payment platform telling that you have successfully created a recurring payment. If the execution day is set to today (e.g. daily execution), you will also receive an email telling you that your credit card is charged. If you don’t get an email, please inform raisenow technical support team. The chapter “Webhooks and Recurring Payments” explains how to customize the response and to implement a subscription overview page. The example will continue at the end of the chapter.

Webhooks 

Table of Contents:


Webhooks are merchant-defined web services that are invoked when certain events occur during the execution of raisenow web services. They are currently defined and supported for the recurring payment process (aka subscriptions) and transaction state changes (e.g. transaction state changed to final success, error, or canceled). So, use these webhooks to be notified about change events of your transactions.

Interacting with APIs like our web services often suffers from two important problems:

  1. There may exist services which do not make an API request, but need to know the response

  2. Some events, like delayed payment slip charges and many recurring payment events, are not the result of a direct API request

Webhooks solve these problems by providing the ability to register a URL that will be invoked through an HTTP POST request if the specified event occurs. All relevant information will be included in the POST request.

In case of webhook failures, invocations will be retried. Such failure includes:

  • No response

  • Unsuccessful response status (non 2xx HTTP status code)

  • request integrity violation

  • response integrity violation

  • Request authentication failure

  • Response authentication failure

The retry interval is calculated using an exponential backoff algortihm predefined by us (currently: 2^invocation_count minutes, e.g. first retry after 1 min, second retry after 2 min, 4min, 8min, etc.). We support up to 12 retries. After the last retry an email can be sent. The email content is predefined by us.

The following PHP script implements a webhook that reads configuration from configuration file parameters.ini and uses EPIK classes to create and send an email message. In this example, this webhook is supposed to be invoked if a customer sets up a recurring payment.

<?php
require_once("../php/EPIKDefaultImpl.php"); require_once("../php/lib/swift/swift_required.php");

$epayment = new EPIKDefaultImpl(); $params = $epayment->getParameters("../config/parameters.ini");

$message = $epayment->createNewEmailMessage($params["webhooks"]);

$message-> setSubject("hello world");
$message-> setFrom(array("john.doe@foo.com" => "John Doe"));
$message-> setTo(array("jane.doe@bar.com" => "Jane Doe"));

$body = $_POST["stored_customer_email"];

$message->setBody($body);
$message->send();?>

Developers and merchant admins can register webhooks via DDT Manager:

Parameter Name Mandatory/Optional Description
URL mandatory Max length: 2000 characters. Info about URL max length: http://stackoverflow.com/a/417184

In case this is empty the Webhook configuration is invalid. Invalid Webhooks are not executed and the event may be propagated to a configured fallback notification subscription.
Username optional The username will be used either for HTTP Basic Authentication or the generation of the Epayment Signature.
Password optional The password will be used either for HTTP basic Authentication or as a shared secret for the generation of the Epayment Signature.
Integrity Check Required mandatory If true: send Content-MD5 HTTP header in request (see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)

Note: When a response contains a Content-MD5 header, then the message integrity is verified even if this attribute is false.
Security Level mandatory 0, 1, 2, 3 or 4 (see the following table)
Merchant Config mandatory
test_mode mandatory Test mode Webhook configurations apply to entities (transaction/subscription) that have been created in test_mode.
Security Level Description
0 No authentication. This security level is only recommended when the webhook recipient uses IP restriction or other strong security measures.
1 Request contains HTTP Basic Authentication header. HTTP Basic Authentication should be used only over an encrypted communication channel, i.e. when using the HTTPS protocol.
2 Security Level 1 + the response is expected to contain an X-Epayment-Signature header. If the signature does not match, this webhook invocation is considered to have failed.
3 Webhook authentication by X-Epayment-Signature header. Request does not contain the HTTP Basic Authentication header but a signature. The webhook recipient can authenticate the request by validating the epayment signature. Authentication information is not transmitted in clear text and therefore this security level can be considered secure over unencrypted communication channels (e.g. HTTP). However the entity body transmitted will not be encrypted when the communication channel is not encrypted.
4 Security Level 3 + the response is expected to contain an X-Epayment-Signature header. If the signature does not match, this webhook invocation is considered to have failed.

In a POST request, your stored parameters and the payment parameters are sent to the registered webhook. The following webhooks are available:

Event Name Parameters
transaction_status_changed_to_final_success

transaction_status_changed_to_final_error

transaction_status_changed_to_aborted
event
transaction_id (deprecated)
epp_transaction_id
subscription_id
subscription_token
created
amount
merchant_config
merchant
currency
payment_method
payment_provider
new_status
language
test_mode
success_url
cancel_url
error_url

Futhermore, all transaction details are returned such as parameters from payment provider.
subscription_cc_expiry_reminder If credit card of a recurring payment subscription will expire next month (expiration month is current month + 1), this webhook will be triggered.

Parameters:
event
amount
cancel_url
charges_count (not available for the subscription_subscribe event)
css_url
currency
epp_transaction_id
error_url
errorCode
errorDetail
errorType
expm
expy
immediate_execution
interval (recurring_interval with prefix "01 00 ", e.g. “01 00 * * *” for daily execution )
language
masked_cc
merchant_config
merchant_name
mobile_mode
payment_method
payment_provider
subscription_token
success_url
test_mode
transaction_id (deprecated)
stored_customer_email
stored_* (all other stored customer and subscription parameters)
subscription_subscribe Same parameters for all subscription_* webhooks
subscription_charged Same parameters for all subscription_* webhooks
subscription_renewed Same parameters for all subscription_* webhooks
subscription_charge_error Same parameters for all subscription_* webhooks
subscription_cancel Same parameters for all subscription_* webhooks

In the webhook configuration GUI in DDT Manager, a “Tester” can be expanded when viewing the details of a webhook configuration. This tester allows to manually trigger test webhook invocations with similar parameters as a real webhook invocation.

  • A special parameter "test_invocation=true"is set and sent as one of the POST parameters to denote that a webhook invocation is just a test invocation. Test invocations do not create entries in the webhook invocations list and are not retried upon failure. In any case, the server should respond as it would respond to a real invocation.

  • Note that manual test invocations will originate from DDT Manager and not from EPP Core (like real webhook invocations), therefore the Source IP Address may be different.

Webhook Message Integrity

Webhooks may be configured to require an integrity check. This is a basic, non-secure data integrity check mechanism that protects against accidental modification of the entity-body in transit [1]. Non-secure means that this is not a protection against malicious attackers that attempt to forge requests. In order to allow the recipient of the webhook request to verify message integrity, we use the HTTP 1.1 standard Content-MD5 header. In the following the protocol as defined in http://www.ietf.org/rfc/rfc1864.txt is described.

Sender (EPP):

  1. Apply any content encoding to the desired entity body (i.e. application/x-www-form-urlencoded or application/json).

  2. Calculate a hash of the content-encoded entity body using the MD5 hash function.

  3. Base 64 encode the resulting MD5 hash.

  4. Add the resulting string to the entity header field Content-Md5.

  5. Apply any transfer encoding to the HTTP entity and send the resulting HTTP request message.

Recipient (Customer):

  1. Receive the HTTP request message and apply any transfer decoding necessary to extract the HTTP entity.

  2. Calculate a hash of the entity body using the MD5 hash function.

  3. Base 64 encode the resulting MD5 hash.

  4. Check if the computed value matches the value of the received Content-MD5 header field.

The server should check and return a 400 HTTP status code, if data integrity is violated. The invocation is retried in this case.


Webhooks and Recurring Payments

The specified URL will be called from the e-payment platform via a POST request with the following POST parameters (x-www-form-urlencoded):

  • epp_transaction_id (except for subscription_canceled_webhook)

  • amount

  • payment_method

  • stored_customer_email

  • interval (it is important to note here that the interval starts with a leading 01 00, e.g. 01 00 L * *, which means that it will be executed 1 minute after midnight)

  • currency

  • language

  • subscription_token

  • masked_cc

  • charges_count (only for subscription_charged_webhook)

All stored_customer_* parameters are also returned (e.g. stored_customer_lastname, stored_customer_firstname) In order to create a customer subscription overview page which allows a customer to cancel or update a recurring payment subscription, you have to retrieve the subscription information via the e-payment service https://api.raisenow.com/epayment/api/subscription/info/{merchantConfig}/{subscriptionToken}/ or use the function getRecurrentPaymentSubscriptionInfo from the EPIK tool. As identifier you have to use the subscription_token. Both returns a JSON object containing the following information:

  • masked_cc

  • interval (note that the interval starts with a leading 01 00, e.g. 01 00 L * *)

  • customer_token

  • status (active|inactive)

  • success_url

  • cancel_url

  • error_url

  • payment_method (e.g. vis for Visa)

  • test_mode

  • currency

  • amount

  • language

  • mobile_mode

  • stored_country (deprecated: should be part of customer object)

  • payment_provider

  • expm; expiry month

  • expy; expiry year (2-digit number, e.g. 13)

  • customer, which contains a JSON string (is deprecated: use JSON object with key customer_obj)

  • customer_obj, which is a JSON object containing all information about the subscriber.

On the subscription overview page you also have to offer services to cancel and renew a subscription for a user: To cancel a subscription you can either call the web service https://api.raisenow.com/epayment/api/subscription/cancel/{merchantConfig}/{subscriptionToken}/ or use the function cancelRecurrentPaymentSubscription. To renew a subscription you have to add the subscription token to your donation form as hidden input field with attribute name subscription_token. The following figure shows an example of a subscription overview page

Image

Figure shows an example of a subscription overview page.

How to use HMAC Feature 

Table of Contents:


Purpose

The HMAC let’s a merchant protect transactions agains common attacks. This is especially useful whenever a customer exchanges money for goods (e.g. online shop), but it’s entirely optional. HMAC signatures are used in both, the initial request to RaiseNow and in the return to success/error pages.

Its worth to note that HMAC signatures do not provide encryption. Their only purpose is to ensure the integrity of the received data. (It can ensure that the data has not been modified between sending the request on one side and receiving it on the other). For more information about HMAC signatures:

https://en.wikipedia.org/wiki/Hash-based_message_authentication_code#Definition_.28from_RFC_2104.29

https://tools.ietf.org/html/rfc2104


How it works

Basically a list of parameters and a secret is used to calculate a hash. This hash is then sent along with the “payment request”. On the RaiseNow Platform, the same list of parameters (from the request) and the same secret are used to calculate the same hash. If the hash provided in the request and the hash calculated are equal the transaction is accepted. If not this indicates an attack and no transaction is processed.

In the return request, it works the other way around. RaiseNow uses a list of parameters and the secret to get the hash and sends it along to the return url. The merchant then can calculate the hash itself and verify that it equals the hash provided by RaiseNow.

For this to work a merchant must decide a number of things (fields/parameters to use, secret, hash algorithm) and let RaiseNow Support configure the merchants account accordingly.


Define Fields

First a merchant needs to decide which fields should be included in the HMAC signature. Per default these are only: amount, currency, test_mode (in initial request) and epp_transaction_id, [hmac,] amount, currency, test_mode, epayment_status (in the return request). To prevent against replay attacks it is recommended to add a “time” field (e.g. stored_transaction_time).

For this tutorial let’s assume we chose the following fields for the initial request:

  • amount

  • currency

  • test_mode

  • stored_transaction_time (unix timestamp)

  • stored_product* (every field starting with stored_product)

  • stored_customer* (every field starting with stored_customer)

For the return request:

  • epp_transaction_id

  • amount

  • currency

  • test_mode

  • epayment_status

  • stored_transaction_time (unix timestamp)

  • stored_product* (every field starting with stored_product)

  • stored_customer* (every field starting with stored_customer)

  • hmac (This is only used if the hmac signature in the initial request was valid)

Note that we include stored_product and stored_customer in the response hmac as well. Depending on the architecture of the checkout process and the online shop, this might or might not be necessary. A merchant is recommended to use webhooks (which provide signatures as well) to validate a transaction before sending goods out.


Choose a Hash Algorithm

Second the merchant needs to choose a secret (a “long” string). This secret should be protected at all times. The security of the hmac signatures relies upon the fact that the secret is indeed secret and only known to the two parties (merchant, raisenow) involved. Once an attacker knows the secret, she would be able to modify the request and recalculate the hmac signature and the attack would not be detectable anymore.

For this tutorial we choose “secretyoumustbe” as our secret.


Define Contexts

HMAC signatures can be used in 3 different context:

  • transaction (for normal one-shot transactions)

  • subscription (for recurring transactions)

  • resubscription (for changing recurring subscriptions)

In a typical shop only the transaction context is required. So for this tutorial we only need “transaction” context.


Let RaiseNow support setup the Configuration

RaiseNow needs to setup the system with the merchants chosen settings. (At the moment merchants are not allowed to setup hmac signature feature themselves). Please contact support@raisenow.com.

Once everything is setup we are ready to implement and test.


Implementation Example

All the code for this example can be found at: https://github.com/raisenow/HMACExample

Not that this is just an example and should not be used as is. First we implement a Class that can be used to calculate hmac signatures.

<?php
 
class RaiseNowSignature {
    private static $defaultSignParameters = array(
    'EPP_TRANSACTION_ID', // response only
    'HMAC', // response only
    'AMOUNT',
    'CURRENCY',
    'TEST_MODE',
    'EPAYMENT_STATUS', // response only
    'STORED_CUSTOMER*', // * will be replaced with a regex below
    'STORED_PRODUCT*', // * will be replaced with a regex below
    'STORED_TRANSACTION_TIME',
  );
 
  /**
   *@param string $secret
   */
  private $secret;
  /**
   * @param string $algorithm
   */
  private $algorithm;
  /**
   * @param array $signature_parameters
   *   The names of the parameters that are be used to generate the signature.
   */
  private $signParameters;
 
  public function __construct($secret, $algorithm) {
    $this->secret = $secret;
    $this->algorithm = $algorithm;
    $this->signParameters = self::$defaultSignParameters;
  }
 
  public function getSignParameters() {
    return $this->signParameters;
  }
 
  public function setSignParameters($signParameters) {
    $this->signParameters = $signParameters;
  }
   
  /**
   * Signs payment message data.
   *
   * @param array $data
   *   Keys are POST parameter names, values are values.
   *
   * @return string
   *   The signature.
   */
  function signData(array $data) {
    // Filter parameters that are not needed for the signature.
    ksort($data); // note that the parameters need to be sorted alphabetically
    $signature_data_string = '';
    foreach ($this->signParameters as $parameter) {
      $signature_parameter_pattern = '/^' . str_replace('*', '\d+?', $parameter) . '$/i';
      foreach ($data as $data_parameter => $value) {
        if (strlen($value) && preg_match($signature_parameter_pattern, $data_parameter)) {
          $signature_data_string .= $value;
        }
      }
    }
 
    return hash_hmac($this->algorithm, $signature_data_string, $this->secret);
  }
}

Now let’s include that in our checkout process.

checkout.php

<?php
    include('./RaiseNowSignature.php');
    $algorithm = "sha256";
    $secret = "secretyoumustbe";
    // handle post request
    if (count($_POST) > 0) {
        $signature = new RaiseNowSignature($secret, $algorithm);
        $hmac = $signature->signData($_POST);
        $order = $_POST;
        $order['hmac'] = $hmac;
        include ('./reviewOrder.php');
        exit();
    } else {
       // default order
       $order = array(
            'hmac' => '',
            'payment_method' => 'VIS',
            'amount' => '5000',
            'currency' => 'chf',
            'test_mode' => 'true',
            'stored_product_name' => 'A book',
            'stored_product_id' => '125',
            'stored_customer_name' => 'John Tester',
            'stored_transaction_time' => (new DateTime('now'))->format('U')
        );
    }
?>
<!-- render form -->
<html>
    <head>
        <title>RaiseNow Example Checkout with HMAC</title>
    </head>
    <body>
    <h2>Make your order</h2>
        <form action="./checkout.php" method="POST">
            <input type="hidden" name="hmac" value="<?php echo $order['hmac'] ?>" />
            <input type="hidden" name="stored_transaction_time" value="<?php echo $order['stored_transaction_time'] ?>" />
            <label for="payment_method">Payment Method</label>
            <input type="text" name="payment_method" value="<?php echo $order['payment_method'] ?>" />
            <br />
            <label for="amount">Amount</label>
            <input type="text" name="amount" value="<?php echo $order['amount'] ?>" />
            <br />
            <label for="currency">Currency</label>
            <input type="text" name="currency" value="<?php echo $order['currency'] ?>" />
            <br />
            <label for="test_mode">TestMode</label>
            <input type="text" name="test_mode" value="<?php echo $order['test_mode'] ?>" />
            <br />
            <label for="stored_product_name">Product Name</label>
            <input type="text" name="stored_product_name" value="<?php echo $order['stored_product_name'] ?>" />
            <br />
            <label for="stored_product_id">Product Id</label>
            <input type="text" name="stored_product_id" value="<?php echo $order['stored_product_id'] ?>" />
            <br />
            <label for="stored_customer_name">Customer Name</label>
            <input type="text" name="stored_customer_name" value="<?php echo $order['stored_customer_name'] ?>" />
            <br />
            <input type="submit" value="Order Now" />
        </form>
    </body>
</html>

reviewOrder.php

<html>
    <head>
        <title>RaiseNow Example Checkout with HMAC</title>
    <body>
        <h2>Review your order</h2>
        <form action="<?php echo $submitUrl; ?>" method="POST">
            <input type="hidden" name="hmac" value="<?php echo $order['hmac']; ?>" />
            <input type="hidden" name="success_url" value="<?php echo $returnUrl; ?>" />
            <input type="hidden" name="error_url" value="<?php echo $returnUrl; ?>" />
            <input type="hidden" name="cancel_url" value="<?php echo $returnUrl; ?>" />
    <!-- test card -->
            <input type="hidden" name="cardno" value="4242424242424242" />
            <input type="hidden" name="expy" value="15" />
            <input type="hidden" name="expm" value="12" />
            <input type="hidden" name="cvv" value="123" />
            <input type="hidden" name="card_holder_name" value="test" />
            <input type="hidden" name="reqtype" value="CAA" />
     
            <input type="hidden" name="stored_transaction_time" value="<?php echo $order['stored_transaction_time'] ?>" />
            <label for="payment_method">Payment Method: <?php echo $order['payment_method']; ?></label>
            <input type="hidden" name="payment_method" value="<?php echo $order['payment_method'] ?>" />
            <br />
            <label for="amount">Amount: <?php echo $order['amount'] ?></label>
            <input type="hidden" name="amount" value="<?php echo $order['amount'] ?>" />
            <br />
            <label for="currency">Currency: <?php echo $order['currency'] ?></label>
            <input type="hidden" name="currency" value="<?php echo $order['currency'] ?>" />
            <br />
            <label for="test_mode">TestMode: <?php echo $order['test_mode'] ?></label>
            <input type="hidden" name="test_mode" value="<?php echo $order['test_mode'] ?>" />
            <br />
            <label for="stored_product_name">Product Name: <?php echo $order['stored_product_name'] ?></label>
            <input type="hidden" name="stored_product_name" value="<?php echo $order['stored_product_name'] ?>" />
            <br />
            <label for="stored_product_id">Product Id: <?php echo $order['stored_product_id'] ?></label>
            <input type="hidden" name="stored_product_id" value="<?php echo $order['stored_product_id'] ?>" />
            <br />
            <label for="stored_customer_name">Customer Name: <?php echo $order['stored_customer_name'] ?></label>
            <input type="hidden" name="stored_customer_name" value="<?php echo $order['stored_customer_name'] ?>" />
            <br />
            <input type="submit" value="Order Now" />
        </form>
    </body>
</html>

Now lets add a return.php that we can use as return url.

return.php

<?php
    include('./RaiseNowSignature.php');
    $algorithm = "sha256";
    $secret = "secretyoumustbe";
    $signature = new RaiseNowSignature($secret, $algorithm);
    $hmac = $signature->signData($_GET);
    $validationResult = ($hmac === $_GET['response_hmac'])? 'passed' : 'failed';
     
    echo "<h1>HMAC Validation: " . $validationResult ."</h1>";
    echo "</p>returned hmac: " .$_GET['response_hmac'];
    echo "<br />calculated hmac: " .$hmac ."</p>";
    echo "<br /><p>Payment Response:";
    foreach ($_GET as $name => $value) {
        echo "<br />" .$name .": " .$value;
    }
    echo "</p>";
?>

List of Supported Hash Algorithms

In case of PHP the “hash_algos()” function can be used to get a list of supported hash algorithms.

The RaiseNow Platform supports the following algorithms:

  • md5

  • sha1

  • sha256

  • sha512

Web Widgets 

What is a web widget?

A web widget is a component, a “chunk of web page” that RaiseNow provides for you to display a donation form coming from RaiseNow on your own pages. Our widgets typically contain a slightly complex mixture of HTML, CSS and Javascript. RaiseNow wants to hide that complexity and make it as easy as possible for you to include the form on your pages.


Table of Contents:


Feature Overview

Widget Name Demo Link to ddswidget.html Features Multi Language Support Recurring Payment Responsive Design Customizable Logo Deeplinking Purpose1 Stored Parameters2 Callback “Widget Loaded”3 Register Event Handlers4
Bre Link to Bre bre/ddswidget.html

optional
SMS donations - - - - - -
Bre2 Link to Bre2 SMS donations - - - - -
Ela Link to Ela ela/ddswidget.html All payment methods - - -
Servino Link to Servino servino/ddswidget.html All payment methods - -
Lema Link to Lema lema/ddswidget.html All payment methods -
Lumnezia Link to Lumnezia lema/ddswidget.html All payment methods -
Tamina Link to Tamina - Donation barometer - - - - -

1 Also CRM campaign IDs can be configured.

2 Add parameters to a form resp. transaction dynamically. Injection via query parameter and Javascript possible.

3 Because widgets are asynchronous loaded, you have the possibility to register a callback function which is triggered after the widget is loaded.

4 Register event handlers for various events, such as “template loaded”, “amount changed” or “search result loaded”.


The Web Widgets

We can offer you five different types of widgets. In the following section, each widget with its specialties is described.

Bre and Bre2 Widget

A simple donation form for SMS payments only. SMS payments via web are secured by a double opt-in mechanism (donor has to answer the short message with yes/ja to confirm the payment). If user confirms the initiated payment, the widget will be notified and redirects to the thank you page.

Bre and Bre2 enables:

  • SMS payments only

  • 3 predefined amounts from 1 to 100

  • 1 custom amount

  • Responsive design

  • Multilanguage support

  • Inject custom parameters


Ela Widget

Ela is currently the most compact widget for one-time donation. All available payment methods are supported. There is no possibility to define a selection of purposes but you can add a purpose via a custom parameter to the form. Therefore the widget is ready in a snap and suitable for emergency calls. The sequence of steps is fixed and defined as follows:

  1. Amount selection

  2. Payment method selection

  3. Confirmation

  4. Thank you Page

Ela contains and enables:

  • One-time payments

  • All payment methods supported

  • 4 predefined amounts (customizable)

  • 1 custom amount

  • Multistep form

  • Customer details form included

  • Donation confirmation

  • Multilanguage support

  • Inject custom parameters

Defined parameters/form fields in Ela

Parameter Remarks
pollstatus_url Defines URL which will be called to poll SMS donation status
success_url URL which will be called when the donation was successful
error_url URL which will be called when an error occurred
cancel_url URL which will be called when a donation is cancelled
test_mode The widget is in the test mode, no real donation can be accepted
mobile_mode Defines if form fields are mobile optimized or not - not used in ela
currency Currency of the donation
language Language of the widget
reqtype RaiseNow used parameter
popup RaiseNow used parameter
amount Donation amount
stored_rnw_product_name Name of the widget type (e.g. ela)
stored_rnw_product_version Version of the product/widget type
stored_rnw_source_url The URL where this widget is hosted
stored_rnw_widget_uuid Defines unique identifier of this widget within a widget type
predefined-amount Predefined donation amount
ela_amount_custom The donation amount which the donor can set by himself
payment_method Payment method of the donation
stored_customer_donation_receipt Receipt of a donation for the customer
stored_customer_firstname Firstname of the customer
stored_customer_lastname Lastname of the customer
stored_customer_street Street name
stored_customer_zip_code Postal code
stored_customer_city City
stored_customer_email Email address of the customer
card_holder_name Card holder name
cardno Credit card number
cvv Three digit number on the back side of a credit card
ela-pf-type Defines it PostFinance Card or PostFinance E-Finance is used as payment method
stored_es_ordered Defines if payment slip without reference number should be sent via mail to donor
msisdn cell phone number for SMS donations
stored_rnw_widget_instance_id Defines widget instance identifier

Servino Widget

Servino Widget allows one-time and recurring payment. For one-time payments all payment methods and for recurring payments credit cards, PostFinance (CH) and LSV/DD (CH) are supported. Servino is a multistep form starting with a purpose selection screen. One can define up to 5 purposes and corresponding impact examples for each amount/purpose combo. The sequence of the following steps is fixed:

  1. Purpose selection

  2. Amount selection

  3. Payment method selection

  4. Confirmation

  5. Thank you Page

Servino contains and enables:

  • One-time and recurring payments

  • All payment methods supported

  • up to 5 purposes

  • 4 predefined amounts (customizable)

  • 1 custom amount

  • Impact examples for each amount

  • Multistep form

  • Customer details form included

  • Donation confirmation

  • Multilanguage support

  • Inject custom parameters

  • Deeplinking to amount selection or payment method selection

Defined parameters/form fields in Servino

Parameter Remarks
stored_customer_firstname Firstname of the customer
stored_customer_lastname Lastname of the customer
stored_customer_email Email address of the customer
currency Currency of the donation
language Language used in the widget
reqtype RaiseNow used parameter
payment_method Used payment method
recurring Defines if it is a recurring donation
recurring_interval Defines interval of the recurring donation
immediate_execution Defines if the donation is immediately executed
recurring_interval_name Name of the interval
no_dd_validation Defines that direct debit data is not validated
meta_recurring Defines if it is a one time or recurring donation
meta_payment_method Defines if it is a one time or recurring donation
es_message Message for the payment slip
amount Donation amount
stored_formatted_amount Donation amount formatted
stored_rnw_product_name Name of the widget type (e.g. lema)
stored_rnw_product_version Version of the product/widget type
stored_rnw_source_url The URL where this widget is hosted
stored_campaign_id ID of the campaign
stored_campaign_subid Sub ID of the campaign
subscription_token Unique token generated after a subscription is created
stored_rnw_purpose_text Donation purpose text
stored_rnw_hide_address_fields Defines if the address fields are hidden
stored_translated_recurring_interval Human readable recurring interval
cardno Credit card number
expm Expiry month of a bankcard
expy Expiry year of a bankcard
cvv Three digit number on the back side of a credit card
card_holder_name Card holder name
sid Short number for SMS donations
keyword Keyword used for the SMS donation
msisdn cell phone number for SMS donations
stored_purpose Donation purpose
donation_target Donation purpose
amount-select Predefined donation amount
sd_amount_custom_single The donation amount which the donor can set by himself for one-time donations
sd_amount_custom_recurring The donation amount which the donor can set by himself for recurring donations
stored_es_ordered Defines if payment slip without reference number should be sent via mail to donor
iban IBAN
stored_dd_interval Defines the recurring interval of the direct debit payment
stored_dd_form_ordered Defineds if direct debit application should be sent via mail to donor
bank_name Name of the bank
bank_zip_code Postal code of the bank
bank_city In which city the bank is located
stored_customer_salutation Salutation of the customer
customer_birthdate_day Day of birth from the customer
customer_birthdate_month Month of birth from the customer
customer_birthdate_year Year of birth from thecustomer
stored_customer_email_permission Defines if the customer wants to receive newsletter?
stored_customer_donation_receipt Defines if customer wants a donation receipt
stored_customer_company Company of the customer
stored_customer_street Street name
stored_customer_street_number Street number
stored_customer_street2 Second street name if needed
stored_customer_pobox Postbox
stored_customer_zip_code Postal code
stored_customer_city City
stored_rnw_widget_uuid Defines unique identifier of this widget within a widget type
stored_rnw_widget_instance_id Defines widget instance identifier
error_url URL which will be called when an error occurred
cancel_url URL which will be called when a donation is cancelled
success_url URL which will be called when the donation was successful
test_mode Defines if test or real transactions can be initiated
mobile_mode Defines if form fields are mobile optimized or not - not used in lema
transaction_id The unique transaction id of a transaction
delete_data_after_submit Defines if all the data is deleted after submitting
refno Reference number on a payment slip

Lema/Lumnezia Widget

Lema Widget is the most powerful widget in the matter of flexibility and extensibility. It supports one-time and recurring payments as the Servino widget and as many purposes as you want. The sequence of steps can be customizable and optional steps can be omitted.

Lema/Lumnezia contains and enables:

  • One-time and recurring payments

  • 5 predefined amounts (customizable)

  • 1 custom amount

  • Sequence of steps customizable

  • Optional steps removable

  • Donation confirmation

  • Multilanguage support

  • Inject custom parameters

  • Add custom text fields

  • Client-side (Javascript) event notifications

Defined parameters/form fields in Lema

Parameter Remarks
stored_customer_firstname Firstname of the customer
stored_customer_lastname Lastname of the customer
stored_customer_email Email address of the customer
currency Currency of the donation
language Language used in the widget
reqtype RaiseNow used parameter
payment_method Used payment method
recurring Defines if it is a recurring donation
recurring_interval Defines interval of the recurring donation
immediate_execution Defines if the donation is immediately executed
recurring_interval_name Name of the interval
no_dd_validation Defines that direct debit data is not validated
meta_recurring RaiseNow used parameter
es_message Message for the payment slip
amount Donation amount
stored_rnw_product_name Name of the widget type (e.g. lema)
stored_rnw_product_version Version of the product/widget type
stored_rnw_source_url The URL where this widget is hosted
stored_campaign_id ID of the campaign
stored_campaign_subid Sub ID of the campaign
subscription_token Unique token generated after a subscription is created
stored_rnw_purpose_text Donation purpose text
stored_rnw_hide_address_fields Defines if the address fields are hidden
stored_translated_recurring_interval Human readable recurring interval
cardno Credit card number
expm Expiry month of a bankcard
expy Expiry year of a bankcard
cvv Three digit number on the back side of a credit card
card_holder_name Card holder name
sid Short number for SMS donations
keyword Keyword used for the SMS donation
msisdn cell phone number for SMS donations
stored_purpose Donation purpose
donation-type Defines if one time or recurring donation
predefined-amount Predefined donation amount
customamount The donation amount which the donor can set by himself
stored_es_ordered Defines if payment slip without reference number should be sent via mail to donor
iban IBAN
stored_dd_form_ordered Defineds if direct debit application should be sent via mail to donor
bank_name Name of the bank
stored_customer_salutation Salutation of the customer
customer_birthdate_day Day of birth from the customer
customer_birthdate_month Month of birth from the customer
customer_birthdate_year Year of birth from thecustomer
stored_customer_email_permission Defines if the customer wants to receive newsletter?
stored_customer_donation_receipt Defines if customer wants a donation receipt
stored_customer_company Company of the customer
stored_customer_street Street name
stored_customer_street_number Street number
stored_customer_street2 Second street name if needed
stored_customer_pobox Postbox
stored_customer_zip_code Postal code
stored_customer_city City
stored_rnw_widget_uuid Defines unique identifier of this widget within a widget type
stored_rnw_widget_instance_id Defines widget instance identifier
error_url URL which will be called when an error occurred
cancel_url URL which will be called when a donation is cancelled
success_url URL which will be called when the donation was successful
test_mode Defines if test or real transactions can be initiated
mobile_mode Defines if form fields are mobile optimized or not - not used in lema
transaction_id The unique transaction id of a transaction
delete_data_after_submit Defines if all the data is deleted after submitting
refno Reference number on a payment slip

Tamina Widget

Tamina allows to display the current total amount per e.g. campaign or purpose. Filter criteria can be defined via Javascript.

Tamina contains and enables:

  • Donation barometer

  • Searching/filgering customizable

  • Responsive design

  • Multilanguage support


How to Integrate a Web Widget into Your Site

  1. Add the following script tag to your page and replace the placeholders type, apikey, and language with your own data which you have received from our support team. Please see the notes below for possible values of the placeholders.

    <script src="https://widget.raisenow.com/widgets/{type}/{apikey}/js/dds-init-widget-{language}.js" type="text/javascript"></script>

    Notes for placeholder values:

    a. Possible values for type are ‘bre’, ‘ela’, or ‘servino’ b. You will get the apikey from our support. The apikey for our demo widget is ‘1234567890’ c. Language value is a two-character ISO 639-1 code, e.g. ‘de’ (for our demo widget use language ‘de’).

  2. Currently, a DOM element has to be added to identify the location of the widget on your page. Please make sure that the DOM element has the class attribute ‘dds-widget-container’. The example below uses a <div/> DOM element as the widget container.

    <div class="dds-widget-container"></div>
  3. Publish the page, open a browser, and check if the widget is rendered correctly.

  4. Because of security reasons, you have to upload the file ddswidget.html (download file from the overview table above) to your web server to submit payments (not necessary/optional for widget Bre). Please tell us via support@raisenow.com the URL of this file (HTTPS preferred, but make sure you have a valid certificate). We will then configure our server to allow payments from this server (for our demo deploy ddswidget.html to your server on path /widgets/{type}/ddswidget.html).


How to Retrieve Widget Information via Javascript

Open the Javascript console in your web browser on the page where the widget is integrated.

A global object called rnwWidget is attached to the window. The following information is stored in this object:

  • rnwWidget.constants: Useful constants such as events are available for custom implementation.

  • rnwWidget.widgets.{type}.configurations: Configurations for the specified type of widget. In case of multiple widgets per page more than one configuration are available. A configuration is identified by the corresponding apikey.

  • rnwWidget.widgets.instances: For widget Tamina, Bre2 and Lema a widget reference is available under instances. Each instance is identified by apikey and name of the instance (default: “default”).

The following snippet shows how to access these parameters:

<script type="text/javascript">
    //Constants
    rnwWidget.constants;

    //Configuration
    rnwWidgets.widgets.lema.configurations["1234567890"]

    //Instance
    rnwWidget.widgets.instances["1234567890-default"];
</script>

How to Customize a Widget

This is only possible in Bre2, Ela, Lema and Tamina.

We attached a Javascript object called rnwWidget to the window. Configurations, options, translations as well as the widget instance is available under this global object. Because the widgets are asynchronously loaded, the object is not ready when the page (where the widget is embedded) is loaded. Therefore we added a hook to inject configurations and options to the widget before it is created. The following snippet shows how to call configureWidget on your on page:

Bre2

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget;
        options.defaults;
    };
</script>

Ela

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget;
        options.defaults;
        options.epikOptions;
        options.payment_methods;
        options.validationOptions;
    };
</script>

Lema

In Lema we allow to configure the widget multiple times by pushing the configuration functions to an array. The last pushed configuration function has priority.

Please note: This feature will be soon available in the widget Ela, Servino and Bre2. Use the new style also in the examples below for Lema.

New style

window.rnwWidget.configureWidget.push(function(options){});

instead of the deprecated style

window.rnwWidget.configureWidget = function(options) {};

The other widgets will be updated soon.

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = [];
    window.rnwWidget.configureWidget.push(function(options) {
        options.widget;
        options.defaults;
        options.custom_fields;
        options.epikOptions;
        options.payment_methods;
        options.validationOptions;
    });
</script>

Tamina

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget;
    };
</script>

Furthermore implementation partner can register event handlers via Javascript to inject own logic and add custom parameters and fields.

The configureWidget method will be called before the widget is created and allows to customize the widget. As argument an options object is given over. This options argument contains the following information :

  • widget := the widget instance

  • defaults := default values for existing input fields or values for new hidden input fields

  • custom_fields := custom fields which will be displaced within the widget

  • epikOptions := contains information for initialise payments

  • payment_methods := shows the available payment methods

  • validationOptions := contains information about client-side validation


How to Customize CSS

It is possible to change the style of every widget via CSS. Add a link element to your page where the widget should be rendered

<link rel="stylesheet" type="text/css" href="https://mydomain/mypath/mycustom.css">

All possible style information can be retrieved via https://widget.raisenow.com/widgets/{type}/{apikey}/css/dds-widget.min.css. Note that the placeholder type and apikey have to be replaced with your own data.

We recommend to change only background and font color. For all other CSS changes, we do not guarantee proper functioning of the widget.

We also allow to import our LESS as base for your customization. LESS files can be retrieved via http: https://widget.raisenow.com/widgets/{type}/_default/less/styles.less

Font and background color

Here is an example of customizing the radio labels, the headers and the background of input fields in the widget Lema:

#lema-container.lema-container .lema-wrapper .lema-radio-label {
    color: orange;
}
#lema-container.lema-container .lema-wrapper .lema-step-header-text {
    color: blue;
}
#lema-container.lema-container input.getunik-radio:checked+label.getunik-radio-label {
    color: green;
}
#lema-container.lema-container .lema-wrapper .lema-input-text {
    background-color: yellow;
}

Checkboxes and Radioboxes

Checkboxes and Radioboxes are based on images. To modify these elements, the images have to be updated. Check out https://widget.raisenow.com/widgets/plain/_defaul/img/check_radio_sheet.png or use the attached source file sprite.psd.zip

We also provide svg versions of the radio button and checkbox. Use inline style to change the color of the elements.

#dds-container-id.dds-container input[type="checkbox"]:checked + label span {
    background: url("https://mydomain/mypath/check_radio_sheet.png") -19px top no-repeat;
}
#dds-container-id.dds-container input[type="radio"] + label span {
    background: url("https://mydomain/mypath/check_radio_sheet.png") -39px center no-repeat;
}
#dds-container-id.dds-container input[type="radio"]:checked + label span {
    background: url("https://mydomain/mypath/check_radio_sheet.png") -58px center no-repeat;
}
#dds-container-id.dds-container input[type="checkbox"] + label span {
    background: url("https://mydomain/mypath/check_radio_sheet.png") left top no-repeat;
}

INFO: You can render the widget with non-minimized/compressed Javascript and CSS. For that purpose, add the hash ddsdev at the end of the URL of your page (e.g. https://mydomain/mypath/mypage#ddsdev).


How to Add Custom Parameters

There are two different ways to add custom parameters:

In Bre and Servino

Add a custom parameter to a transaction via Javascript:

ddsWidgetConfig.ddsStoredParameters = {};
ddsWidgetConfig.ddsStoredParameters['stored_customer_id'] = 'text';

Parametes can also be set via query parameter: dds-stored_[\w], e.g. dds-stored_customer_id

INFO: Query parameters have higher priority than parameters set via Javascript.

In Bre2, Ela, Lema/Lumnezia and Tamina

You want to add custom parameters to enrich a payment transaction? The following code shows how to add a custom parameter:

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.defaults['stored_my_parameter'] = 'test';
    };

    // adding multiple configuration callbacks, only possible for lema

    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = [];

    window.rnwWidget.configureWidget.push(function(options) {
        options.defaults['stored_my_parameter'] = 'test1';
    });
    window.rnwWidget.configureWidget.push(function(options) {
        options.defaults['stored_my_parameter'] = 'test2';
    });
</script>

The code above add the parameter “stored_my_parameter” with value “test” to the payment transaction. Custom parameter name has to start with “stored_” to persist it in the RaiseNow platform.


How to Implement Custom Event Handlers

Custom event handlers only can be implemented in the widgets Bre2, Ela, Lema and Tamina.

rnwWidget object contains a list of all events. Have a look at rnwWidget.constants.events. It depends on the widget which of these events are available. Compare the following snippets to see which events are supported in which widgets.

Bre2

<script type="text/javascript">
    window.rnwWidget.constants.events.WIDGET_LOADED;
    window.rnwWidget.constants.events.AMOUNT_CHANGED;
    window.rnwWidget.constants.events.PAYMENT_COMPLETE;
    window.rnwWidget.constants.events.VALIDATING_PARAMETERS;
    window.rnwWidget.constants.events.VALIDATION_ERROR;
</script>

Ela

<script type="text/javascript">
    window.rnwWidget.constants.events.WIDGET_LOADED;
    window.rnwWidget.constants.events.PAGE_LOADED;
    window.rnwWidget.constants.events.AMOUNT_CHANGED;
    window.rnwWidget.constants.events.PURPOSE_CHANGED;
    window.rnwWidget.constants.events.PAYMENT_METHOD_CHANGED;
    window.rnwWidget.constants.events.BEFORE_SUBMIT;
    window.rnwWidget.constants.events.PAYMENT_COMPLETE;
    window.rnwWidget.constants.events.PROCESS_FORM;
    window.rnwWidget.constants.events.VALIDATING_PARAMETERS;
    window.rnwWidget.constants.events.VALIDATION_ERROR;
</script>

Lema

<script type="text/javascript">
    window.rnwWidget.constants.events.WIDGET_LOADED;
    window.rnwWidget.constants.events.PAGE_LOADED;
    window.rnwWidget.constants.events.AMOUNT_CHANGED;
    window.rnwWidget.constants.events.PURPOSE_CHANGED;
    window.rnwWidget.constants.events.PAYMENT_METHOD_CHANGED;
    window.rnwWidget.constants.events.DONATION_TYPE_CHANGED;
    window.rnwWidget.constants.events.BEFORE_SUBMIT;
    window.rnwWidget.constants.events.INTERVAL_CHANGED;
    window.rnwWidget.constants.events.PAYMENT_COMPLETE;
    window.rnwWidget.constants.events.PROCESS_FORM;
    window.rnwWidget.constants.events.VALIDATING_PARAMETERS;
    window.rnwWidget.constants.events.VALIDATION_ERROR;
    window.rnwWidget.constants.events.SUBSCRIPTION_EDIT_COMPLETE
</script>

Tamina

<script type="text/javascript">
    window.rnwWidget.constants.events.WIDGET_LOADED;
    window.rnwWidget.constants.events.SEARCH_RESULT_LOADED;
</script>

When the specified event has been triggered, a jQuery event object is given over as an argument. Depending on the event, this object argument contains the following extra information:

  • type := the specified event type

  • widget := the widget instance

  • value := depends on the event, for example the donated amount, the payment method or the donation interval

  • error := description of the error

  • errorList := lists all the objects with a validation error in an array

  • computedFields := shows the object containing the dynamically added fields

  • payment := payment object containing all parameters of the payment which are returned from the platform

  • paymemtStatus:= prints the status of the payment (e.g. aborted, success)

The following snippets show how to register a custom event handler for the defined events:

Example for the event WIDGET_LOADED

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget.on(window.rnwWidget.constants.events.WIDGET_LOADED, function(event) {
            console.log("The widget is loaded, please go on with your donation");
            console.log(event);
        });
    };
</script>

This event is triggered after the whole content of your widget is loaded. In this example, a note as well as the jQuery event object containing all the information are logged to your console.

Example for the event PAGE_LOADED

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
           options.widget.on(window.rnwWidget.constants.events.PAGE_LOADED, function(event) {
            console.log(event);
        });
     };
</script>

This event is triggered when the whole content of your page is loaded.

Example for the event AMOUNT_CHANGED

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget.on(window.rnwWidget.constants.events.AMOUNT_CHANGED, function(event) {
            console.log(event.value);
        });
    };
</script>

This event is triggered after the donation amount has been changed. The parameter event.value contains the new amount (in cents).

Example for the event PURPOSE_CHANGED

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget.on(window.rnwWidget.constants.events.PURPOSE_CHANGED, function(event) {
            console.log(event);
            console.log(event.purposeTitle);
            console.log(event.campaignId);
               console.log(event.campaignSubId);
            console.log(event.value);
           });
    };
</script>

This event is triggered if the purpose of the donation has been changed. The parameter event.value contains the value of the input field called stored_purpose. The parameter event.purposeTitle, event.campaignId, event.campaignSubId are values set in the widget translations.

Example for the event PAYMENT_METHOD_CHANGED

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
           options.widget.on(window.rnwWidget.constants.events.PAYMENT_METHOD_CHANGED, function(event) {
            console.log(event.value);
         });
     };
</script>

This event is triggered after the payment method has been changed. The parameter event.value contains the current selected payment method.

Example for the event DONATION_TYPE_CHANGED

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget.on(window.rnwWidget.constants.events.DONATION_TYPE_CHANGED, function(event) {
            console.log(event);
            console.log(event.value);
        });
    };
</script>

This event is triggered after the donation type (one-time or recurring donation) has been changed. The parameter event.value contains either value true or false depending on the type of the donation: the value true defines recurring whereas false defines a one-time donation.

Example for the event INTERVAL_CHANGED

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget.on(window.rnwWidget.constants.events.INTERVAL_CHANGED, function(event) {
            console.log(event);
            console.log(event.value);
        });
    };
</script>

This event is triggered after the interval of a recurring donation has been changed. The parameter events.value contains the interval of the donation, e.g. monthly.

Example for the event BEFORE_SUBMIT

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget.on(window.rnwWidget.constants.events.BEFORE_SUBMIT, function(event) {
            console.log(event);
            console.log(event.computedFields);
        });
    };
</script>

This event is triggered after the donor submitted the completed form and before the donation has been initiated. The parameter event.computedFields contains fields which are dynamically created from other parameters, e.g. birthdate.

Example for the event PAYMENT_COMPLETE

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget.on(window.rnwWidget.constants.events.PAYMENT_COMPLETE, function(event) {
            console.log(event);
            console.log(event.payment);
            console.log(event.paymentStatus);
        });
    };
</script>

This event is triggered after the payment has been completed, no matter if successfully or not. The parameter event.paymentStatus contains the status of the payment. The parameter event.payment is an object containing all returned parameters.

Example for the event PROCESS_FORM

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget.on(window.rnwWidget.constants.events.PROCESS_FORM, function(event) {
            console.log(event);
            console.log(event.computedFields);
        });
    };
</script>

This event is triggered when the form is processed.

Example for the event VALIDATING_PARAMETERS

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget.on(window.rnwWidget.constants.events.VALIDATING_PARAMETERS, function(event) {
            console.log(event);

        });
    };

This event is triggered before validating the current form.

Example for the event VALIDATION_ERROR

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget.on(window.rnwWidget.constants.events.VALIDATION_ERROR, function(event) {
            console.log(event.error);
            console.log(event.errorList);

        });
    };
</script>

This event is triggered if the validation of the completed fields returns an error. In this example, the error message as well as the list with all the errors are logged in your console.

Example for the event SUBSCRIPTION_EDIT_COMPLETE

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        options.widget.on(window.rnwWidget.constants.events.SUBSCRIPTION_EDIT_COMPLETE, function(event) {
            console.log(event.paymentStatus);
            console.log(event.payment);

        });
    };
</script>

This event is triggered after a recurring payment has been modified, no matter if successfully or not. The parameter event.paymentStatus contains the status of the payment. The parameter event.payment is an object containing all returned parameters.

Example for the event SEARCH_RESULT_LOADED

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {

        //Target level in CHF
        options.barometerTargetLevel = 2500;

        //Search sub query, please do not use whitespace or special characters or camelCase in key and value
        options.searchQuery = [{'stored_campaigner_name' : 'foobar'}];

        options.widget.on(window.rnwWidget.constants.events.SEARCH_RESULT_LOADED, function (e) {
            //Current level
            alert("current level " + e.level);

            //Add CHF 100.- to current level, e.g. to add offline donations
            e.widget.setLevel(100 + e.level);
        });

    });
</script>

This event is only supported by the widget Tamina. It is triggered if the searched sub query is loaded. In this example, CHF 100.- is added to the current donation level.


How to Set the Widget into Test Mode

This is only possible in the Lema widget.

To test a widget, especially the error handling and thank you page, one can set the widget into test mode. The values “false” for production mode and “true” for test mode are available.

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = [];
    window.rnwWidget.configureWidget.push(function(options) {
        options.epikOptions.test_mode = "true";
});
</script>

How to Add Custom Fields

This is only possible in the Lema widget.

The donation form has for most use cases available fields. However in some case you want some extra fields. The following snippet shows how to add custom fields:

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = [];
    window.rnwWidget.configureWidget.push(function(options) {
        options.extend({
            custom_fields : {
                stored_customer_institution : {
                    type : 'text',
                    location : 'before',
                    reference : 'customer_firstname',
                    placeholder : 'Institution',
                }
            }
        });
      });
</script>

Currently we support text, textarea, checkbox, select and date (3 fields; for day, month and year) as field type. Parameters of custom fields are:

  • type := text|select|checkbox|textarea|radio|date

  • location := where to add the field, before|after the element defined by the parameter reference

  • reference := relative to which element (value of the attribute data-bock-id of the html element)

  • placeholder := placeholder label (text, textarea supported)

  • label := label of an input element (date, checkbox supported)

  • initial := value for text field or textarea

  • value := value of an input element (checkbox, select supported)

  • name := name of an select option element

  • options := options for the select element. options is an array containing an object with two key value pairs (key := name|value, see above)

  • initial := initial value of an input element (text, textarea supported)

  • rows := define rows of a textarea

Example select:

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = [];
    window.rnwWidget.configureWidget.push(function(options) {
        options.extend({
            custom_fields : {
                stored_customer_rating : {
                    type : 'select',
                    location : 'after',
                    reference : 'customer_street',
                    options : [ {'name': 'bad', 'value': '0'}, {'name': 'ok', 'value': '1'}, {'name': 'good', 'value': '2'}],
                }
            }
        });
    });
</script>

Example radio:

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = [];
    window.rnwWidget.configureWidget.push(function(options) {
        options.extend({
            custom_fields : {
                stored_customer_rating : {
                    type : 'radio',
                    location : 'before',
                    reference : 'customer_firstname',
                    options : [ {"label": 'Organisation', 'value': "organisation"}, {"label": 'Private', 'value': "private"}],
                }
            }
        });
    });
</script>

Example checkbox:

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = [];
    window.rnwWidget.configureWidget.push(function(options) {
        options.extend({
            custom_fields : {
                stored_customer_partner_permission : {
                    type : 'checkbox',
                    location : 'after',
                    reference : 'customer_permission',
                    label : 'I am a partner',
                    value : 'true',                            }
            }
        });
    });
</script>

Example textarea:

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = [];
    window.rnwWidget.configureWidget.push(function(options) {
        options.extend({
            custom_fields : {
                stored_customer_additional_message : {
                    type : 'textarea',
                    location : 'after',
                    reference : 'customer_message',
                    placeholder : 'Additional Message',
                    initial : 'my text',
                    rows: 8,                                    }
            }
        });
    });
</script>

Available references (data-block-id)

  • amount-container

  • custom-amount-container

  • iban

  • bank_name

  • customer_salutation

  • customer_firstname

  • customer_lastname

  • customer_birthdate

  • customer_email

  • customer_permission

  • customer_message

  • customer_receipt

  • customer_company

  • customer_street

  • customer_street2

  • customer_pobox

  • customer_city

  • customer_country

  • recipient_salutation

  • recipient_firstname

  • recipient_lastname

  • recipient_birthdate

  • recipient_street

  • recipient_street2

  • recipient_pobox

  • recipient_city

  • recipient_country


How to Hide/Show Steps and Blocks

This is only possible in the Lema widget.

In some situation you want to hide or show some steps or blocks (see above). Therefore the widget instance has a method hideStep/showStep respectively hideBlock/showBlock.

The following steps are available:

+ donation-target
+ amount
+ payment-method
+ customer-identity
+ customer-address
+ recipient-information
+ members

Example of how to hide the donation target and the amount while showing the block ‘customer firstname’:

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = [];
    window.rnwWidget.configureWidget.push(function(options) {            options.widget.on(window.rnwWidget.constants.events.WIDGET_LOADED, function(event) {
            event.widget.hideStep("donation-target");
            event.widget.hideStep("amount");
            event.widget.showBlock("customer_firstname");
        });
    });
</script>

How to Customize Validation

This is only possible in the Lema widget.

If you have added custom fields or if you want some custom validation rule for some fields, you can define your own validation rules. The following code shows how.

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = [];
    window.rnwWidget.configureWidget.push(function(options) {
        options.extend({
            custom_fields : {
                stored_customer_institution : {
                    type : 'text',
                    location : 'before',
                    reference : 'customer_firstname',
                    placeholder : 'Institution',
                }
            },
            validationOptions : {
                classRules : {
                    stored_customer_institution : {
                        required : true,
                        messages: "My error validation message"
                    }
                }
            }
        });
    });
</script>

The identifier for the class rules has to be the same as the custom field name. Parameters of the rules are from the jquery validation plugin. More information is available under http://jqueryvalidation.org/.

How to Set Default Amounts

This is only possible in the Lema and Ela widget.

If you want to set default amount values or change from one-time to recurring donation as default, you can define defauls as shown in the following code.

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = function(options) {
        //Sets widget default to recurring payment and interval to quarterly
        options.defaults['recurring_interval'] = 'quarterly';

        //Sets default for recurring interval to quarterly
        options.defaults['ui_recurring_interval_default'] = 'quarterly';

        //Sets default recurring payment amount for interval quarterly to currency subunit 15000
        options.defaults['ui_recurring_amount_default'] = '15000';

        //Sets default for one-time payment amount to currency subunit 1000.
        options.defaults['ui_onetime_amount_default'] = '1000';
    };
</script>

Parameter Values:

  • recurring_interval := Sets widget default to recurring payment. Do not set this parameter if you want to have one-time donation as default. Allowed values: monthly|quarterly|semestral|yearly

  • ui_recurring_interval_default := Sets default for recurring interval. Allowed values: monthly|quarterly|semestral|yearly

  • ui_recurring_amount_default := Sets default amount for recurring payments. Use currency subunit.

  • ui_onetime_amount_default := Sets default amount for one-time payment. Use currency subunit.

Be careful: If combination amount-interval does not exists, the custom amount field will be used.


Deeplinking

This is only possible in the Servino widget.

Deeplinking and View-Mode-Restrictions on purpose- and amount-selection screen are possible. Be aware that deeplinking query parameters inhibit the deeplinking parameters set via Javascript.

Deeplinking:

  • ddsPurpose: 1-5

  • ddsInterval: monthly|quarterly|semestral|yearly (if one-time donation, ddsInterval must not be set)

  • ddsAmount: 1-99999

Purpose-View-Mode-Restriction (ddsPurposeViewModeRestriction):

  1. collapsed (Step 1 navigation bar is visible, but collapsed)

  2. collapsedlocked (Step 1 navigation bar is visible, but collapsed and not editable and not expandable)

  3. hidden (Step 1 navigation bar is not visible)

Amount-View-Mode-Restriction (ddsAmountViewModeRestriction):

  1. collapsed (Step 1 navigation bar is visible, but collapsed)

  2. collapsedlocked (Step 1 navigation bar is visible, but collapsed and not editable and not expandable). Has to be used in combination with Purpose-View-Mode-Restriction “collapsedlocked” or “hidden”

    <script type="text/javascript">
         var ddsWidgetConfig = ddsWidgetConfig || {};
         ddsWidgetConfig.ddsPurpose = 2;
         ddsWidgetConfig.ddsAmount = 30;
         ddsWidgetConfig.ddsPurposeViewModeRestriction  = "hidden";
         ddsWidgetConfig.ddsAmountViewModeRestriction  = "collapsedlocked";
     </script>

Deeplinking can also be set via query parameters:

dds-purpose := selected purpose id (i.e. ‘1’ indicates the first purpose in row)

dds-amount := selected amount in CHF (i.e. ‘5’ for CHF 5)

dds-interval := recurring payment interval (i.e. ‘monthly’, ‘quarterly’, ‘semestral’, ‘yearly’). If parameter is not set, one-time donation is activated.


How to Register to the Callback function “Widget Loaded”

(deprecated)

How to register the callback function which will be triggered after the widget is loaded:

ddsWidgetConfig.ddsWidgetLoaded = function () {
    alert("widget is loaded");
};

Edit translations

You can edit most of the text in your widget. If you don’t want to, a default text from us will be displayed.

Web Widgets also do the email. Email text, sender email address and bcc are configurable. In Lema and Lumnezia, texts are configurable per payment method and other custom parameters.

For any adjustment of your text, please

  1. Contact our support team at support@raisenow.com. You will get the latest translations of your own widget and an Excel table with the text modules to adjust.

  2. Update the text and send it back to the support team (online editing and upload functionality is on the roadmap).

Test Credit Cards 

 

Payment Card Industry provides also Test Credit Cards to test payments in test_mode true. Note that all card numbers only work in our test environment! Productive cards cannot be processed on the test account.

Card Type Card Number Exp Date CVV Test Rule
Amex 375811111111115 12/2018 1234 With limit
Amex 375000000000007 12/2018 1234 Without limit
MasterCard 5404000000000001 12/2018 123 With limit
MasterCard 5200000000000007 12/2018 123 Without limit
Visa 4242424242424242 12/2018 123 With limit
Visa 4900000000000003 12/2018 123 Without limit
Diners 36168002586009 12/2018 123 With limit
Diners 36167719110012 12/2018 123 Without limit
JCB 3569990010030442 12/2018 123 With limit
JCB 3569990010030400 12/2018 123 Without limit

The following test rules apply for all cards with limit:

Amount / amount range Error message
<= 90 CHF Transaction authorized
>90 CHF and <= 100 CHF Transaction declined (i.e. insufficient limit, bad expiry date)
>100 CHF and <= 110 CHF Referral
>110 CHF Card blocked (lost or stolen)

If you need syntactically correct IBAN numbers but not your own, use the following numbers:

  • CH9300762011623852957

  • DE89370400440532013000

  • AT611904300234573201

  • GB29NWBK60161331926819

About PayPal 

Table of Contents:


Welcome to the RaiseNow PayPal Tips & Tricks section

Here you can find support with various issues regarding PayPal. This section is under constant expansion.

If you can’t find the desired information here, you can always contact our support: support@raisenow.com


FAQ about PayPal


Bank account information

You can check the saved bank account details in PayPal as follows:

  • Profile -> Account settings -> My money -> add or remove bank account

  • You only see part of the saved account number, the last 4 digits. You can add as many accounts as you like.


E-mail address for customer requests

You can save several e-mail addresses, one of these will be set as your ‘standard’.

  • Profile -> Account settings -> My business info -> Email

  • Under “Customer Service Email” you can set your standard e-mail address to be shown to the donor. If you don’t specify one, your primary Email address will be used.


Name on credit card invoice

The name to be shown on the credit card invoice can be changed as follows:

  • Profile -> Account settings -> My selling tools -> Credit card statement name

Automatic transfer of PayPal credits to bank account

You can configure an automatic transfer on a daily basis.

  • My account -> Menu “transfer money” (don’t click on sub-menu “transfer to bank account”)

  • Afterwards, activate the function.


PayPal integration into the RaiseNow Platform


Type of integration

As per most recent status, we use the ‘Third-Party Authentication’ in the PayPal API area.

Third-Party Authentication

If your shopping cart is a hosted solution and your customers interact with your cart installed on your servers or another service provider’s service, then use third-party API authentication.

With third-party authentication, you perform the following tasks:

  • Submit API calls to PayPal on your merchant’s behalf.
  • Set up API credentials for your business account, and use your API username and password for every call.
  • Specify the merchant by populating the Subject field of the API request with the email address of your merchant’s Verified PayPal Business account.

RaiseNow currently offers only the PayPal Express Checkout option. Express Checkout makes it possible to pay with a PayPal account. Credit card payments are not possible.

Go to “Tools” -> “Manage your business” -> “API Access”, a pop-up window titled “Set up API access” will appear. Click on the button “Go to API Access”.

You can choose from two different options.


Activation of the PayPal payment option for RaiseNow

PayPal business account:

In order to receive PayPal payments, you need a PayPal business account.

Open a business account:

  1. Go to the website www.paypal.ch

  2. Click the button ‘Register’

  3. Choose ‘PayPal for your business’

  4. Add all the relevant information

Opening a PayPal business account is free of charge. If you already have a business account, skip to the next step.

Add API-Third-Party Authorization:

  1. Log in to your PayPal account.

  2. Click Profile and My Business Setup, choose Option B (add PayPal checkout yourself using our APIs) and then click on the option Set up API access when you’re ready to go live.

    Image

    Then choose Option 1 (on the left hand side of the screen) Grant API permission.

    Image

  3. Register the following entry as user name for Third-Party Authorizations: epayment_api1.getunik.com and click Lookup.

    Image

  4. Choose the ticked options. This is important in order for the payment to go through with PayPal and RaiseNow correctly and successfully. Confirm here with add:

    Image

  5. Inform RaiseNow, that you have registered at PayPal (support@raisenow.com) and send us the e-mail address (user name) of your PayPal business account.

  6. In order to finish the activation of your PayPal account, you will receive a verification code which you have to input on your PayPal account to be able to receive payments. For details on this, please address your PayPal support.


Using PayPal Sandbox Accounts for Testing

In order to test PayPal Express Checkout Payments the ‘Third-Party Authentication’ is not sufficient. Instead, a Sandbox Business Account has to be set up:

  1. Go to the website www.paypal.com

  2. Login using your Business Account (or create one following the steps described here: Activation of PayPal payment option in RaiseNow e-payment)

  3. Then navigate to the developer site of PayPal developer.paypal.com

  4. On the top right, click on ‘Dashboard’ and then on the left sidebar in the Section ‘Sandbox’ on ‘Accounts’

    Image

  5. Click ‘Create Account’ on the top right

  6. Select your country and as ‘Account Type’ select ‘Business (Merchant Account)’

    Image

  1. In Section ‘Payment Methods’ type in the amount of money your Sandbox Account will have access to (Choose a high enough amount to process multiple transactions. Once the amount is reached you will not be able to make any payments with that account anymore). Furthermore, choose ‘Yes’ for ‘Bank Verified Account’ and select ‘Visa’ as ‘Credit Card’. Finally, hit ‘Create Account’.

    Image

  1. On the ‘Sandbox Test Accounts’ Page click on the small triangle next to your previously created account and click on ‘Profile’

    Image

  1. In the PopUp window, choose tab ‘API Credentials’ and send us the ‘Username’, ‘Password’ and the ‘Signature’.

    Image

    Please note that if you followed the previous steps, these are credentials for a Sandbox Account which will not be able to process actual (i.e. live) payments.

PCI DSS Certification 

Table of Contents:


What is PCI DSS?

The Payment Card Industry Data Security Standard (PCI DSS) is a proprietary information security standard for organizations that handle branded credit cards from the major card schemes including Visa, MasterCard, American Express, Discover, and JCB. Private label cards – those which aren’t part of a major card scheme – are not included in the scope of the PCI DSS.

The PCI Standard is mandated by the card brands and administered by the Payment Card Industry Security Standards Council. The standard was created to increase controls around cardholder data to reduce credit card fraud via its exposure. Validation of compliance is performed annually, either by an external Qualified Security Assessor (QSA) that creates a Report on Compliance (ROC) for organizations handling large volumes of transactions, or by Self-Assessment Questionnaire (SAQ) for companies handling smaller volumes.

Source: https://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard


RaiseNow is PCI DSS certified

RaiseNow is PCI DSS-certified. We are ‘Service Provider Level 2’. Please find details about the certification criterias here: PCI Security Standards

Our certificate can be downloaded from the following link: TÜV Süd Service Provider Level 2 Certificate

Glossary 

General Errors

A

Name Description
amount Amount of money a customer pays
Acquirer An Institution (e.g. bank) that actually processes and transfers the money.
amx Acronym for the payment method American Express
API endpoint The getunik e-payment web service
authority Parameter which indicates a part (authority) of a base URL
auto_submit Parameter that indicates if the form should be submitted automatically on submit event.

B

Name Description
bcc_email_address Parameter which indicates the BCC mail address

C

Name Description
cancel_url Parameter that indicates the redirect URL in case of triggered cancel event.
card_holder_name Parameter which indicates the name of the credit card holder
currency Currency in ISO Code (427)
css_url Parameter to include a custom css file into the e-payment forms

D

Name Description
Datatrans Is a Payment Provider that processes credit card and PayPal transactions.
datatrans_acq_authorization_code See datatrans documentation
datatrans_acq_error_code See datatrans documentation
datatrans_amount See datatrans documentation
datatrans_currency See datatrans documentation
datatrans_error_code See datatrans documentation
datatrans_error_detail See datatrans documentation
datatrans_error_message See datatrans documentation
datatrans_pmethod See datatrans documentation
datatrans_refno See datatrans documentation
datatrans_reqtype See datatrans documentation
datatrans_response_code See datatrans documentation
datatrans_response_message See datatrans documentation
datatrans_status See datatrans documentation
datatrans_upp_msg_type See datatrans documentation
datatrans_upptransaction_id See datatrans documentation
dd Acronym for the payment method Direct Debit/LSV
din Acronym for the payment method Diners/Discovery

E

Name Description
eca Acronym for the payment method MasterCard
email_content_type Parameter which indicates the content type of the email
enable_jquery Parameter which indicates if jQuery is allowed on the page where the e-payment form is included.
epayment_status Parameter that indicates the status of the e-payment transaction.
epp_transaction_id System-wide unique transaction id generated from the e-payment platform. Can be used amongst others to retrieve details of a transaction or refund a transaction.
error_url Parameter indicating the redirect URL in case of an error.
es Acronym for the payment method red payment slip, ala Einzahlungsschein ohne Referenznummer
ezs Acronym for the payment method orange payment slip, aka Einzahlungsschein mit Referenznummer
ezspayment_payer_line_1 (1-4) Return value which indicates the payer lines of a payment slip
ezspayment_refno Return vales which indicates the reference number of a payment slip

F

Name Description
from_email_address Parameter which indicates the from email address for recurring payments.
from_email_name Parameter indicating the name used for recurring payments.

G

Name Description

H

Name Description

I

Name Description
iframe_container Parameter which indicates the ID of the DOM Element in which the iframe should be loaded
iframe_landing_url Parameter indicating an URL which will be called in any case (success, error, and cancel event).

J

Name Description

K

Name Description

L

Name Description
language Parameter which indicates the language of the returned e-payment forms

M

Name Description
merchant_config_id Parameter which indicates the config ID of the merchant
Merchant Transaction ID A per merchant unique string identifying a transaction
method Parameter which indicates the HTTP method; Currently only POST is supported
mobile_mode Parameter which indicates if the e-payment forms should be optimized for mobile devices.
msisdn Parameter which indicates a mobile phone number

N

Name Description

O

Name Description

P

Name Description
parameter_count Return value which indicates the number of parameters returned
payer_line1 (1-4) Parameter which may be used when an payment slip is generated
payment_method Parameter which indicates the payment method
Payment Method Describes the method used for a transaction. I.e. VISA, Postcard, etc.
payment_provider Parameter which indicates the payment provider
Payment Provider An organisation which transfers the money from the buyer to the merchant
paypal_amount See PayPal documentation
paypal_currency See PayPal documentation
paypal_customer_city See PayPal documentation
paypal_customer_country_code See PayPal documentation
paypal_customer_email See PayPal documentation
paypal_customer_firstname See PayPal documentation
paypal_customer_id See PayPal documentation
paypal_customer_lastname See PayPal documentation
paypal_customer_street See PayPal documentation
paypal_customer_street2 See PayPal documentation
paypal_customer_salutation See PayPal documentation
paypal_customer_status See PayPal documentation
paypal_customer_zip_code See PayPal documentation
paypal_hold_reason See PayPal documentation
paypal_payment_status See PayPal documentation
paypal_pending_reason See PayPal documentation
paypal_order_time See PayPal documentation
paypal_reversal_reason See PayPal documentation
paypal_transaction_id Transaction ID of a PayPal transaction
paypal_transaction_type See PayPal documentation
pef Acronym for the payment method Postfinance E-Finance
pex Acronym for the payment method PayPal ExpressCheckout
pfc Acronym for the payment method Postfinance Card
pollstatus_url Parameter that indicates the URL of the SMS status of a SMS e-payment transaction.
popup Parameter which indicates if the PayPal window should be opened in a popup (true or false)
pos Acronym for the payment method Post Finance
protocol Parameter which indicates the HTTP protocol (http or https allowed)

Q

Name Description

R

Name Description
recurrentpayment _subscription_api Parameter which indicates the path to the recurring payment API
recurrent_payment_subscribed_template Parameter that indicates the path to the subscribed template.
recurrent_payment_unsubscribed_template Parameter that indicates the path to unsubscribed template.
recurrent_payment_payment_details_updated_template Parameter which indicates the path to recurring payment subscription template
recurring Parameter which indicates if the transaction is a recurring payment transaction
recurring_interval Parameter which indicates the interval of the recurring payment
refno Parameter which indicates the reference number of the payment slip

S

Name Description
secure_cookie Directing browsers to use cookies only via secure/encrypted connections.
smtp_encription Parameter that indicates the encryption method used.
smtp_host Parameter which indicates the host name
smtp_password Parameter which indicates the password
smtp_port Parameter which indicates port
smtp_username Parameter which indicates the username
sms Acronym for the payment method SMS
smspayment_status Return value which indicates the status of the payment
stored_customer_city Parameter which indicates customer details
stored_customer_country Parameter which indicates customer details
stored_customer_email Parameter which indicates customer details
stored_customer_fax Parameter which indicates customer details
stored_customer_firstname Parameter which indicates customer details
stored_customer_lastname Parameter which indicates customer details
stored_customer_name Parameter which indicates customer details
stored_customer_phone Parameter which indicates customer details
stored_customer_street Parameter which indicates customer details
stored_customer_street2 Parameter which indicates customer details
stored_customer_zip_code Parameter which indicates customer details
subscription_charged_webhook Parameter which indicates the URL for recurring payment charged webhook
subscription_renewed_webhook Parameter which indicates the URL for recurring payment renewed webhook
subscription_subscribed_webhook Parameter which indicates the URL for recurring payment subscribed webhook
success_url -

T

Name Description
test_mode Parameter which indicates the mode of the e-payment transaction
transaction_api Merchant Transaction ID
transaction_id Parameter which indicates the transaction ID
trigger_event Parameter that indicates which trigger will be enabled on the e-payment form.

U

Name Description

V

Name Description
vis Acronym for the payment method VISA

W

Name Description

X

Name Description

Y

Name Description

Z

Name Description

Generated by aglio on 06 Feb 2017