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.

Supported Payment Methods 

 

The following list represents all available payment methods and their abbreviations to initiate transactions via our API.

Payment Method Abbreviation Recurring Remarks
American Express amx
Cymba cym only GB
Diners Club din
Direct Debit/Lastschriftverfahren dd
Discovery dis
EBS ebs - only available in India
Elektronisches Lastschriftverfahren elv -
EPS Überweisung eps - only available in Austria
MasterCard eca
MasterPass vis
Payment Slip es -
PayPal pp Recurring payments currently not available in Germany and China
PostFinance Card pfc only available in Switzerland
PostFinance E-Finance pef - only available in Switzerland
SEPAone Lastschriftverfahren sod
Sofortüberweisung dib -
Stripe stp check stripe website for supported countries
Swiss Payment Slip with Reference Number ezs - only available in Switzerland
Swiss Text Message sms only available in Switzerland
Twint twi - only CH
Visa vis

How to test payments 

 

Some of the payment providers allow to test their payment methods with specific details when using test_mode true.

Datatrans Test Credit Cards

Note that all card numbers only work in when using test_mode true. Productive cards cannot be processed with test_mode true.

Card Type Card Number Exp Date CVV Test Rule
American Express 375811111111115 12/2018 1234 With limit
American Express 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 Club 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)

Ingenico Test Credit Cards

Checkout Ingenico Integration Guides

Ingenico lists the test cards with a Payment product ID. The list below shows Ingenico Payment Product Ids and their corresponding cart type.

Card Type Payment product ID
American Express 2
MasterCard 3
Visa 1
Diners 132
Discover 128
JCB 125

The complete list can be found on https://epayments-api.developer-ingenico.com/s2sapi/v1/en_US/java/paymentproducts.html

Adyen Test Credit Cards

The complete list is available at https://docs.adyen.com/developers/test-cards/test-card-numbers. It is possible to use special card holder names to decline a transaction, as detailed at https://docs.adyen.com/developers/risk-management/error-code-testing.

For 3D Secure authentication, the username is user and the password is password.

Card Type Card Number Exp Date CVV 3D Secure
American Express 370000000000002 10/2020 7373 -
American Express 345177925488348 10/2020 7373
MasterCard 2223000048410010 10/2020 737 -
MasterCard 5212345678901234 10/2020 737
Visa 4111111111111111 10/2020 737 -
Visa 4212345678901237 10/2020 737
Diners 36006666333344 10/2020 737 -
JCB 3569990010095841 10/2020 737 -
JCB 3569990010095833 10/2020 737

PayPal

You have to create a Sandbox Account. Check also our documentation

Test IBAN for Direct Debit (dd)

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

  • CH9300762011623852957

  • DE89370400440532013000

  • AT611904300234573201

  • GB29NWBK60161331926819

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.


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 a view payment methods are supported for recurring payments (verify that when recurring is true, the correct payment method is selected - see Supported Payment Methods). 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.

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).

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

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.

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
Bre2 Link to Bre2 SMS donations - - - - -
Ela Link to Ela ela/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.

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

Lema/Lumnezia Widget

Lema Widget is the most powerful widget in the matter of flexibility and extensibility. It supports one-time and recurring payments 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 ‘bre2’, ‘ela’, or ‘lema’ 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 and Lema

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

New style

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

instead of the deprecated style

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

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = 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

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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 || [];
    window.rnwWidget.configureWidget.push(function(options) {
        options.defaults['stored_my_parameter1'] = 'test1';
    });
    window.rnwWidget.configureWidget.push(function(options) {
        options.defaults['stored_my_parameter2'] = 'test2';
    });
</script>

The code above add the parameter “stored_my_parameter1” with value “test1” 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
    window.rnwWidget.constants.events.MULTIPLE_INTERNAL_RETURN_EXECUTIONS
</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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(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 MULTIPLE_INTERNAL_RETURN_EXECUTIONS

<script type="text/javascript">
    window.rnwWidget = window.rnwWidget || {};
    window.rnwWidget.configureWidget = window.rnwWidget.configureWidget || [];
    window.rnwWidget.configureWidget.push(function(options) {
        options.widget.on(window.rnwWidget.constants.events.MULTIPLE_INTERNAL_RETURN_EXECUTIONS, function(event) {
            console.log(event);
            console.log(event.internalReturnExecutions); //returns number of requests
            console.log(event.payment);
            console.log(event.paymentStatus);
        });
    });
</script>

In some rare cases (e.g. unstable or lost internet connection) the response html page can be loaded more than once. In this cases this event will be triggered. Be aware that the payment and paymentStatus can be undefined. In this case you should show a message to the user that he has to contact your organisation.

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.


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).

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

Generated by aglio on 26 Apr 2018