Signing

Same-device, different-device, and wildcard signing with sign and confirm actions — full examples.

Signature scopes replace OTP confirmations, paper tax filings, real-estate deals, and medical consent with identity-bound sign and confirm flows.

Sandbox base URL: https://s.pasby.africa

Server-side examples use @finsel-dgi/pasby (pasby.signing.*). Initialize once with apikeyAuth, appSecretKey, and basePath.

Supported actions: sign (cryptographic signature, requires webhook on v2) and confirm (transaction confirmation, track with ping only on v2).

On v1 signing endpoints, a webhook is required for every action. On v2, only sign requires a webhook; confirm does not.

Request body by action

sign — webhook required on v2:

sign action

{
  "action": "sign",
  "nin": "12345678901",
  "payload": "Sign the service agreement",
  "webhook": {
    "host": "https://your-app.com/pasby/events",
    "reference": "order-789"
  }
}

confirm — no webhook on v2:

confirm action

{
  "action": "confirm",
  "nin": "12345678901",
  "payload": "Confirm your purchase"
}

Signature model

idstring
Unique flow identifier.
consumerstring
Organisation id.
appstring
App id.
namestring
App display name.
userstring
Target user NIN.
modestring
Signature mode.
iatnumber
Created-at unix timestamp.
expnumber
Expiration unix timestamp.
signaturestring
JWT stamp from pasby server.
payloadstring
Intent text shown to the user.

Same device

POST /api/v2/signing/same-device · Scope: signing:same · Autosign

User visits your app on the same device as pasby. Returns a link to open (often open.pasby.africa/auth/?mode=signature&…).

Body field	Type	Required	Notes
`nin`	string	Yes	Target NIN
`action`	string	Yes	`sign` or `confirm`
`payload`	string	Yes	User-visible intent
`webhook`	object	If `sign` on v2	`host` + `reference`

curl -sS -X POST "https://s.pasby.africa/api/v2/signing/same-device" \
  -H "x-api-key: bk-test_YOUR_KEY" \
  -H "x-access-secret: YOUR_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sign",
    "nin": "12345678901",
    "payload": "Sign documents online",
    "webhook": {
      "host": "https://your-app.com/pasby/events",
      "reference": "doc-sign-001"
    }
  }'

201 Created

{
  "status": "successful",
  "reason": "Signature request created",
  "data": {
    "link": "https://open.pasby.africa/auth/?mode=signature&id=req_1707024462-VEGN&source=mobile&nin=12345678901",
    "request": {
      "id": "req_1707024462-VEGN",
      "consumer": "bcn_•••••••",
      "app": "app_•••••••",
      "name": "Your app name",
      "mode": "signature",
      "action": "confirm",
      "user": "12345678901",
      "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6InJlcV8xNzA3MDI0NDYy…",
      "iat": 1707024462,
      "exp": 1707025182,
      "payload": "Confirm your purchase"
    }
  }
}

SampleCode: autosign.

Wildcard

POST /api/v2/signing/wildcard · Scope: signing:wildcard · Secure sign · v2 only

Omit nin; pass seeds (1–10). Returns seeds[] for QR. sign still requires webhook.

Body field	Type	Required	Notes
`action`	string	Yes	`sign` or `confirm`
`seeds`	number	Yes	1–10
`payload`	string	Yes	User-visible intent
`webhook`	object	If `sign`	Required for sign

First scan wins. Cannot target a specific NIN.

curl -sS -X POST "https://s.pasby.africa/api/v2/signing/wildcard" \
  -H "x-api-key: bk-test_YOUR_KEY" \
  -H "x-access-secret: YOUR_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sign",
    "seeds": 4,
    "payload": "Sign your name for access",
    "webhook": {
      "host": "https://your-app.com/pasby/events",
      "reference": "wildcard-sign-001"
    }
  }'

201 Created

{
  "status": "successful",
  "reason": "Signature request created",
  "data": {
    "request": {
      "id": "req_1714702298-wfDZ",
      "consumer": "bcn_•••••••",
      "app": "app_•••••••",
      "mode": "signature",
      "action": "sign",
      "user": "",
      "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
    },
    "seeds": [
      "pasby://cef9e405bc99eff7d7f749055562fa495747e3-vi(ebe0d7f367cedfc39efbac3fb402996c)"
    ]
  }
}

SampleCode: secure sign.

Different device

POST /api/v2/signing/different-device · Scope: signing:another · Direct start

Requires nin. pasby pushes to the holder's devices — no link returned; wait for webhook (sign) or ping (confirm).

Body field	Type	Required	Notes
`nin`	string	Yes	Target NIN
`action`	string	Yes	`sign` or `confirm`
`payload`	string	Yes	User-visible intent
`webhook`	object	If `sign` on v2	HTTPS callback

curl -sS -X POST "https://s.pasby.africa/api/v2/signing/different-device" \
  -H "x-api-key: bk-test_YOUR_KEY" \
  -H "x-access-secret: YOUR_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sign",
    "nin": "12345678901",
    "payload": "Sign documents online",
    "webhook": {
      "host": "https://your-app.com/pasby/events",
      "reference": "order-789"
    }
  }'

201 Created

{
  "status": "successful",
  "reason": "Signature request created",
  "data": {
    "request": {
      "id": "req_1707024500-XxYy",
      "consumer": "bcn_•••••••",
      "app": "app_•••••••",
      "name": "Your app name",
      "mode": "signature",
      "action": "sign",
      "user": "12345678901",
      "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
    }
  }
}

If the NIN has no pasby ID, see Identity not on pasby.

Webhooks · Flow lifecycle
API signing · Integration recipes

Request body by action

Signature model

Same device

Wildcard

Different device

Related

On this page