🅿🅵
Get started with Payflowly
https://get.payflowly.com/
Payflowly is a simple platform allowing applications to integrate with a lot of payment services.
- Version: 1.1
- Author: Payflowly team
- Created: 8 April 2022
- Update: 7 March 2024
If you have any questions that are beyond the scope of this help file, Please feel free to email us.
Installation
Follow the steps below to set up your test application
- visit our dashboard at https://portal.payflowly.com/
- sign up for free or login if you already have an account.
- choose application in left side menu
- click "New Application" button and enter your application details
Property Usage Example App Name (string,required)
Your application name. Payflowly Secret (string,required)
Random string to verify requests between your application and payflowly to go production,your secret must
- has 15 characters length or more
- contains lowercase letter, Uppercase letter, digit and special characters
note: always use secret in header to communicate with payflowly6-u9dQvn2iZ.__qL)n App Website (string)
Your application domain. https://www.eshop.com/ - after saving ,you now has application ID and can create payflowly link for your application.
Process Flow Diagram
There are two ways to create payflowly link and redirect to payment gateway

First Diagram

Second Diagram
Flow of the Payment Process
- Post/Sign: The user initiates the payment process within your application, likely by clicking a "Pay" button or similar action.
- Payflowly Link: Your application generates a link using Payflowly's service.
-
In First Diagram:
- Post Payflowly Link : Your application generates a Payment Gateway link using Payflowly's service.
- Open Payflowly Link in Browser: The application redirects user to payflowly link, opening the Payflowly page in their browser.
- User Clicks Pay: On the Payflowly checkout page, the user clicks the "Pay" button to proceed with the payment.
- User is Redirected to Payment Gateway: The user is redirected to the chosen payment gateway (Tap, Tamara, etc.) to complete the payment.
- Send Payment Status: After the payment is processed, the payment gateway sends a notification (webhook or other method) to Payflowly with the payment status.
- Send Payment Webhooks: Payflowly, in turn, sends webhooks to your application to inform it about the final payment status.
Create Payflowly Link
now you can start integrating and testing PayFlowly within your apps (Web & Mobile) directly
after signing up,using our testing environment.
Request
POST /sign
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
Content-Type
(required) |
use application/x-www-form-urlencoded or application/json |
REQUEST BODY
app_id
(UUID,required) |
Your application ID. | ||
reference_id
(string,required) |
Reference ID (unique for payment operation in application).
You can't use this reference again unless payment failed. |
||
webhook_url
(string) |
POST callback URL to send payment
response &
webhooks to your application.
It was previously named post_url |
||
customer_id
(string) |
customer’s id | ||
order_customer_first_name
(string,required) |
Customer’s first name. If not provided, the customer will need to add it on the invoice page. | ||
order_customer_last_name
(string,required) |
Customer’s last name. If not provided, the customer will need to add it on the invoice page. | ||
phone_number
(string,required) |
Customer’s phone number. If not provided, the customer will need to add it on the invoice page. | ||
order_email
(string,required) |
Customer’s email. If not provided, the customer will need to add it on the invoice page. | ||
total
(string,required) |
Total to pay no regrading any other value. | ||
order_description
(string) |
The description of the items or the service that your user is billed
for.
note: required for moyasar / tamara |
||
currency
(string) |
Payment currency code.
Make sure that currency is available in payment gateway you use(for testing we use tap as default). If not provided ,we use default currency for your application. You can make default currency for each payment gateway you use. Currency Codes List |
||
payment_method
(string) |
One of the configured payment methods available for the application(Tap,Tabby,Tamara,....) | ||
response_format
(Enum:[ 'URL', 'JSON' ]) Default:URL |
The response can be returned either as a URL string or as a JSON object with a property "URL". | ||
custom_data
(object) |
Data specific to your application and sent along with webhooks. | ||
app_redirect_url
(string) |
GET URL to which the user should be
redirected following a successful or failed checkout process note: if you intend to direct the user to the Payflowly page, the value should be set to fullUrl. URL to which the user should be redirected following a successful or failed checkout process |
||
expire_after
(string) Default: 4d |
The duration after which payment will be no longer be valid or
active.
If Subscription is enabled, default will be subscription_interval use Time Abbreviations Use Case If you need to expire a payment before or after a specific time period (e.g., a month plus/minus days), you can use relative time expressions like:
|
||
abandoned_time
(string) Default: 1H |
The duration after which your app will recieve event USER_PAYMENT_ABANDONED
if user still not try to pay
use Time Abbreviations |
||
multiple_tries
(boolean|number) Default: false |
Send true / 1 for single Payment Attempt: "Limit payments to one try per
link."
Send false / 0 for multiple Attempts: "Enable multiple payment attempts with the same link until expiration." |
||
To add invoice items | |||
|
|||
item_name
(string) |
Product/Item name.
note: required for tabby / tamara |
||
item_desc
(string) |
Short product/item description is recommended. | ||
item_price
(number|string) |
Product/Item Price.
If no credit or debit, the total value will be applied. note: required as number for tabby / tamara |
||
item_currency
(string) |
Currency code. | ||
item_img
(string) |
Product image URL (base64 or URL). | ||
item_url
(string) |
URL of the item from merchant's website | ||
item_qty
(number|string) |
Product/Item quantity.
note: required as number for tabby / tamara |
||
item_category
(string) |
Name of high-level category (Clothes, Electronics,etc.);
note: required for tabby / tamara |
||
item_reference_id
(string) |
The unique id of the item from merchant's side
note: required for tamara |
||
item_sku
(string) |
Product SKU. <= 128 characters
note: required for tamara |
||
To add invoice credits | |||
|
|||
credit_name
(string) |
Any credits in invoice as previous user credit or coupons. | ||
credit_value
(number) |
Credit value. | ||
credit_currency
(string) |
Currency code.
If your not provide,we use payment currency. |
||
To add invoice debits | |||
|
|||
debit_name
(string) |
Debit in invoice as taxes or shipment value. | ||
debit_value
(number) |
Debit value. | ||
debit_currency
(string) |
Currency code.
If your not provide,we use payment currency. |
||
To enable/disable recovery | |||
recovery_enabled
(boolean|number) Default: false |
Send true / 1 to enable recovery.
Send false / 0 to disable recovery. |
||
recovery_interval
(array|string) Default: ['1d','2d','3d'] / '1d,2d,3d' |
The times between sending the sign request and sending the recovery
emails.
Value can be an array of strings or comma seperated string of time abbreviations
Default will be used if recovery is enabled, and you didn't provide |
||
To enable/disable reminder | |||
reminder_enabled
(boolean|number) Default: false |
Send true / 1 to enable reminder.
Send false / 0 to disable reminder. |
||
reminder_interval
(array|string) Default: 1d |
The times to send reminder emails before payment start.
Value can be an array of strings or comma seperated string of time abbreviations
Default will be used if reminder is enabled, and you didn't provide |
||
To enable/disable subscription | |||
subscription_enabled
(boolean|number) Default: false |
Send true / 1 to enable subscription.
Send false / 0 to disable subscription. |
||
subscription_start_date
(string) |
The time to initiate subscription
Accepted date format is 'YYYY-MM-DD HH:mm:ss' or string contain one time abbreviations If not provided,Subscription will start directly |
||
subscription_interval
(string,required) |
The subscription interval refers to the frequency or time period between
each
payment or billing cycle in a subscription. Required only if subscription is enabled Use time abbreviations |
||
subscription_recurring
(number) |
Specifies how many times the subscription interval should repeat.
For example, if subscription_interval is 30 days and subscription_recurring is 12, the subscription will recur every 30 days for a total of 12 times. If not provided, the subscription will continue to renew every 30 days (or the defined interval) indefinitely until it is canceled. |
Some payment getaways required more data
tabby | ||
buyer_history_loyalty_level
(number,required) Default: 0 |
user's loyalty level within your store, should be sent as a number of successfully placed orders in the store with any payment methods | |
buyer_history_registered_since
(string,required) |
Time the user got registered with you, in UTC, and displayed in ISO 8601 datetime format. | |
shipping_address_address
(string,required) |
Building name, apartment number. | |
shipping_address_city
(string,required) |
Name of city, municipality, or village. | |
shipping_address_zip
(string,required) |
Postal code. | |
tamara | ||
order_shipping_amount
(number,required) Minimum: 0 |
Total amount for the shipping of the order . | |
order_tax_amount
(number,required) Minimum: 0 |
Total amount of taxes | |
country_code
(string,required) |
The two-character ISO 3166-1 country code | |
city
(string,required) |
City for shipping address | |
shipping_address
(string,required) |
The location a consumer prefers to have an order delivered. | |
order_instalments
(string,required) |
The number of instalments that Tamara offers you to offer to your customer. | |
order_shipping_company
(string,required) |
Name of the shipping company. Limited to 100 characters. | |
order_shipped_at
(string,required) |
Shipping date | |
locale
(string) Default: ar_SA |
Display language for Tamara checkout page. Language to be defined by the merchant following RFC 1766, e.g. en_US or ar_SA |
Response
Status 200
response format is returned based on response_format param in request or predefined in application data
<!-- ==============payment============== -->
https://payflowly.com/payment/{app_id}/{reference_id}/{token}
<!-- ==============subscription============== -->
https://payflowly.com/subscription/{app_id}/{reference_id}/{token}
where app_id & reference_id is your body request parameter and token is unique hash for this payment
you can use both reference_id and token to get current payment data or status
You can use this link to show invoice page via GET method or redirect user to payment gateway if you call it POST method
Status 422 / Status 500
You will receive an error message
status | Message | Reason |
---|---|---|
401 | Invalid authorization credentials | No valid secret or app_id was provided |
422 | Missing {field} field | If on or more required field is missing |
422 | Invalid total field value | If field "total" is zero or field is not integer |
422 | Invalid expire_after field value | If field "expire_after" is not sent in correct time abbreviations |
422 | Your application is not active | Application with provided id is not active anymore |
422 | Payment method is not configured | Application with provided id has no configured payment method |
422 | Your application has no active payment method | Application with provided id has no active payment method |
422 | Payment gateway doesn't support input currency | If field "currency" is not supported by Payment gateway |
422 | Server domain/IP is not in whitelist | Your request is coming from server not in whitelist |
422 | The reference ID provided has already been used previously | If field "reference_id" is already used in payment/subscription and application setting of reference repetition is NEVER |
422 | The reference ID provided has already been used successfully | If field "reference_id" is already used with successful payment and application setting of reference repetition is ON_FAILED_ONLY |
422 | The payment associated with this reference ID has not been completed yet | If field "reference_id" is already used with payment with status New or Pending |
If recovery is enabled | ||
422 | The expiration date precedes the recovery date | If maximum calculated recovery date precedes the calculated expiration date,Be sure to review the default values |
422 | Invalid recovery_interval field value | If field "recovery_interval" is not sent in correct time abbreviations |
If subscription is enabled | ||
422 | The reference ID provided has already been used in active subscription | If field "reference_id" is already used with active subscription and application setting of subscription reference repetition is ON_INACTIVE_ONLY |
422 | Invalid subscription_start_date field value | If field "subscription_interval" value not match 'YYYY-MM-DD HH:mm:ss' or time abbreviations |
422 | Can not find active subscription. | Invalid subscription token or subscription is not active |
422 | Your payment not initiated or started yet. | No matched payment id in a subscription or payment not started yet |
500 | An error has occurred | An unexpected error has occurred. Please contact our support team for assistance |
Use cases
This use cases outlines the key differences between subscription and installment payment methods. While both involve recurring payments, they have distinct characteristics.
Subscription
- Open-ended: Subscriptions typically have no fixed end date. They continue until canceled by the user or the provider.
- Examples: Netflix, Spotify, gym memberships.
Installment
- Fixed-term: Installments are structured with a predetermined number of payments.
- Examples: Car loans, student loans.
Total Payment: SAR 1000
Number of Installments: 10
Installment Amount: SAR 100
Go payment gateway
now you can go to payment gateway directly without visiting invoice page by post payflowly link
Request
POST ${Payflowly Link}
Response
Status 200
Response format is JSON
<!-- ==============JSON============== -->
{status:"...","URL":"https://........"}
where status will be one Of Pending,Success,Failed and URL is gateway payment link
Status 422 / Status 500
You will receive an error message
status | Message | Reason |
---|---|---|
422 | Invalid token. | Not a valid payflowly link. |
422 | Couldn't make payment url,Please try again later. | Error in payment gateway. Please contact our support team for assistance |
500 | An error has occurred | An unexpected error has occurred. Please contact our support team for assistance |
Payments
Create a payment
use create payflowly link and set "subscription_enabled" to false.
Retrieve a payment
1. By reference
GET /payment/reference_id/{reference_id}
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
QUERY PARAMETERS
app_id
(UUID,required) |
Your application id. |
2. By payflowly id
GET
/payment/id/{payflowly_id}
You application receive payflowly_id with all events
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
QUERY PARAMETERS
app_id
(UUID,required) |
Your application id. |
3. By token
GET
/payment/token/{token}
you can find token in payflowly link
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
QUERY PARAMETERS
app_id
(UUID,required) |
Your application id. |
Response
payflowly_id
(string) |
id created by payflowly | ||
reference_id
(string) |
"reference_id" in request | ||
total
(number) |
"total" in request | ||
refund
(number) |
Refunded amount (less or equal total) | ||
net
(number) |
Difference between total and refunded | ||
currency
(string) |
The currency used for payment | ||
status
(string) |
current payment status
check all statuses |
||
customer_id
(string) |
"customer_id" in request | ||
phone_number
(string) |
"phone_number" in request | ||
order_email
(string) |
the "order_email" field in request | ||
items
(array) |
"items" in /sign request
if you use item_name / item_price/ item_image will be one object here. |
||
credit
(array) |
"credit" in sign request
if you use credit_name / credit_value will be one object here. |
||
debit
(array) |
"debit" in sign request if you use debit_name / debit_value will be one object here. | ||
custom_data
(any) |
"custom_data" in sign request | ||
recovery_enabled
(boolean) |
The recovery status used for payment | ||
reminder_enabled
(boolean) |
The reminder status used for payment | ||
payment_gateway
(boolean) |
Payment gateway used for payment | ||
app_id
(UUID) |
Your application id | ||
payment_start_time
(date) |
when this payment will be available to user to pay | ||
payment_deadline
(date) |
The duration after which the payment will expire. | ||
type
(string) |
always will have type 'payment' | ||
token
(string) |
token in payflowly url | ||
payment_service_response
(object) |
Payment service (tap,tamara,..) response | ||
Only for search in payments in a subscription | |||
payment_installment
(array) |
Array of installment(s) in payment | ||
index
(number) |
The payment order within this subscription commences from 1 | ||
start_date
(date) |
Installment start date | ||
end_date
(date) |
Installment end date |
Update a payment
you can update some payments data if payment status is "new".
1. By reference
POST /payment/reference_id/{reference_id}
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
REQUEST BODY
app_id
(UUID,required) |
Your application id. |
customer_id
(string) |
Update customer’s id |
custom_data
(any) |
Updated custom data |
phone_number
(string) |
Updated customer phone number |
order_email
(string) |
Updated customer email |
order_customer_first_name
(string) |
Updated customer’s last name. |
order_customer_last_name
(string) |
Updated customer’s last name. |
order_description
(string) |
Updated order description |
2. By payflowly id
POST
/payment/id/{payflowly_id}
You application receive payflowly_id with all events
3. By token
POST
/payment/token/{token}
you can find token in payflowly link
Response
List payments
Request
GET /payment/list
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
QUERY PARAMETERS
app_id
(UUID,required) |
Your application id. |
id
(string) |
You application receive payflowly_id with all events |
status
(string) |
Payment Statuses |
reference_id
(string|object) |
The reference_id value can be a string or an object. To find exact matches, use string comparison or use a regular expression with the $regex operator. |
total
(number|object) |
The total can be either a numerical value or a complex object. To refine your search, use comparison operators like $lt(less than), $gt(greater than), $lte(less than/equal), and $gte(greater than/equal) to filter results based on specific numerical criteria. |
refund
(string|object) |
difference between total and refund
use the same search as total |
net
(string|object) |
difference between total and refund
use can the same search keys as total |
currency
(string) |
Payment currency code. |
token
(string) |
token in payflowly url |
custom_data
(string|object) |
In order to search within this object, you can append the desired key to
the
custom_data property.
For instance, if you can provide a value of {"coupon_id": "123"} for the custom_data field. Subsequently, you can perform a search using the custom_data.coupon_id key to retrieve the corresponding data. Don't forget you can use $regex for string values or search keys as total for number values |
customer_id
(string) |
to search in customer_id |
order_email
(string|object) |
Use $regex as key to search with regular expression for email |
phone_number
(string|object) |
Use $regex as key to search with regular expression for phone number |
recovery_enabled
(boolean) |
Use true / 1 to search for payment/subscription has recovery enabled.
Use false / 0 to search for payment/subscription has recovery not enabled. |
items.name
(string|object) |
Use $regex as key to search with regular expression for item name |
items.desc
(string|object) |
Use $regex as key to search with regular expression for item desc |
items.price
(string|object) |
Use $regex as key to search with regular expression for item price |
items.currency
(string|object) |
Use $regex as key to search with regular expression for item currency |
items.qty
(string|object) |
Use $regex as key to search with regular expression for item qty |
credit.name
(string|object) |
Use $regex as key to search with regular expression for credit name |
credit.value
(string|object) |
Use $regex as key to search with regular expression for credit value |
credit.currency
(string|object) |
Use $regex as key to search with regular expression for credit currency |
debit.name
(string|object) |
Use $regex as key to search with regular expression for debit name |
debit.value
(string|object) |
Use $regex as key to search with regular expression for debit value |
debit.currency
(string|object) |
Use $regex as key to search with regular expression for debit currency |
payment_start_time
(string|object) |
use can the same search keys as total
format YYYY-MM-DD YYYY-MM-DD HH:MM:SS YYYY-MM-DDTHH:MM:SSZ |
payment_deadline
(string|object) |
use can the same search keys as total
format YYYY-MM-DD YYYY-MM-DD HH:MM:SS YYYY-MM-DDTHH:MM:SSZ |
limit
(number <= 20) Default:20 |
Limits the number of returned results. |
offset
(number) |
The number of records into a dataset that you want to start, indexed at 0. |
Only for search in payments in a subscription | |
payment_installment.index
(number|object) |
The payment order within this subscription commences from 1 |
payment_installment.start_date
(string|object) |
The payment installment start date |
payment_installment.end_date
(string|object) |
The payment installment end date |
Response
payments
(array) |
array of payment objects | ||
payflowly_id
(string) |
id created by payflowly | ||
reference_id
(string) |
"reference_id" in request | ||
total
(number) |
"total" in request | ||
refund
(number) |
Refunded amount (less or equal total) | ||
net
(number) |
Difference between total and refunded | ||
currency
(string) |
The currency used for payment | ||
status
(string) |
current payment status
check all statuses |
||
cutomer_id
(string) |
"cutomer_id" in request | ||
phone_number
(string) |
"phone_number" in request | ||
order_email
(string) |
the "order_email" field in request | ||
items
(array) |
"items" in complete /sign request
if you use item_name / item_price/ item_image will be one object here. |
||
credit
(array) |
"credit" in complete sign request
if you use credit_name / credit_value will be one object here. |
||
debit
(array) |
"debit" in complete sign request if you use debit_name / debit_value will be one object here. | ||
custom_data
(any) |
"custom_data" in sign request | ||
recovery_enabled
(boolean) |
The recovery status used for payment | ||
reminder_enabled
(boolean) |
The reminder status used for payment | ||
payment_gateway
(boolean) |
Payment gateway used for payment | ||
app_id
(UUID) |
Your application id | ||
payment_start_time
(date) |
when this payment will be available to user to pay | ||
payment_deadline
(date) |
The duration after which the payment will expire. | ||
type
(string) |
always will have type 'payment' | ||
token
(string) |
token in payflowly url | ||
payment_service_response
(object) |
Payment service (tap,tamara,..) response | ||
Only for search in payments in a subscription | |||
payment_installment
(array) |
Array of installment(s) in payment | ||
index
(number) |
The payment order within this subscription commences from 1 | ||
start_date
(date) |
Installment start date | ||
end_date
(date) |
Installment end date | ||
count
(number) |
Total payments count. | ||
limit
(number) |
Limits the number of returned results. | ||
offset
(number) |
Offset from which start returned results. |
Subscriptions
Create a subscription
use create payflowly link and set "subscription_enabled" to true.
Retrieve a subscription
1. By reference
GET /subscription/reference_id/{reference_id}
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
QUERY PARAMETERS
app_id
(UUID,required) |
Your application id. |
2. By payflowly id
GET
/subscription/id/{payflowly_id}
You application receive payflowly_id with all events
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
QUERY PARAMETERS
app_id
(UUID,required) |
Your application id. |
3. By token
GET
/subscription/token/{token}
you can find token in payflowly url
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
QUERY PARAMETERS
app_id
(UUID,required) |
Your application id. |
Response
payflowly_id
(string) |
id created by payflowly | ||
reference_id
(string) |
"reference_id" in request | ||
total
(number) |
"total" in request | ||
currency
(string) |
The currency used for payment | ||
status
(string) |
current payment status
check all statuses |
||
customer_id
(string) |
"customer_id" in request | ||
phone_number
(string) |
"phone_number" in request | ||
order_email
(string) |
the "order_email" field in request | ||
items
(array) |
"items" in /sign request
if you use item_name / item_price/ item_image will be one object here. |
||
credit
(array) |
"credit" in sign request
if you use credit_name / credit_value will be one object here. |
||
debit
(array) |
"debit" in sign request if you use debit_name / debit_value will be one object here. | ||
custom_data
(any) |
"custom_data" in sign request | ||
recovery_enabled
(boolean) |
The recovery status used for subscription | ||
reminder_enabled
(boolean) |
The reminder status used for subscription | ||
app_id
(UUID) |
Your application id | ||
type
(string) |
always will have type 'subscription' | ||
token
(string) |
token in payflowly url | ||
subscription_start_date
(date) |
Date on which a user's subscription begins | ||
subscription_end_date
(date) |
Date on which a user's subscription ends | ||
subscription_recurring
(number) |
The number of installments | ||
subscription_interval
(string) |
Subscription interval | ||
payments
(array) |
Array of payment(s) in subscription | ||
payflowly_id
(string) |
id for this payment | ||
status
(text) |
subscription status(Active,Inactive,Success,Failed) | ||
payment_installment
(array) |
The payment installment within this subscription | ||
index
(number) |
The payment order within this subscription commences from 1 | ||
start_date
(date) |
Installment start date | ||
end_date
(date) |
Installment end date | ||
service_termination
(date) |
Maximum end date for successful payments in subscription |
List subscriptions
Request
GET /subscription/list
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
QUERY PARAMETERS
app_id
(UUID,required) |
Your application id. |
id
(string) |
You application receive payflowly_id with all events |
status
(string) |
Subscription Statuses |
reference_id
(string|object) |
The reference_id value can be a string or an object. To find exact matches, use string comparison or use a regular expression with the $regex operator. |
total
(number|object) |
The total can be either a numerical value or a complex object. To refine your search, use comparison operators like $lt(less than), $gt(greater than), $lte(less than/equal), and $gte(greater than/equal) to filter results based on specific numerical criteria. |
currency
(string) |
Payment currency code. |
token
(string) |
token in payflowly url |
custom_data
(string|object) |
In order to search within this object, you can append the desired key to
the
custom_data property.
For instance, if you can provide a value of {"coupon_id": "123"} for the custom_data field. Subsequently, you can perform a search using the custom_data.coupon_id key to retrieve the corresponding data. Don't forget you can use $regex for string values or search keys as total for number values |
customer_id
string |
to search in customer_id |
order_email
(string|object) |
Use $regex as key to search with regular expression for email |
phone_number
(string|object) |
Use $regex as key to search with regular expression for phone number |
recovery_enabled
(boolean) |
Use true / 1 to search for payment/subscription has recovery enabled.
Use false / 0 to search for payment/subscription has recovery not enabled. |
items.name
(string|object) |
Use $regex as key to search with regular expression for item name |
items.desc
(string|object) |
Use $regex as key to search with regular expression for item desc |
items.price
(string|object) |
Use $regex as key to search with regular expression for item price |
items.currency
(string|object) |
Use $regex as key to search with regular expression for item currency |
items.qty
(string|object) |
Use $regex as key to search with regular expression for item qty |
credit.name
(string|object) |
Use $regex as key to search with regular expression for credit name |
credit.value
(string|object) |
Use $regex as key to search with regular expression for credit value |
credit.currency
(string|object) |
Use $regex as key to search with regular expression for credit currency |
debit.name
(string|object) |
Use $regex as key to search with regular expression for debit name |
debit.value
(string|object) |
Use $regex as key to search with regular expression for debit value |
debit.currency
(string|object) |
Use $regex as key to search with regular expression for debit currency |
subscription_start_date
(string|object) |
use can the same search keys as total
format YYYY-MM-DD YYYY-MM-DD HH:MM:SS YYYY-MM-DDTHH:MM:SSZ |
subscription_end_date
(string|object) |
use can the same search keys as total
format YYYY-MM-DD YYYY-MM-DD HH:MM:SS YYYY-MM-DDTHH:MM:SSZ |
limit
(number <= 20) Default:20 |
Limits the number of returned results. |
offset
(number) |
The number of records into a dataset that you want to start, indexed at 0. |
Response
array of subscription objects
subscriptions
(array) |
array of subscription objects | ||||
payflowly_id
(string) |
id created by payflowly | ||||
reference_id
(string) |
"reference_id" in request | ||||
total
(number) |
"total" in request | ||||
currency
(string) |
The currency used for payment | ||||
status
(string) |
current payment status
check all statuses |
||||
customer_id
(string) |
"customer_id" in request | ||||
phone_number
(string) |
"phone_number" in request | ||||
order_email
(string) |
the "order_email" field in request | ||||
items
(array) |
"items" in /sign request
if you use item_name / item_price/ item_image will be one object here. |
||||
credit
(array) |
"credit" in sign request
if you use credit_name / credit_value will be one object here. |
||||
debit
(array) |
"debit" in sign request if you use debit_name / debit_value will be one object here. | ||||
custom_data
(any) |
"custom_data" in sign request | ||||
recovery_enabled
(boolean) |
The recovery status used for subscription | ||||
reminder_enabled
(boolean) |
The reminder status used for subscription | ||||
app_id
(UUID) |
Your application id | ||||
type
(string) |
always will have type 'subscription' | ||||
token
(string) |
token in payflowly url | ||||
subscription_start_date
(date) |
Date on which a user's subscription begins | ||||
subscription_end_date
(date) |
Date on which a user's subscription ends | ||||
subscription_recurring
(number) |
The number of installments | ||||
subscription_interval
(string) |
Subscription interval | ||||
payments
(array) |
Array of payment(s) in subscription | ||||
payflowly_id
(string) |
id for this payment | ||||
status
(text) |
subscription status(Active,Inactive,Success,Failed) | ||||
payment_installment
(array) |
The payment installment within this subscription | ||||
index
(number) |
The payment order within this subscription commences from 1 | ||||
start_date
(date) |
Installment start date | ||||
end_date
(date) |
Installment end date | ||||
service_termination
(date) |
Maximum end date for successful payments in subscription | ||||
count
(number) |
Total subscriptions count. | ||||
limit
(number) |
Limits the number of returned results. | ||||
offset
(number) |
Offset from which start returned results. |
Subscription termination
Subscription termination will prevent the user from making any further installment payments.
Request
POST /subscription/disable
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
Content-Type
(required) |
use application/x-www-form-urlencoded or application/json |
REQUEST BODY
Property | Usage |
---|---|
app_id
(UUID,required) |
Your application id. |
reference_id
(string,required) |
Reference ID for this payment |
Response
You will receive unified response of subscription and with "Inactive" status
Refunds
You can process refunds either through our dashboard or by utilizing our refund API. Full or partial refunds are available.
Create a refund
Request
POST /refund
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
Content-Type
(required) |
use application/x-www-form-urlencoded or application/json |
REQUEST BODY
app_id
(UUID,required) |
Your application ID. | |
One of |
id
(string,required) |
Payflowly ID for successful payment |
reference_id
(string,required) |
Reference ID for successful payment | |
total
(string,required) |
Amount to be returned |
Response
Status 200
This JSON object represents a refund response with a single property:
{ "refundId": "payflowly_refunded_id" }
Status 422 / Status 500
You will receive an error message
status | Message | Reason |
---|---|---|
401 | Invalid authorization credentials | No valid secret or app_id was provided |
422 | Missing {field} field | If on or more required field is missing |
422 | Invalid total field value | If field "total" is zero or field is not integer |
500 | An error has occurred | An unexpected error has occurred. Please contact our support team for assistance |
Retrieve a refund
Request
1. By reference
GET /refund/reference_id/{reference_id}
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
QUERY PARAMETERS
app_id
(UUID,required) |
Your application id. |
2. By payflowly id
GET /refund/id/{payflowly_id}
You application receive payflowly_id with all events
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
QUERY PARAMETERS
app_id
(UUID,required) |
Your application id. |
Response
payflowly_id
(string) |
refund id | ||
reference_id
(string) |
"reference_id" in request | ||
total
(number) |
"total" in request | ||
currency
(string) |
The currency used for payment | ||
status
(string) |
current refund status
check all statuses |
||
type
(string) |
always will have type 'refund' |
List refunds
Request
GET /refund/list
REQUEST HEADERS
Authorization
(required) |
Secret you provided while adding your application.
Bearer {{secret}}} |
QUERY PARAMETERS
app_id
(UUID,required) |
Your application id. |
id
(string) |
This id is refundId in response of create a refund api |
status
(string) |
Refund Status |
reference_id
(string|object) |
The reference_id value can be a string or an object. To find exact matches, use string comparison or use a regular expression with the $regex operator. |
total
(number|object) |
The total can be either a numerical value or a complex object. To refine your search, use comparison operators like $lt(less than), $gt(greater than), $lte(less than/equal), and $gte(greater than/equal) to filter results based on specific numerical criteria. |
currency
(string) |
Payment currency code. |
limit
(number <= 20) Default:20 |
Limits the number of returned results. |
offset
(number) |
The number of records into a dataset that you want to start, indexed at 0. |
Response
refunds
(array) |
array of refund objects | |
payflowly_id
(string) |
refund id | |
reference_id
(string) |
"reference_id" in request | |
total
(number) |
"total" in request | |
currency
(string) |
The currency used for payment | |
status
(string) |
current refund status
check all statuses |
|
type
(string) |
always will have type 'refund' | |
count
(number) |
Total refunds count. | |
limit
(number) |
Limits the number of returned results. | |
offset
(number) |
Offset from which start returned results. |
Recovery
Sending a mail notification to your user after a specified period of time has elapsed since the initiation of payment, and the invoice remains unpaid.
By default, recovery is not enabled, but you can enable it by sending "recovery_enabled" with sign request and your user will receive a mail like next image in "recovery_interval"

