Start accepting payments on your website or app.
When the shopper goes to checkout on your website, you redirect them to a Hosted Checkout page. After they make the payment, the shopper gets redirected to your page, and you show the shopper the outcome of the payment session.
You make two API requests to our server:
Before you begin to integrate, make sure you have followed the Get started with Safepay guide to:
After you have created your test account:
1
# Install the API librarynpm install --save @sfpy/node-core2
When the shopper goes to checkout, for example by selecting a Checkout button, make a POST /order/payments/v3/ request from your server, including:
| Parameter | Required | Description |
|---|---|---|
merchant_api_key | Yes | The public API key for your account. Your test and live accounts will have different API Keys. |
intent | Yes | The payment channel you wish your shopper to make the payment through. Acceptable values are CYBERSOURCE and MPGS. |
mode | Yes | This defines the payment flow you want your customer to go through. Refer to the section on modes for more details on what each mode can do. |
currency | Yes | This is the currency to charge your customer in. Refer to the section on supported currencies to understand what currencies Safepay currently supports. |
amount | Yes | This is the amount, in lowest denomination, to charge your customer. For instance, if you wish to charge $100, the currency will be USD and the amount will be 10000. |
For example:
const safepay = require('@sfpy/node-core')('SAFEPAY_SECRET_KEY', {
authType: 'secret',
host: 'https://sandbox.api.getsafepay.com' // for live payments use https://api.getsafepay.com
});
try {
const response = safepay.payments.session.setup({
"merchant_api_key": "SAFEPAY_API_KEY",
"intent": "CYBERSOURCE",
"mode": "payment",
"currency": "USD",
"amount": 10000
})
} catch (err) {
console.log(error);
}
The /order/payments/v3/ response will give you the payment session you have just created. The response will have the token for the tracker object which is the payment session. This will be required when generating the Checkout URL.
For example:
{
"data": {
"tracker": {
"token": "track_4f7d7e2d-ee05-44e3-81b7-6f6f2cca9727",
"client": "sec_a8e0a889-b987-4b7e-9757-a6bf28e4d4e2",
"environment": "sandbox",
"state": "TRACKER_STARTED",
"intent": "CYBERSOURCE",
"mode": "payment",
"next_actions": {
"CYBERSOURCE": {
"kind": "GENERATE_CAPTURE_CONTEXT"
}
},
"purchase_totals": {
"quote_amount": {
"currency": "USD",
"amount": 10000
},
"base_amount": {
"currency": "PKR",
"amount": 27800
},
"conversion_rate": {
"base_currency": "PKR",
"quote_currency": "USD",
"rate": 278
}
}
},
"capabilities": {
"CYBERSOURCE": true
}
},
"status": {
"errors": [],
"message": "success"
}
}
3
After creating the payment session, make a POST request to /client/passport/v1/token to generate a short lived authentication token.
For example:
const safepay = require('@sfpy/node-core')('SAFEPAY_SECRET_KEY', {
authType: 'secret',
host: 'https://sandbox.api.getsafepay.com' // for live payments use https://api.getsafepay.com
});
try {
const response = safepay.auth.passport.create()
} catch (err) {
console.log(error);
}
The /client/passport/v1/token response will give you the authentication token you will need to generate the Checkout URL.
For example:
{
"data": "xnTyRgITVcHlyeKT2cf59_e836PouieQ6xPpuQiwFXD8M6HoJ283EP_zta2SKkm6B_IFNGEBmg=="
}
4
Now that the payment session and authentication token have been generated, your server will have to generate the URL for the Checkout page in order for you to redirect your shopper to complete their payment.
You can use our SDKs to generate the URL for you. For example:
const safepay = require('@sfpy/node-core')('SAFEPAY_SECRET_KEY', {
authType: 'secret',
host: 'https://sandbox.api.getsafepay.com' // for live payments use https://api.getsafepay.com
});
try {
const checkoutURL = safepay.checkouts.payment.create({
// this the tracker.token from the payment session response
tracker: "TRACKER_TOKEN",
// the authentication token
tbt: "AUTHENTICATION_TOKEN",
// either production or sandbox
environment: "sandbox",
// attach a source, like your website domain or mobile app bundle identifier (or "mobile" for mobile webview)
source: "mywebsite.com",
// the success URL to redirect your customer to after payment complete
redirect_url: "https://mywebsite.com/order/success",
// the cancel URL to redirect your customer to after the customer cancels the checkout session
cancel_url: "https://mywebsite.com/order/cancel"
})
} catch (err) {
console.log(error);
}
Redirect the shopper to the URL (url) generated above. The shopper pays on the Hosted Checkout page.
5
After the shopper makes the payment, they are redirected back to your website.
Get the tracker that is appended to the return URL from the Hosted Checkout page. Use it to get the outcome of the payment session.
https://your-company.com/order/complete?tracker=track_4f7d7e2d-ee05-44e3-81b7-6f6f2cca9727
Make a GET /reporter/api/v1/payments/{tracker} request including the tracker token. For example:
const safepay = require('@sfpy/node-core')('SAFEPAY_SECRET_KEY', {
authType: 'secret',
host: 'https://sandbox.api.getsafepay.com' // for live payments use https://api.getsafepay.com
});
try {
const response = safepay.reporter.payments.fetch(trackerToken)
} catch (err) {
console.log(error);
}
The response includes the current status of the payment. Search for the tracker.state property. If it shows TRACKER_ENDED, the payment has been successfully completed. For example:
{
"data": {
"tracker": {
"token": "track_1a46dc70-91f9-4892-8e25-0bb5205b69c7",
"client": "sec_edeade52-46aa-483b-b87d-009d3ce41554",
"environment": "sandbox",
"state": "TRACKER_ENDED",
"intent": "CYBERSOURCE",
"mode": "payment",
"next_actions": {
"CYBERSOURCE": {
"kind": "NOOP",
"request_id": "req_9ea53be5-828f-4730-b187-9d3d350ab72a"
}
},
"purchase_totals": {
"quote_amount": {
"currency": "PKR",
"amount": 600000
},
"base_amount": {
"currency": "PKR",
"amount": 600000
},
"conversion_rate": {
"base_currency": "PKR",
"quote_currency": "PKR",
"rate": 1
}
}
},
"action": {
"token": "req_9ea53be5-828f-4730-b187-9d3d350ab72a",
"payment_method": {
"token": "card_353d4bd9-1d72-4f4d-a358-b277833795a4",
"expiration_month": "12",
"expiration_year": "2023",
"card_type_code": "001",
"card_type": "Visa",
"bin_number": "445653",
"last_four": "1096"
}
}
},
"status": {
"errors": [],
"message": "success"
}
}
You get the outcome of each payment asynchronously, in a payment.succeeded webhook. Use the tracker from the webhook to match it to the tracker you generated in the payment session step.
For a successful payment, the event contains success: true.
Refer to Webhooks for more information on how to get set up to receive events from Safepay.
For mobile, you may render the checkout session in a WebView. Note that when generating the checkout URL using the backend SDKs, you will need to set the source as mobile.
To mimic redirection, you can observe changes to the checkout URL and close the Webview on success or cancellation. The paths to observe are as follows:
| Scenario | URL path | Example |
|---|---|---|
| Success | /external/complete | https://sandbox.api.getsafepay.com/embedded/external/complete?environment=sandbox&... |
| Cancellation | /external/error | https://sandbox.api.getsafepay.com/embedded/external/error?environment=sandbox&... |
If the payment encounters an error, the shopper can retry the payment on the Hosted Checkout page. You receive a webhook for each payment attempt. So, you can receive more than one webhook with the same tracker.
The Hosted Checkout page expires after the authentication token expires. A single authentication token lasts for 1 hour. In case the authentication token expires, we prompt the shopper to return back to your store and restart the checkout process.
Before going live, use our list of test cards and other payment methods to test your integration. We recommend testing each payment method that you intend to offer to your shoppers.
You can check the test payments in your Dashboard, under the Payments > Payments 2.0 tab.
When you are ready to go live, you need to: