Integration

The approach of marrying the OAuth 2.0 protocol to sign2pay's secure mobile payments was dubbed internally as Authature. The Authature protocol supports the standard authorization code grant type.

In order to complete a purchase, you should implement the flow described below in your application. For On-Demand payment integration, the flow must include these 3 sequential steps: requesting access permission, obtaining an access token, and requesting the payment.

Request

Authorization happens with or without a signature of your user.

Obtaining an Authorization Code with your users' signature

Method: GET

Authorization URI: https://app.sign2pay.com/oauth/authorize

Parameter Required Type Description
client_id yes Number The client id issued to your Sign2Pay Client Application.
redirect_uri yes String The uri the user will be redirected to after authorization. Must have the same domain as the application. Must match the redirect_uri specified in the Sign2Pay Merchant Admin application settings.
scope yes String A space separated string list of permission scopes. They include: payment, preapproval, authenticate, capture. For on-demand payments, the scope must be specified as payment.
state yes String A session string that your client uses to maintain state between requests.
response_type yes String Must be specified as code.
amount yes/no Integer When requesting the payment scope, the amount of payment in cents is required. Otherwise, it is optional.
ref_id yes/no String (max 35 chars) When requesting the payment scope, your unique id for your purchase is required. Otherwise, it is optional.
locale no String The ISO 3166-1 alpha-2 code reflecting the language to render the Sign2Pay UI in.
meta_data no Hash Extra optional data attached to a payment. This is not shown to a customer. Format must follow meta_data[KEY]=VALUE in the request.
user_params[identifier]* no String The identifier address used to identify the user
user_params[first_name] no String The user's first name
user_params[last_name] no String The user's last name
user_params[mobile]* no String Mobile number for this user including country code (ie: +32484831234)
user_params[address] no String Street address for this user including house/apt number
user_params[city] no String City of the user's address
user_params[postal_code] no String User's postal code
message no String This is an unique message to add to the transaction. When not provided, the parameter ref_id is used.
* Can be used as an identifier.

Example Request URL:

      https://app.sign2pay.com/oauth/authorize?
      client_id=c509fd593742b6b08adf4f0b41a4801c&
      response_type=code&
      redirect_uri=http%3A%2F%2Fexample.com%2Foauth%2Fcallback%2Fc509fd593742b6b08adf4f0b41a4801c&
      state=8e108029ade0d75a1e134d1404f44325eec53356ae665ba21cba1bf8559f5e8d&
      scope=payment&
      ux_style=popup&
      user_params%5Bidentifier%5D=nick%40sign2pay.com&
      user_params%5Bfirst_name%5D=Nick&
      user_params%5Blast_name%5D=Lloyd&
      amount=1995&
      ref_id=5795c838647f84abea6719cb1e15f2ba7&
      meta_data%5Bpromo%5D=new_promo&meta;_data%5Bcampaign%5D=wintersale&
      message=Test Message

Example Popup

Obtaining an Authorization Code without your users' signature

Method: POST

Authorization URI: https://app.sign2pay.com/oauth/no-authorize

Parameter Required Type Description
client_id yes Number The client id issued to your Sign2Pay Client Application.
redirect_uri yes String The uri the user will be redirected to after authorization. Must have the same domain as the application. Must match the redirect_uri specified in the Sign2Pay Merchant Admin application settings.
scope yes String A space separated string list of permission scopes. They include: payment, preapproval, authenticate, capture. For on-demand payments, the scope must be specified as payment.
state yes String A session string that your client uses to maintain state between requests.
response_type yes String Must be specified as code.
amount yes/no Integer When requesting the payment scope, the amount of payment in cents is required. Otherwise, it is optional.
ref_id yes/no String (max 35 chars) When requesting the payment scope, your unique id for your purchase is required. Otherwise, it is optional.
locale no String The ISO 3166-1 alpha-2 code reflecting the language to render the Sign2Pay UI in.
meta_data no Hash Extra optional data attached to a payment. This is not shown to a customer. Format must follow meta_data[KEY]=VALUE in the request.
user_params[email]* no String The email address used to identify the user
user_params[first_name] no String The user's first name
user_params[last_name] no String The user's last name
user_params[mobile]* no String Mobile number for this user including country code (ie: +32484831234)
user_params[address] no String Street address for this user including house/apt number
user_params[city] no String City of the user's address
user_params[postal_code] no String User's postal code
user_params[national_registry_number]* no String User's national registry number
user_params[iban] no String User's International Bank Account Number (IBAN)
message no String This is an unique message to add to the transaction. When not provided, the parameter ref_id is used.
* E-mail, Mobile Phone number or National Registry Number can be used as an identifier.

