Safepay NodeJS SDK
Official nodejs library for Safepay API.
Installation
With Yarn
yarn add @sfpy/node-sdk
With NPM
npm install @sfpy/node-sdk
Usage
Import and create a Safepay client by passing your config;
import { Safepay } from '@sfpy/node-sdk'
const safepay = new Safepay({
environment: 'sandbox',
apiKey: 'sec_asd12-2342s-1231s',
v1Secret: 'bar',
webhookSecret: 'foo'
})
You can now create payments and checkout links.
Payments
Create payment
Parameter |
Type |
Required |
amount |
number |
Yes |
currency |
PKR , USD |
Yes |
const { token } = await safepay.payments.create({
amount: 10000,
currency: 'PKR'
})
// Pass `token` to create checkout link
Checkout
Create checkout link
Parameter |
Type |
Description |
Required |
token |
string |
Token from safepay.payments.create |
Yes |
orderId |
string |
Your internal invoice / order id |
Yes |
cancelUrl |
string |
Url to redirect to if user cancels the flow |
Yes |
redirectUrl |
string |
Url to redirect to if user completes the flow |
Yes |
source |
string |
Optional, defaults to custom |
No |
webhooks |
boolean |
Optional, defaults to false |
No |
const url = safepay.checkout.create({
token,
orderId: 'T800',
cancelUrl: 'http://example.com/cancel',
redirectUrl: 'http://example.com/success',
source: 'custom',
webhooks: true
})
// redirect user to `url`
Verification
Signature
Parameter |
Type |
Description |
Required |
request |
object |
The req object from your server |
Yes |
const valid = safepay.verify.signature(request)
// mark the invoice as paid if valid
// show an error if invalid
Webhook
Parameter |
Type |
Description |
Required |
request |
object |
The req object from your server |
Yes |
const valid = await safepay.verify.webhook(request)
// mark the invoice as paid if valid
// show an error if invalid
Subscriptions
Create subscription link
Parameter |
Type |
Description |
Required |
planId |
string |
The plan id corresposnding to the plan you created on Safepay's merchant dashboard |
Yes |
reference |
string |
Uniquely identify subscription with your internal identifier e.g. order_id |
Yes |
cancelUrl |
string |
Url to redirect to if user cancels the flow |
Yes |
redirectUrl |
string |
Url to redirect to if user completes the flow |
Yes |
safepay.checkout
.createSubscription({
cancelUrl: 'https://www.google.com/',
redirectUrl: 'https://www.google.com/',
planId: 'plan_33e626b3-d92e-40b3-a379-4f89d61f8c83',
reference: 'cc3f2475-4fb1-4d80-99f8-3a582a496fa6'
})
.then(url => {
console.log(url)
})
.catch(error => {
console.error(error)
})
// redirect user to `url`
Create authorization token first and then generate subscription link
Parameter |
Type |
Description |
Required |
planId |
string |
The plan id corresposnding to the plan you created on Safepay's merchant dashboard |
Yes |
reference |
string |
Uniquely identify subscription with your internal identifier e.g. order_id |
Yes |
cancelUrl |
string |
Url to redirect to if user cancels the flow |
Yes |
redirectUrl |
string |
Url to redirect to if user completes the flow |
Yes |
authToken |
string |
The generated authentication token |
Yes |
// To create subscription url
const generateUrl = (token: string) => {
return safepay.checkout.createSubscriptionWithToken({
cancelUrl: 'https://www.google.com/',
redirectUrl: 'https://www.google.com/',
planId: 'plan_33e626b3-d92e-40b3-a379-4f89d61f8c83',
reference: 'cc3f2475-4fb1-4d80-99f8-3a582a496fa6',
authToken: token
})
}
// To generate authentication token
safepay.authorization
.create()
.then(token => {
generateUrl(token)
// redirect user to `url`
})
.catch(error => {
console.log(error)
})
Cancel Subscription
Parameter |
Type |
Description |
Required |
subscriptionId |
string |
The id for subscription you wish to cancel |
Yes |
safepay.subscription
.cancel('sub_c94f2ffa-78cf-4de5-80c0-f57e3d1ce746')
.then(response => {
console.log(response)
})
.catch(error => {
console.log(error.response.data.error)
})
Pause Subscription
Parameter |
Type |
Description |
Required |
subscriptionId |
string |
The id for subscription you wish to cancel |
Yes |
behavior |
string |
'KEEP_AS_READY' or 'MARK_UNCOLLECTIBLE' or 'MARK_VOID' |
Yes |
Opt for marking the payment transaction as 'KEEP_AS_READY' during the pause, to retain payment readiness during subscription pause and automatically adjust the billing cycle for uninterrupted service when the payment ends
Opt for marking the payment transaction as 'MARK_UNCOLLECTIBLE' during the pause, indicating no collection attempts during this period. Ideal for mainting clear billing records
Opt for marking the payment transaction as 'MARK_VOID' during the pause, rendering it null and preventing any accidental payment processing. A safeguard for for accurate financial records
safepay.subscription
.pause({
behavior: SubscriptionPauseBehavior.MarkUncollectible,
subscriptionId: 'sub_c94f2ffa-78cf-4de5-80c0-f57e3d1ce746'
})
.then(response => {
console.log(response)
})
.catch(error => {
console.log(error.response.data.error)
})
Resume Subscription
Parameter |
Type |
Description |
Required |
subscriptionId |
string |
The id for subscription you wish to cancel |
Yes |
safepay.subscription
.resume('sub_c94f2ffa-78cf-4de5-80c0-f57e3d1ce746')
.then(response => {
console.log(response)
})
.catch(error => {
console.log(error.response.data.error)
})