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. |
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
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. |
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.
Next Step
Obtaining an Access TokenExchanging 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
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"
}
}
Next Step
Requesting PaymentMaking 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
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.