Introduction

Welcome to Sign2Pay! This should be seen as an organic document as we are still flushing out some of the details. If any of your questions aren’t answered here, reach out and we’ll be happy to help!

Integration Overview

Sign2Pay integrates into your checkout process by first setting a few variables and including the sign2pay.js script within your checkout flow. Our script handles all of the passing of data to our API via secure POST over https. Responses from the API are listened for by a hidden iframe that is generated by our script which deals with message and error handling.

The second requirement of integrating the full Sign2Pay payment solution includes providing us with a Postback URL. This Postback URL is hosted in your own environment and is used to listen for Payment Notifications and perform updates to your backend.

Key Concepts

Risk Assessment

Sign2Pay provides you a frictionless method for your users to make a mobile payment using their IBAN and a signature. One of the reasons we guarantee these payments is because we have already built a consumer profile, and run our above industry standard Risk Assessment, before the Sign2Pay Payment Method is even presented to the user.

Sign2Pay

If the risk score from our Risk Assessment allows for it, the user can then opt to Sign2Pay. This entails adding their IBAN, and providing us a signature.

Payment Postback

Once this step has passed validation and the official SEPA mandate has been created on our side, we will send a signed POST to the Postback URL you provided during your Merchant Intake process to indicate the successful payment.

Redirect

The user is then redirected to the URL of your choice along with any parameters your site needs to finalize your process.

Merchant API (BETA)

{
   "merchant":{
      "id":"537ba23a416972867f000000",
      "name":"Ruecker-Medhurst",
      "email":"[email protected]",
      "applications":[
         {
            "id":"537b4de741697252c2040000",
            "name":"Hoppe, Shields and Stark",
            "implementation_url":"http://schmittkulas.com/valerie",
            "postback_url":"http://schustermorar.net/myra.fadel",
            "mode":"test",
            "created_at":"2014-05-20T12:43:19.881Z",
            "updated_at":"2014-05-20T12:43:19.881Z"
         },
         {
            "id":"537b4de741697252c2050000",
            "name":"Metz-Goldner",
            "implementation_url":"http://stanton.name/yvette.pagac",
            "postback_url":"http://wiegandprosacco.name/mabel",
            "mode":"test",
            "created_at":"2014-05-20T12:43:19.885Z",
            "updated_at":"2014-05-20T12:43:19.885Z"
         }
      ],
      "api_tokens":[
         {
            "token":"726599a60f2d990bbac4c065ac48371e",
            "created_at":"2014-05-20T18:43:06.755Z"
         }
      ]
   }
}

Currently, the Merchant Intake is a manual process. This gives us a chance to get to know you and make sure you are getting the best support possible. Once this process is complete, we’ll create your Sign2Pay account, and an initial Sign2Pay Merchant App.

We are testing a Merchant API which will allow you to register a merchant via JSON. After the creation, a confirmation email will be sent and the rest of the merchang on-boarding happens in the Sign2Pay environment.

The merchant profile JSON is shown on the right.

Create a merchant

# create a merchant
curl "https://sign2pay.com/api/v2/merchants.json" \
  -H "Content-Type: application/json" \
  -d "{\"merchant\":{\"email\":\"[email protected]\",\"name\":\"Widgets, Inc\"}}"
# with two embedded applications (storefronts)
curl "https://sign2pay.com/api/v2/merchants.json" \
  -H "Content-Type: application/json" \
  -d "{\"merchant\":{\"name\":\"Powlowski, Weissnat and Hayes\",\"email\":\"[email protected]\",\"applications\":[{\"name\":\"Hoppe, Shields and Stark\",\"implementation_url\":\"http://schmittkulas.com/valerie\",\"postback_url\":\"http://schustermorar.net/myra.fadel\"},{\"name\":\"Metz-Goldner\",\"implementation_url\":\"http://stanton.name/yvette.pagac\",\"postback_url\":\"http://wiegandprosacco.name/mabel\"}]}}"

The response is a Merchant

Name and email are required fields. Optionally you can include applications to be created. Every purchase must be made through one application (aka storefront). Merchants can have separate applications in test and production mode.

Attributes

Attribute Required Description Default
name yes legal business name
email yes email address
enabled no boolean true
process_payments no boolean true
website no
description no
logo no image file as a Data URI

Response codes

Code Description
201 Merchant created
400 Missing or malformed input fields
403 Validation error(s)
429 Rate limited: enhance your calm

Applications

curl "https://sign2pay.com/api/v2/applications.json" \
  -H "Authorization: Token token=\"0047f40cf37dbb5cc6301d17194ed2e2\"" \
  -H "Content-Type: application/json" \
  -d "{\"application\":{\"name\":\"Hoppe, Shields and Stark\",\"implementation_url\":\"http://schmittkulas.com/valerie\",\"postback_url\":\"http://schustermorar.net/myra.fadel\"}}"

You are encouraged to create one or more application per merchant directly in the merchant create method. Provide a separate application for each storefront. Every application must have it’s own implementation and postback URL.

Attribute Required Description
name yes storefront name
implementation_url yes URL where the requests will originate
postback_url no URL where Sign2Pay should post payment details
mode no test or production, defaults to test

To create applications for an existing merchant, you must use Token authentication. After signup you will have received an API access token to authenticate with. It is important that this access token is kept strictly private. If it ever becomes compromised, you must revoke the old access token and generate a new one as soon as possible.

Code Description
201 Application created
400 Missing or malformed input fields
401 Invalid authorization
403 Validation error(s)
429 Rate limited: enhance your calm

Access tokens

Sign2Pay uses tokens to allow access to the API. Access tokens are handed to every merchant directly after succesful registration. Store the tokens securely and pass one with every request. For protected resources, you must pass a valid token in a HTTP Token Authorization header.

Authorization: Token token="0047f40cf37dbb5cc6301d17194ed2e2"

Applications

As a merchant, you can add many applications to your Sign2Pay account. Each storefront will be a separate application.

Merchant ID

Your Merchant ID is the id of your Sign2Pay account and is required for integration of the sign2pay.js. This will be supplied to you as soon as you are setup.

Token

The application token identifies your application to our API and is required for integration of the sign2pay.js.

Sign2Pay Application Settings

The following information will be requested during the Merchant Intake process for each Sign2Pay application you’d like setup.

Implementation URL

This is the full URI including protocol, from which API requests will be made.

For example: https://www.example.com/checkout/orders/12345

Currently, the same goes for integrating via the Sign2Pay iOS Library.

Postback URL

This is the complete URL that our backend will send a POST to once we have collected all payment details, and have authorized the transaction.

For example: https://api.example.com/checkout/postback

Check Postback for full details.

Mode

If your application is in test mode, no payments will be processed associated with this application token. The Risk Assessment and Signature verification will however function as normal.

Sign2Pay iOS Library

The Sign2Pay iOS SDK simplifies 3 tasks:

  1. authorize access and usage to the Sign 2 Pay API service
  2. running risk assessments
  3. present the Sign 2 Pay overlay to kick off the payment process

Installation

Targets > Your App > Build Phases > Link Binary With Libraries.

Download our library and include it in Link Binary With Libraries.

Usage

S2PSDK
======
@interface S2PSDK : NSObject
- (id)   init:(S2PConfiguration *)configuration;
- (void) assessRiskForTransaction:(S2PTransaction *)transaction withCompletion:(void (^)(S2PResponse *response, NSError *error))completion;
- (void) sign2payFromViewController:(UIViewController *)presentingViewController;
@end

The S2PSDK class provides 3 important public methods. Each method corresponds to a step in the Sign 2 Pay flow.

Authorize Risk Assessment Payment
init: assessRiskForTransaction:error: sign2payFromViewController:

Your app should not show the Sign 2 Pay button until the SDK returns a valid risk assessment. This means you will run at least one succesfull risk assessment and evaluate it’s response type. If the response type allows a Sign 2 Pay payment you can show the relevant button.

