Yoursafe Flowguard
Yoursafe Flowguard is a cutting-edge payment integration solution designed for Verotel, CardBilling, and Gaycharge. It provides an improved, modern alternative to redirect-based models, like FlexPay, by allowing you to embed secure payment iframes directly into your order pages. This streamlines the buyer's experience, removes redirects, thereby improving conversion rates without compromising data security or PCI compliance.
Key Benefits
- No Redirects: Flowguard boosts conversions by keeping buyers on your website without the need for redirects
- Fully PCI-DSS Compliant: By using iframe components, Flowguard allows you to avoid handling card-data. This significantly limits your PCI-DSS exposure
- Highly Customizable: The components are fully customizable, allowing you to create a fully branded, seamless checkout experience
- Reduced Fraud & Chargebacks: As you are used to with our other integration methods, Flowguard provides you with 3DS Support and strong fraud controls
Core Components
Flowguard provides two main tools for integration: the Flowguard SDK and the Flowguard API. These tools ensure that sensitive card data remains isolated from the merchant while offering a seamless and fully customizable user experience.
Flowguard SDK
This is the JavaScript-based toolkit that enables embedding iframes securely. The iframes are hosted on flowguard.yoursafe.com, and remain isolated from your servers. It allows you to customize the look and feel of the components to seamlessly integrate with your own page design. See the Flowguard SDK docs for more info.
Flowguard API
This API allows you to initiate purchases and manage subscriptions. Transactions are processed in the background. It also enables postback integrations, which provides you with any and all status updates.
Need help?
For any questions or technical issues, feel free to contact our support team at merchantsupport@verotel.com. We're here to assist you!
Getting started
Welcome to the Yoursafe Flowguard API documentation.
Yoursafe Flowguard is designed to seamlessly integrate secure payment processing with full control, offering unparalleled control over your payment flow while ensuring top-tier security and compliance.
Yoursafe Flowguard overview
Following overview provides a high-level understanding of how Yoursafe Flowguard works.
Security
All Yoursafe Flowguard API endpoints are secured with JWTs (Json Web Tokens), which ensures security of your data.
JWT has to consist of three parts: header, payload, and signature. We recommend JWT Debugger if you need to debug your JWTs.
JWT Header
JWT header has to contain the following fields:
| Field | Field value |
|---|---|
| alg | HS256 |
| typ | JWT |
JWT Payload
Payload for JWT is a JSON object with different fields for each endpoint.
You can find the required fields in the specific endpoint documentation.
JWT Signature
JWT has to be signed using the signatureKey that you will find in the Control Center. In the case JWT signature is not provided or is invalid, the API will return a 401 Unauthorized error. An example of the code
JWT Example
An example of the signJWT function of the example above:
// JWT Header
{{
"alg": "HS256",
"typ": "JWT"
}}
// JWT Body
{{
"shopId": "65151",
"priceAmount": "10.00",
"priceCurrency": "USD",
"successUrl": "https://merchant.com/success",
"declineUrl": "https://merchant.com/decline",
"postbackUrl": "https://merchant.com/postback",
"email": "shoper@example.com"
}}
const signatureKey = "signatureKeyFromControlCenter";
console.log(await signJWT(header, payload, signatureKey));
// Output:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaG9wSWQiOiI2NTE1MSIsInByaWNlQW1vd
W50IjoiMTAuMDAiLCJwcmljZUN1cnJlbmN5IjoiVVNEIiwic3VjY2Vzc1VybCI6Imh0dHBzOi8
vbWVyY2hhbnQuY29tL3N1Y2Nlc3MiLCJkZWNsaW5lVXJsIjoiaHR0cHM6Ly9tZXJjaGFudC5jb
20vZGVjbGluZSIsInBvc3RiYWNrVXJsIjoiaHR0cHM6Ly9tZXJjaGFudC5jb20vcG9zdGJhY2s
iLCJlbWFpbCI6InNob3BlckBleGFtcGxlLmNvbSJ9.z1aqZb0YR93Dw4_Gh6mVC4EWLxs_GDBJ
L_xEHHTeVdQ
// Signing the JWT function - or use your own implementation
async function signJWT(header, payload, signatureKey) {
const enc = new TextEncoder();
const base64url = (obj) =>
btoa(JSON.stringify(obj))
.replace(/=/g, "")
.replace(/\+/g, "-")
.replace(/\//g, "_");
const encodedHeader = base64url(header);
const encodedPayload = base64url(payload);
const data = `${encodedHeader}.${encodedPayload}`;
const key = await crypto.subtle.importKey(
"raw",
enc.encode(signatureKey),
{ name: "HMAC", hash: "SHA-256" },
false,
["sign"]
);
const sigBuffer = await crypto.subtle.sign("HMAC", key, enc.encode(data));
const signature = btoa(String.fromCharCode(...new Uint8Array(sigBuffer)))
.replace(/=/g, "")
.replace(/\+/g, "-")
.replace(/\//g, "_");
return `${data}.${signature}`;
POST /api/merchant/purchase/startconst url = new URL("/api/merchant/purchase/start");
const response = await fetch(url, { method: "POST" });from urllib.request import urlopen
response = urlopen("/api/merchant/purchase/start")// POST /api/merchant/purchase/start
$url = "/api/merchant/purchase/start";// POST /api/merchant/purchase/start
String url = "/api/merchant/purchase/start";/api/merchant/purchase/startAPI that allows you to integrate a single secure payment for your website.
Use this endpoint to initiate the order process for a single purchase.
Response of this endpoint sessionId has to be passed to the
Yoursafe Flowguard SDK to start the payment process.
This endpoint is secured by JWTs. You can find more information how to work with JWTs in the Security section.
JWT Payload
JWT payload has to contain the following fields:
| Field | Field type | Note |
|---|---|---|
| shopId | number or string | Shop ID from ControlCenter. |
| priceAmount | string | In format NNN.NN |
| priceCurrency | string | One of: USD, EUR, GBP, AUD, CAD, CHF, DKK, NOK, SEK |
| successUrl | string | Max length 255 characters. |
| declineUrl | string | Max length 255 characters. |
| postbackUrl | string | Max length 255 characters. |
| string | Max length 100 characters. | |
| referenceId | string or null | Optional. Max length 100 characters. |
JWT Example
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaG9wSWQiOiI2NTE1MSIsInByaWNlQW1vdW50IjoiMTAuMDAiLCJwcmljZUN1cnJlbmN5IjoiVVNEIiwic3VjY2Vzc1VybCI6Imh0dHBzOi8vbWVyY2hhbnQuY29tL3N1Y2Nlc3MiLCJkZWNsaW5lVXJsIjoiaHR0cHM6Ly9tZXJjaGFudC5jb20vZGVjbGluZSIsInBvc3RiYWNrVXJsIjoiaHR0cHM6Ly9tZXJjaGFudC5jb20vcG9zdGJhY2siLCJlbWFpbCI6InNob3BlckBleGFtcGxlLmNvbSJ9.J8LY9lYSI9HWAiZPjXKLZ7dXIMno9CBIRt5fk9M5gOM
Request bodyrequired
application/jwt
DatastringrequiredResponses
Successful Response
sessionIduuidrequiredUnauthorized
errorsstringrequiredUnprocessable Content
errorsobjectrequiredLocked
errorsstringrequiredSubscription
API that allows you to integrate subscription payments for your website.
POST /api/merchant/subscription/cancelconst url = new URL("/api/merchant/subscription/cancel");
const response = await fetch(url, { method: "POST" });from urllib.request import urlopen
response = urlopen("/api/merchant/subscription/cancel")// POST /api/merchant/subscription/cancel
$url = "/api/merchant/subscription/cancel";// POST /api/merchant/subscription/cancel
String url = "/api/merchant/subscription/cancel";/api/merchant/subscription/cancelThis endpoint is used to cancel a subscription.
This endpoint is secured by JWTs. You can find more information how to work with JWTs in the Security section.
JWT Payload
JWT payload has to contain the following fields:
| Field | Field type | Note |
|---|---|---|
| saleId | number or string | Sale ID of subscription to cancel. |
| shopId | number or string | Shop ID from ControlCenter. |
| cancelledBy | string | Optional, one of: merchant, buyer |
JWT Example
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaG9wSWQiOiI2NTE1MSIsInNhbGVJZCI6IjIwODAiLCJjYW5jZWxsZWRCeSI6Im1lcmNoYW50In0.gAbebyxDsecJrriAosWvtdi-SG_dt6MTVMC6NmOGriE
Request bodyrequired
application/jwt
DatastringrequiredResponses
Successful Response
Unauthorized
errorsstringrequiredUnprocessable Content
errorsobjectrequiredPOST /api/merchant/subscription/startconst url = new URL("/api/merchant/subscription/start");
const response = await fetch(url, { method: "POST" });from urllib.request import urlopen
response = urlopen("/api/merchant/subscription/start")// POST /api/merchant/subscription/start
$url = "/api/merchant/subscription/start";// POST /api/merchant/subscription/start
String url = "/api/merchant/subscription/start";/api/merchant/subscription/startUse this endpoint to initiate the subscription process.
Response of this endpoint sessionId has to be passed to the
Yoursafe Flowguard SDK to start the payment process.
This endpoint is secured by JWTs. You can find more information how to work with JWTs in the Security section.
JWT Payload
JWT payload has to contain the following fields:
| Field | Field type | Note |
|---|---|---|
| shopId | number or string | Shop ID from ControlCenter. |
| priceAmount | string | In format NNN.NN |
| priceCurrency | string | One of: USD, EUR, GBP, AUD, CAD, CHF, DKK, NOK, SEK |
| successUrl | string | Max length 255 characters. |
| declineUrl | string | Max length 255 characters. |
| postbackUrl | string | Max length 255 characters. |
| string | Max length 100 characters. | |
| subscriptionType | string | One of: recurring, one-time |
| period | string | In ISO 8601 period format (e.g. P30D, P1M, P1Y) |
| referenceId | string or null | Optional. Max length 100 characters. |
| trialAmount | string or null | Optional. In format NNN.NN |
| trialPeriod | string or null | Optional. In ISO 8601 period format (e.g. P30D, P1M, P1Y) |
Period format
Period consists of 3 parts (P, number, unit). Units can be: D - day, M - month, Y - year. For example:
- P30D - 30 days
- P1M - 1 month
- P1Y - 1 year
Minimum and maximum period restrictions
- for one-time subscription minimum period length is 2 days, maximum period length is 180 days
- for recurring subscription minimum period length is 7 days, maximum period length is 180 days
- maximum period can be prolonged up to 730 days if merchant has long subscriptions enabled
Minimum and maximum trialPeriod restrictions
- minimum trialPeriod length is 2 days, maximum trialPeriod length is 180 days
- maximum trialPeriod can be prolonged up to 730 days if merchant has long subscriptions enabled
JWT Example
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaG9wSWQiOiI2NTE1MSIsInByaWNlQW1vdW50IjoiMTAuMDAiLCJwcmljZUN1cnJlbmN5IjoiVVNEIiwic3VjY2Vzc1VybCI6Imh0dHBzOi8vbWVyY2hhbnQuY29tL3N1Y2Nlc3MiLCJkZWNsaW5lVXJsIjoiaHR0cHM6Ly9tZXJjaGFudC5jb20vZGVjbGluZSIsInBvc3RiYWNrVXJsIjoiaHR0cHM6Ly9tZXJjaGFudC5jb20vcG9zdGJhY2siLCJlbWFpbCI6InNob3BlckBleGFtcGxlLmNvbSIsInN1YnNjcmlwdGlvblR5cGUiOiJyZWN1cnJpbmciLCJwZXJpb2QiOiJQMU0iLCJ0cmlhbEFtb3VudCI6IjUuMDAiLCJ0cmlhbFBlcmlvZCI6IlAzRCJ9.EwpofyMOWGqqmk4RQU7DgQHWCxl32GQLckrNOnHBSy4
Request bodyrequired
application/jwt
DatastringrequiredResponses
Successful Response
sessionIduuidrequiredUnauthorized
errorsstringrequiredUnprocessable Content
errorsobjectrequiredLocked
errorsstringrequiredPostbacks
This part of documentation outlines the event types that occur during the payment process and the mechanism for receiving notifications via postbacks.
Postback URL Configuration
When invoking the purchase/start or subscription/start endpoints, you are required to provide a postbackUrl.
This URL will be used to send notifications of relevant events.
Postback Format
The postback will be sent as a JWT (JSON Web Token) token, which will be signed using your provided signature key. Upon receiving the postback, your system must respond with an HTTP status code of 200 OK in 30 seconds.
Retry Policy
In the event that your system does not respond with a 200 OK status code, the API will automatically retry sending the postback up to three (3) times.
Postback Content
The JWT token included in the postback will contain a field named postbackType. This field indicates the type of event that has occurred. Refer to the sections below for detailed information on the data structure for each event type that may be sent via postback.
Purchase approved
Postback sent when a purchase is successfully completed by a buyer.
We will automatically refund the payment if the postback is not received (if your system does not respond with 200 OK
HTTP status) after all retries.
| Field | Field type | Note |
|---|---|---|
| postbackType | string | approved |
| orderType | string | purchase |
| saleId | number or string | |
| transactionId | number or string | |
| shopId | number or string | Shop ID from ControlCenter. |
| priceAmount | string | In format NNN.NN |
| priceCurrency | string | One of: USD, EUR, GBP, AUD, CAD, CHF, DKK, NOK, SEK |
| referenceId | string or null | Optional |
Purchase refund
Both chargeback and credit postbacks represent refund transactions of purchase. They differ in terms of the initiator of the refund.
| Field | Field type | Note |
|---|---|---|
| postbackType | string | chargeback , credit |
| orderType | string | purchase |
| saleId | number or string | |
| transactionId | number or string | |
| shopId | number or string | Shop ID from ControlCenter. |
| parentId | number or string | Id of transaction that is being refunded |
| priceAmount | string | In format NNN.NN |
| priceCurrency | string | One of: USD, EUR, GBP, AUD, CAD, CHF, DKK, NOK, SEK |
| referenceId | string or null | Optional |
Subscription approved
Postback sent when a subscription is successfully completed by a buyer.
We will automatically refund the payment if the postback is not received (if your system does not respond with 200 OK
HTTP status) after all retries.
| Field | Field type | Note |
|---|---|---|
| postbackType | string | approved |
| orderType | string | subscription |
| saleId | number or string | |
| transactionId | number or string | |
| shopId | number or string | Shop ID from ControlCenter. |
| priceAmount | string | In format NNN.NN |
| priceCurrency | string | One of: USD, EUR, GBP, AUD, CAD, CHF, DKK, NOK, SEK |
| subscriptionType | string | recurring , one-time |
| subscriptionPhase | string | normal , trial |
| nextChargeOn | string or null | Optional. In format YYYY-MM-DD. Present for recurring subscriptionType |
| expiresOn | string or null | Optional. In format YYYY-MM-DD. Present for one-time subscriptionType. |
| referenceId | string or null | Optional |
Subscription refund
Both chargeback and credit postbacks represent refund transactions of subscription. They differ in terms of the initiator of the refund.
| Field | Field type | Note |
|---|---|---|
| postbackType | string | chargeback , credit |
| orderType | string | subscription |
| saleId | number or string | |
| transactionId | number or string | |
| shopId | number or string | Shop ID from ControlCenter. |
| parentId | number or string | Id of transaction that is being refunded |
| priceAmount | string | In format NNN.NN |
| priceCurrency | string | One of: USD, EUR, GBP, AUD, CAD, CHF, DKK, NOK, SEK |
| subscriptionType | string | recurring , one-time |
| subscriptionPhase | string | terminated |
| referenceId | string or null | Optional |
Subscription rebill
Postback sent when each recurring subscription payment is successfully processed. For example, if a subscription period is set do P1M, a rebill postback will be sent each month.
| Field | Field type | Note |
|---|---|---|
| postbackType | string | rebill |
| orderType | string | subscription |
| saleId | number or string | |
| transactionId | number or string | |
| shopId | number or string | Shop ID from ControlCenter. |
| priceAmount | string | In format NNN.NN |
| priceCurrency | string | One of: USD, EUR, GBP, AUD, CAD, CHF, DKK, NOK, SEK |
| subscriptionType | string | recurring |
| subscriptionPhase | string | normal |
| nextChargeOn | string | In format YYYY-MM-DD. |
| referenceId | string or null | Optional |
Subscription expiration
This postback will be sent, after the last subscription payment.
| Field | Field type | Note |
|---|---|---|
| postbackType | string | expiry |
| orderType | string | subscription |
| saleId | number or string | |
| shopId | number or string | Shop ID from ControlCenter. |
| subscriptionType | string | recurring , one-time |
| referenceId | string or null | Optional |
Subscription cancel
This postback will be sent, after the subscription is cancelled.
| Field | Field type | Note |
|---|---|---|
| postbackType | string | cancel |
| orderType | string | subscription |
| saleId | number or string | |
| shopId | number or string | Shop ID from ControlCenter. |
| subscriptionType | string | recurring |
| subscriptionPhase | string | normal , trial |
| cancelledBy | string | user , support , merchant , system |
| expiresOn | string or null | Optional. In format YYYY-MM-DD. |
| referenceId | string or null | Optional |
Subscription uncancel
This postback will be sent, after the subscription is uncancelled.
| Field | Field type | Note |
|---|---|---|
| postbackType | string | uncancel |
| orderType | string | subscription |
| saleId | number or string | |
| shopId | number or string | Shop ID from ControlCenter. |
| subscriptionType | string | recurring |
| subscriptionPhase | string | normal , trial |
| uncancelledBy | string | support |
| nextChargeOn | string or null | Optional. In format YYYY-MM-DD. Present if subscription is still active. |
| referenceId | string or null | Optional |
Subscription extended
Postback sent when subscription is extended.
| Field | Field type | Note |
|---|---|---|
| postbackType | string | extend |
| orderType | string | subscription |
| saleId | number or string | |
| shopId | number or string | Shop ID from ControlCenter. |
| subscriptionType | string | recurring , one-time |
| subscriptionPhase | string | normal , trial |
| nextChargeOn | string or null | Optional. In format YYYY-MM-DD. Present for recurring subscriptionType |
| expiresOn | string or null | Optional. In format YYYY-MM-DD. Present for one-time subscriptionType. |
| referenceId | string or null | Optional |