For on-demand payments, you must include client_id, response_type, redirect_uri, scope, state, amount, and ref_id parameters with the GET request.

It is important to note that Sign2Pay employs the idea of Progressive Registration. This means that you can provide as much or as little user detail that you have available at the time, and the Identification portion of the process will request the missing detail. You can provide additonal user detail when building your payment link by passing in the optional user_params object.

Response

Once the user authorizes access, the user is redirected back to the redirect_uri you originally specified.

When the redirect uri represents a native application, the access grant is returned as a JSON object. Otherwise, the authorization code and state is appended to the redirect_uri as shown below.

A successful authorization response will include the code and state params. It will also include the optional meta_data if it was included in the original request.

Native Example:
{
  "code" : "829de1eb40385ebdfcc854e2ba94fb96",
  "state" : "x3buLJqq3iAx3buLJqq3iA",
  "meta_data" : { "promo" : "new_promo", "campaign" : "wintersale" }
}
Web Example:
https://example.com/oauth/redirect_uri?code=829de1eb40385ebdfcc854e2ba94fb96&state;=x3buLJqq3iAx3buLJqq3iA&meta;_data%5Bpromo%5D=new_promo&meta;_data%5Bcampaign%5D=wintersale

Either way, you'll need the access grant code in order to move onto the next step, exchanging it for an Access Token.

The authorization code is short lived - it will expire within 120 seconds from creation. It must be immediately transferred for an Access Token.
If there was an error in the authentication code request, your redirect_uri will receive a request containing the error and error_description params for you to parse. You can read more about handling errors here.

Next Step

Obtaining an Access Token

Exchanging Authentication Code for an Access Token

Now that you have the Authorization Code, you'll exchange it for an Access Token. This is done by sending an authenticated POST request to the exchange endpoint.

Method: POST

URI: https://app.sign2pay.com/oauth/token

Authentication: Authorization: Basic [Base64.encoded CLIENT_ID:CLIENT_SECRET]

The requirements for exchanging your Authentication Code for an Access Token are listed below.

Parameter Required Type Description
client_id yes Number The client id issued to your Sign2Pay Client Application.
code yes String The Authentication Code returned in the previous step when requesting user's permission.
state yes String The session string that your client sent with the original Authorization Request.
redirect_uri yes String The uri the user will be redirected to after payment. Must have the same domain as the application. Must match the redirect_uri specified in the Sign2Pay Merchant Admin application settings.

Example Request Header:

      Authorization: Basic YzUwOWZkNTkzNzQyYjZiMDhhZGY0ZjBiNDFhNDgwNOM6YTVjMWQyN2U0MGEzMGRkNjA2OTgyNTc4MWEyYWJlNGY=
      Content-Type: application/x-www-form-urlencoded
The Authorization: Basic authorization header is generated through a Base64 encoding of CLIENT_ID, CLIENT_SECRET per RFC 2617. You can use https://www.base64encode.org/ to see how it should be encoded.

Example Request Body:

      client_id=c509fd593742b6b08adf4f0b41a4801c&
      redirect_uri=http%3A%2F%2Fexample.com%2Foauth%2Fcallback%2Fc509fd593742b6b08adf4f0b41a4801c&
      code=829de1eb40385ebdfcc854e2ba94fb96&
      state=x3buLJqq3iAx3buLJqq3iA