When go production, you can choose to have the default recovery mode enabled or disabled. This will eliminate the need to include the ""recovery_enabled"" parameter with every signature request, unless you specifically want to override the default setting.
And also you can set your template rather than default template
Reminder
By default, reminders is not enabled, but you can enable it by sending "reminder_enabled" with sign request and your user will receive a mail like next image in "reminder_interval" before payment date

When go production, you can choose to have the default reminder mode enabled or disabled. This will eliminate the need to include the ""reminder_enabled"" parameter with every signature request, unless you specifically want to override the default setting.
And also you can set your template rather than default template
Events
Whenever there is any user action or a payment status changes, we send data to a designated webhook_url to ensure that you receive timely updates about any changes.
Payment Events
You will always receive payment data and more properties
event_type
(string) |
|
||||||||||||||||||||||||||||||||
event_data
(object) |
if event type is USER_PAYMENT_SUCCESS or USER_PAYMENT_FAILED
if event type is USER_REFUND_SUCCESS or USER_REFUND_FAILED
|
||||||||||||||||||||||||||||||||
hash
(string) |
A hash is generated to verify the authenticity and integrity of data sent. The process involves:
This hash can be used to validate the data sender's identity and ensure data hasn't been tampered with during transmission. Example:
|
Subscription Events
You will always receive subscription data and more properties
event_type
(string) |
|
||||||||||
hash
(string) |
as described before |
Response Statuses
Payment Statuses
NO. | Status | Cases |
---|---|---|
1 | New | Once the payflowly link is created and user not click pay yet. |
2 | Pending | User click pay and redirect to payment gateway |
3 | Success | User make successful payment |
4 | Refunded | User make successful payment then refunded |
5 | Refunded Partially | User make successful payment then partially refunded |
6 | Failed |
Your user try to pay and payment failed
Payment status will "Failed" if user is redirect to payment gateway and didn't enter payment data(timeout) note:user still can pay if "recovery_enabled" is true |

Refund Statuses
NO. | Status | Cases |
---|---|---|
1 | Pending | refund is started |
2 | Success | Successful refund |
6 | Failed | Unsuccessful refund |

Subscription Statuses
NO. | Status | Cases |
---|---|---|
1 | Active | Once the subscription link is created and user not click pay yet. |
2 | Inactive | Subscription is terminated by app using termination api. |
3 | Success | All payments are done successfully |
4 | Failed | The subscription has failed to proceed due to a payment deadline being exceeded. |

Time Abbreviations
NO. | Abbreviation | Stand for |
---|---|---|
1 | m/M | Minute |
2 | h/H | Hour |
3 | d/D | Day |
4 | mo/MO | Month |
5 | y/Y | Year |
FAQ
The details will be added later.
Support
If this documentation doesn't answer your questions, So, Please send us Email via support@payflowly.com
We are located in GMT +3 time zone, and we answer all questions within 24-48 hours in weekdays. In some rare cases the waiting time can be to 48 hours. (except holiday seasons which might take longer).