Signing
Signature scopes simplify contract and agreement signing online. It is equivalent to using your passport or other official ID for signing purposes.
Ensuring the safety of your identity is crucial, and pasby™ takes measures to prevent identity theft.
pasby™ signature flows substitutes these use cases:
-
Use of OTP codes for transaction confirmations.
-
Official Tax Declarations
-
Real estate paper deals
-
Medical agreements
Above is an ideal example of a signature flow from our past version
On this note the signature scopes support 2 flow action types:
- sign
- confirm
Each flow action acts differently when interfaced with by pasby™-users and their request bodies differ from each other.
Flow action - sign
A signature flow controlled by the sign action requires such a request body.
Request Body
{
// ...,
"action": "sign",
"webhook": {
"host": "{{web-hook-endpoint i.e https://bucket.ts}}",
"reference": "{{web-hook-reference}}"
},
"payload": "Describe signature intent"
}
A webhook must be provided for any sign action. The webhook parameters are described:
- "host": (string) Host url
- "reference": (string) Something to help you identify our response
Flow action - confirm
A signature flow controlled by the confirm action requires such a request body.
Request Body
{
// ...,
"action": "confirm",
"payload": "Describe signature intent"
}
Signature flows of the confirm action use a simple request body and can be easily flow:ping for state changes.
This differences are only observed in v2 signature endpoints. pasby™ v1 signature endpoints will always require a webhook present in your request body no matter the flow action.
The signature model
A signature flow model will contain information about the flow reference ID, its date of creation and expected expiration, the IP address where this flow originated, your apps' information, and a signature response from pasby™ servers.
Properties
- Name
id- Type
- string
- Description
Unique identifier for this flow.
- Name
consumer- Type
- string
- Description
The ID of the flow creating apps organisation.
- Name
app- Type
- string
- Description
The ID of the flow creating app.
- Name
name- Type
- string
- Description
The alphabetic name of the flow creating app.
- Name
user- Type
- string
- Description
pasby™ user.
- Name
mode- Type
- string
- Description
e-ID mode of flow; would always be signature in this case.
- Name
iat- Type
- number
- Description
Timestamp of request creation in unix format.
- Name
exp- Type
- number
- Description
Timestamp of request expiration in unix format.
- Name
signature- Type
- string
- Description
jwt signature stamp from pasby™-server.
- Name
ip- Type
- string
- Description
IP address of where flow originated from.
- Name
useragent- Type
- string
- Description
Identifies the application or operating system which propagated the flow request.
- Name
payload- Type
- string
- Description
The description of the flow intent.
Same device
The ---:same scope in pasby™ is otherwise called Autosign flow. The most effective form of pasby is Mobile pasby™, which works well on mobile phones and tablets. pasby™-users use it with a security code, facial recognition, or fingerprints, depending on the device and preferences.
signing:same in this case adopts both the Autosign and Direct start mechanism.
Same-device flows occur when the user visits a service provider's application (web/mobile) on the same device as the device on which their pasby™ is installed.
Signature flows that begin this way are automatically picked up and handled by the pasby app once a pasby button variant is clicked/pressed/engaged.
Request Body
| Key | Type | Description | Optional |
|---|---|---|---|
nin | (text) | The unique NIN identifier of an African national. | NO |
action | (text) | Flow action to be performed | NO |
webhook | (object) | Provides a webhook reference and host to return signature status was processed. | if v2 endpoint and action type is confirm |
payload | (sting) | Describe the action intent to your user | NO |
Request
cURL "https://s.pasby.africa/api/v1/signing/same-device" \
-H "x-access-secret: snb_" \
-H "x-api-key: bk-test_" \
-d "{"action": "sign", "nin": "12345678910", "webhook": { "reference": "some_ref", "host": "https://my-endpoint.site.com"}, "payload": "Sign documents online and more"}"
Request
cURL "https://s.pasby.africa/api/v2/signing/same-device" \
-H "x-access-secret: snb_" \
-H "x-api-key: bk-test_" \
-d "{"action": "sign", "nin": "12345678910", "webhook": { "reference": "some_ref", "host": "https://my-endpoint.site.com"}, "payload": "Sign documents online and more"}"
See pasby™ demo sample code server to better understand how to use autosign flow with the SDKs.
Response
{
"status": "successful",
"reason": "Signature request created",
"data": {
"link": "https://open.pasby.africa/auth/?mode=signature&id=req_1707024462-VEGN&source=mobile&nin=83491998057",
"request": {
"id": "req_",
"consumer": "bcn_•••••••",
"app": "app_•••••••",
"name": "Your app name",
"mode": "signature",
"action": "confirm",
"user": "12345678910",
"signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6InJlcV8xNzA3MDI0NDYyLVZFR04iLCJtb2RlIjoic2lnbmF0dXJlIiwiYWN0aW9uIjoiY29uZmlybSIsIm5hbWUiOiJCaXZyYSIsInVzZXJhZ2VudCI6IlBvc3RtYW5SdW50aW1lLzcuMzYuMSIsImNvbnN1bWVyIjoiYmNuX2MyNDMxZTY2LWE3ZDctNDA2Zi04YzI4LTcxNWM5ZGM3MjhlMyIsInBheWxvYWQiOiJDb25maXJtIHlvdXIgcHVyY2hhc2UgZm9yIGFjY2VzcyB0byB4eXogd29ya3NwYWNlIiwiYXBwIjoiYXBwXzAzYzY5YzUwLTdhNGEtNWJhYS1iYTgyLWFhODEwODRhMTQ5ZSIsInVzZXIiOiJiaWRfODM0OTE5OTgwNTciLCJpcCI6IjE1NC4xMTMuMTU1LjYiLCJpYXQiOjE3MDcwMjQ0NjIsImV4cCI6MTcwNzAyNTE4Mn0.MZFCABglrMETPfHLCDksV8ZwfsYYh-ohSEMHFP98z-Q",
// ....
}
},
// ...
}
Response body
| Object | Description |
|---|---|
request | Standard signature flow data model |
link | On the client end you call upon this string/url to begin signature flow. |
signing:same returns a link object on a successful response. Once received, this link object should be opened on the client's end.
If the user has an active pasby on his/her device, the pasby™-app will automatically handle this signature flow.
Otherwise, the user will be shown a step-by-step guide for getting and activating a pasby for their national identity.
Wildcard
The signing:wildcard scope in pasby™ is otherwise called Secure sign. This eliminates the need for users to write their NINs or any other identifier when trying to interact with your platform.
Secure sign: Use a QR code mechanism to begin a signature flow. The QR code data is returned as seeds objects in the JSON response from pasby™. You must then present these seeds randomly as a QR code for your user audience to scan.
signing:wildcard is ideal when the user visits a service provider on one device and uses the pasby™-app on another device.
Once the user scans any of the displayed QR codes created by your client with their pasby™-app, a session is made for just that user and your app. It's a first-pick, first-serve mechanism, meaning any other scans will be automatically void.
Request Body
| Key | Type | Description | Optional |
|---|---|---|---|
action | (text) | Flow action to be performed | NO |
webhook | (object) | Provides a webhook reference and host to return signature status was processed. | if action type is confirm |
seeds | (number) | Number of unique flow codes to generate for QR code generation purpose | |
payload | (sting) | Describe the action intent to your user | NO |
Request
cURL "https://s.pasby.africa/api/v2/signing/wildcard" \
-H "x-access-secret: snb_" \
-H "x-api-key: bk-test_" \
-d "{"action": "sign", "seeds": 4, "webhook": { "reference": "some_ref", "host": "https://my-endpoint.site.com"}, "payload": "Sign documents online and more"}"
See pasby™ demo sample code server to better understand how to use secure sign flow with the SDKs.
Response
{
"status": "successful",
"reason": "Signature request created",
"data": {
"request": {
"id": "req_",
"consumer": "bcn_•••••••",
"app": "app_•••••••",
"name": "Your app name",
"mode": "signature",
"action": "confirm",
"user": "",
"signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6InJlcV8xNzE0NzAyMjk4LXdmRFoiLCJtb2RlIjoic2lnbmF0dXJlIiwiYWN0aW9uIjoic2lnbiIsIm5hbWUiOiJCaXZyYSIsInVzZXJhZ2VudCI6IlBvc3RtYW5SdW50aW1lLzcuMzguMCIsImNvbnN1bWVyIjoiYmNuX2MyNDMxZTY2LWE3ZDctNDA2Zi04YzI4LTcxNWM5ZGM3MjhlMyIsInBheWxvYWQiOiJTaWduIHlvdXIgbmFtZSBmb3IgYWNjZXNzIHRvIHh5eiB3b3Jrc3BhY2UiLCJhcHAiOiJhcHBfMDNjNjljNTAtN2E0YS01YmFhLWJhODItYWE4MTA4NGExNDllIiwidXNlciI6IiIsImlwIjoiOjoxIiwiaWF0IjoxNzE0NzAyMjk4LCJleHAiOjE3MTQ3MDMwMTh9.OL96y3FJtcNu2EMtsh220SdxU9SLPWYTZ5gWQmu2CVs",
// ....
},
"seeds": [
"pasby://cef9e405bc99eff7d7f749055562fa495747e3-vi(ebe0d7f367cedfc39efbac3fb402996c)",
// ...
]
},
// ...
}
Response body
| Object | Description |
|---|---|
request | Standard signature flow data model |
seeds | On the client end you create an animated QR code for scanning by randomly shuffling the unique flow codes found in this array. |
signing:wildcard returns a seed array object on a successful response. Use the string contents of this array to generate on your client-end a QR code for your user audience to scan.
The user will have to open the pasby app and then scan the QR code to process your flow request.
This scope only attributes a user to your signature flow if their pasby™ was the first to pick up the flow request as it was created. Using this scope, you cannot direct an identification request to anyone's NIN.
Different device
The ---:another scopes in pasby™ are a unique type of flow requests which adopts Direct start.
This scope type require a NIN (National Identification Number) to operate.
Direct start: Uses a user's NIN entry to begin an identification flow.
identification:another will immediately propagate a flow request to the pasby™-user's devices to process his/her consent to your identification flow.
To protect users and businesses, there will be an introduction of restricted scopes from 1st of October 2024.
The identification:another, signature:same, signature:another and document:sign will be greatly affected by these changes.
Request Body
| Key | Type | Description | Optional |
|---|---|---|---|
nin | (text) | The unique NIN identifier of an African national. | NO |
action | (text) | Flow action to be performed | NO |
webhook | (object) | Provides a webhook reference and host to return signature status was processed. | if action type is confirm |
payload | (sting) | Describe the action intent to your user | NO |
Request
cURL "https://s.pasby.africa/api/v1/signing/different-device" \
-H "x-access-token: {bearer-token}" \
-H "x-api-key: bk-test_" \
-d "{"action": "sign", "nin": "12345678910", "webhook": { "reference": "some_ref", "host": "https://my-endpoint.site.com"}, "payload": "Sign documents online and more"}"
Request
cURL "https://s.pasby.africa/api/v2/signing/different-device" \
-H "x-access-secret: snb_" \
-H "x-api-key: bk-test_" \
-d "{"action": "sign", "nin": "12345678910", "webhook": { "reference": "some_ref", "host": "https://my-endpoint.site.com"}, "payload": "Sign documents online and more"}"
Response
{
"status": "successful",
"reason": "Signature request created",
"data": {
"request": {
"id": "req_",
"consumer": "bcn_•••••••",
"app": "app_•••••••",
"name": "Your app name",
"mode": "signature",
"action": "confirm",
"user": "12345678910",
"signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6InJlcV8xNzA3MDI0NDYyLVZFR04iLCJtb2RlIjoic2lnbmF0dXJlIiwiYWN0aW9uIjoiY29uZmlybSIsIm5hbWUiOiJCaXZyYSIsInVzZXJhZ2VudCI6IlBvc3RtYW5SdW50aW1lLzcuMzYuMSIsImNvbnN1bWVyIjoiYmNuX2MyNDMxZTY2LWE3ZDctNDA2Zi04YzI4LTcxNWM5ZGM3MjhlMyIsInBheWxvYWQiOiJDb25maXJtIHlvdXIgcHVyY2hhc2UgZm9yIGFjY2VzcyB0byB4eXogd29ya3NwYWNlIiwiYXBwIjoiYXBwXzAzYzY5YzUwLTdhNGEtNWJhYS1iYTgyLWFhODEwODRhMTQ5ZSIsInVzZXIiOiJiaWRfODM0OTE5OTgwNTciLCJpcCI6IjE1NC4xMTMuMTU1LjYiLCJpYXQiOjE3MDcwMjQ0NjIsImV4cCI6MTcwNzAyNTE4Mn0.MZFCABglrMETPfHLCDksV8ZwfsYYh-ohSEMHFP98z-Q",
// ....
}
},
// ...
}
Response body
| Object | Description |
|---|---|
request | Standard Identification flow data model |
In a situation where the provided NIN hasn't been linked to pasby™, find more information on the non-existent identity.