There are a couple of helper classes that are important:

S2PConfiguration
================
@interface S2PConfiguration : NSObject
@property (nonatomic, copy) NSString *merchantId;
@property (nonatomic, copy) NSString *implementationURL;
@property (nonatomic, copy) NSString *applicationToken;
- (id) initWithMerchantId:(NSString *)merchantId implementationURL:(NSString *)referalURL applicationToken:(NSString *)applicationToken;
@end

S2PTransaction
==============
@interface S2PTransaction : NSObject
NSString *firstName;
NSString *lastName;
NSString *email;        // for transactional emails
NSString *address;
NSString *postalCode;
NSString *city;
NSString *region;
NSString *country;      // iso code
NSNumber *amount;       // in cents, no points or other delimeters
NSString *referenceId;  // your shopping cart reference

// init an S2PTransaction with a provided camelCased dict and error
+ (instancetype) transactionWithDictionary:(NSDictionary *)dictionary error:(NSError * __autoreleasing *)error;
@end

S2PResponseType
===============
// the possible values of an S2PResponse type property

typedef NS_ENUM(NSInteger, S2PResponseType){
    S2PResponseTypeNil,
    S2PResponseTypeDenied,
    S2PResponseTypeFailure,
    S2PResponseTypeAllowed,
    S2PResponseTypeExpand,
    S2PResponseTypeProcessing,
    S2PResponseTypeRedirect,
    S2PResponseTypeCount
};

Authorization

// init the sdk in e.g. your app delegate

#import "S2PSDK.h"

- (void) setupSign2Pay
{
    S2PConfiguration *configuration;
    // Replace the values with your personal credentials.
    // You can find them in your dashboard.

    NSString *merchantId        = @"e87654b84e6963064d000000";
    NSString *implementationURL = @"http://my.eshopexperience.com/checkout";
    NSString *token             = @"67ewbc135370611247020000";
    configuration = [[S2PConfiguration alloc] initWithMerchantId: merchantId
                                               implementationURL: implementationURL
                                                applicationToken: token ];
    sign2pay = [[S2PSDK alloc] init:configuration];
}

Your app needs authorization in order to use Sign 2 Pay’s risk assessment service and payments later on.

The SDK provides a S2PConfiguration class to make this process as easy as possible. Initialize an instance of S2PConfiguration with your personal credentials.

[S2PSDK init:] does not trigger a web request.
It just sets the necessary information on the S2PSDK instance.

Risk Assessments

/*
S2PTransaction
---------------
example usage:
create a transaction object with the information collected
from the current user
*/
NSError *transactionError = nil;
// no network request is made at this point
S2PTransaction *transaction = [S2PTransaction transactionWithDictionary:self.formDictionary error:&transactionError];
if( transactionError )
{
  // handle error
  // at this point you'll get a hardcoded error stating the email address was not provided
  // better error messages are in the making
}

You should trigger a risk assesment any time you can provide the API with an updated, valid form. The assessment runs on a background thread and should not block your UI. You need an instance of S2PSDK and an instance of S2PTransaction in order to trigger an assessment.

You can pass in a valid S2PTransaction when using S2PSDK’s assessRiskForTransaction:withCompletion method. You can create an instance of a transaction by providing an NSDictionary that holds appropriately named keys with their values to the transactionWithDictionary:error: method.

S2PTransaction *transaction = [S2PTransaction transactionWithDictionary:self.formDictionary error:&transactionError];