Response

As this request is server side only, the Access Token is returned as a JSON object.

Included within the Access Token object are some additonal user and account details that you may find useful for display within your own application.

It is important to note that the token attribute is directly related to the account object as this is the account the user has granted you permission to use.

Example Response:

      {
        "access_token":
          {
            "token": "70ae0833466bacd744e68e38ae4ace70a7a5ad1ef302c406a35bec227abf96f6",
            "type": "bearer",
            "scopes": "payment",
            "user": {
              "first_name": "nick",
              "last_name": "lloyd",
              "identifier": "[email protected]"
            },
            "account": {
              "masked_iban": "************1437",
              "primary": true,
              "uid": "3150d493acabcb319d395037de2f03f9",
              "bank": {
                "swift": "KREDBEBB",
                "country_code": "BE",
                "logo": "https://s2p.s3-eu-west-1.amazonaws.com/banks/BE/KREDBEBB.png?1429107098",
                "has_logo": true,
                "bank_name": "KBC BANK"
              }
            },
            "expires": "2015-09-16T11:33:06.883+02:00"
          }
        }
When the scope is for "payment", and not "preapproval", the access token is short lived - it will expire in 2 minutes from creation, and can only be used for a single payment.
If there was an error in the Access Token request, your redirect_uri will receive a request containing the error and error_description params for you to parse. You can read more about handling errors here.

Next Step

Requesting Payment

Making a Payment Request

For On-Demand Payments, you'll make the payment request immediately after you receive the Access Token. This is done by sending an authenticated POST request to the payment capture endpoint.

Method: POST

URI: https://app.sign2pay.com/api/v2/payment/authorize/capture

Authentication: Authorization: Basic [encoded credentials CLIENT_ID, CLIENT_SECRET]

The requirements for making a payment request are listed below.

Parameter Required Type Description
client_id yes Number The client ID issued to your Sign2Pay Client Application.
amount yes Integer Amount of payment being requested in cents.
ref_id yes String Your unique id for your purchase.
token yes String The Access Token you just received
meta_data no Hash Extra optional data attached to a payment. This is not shown to a customer. Format must follow meta_data[KEY]=VALUE in the request.

Example Request Header:

      Authorization: Basic YzUwOWZkNTkzNzQyYjZiMDhhZGY0ZjBiNDFhNDgwNOM6YTVjMWQyN2U0MGEzMGRkNjA2OTgyNTc4MWEyYWJlNGY=
      Content-Type: application/x-www-form-urlencoded
The Authorization: Basic authorization header is generated through a Base64 encoding of CLIENT_ID, CLIENT_SECRET per RFC 2617. You can use https://www.base64encode.org/ to see how it should be encoded.

Example Request Body:

      client_id=c509fd593742b6b08adf4f0b41a4801c&
      token=bb1cd6ce37d093eb2e8c32e7ec9847b3058112b92d3868371ae5426c463dad0d&
      ref_id=123654123&
      amount=1692&
      meta_data%5Bpromo%5D=new_promo&meta;_data%5Bcampaign%5D=wintersale

Response

A successful Payment request returns a JSON object containing the "purchase_id".

Example Response:
      {
        "purchase_id": "55f980b6e6db99dba9000001"
      }

Since the payment process is now complete, the user will be redirected back to your application through the URL specified as your application's redirect_uri.

This is your opportunity to update your local object (purchase, order, payment or whatever your model is named) as "paid", and redirect your user to your next step such as a "Thanks for your purchase" page.

Don't forget this is happening server side, so you'll want to pass along the message if need be to your iOS client, or simply redirect your user in your web application.
If there was an error in the payment request, your redirect_uri will receive a request containing the error and error_description params for you to parse. You can read more about handling errors here.

Stuck on Something?

Be sure to check our FAQs, Support, or Contact Us directly.