[[s2pSDK assessRiskForTransaction:transaction withCompletion:^(S2PResponse *response, NSError *error) { ... }];

You can evaluate response.type inside that completion block.

These are the possible response types: S2PResponseTypeNil,S2PResponseTypeDenied,S2PResponseTypeFailure,S2PResponseTypeProcessing,S2PResponseTypeRedirect,S2PResponseTypeCount

Sign2Pay overlay

Once the risk assessment allows the use of Sign2Pay as payment provider you can present your own custom “Pay with Sign2Pay” button. When the user clicks the button the SDK can present the Sign2Pay overlay which will take care of the payment process.

[s2pSDK sign2payFromViewController:self];

You can listen for notifications in order to anticipate the closing of the Sign2Pay viewcontroller. The SDK provides access to const values to minimize typos: - kS2PWillCloseS2PPaymentViewController - kS2PDidCloseS2PPaymentViewController

When one of these notifications comes in, the object property contains a S2PResponseType value.

If the value is equal to S2PResponseTypeRedirect the payment was successful. In all other cases the payment was not successful.

The possible values of the other S2PResponseTypes you can receive should be self explanatory.

Sign2Pay.js

Integrating Sign2Pay into your checkout page is similar to adding Google Analytics to your page. It involves setting up access to a few variables, and including the script that will add the sign2pay.js to your page asynchronously.

There are a few ways to integrate Sign2Pay into your site/application. How your checkout process works will determine the method you’ll use.

Single Page Checkout

This can be included anywhere in your page, just don’t forget to wrap in a <script> tag.

  window.sign2PayOptions = {
    merchant_id: 'e29550b84e6963064d000000',
    token: '52fa46da537061f622000000',
    el : '#sign2pay',
    checkout_type: 'single',
    domain : "sign2pay.com",
    map:{
      first_name: '#consumer_first_name',
      last_name: '#consumer_last_name',
      email: '#consumer_email',
      address: '#consumer_address',
      postal_code: '#consumer_postal_code',
      city: '#consumer_city',
      region: '#consumer_region',
      country: '#consumer_country',
      amount: #consumer_amount,
      ref_id : '#order_id'
    }
  };
  (function() {
    var s = document.createElement("script");
    s.type = "text/javascript";
    s.src = "//sign2pay.com/merchant.js";
    s.async = true;
    t = document.getElementsByTagName('script')[0];
    t.parentNode.insertBefore(s, t);
  })();

amount is provided as an integer reflecting cents.

You’ll use the Single Page integration if:

or

and

The Map Object

The map object within sign2PayOptions provides the means for us to parse your page for values either by providing css selectors OR if a js function is provided, we’ll call it and use the return value. The function approach is useful say if your site/application stores the amount in euros.

We continuously ‘watch’ your page using the map until the required params have been populated, at which point, the Sign2Pay Risk Assessment is initiated.

It should be noted that if any of the params are changed after a Risk Assessment has been run, a new one will be initiated using the new param value(s). Ie. if a user changes their email address or your site/application updates the amount based on shipping method, we’ll kick off a new Risk Assessment.

Multi Page Checkout

All values shown as ‘<example>’ should be replaced as strings except amount, which is a number representing the amount in cents.

  window.sign2PayOptions = {
    merchant_id: 'e29550b84e6963064d000000',
    token: '52fa46da537061f622000000',
    el : '#sign2pay',
    checkout_type: 'multi',
    domain : "sign2pay.com",
    first_name: "<first_name>",
    last_name: "<last_name>",
    email: "<email>",
    address: "<address>",
    postal_code: "<postal_code>",
    city: "<city>",
    region: "<region>",
    country: "<country>",
    amount:<amount in cents>,
    ref_id : "<your order id>",
  };
  (function() {
    var s = document.createElement("script");
    s.type = "text/javascript";
    s.src = "//sign2pay.com/merchant.js";
    s.async = true;
    t = document.getElementsByTagName('script')[0];
    t.parentNode.insertBefore(s, t);
  })();

You’ll use the Multi Page integration if:

and

The Multi Page intergration looks similar to the Single Page one, however, each of the required param’s values are set rather than supplying a map to retrive them.

On Demand

jQuery(document).ready(function($) {
  (function() {
    var mySleep=setInterval(function(){sleep()},3000);
    function sleep(){
      if(typeof(window.s2p) !== "undefined" ){
        window.clearInterval(mySleep);
        window.sign2PayOptions = {
          merchant_id: "e29550b84e6963064d000000",
          token: "52fa46da537061f622000000",
          el : '#sign2pay',
          address: "Any Street 53",
          amount: 1780,
          checkout_type: "multi",
          city: "Anytown",
          country: "BE",
          domain: "sign2pay.com",
          email: "[email protected]",
          first_name: "Pink",
          last_name: "Floyd",
          postal_code: "2018",
          ref_id: "b133441981683b86"
        };
        window.s2p.options.initTransport();
      }
    }
  })();
});

If you want/need control over when to initiate the Sign2Pay Risk Assessment, it is possible to call it from your own js, providing that all required param values are available.

In this scenario, you include the asynchronous script as usual, but without providing the window.sign2payOptions object. When you have all of the required data, simply create the window.sign2payOptions, and call window.s2p.options.initTransport();.

To ensure the sign2pay.js has completed loading and the s2p namespace is available for use, it’s wise to wrap this call within an interval. An example of how you might approach this is shown on the right.

Risk Assessment

As soon as the sign2pay.js has all of the required variables, a Risk Assessment is initiated in the background. The result of the Risk Assessment will determine whether or not the Sign2Pay Payment Method will be offered to the current user.

On our end, by using a range of machine learning techniques, including behaviour analysis and predictive modeling, we assess the risk of the proposed transaction in realtime. In additon, the details of the transaction must pass through several validation checkpoints that ensure your protection from fraudulent or abusive behaviour.

If the Risk Assessment returns an acceptable score, the Sign2Pay Payment Method option will appear amongst your payment options.

If the Risk Assessment denies the transaction, depending on the reason, the Sign2Pay option may be displayed, but disabled depending on the reason for denial.

Sign2Pay

If your consumer is a first time Sign2Pay user, they will be presented with the Sign2Pay overlay requesting their IBAN account. This overlay is sandboxed from your checkout page within a secure iFrame that sits on top of your checkout page, and can be cancelled at any time.

IBAN

Your consumer’s IBAN is validated on several levels. Once validated, we perform a lookup of the issuing bank, it’s address, and the matching BIC which gets cached with their account info.

If this is a returning consumer, we have a valid IBAN attached to their Sign2Pay account, and their account has been verified, the user will be presented the signature overlay directly with the opportunity to change the IBAN they wish to use.

Signature

The signature of a first time consumer is stored to their Sign2Pay account which will later need to be verified before being able to process any further transactions via Sign2Pay.

For a returning consumer, their signature is compared to those we have on file across a 4 tier algorythm to determine it’s authenticity. To find out more about the comparison and validation process, ask us!

The Payment Postback

Once we’ve collected all of the required data and signature for a valid SEPA mandate, we’ll perform a serverside POST to the URL you provided during your Merchant Intake process so that you can update your backend accordingly.

POST

Parameter Type Description
merchant_id string your Sign2Pay Merchant ID
purchase_id string the Sign2Pay ID of this transaction
ref_id string your internal reference ID to retrieve the order
amount number the purchase amount in cents
status string “mandate_valid” indicates you will receive payment
token string a randomly generated string with length 50.
timestamp string the number of seconds passed since January 1, 1970 (UTC)
signature string string with hexadecimal digits generated by HMAC algorithm

To verify the webhook is originating from Sign2Pay you need to:

Response

After validating the authenticity of the POST request, you may want to update your order record status as paid (or whatever your internal process is). Once this is complete, a response is required for use to redirect your consumer appropriately.

Parameter Type Description
status string “success” or “failed”
redirect_to string the URL the consumer should be redirected to
params string any additonal params you would like passed to your redirect_url (ie.: authorization_code, user_message etc)

Redirect

When the Postback process is complete, your consumer will be directed to the url provided in the postback response with any params you’ve returned appended to the query string.

This is a bit different if you are using the Sign2Pay iOS Library as we instead broadcast an event your app can listen for.

Errors

The Sign2Pay API uses the following error codes:

Error Code Meaning
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.