🅿🅵

Get started with Payflowly

https://get.payflowly.com/

Payflowly is a simple platform allowing applications to integrate with a lot of payment services.


  • 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

  1. visit our dashboard at https://portal.payflowly.com/
  2. sign up for free or login if you already have an account.
  3. choose application in left side menu
  4. 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

    1. has 15 characters length or more
    2. contains lowercase letter, Uppercase letter, digit and special characters

    note: always use secret in header to communicate with payflowly
    6-u9dQvn2iZ.__qL)n
    App Website

    (string)

    Your application domain. https://www.eshop.com/
  5. 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

First Diagram

Second Diagram

Second Diagram

Flow of the Payment Process
  1. Post/Sign: The user initiates the payment process within your application, likely by clicking a "Pay" button or similar action.
  2. Payflowly Link: Your application generates a link using Payflowly's service.
  3. In First Diagram: In Second Diagram:
    • 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.
  4. User is Redirected to Payment Gateway: The user is redirected to the chosen payment gateway (Tap, Tamara, etc.) to complete the payment.
  5. Send Payment Status: After the payment is processed, the payment gateway sends a notification (webhook or other method) to Payflowly with the payment status.
  6. 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:
  • 1Mo+3d → 1 month and 3 days from now
  • 2Mo-5d → 2 months minus 5 days from now
When to Use This?
  • Subscription renewals (e.g., "1Mo+7d grace period")
  • Temporary access tokens (e.g., "2Mo-2d early expiry")
  • Dynamic billing cycles
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
items

(array)

Array of item(s) we want to be paid for.
name

(string)

Product/Item name.
note: required for tabby / tamara
desc

(string)

Short product/item description is recommended.
price

(number|string)

Product/Item Price.
note: required as number for tabby / tamara
currency

(string)

Currency code.
img

(string)

Product Image URL (base64 or URL).
url

(string)

URL of the item from merchant's website
qty

(number|string)

Product/Item quantity.
note: required as number for tabby / tamara
category

(string)

Name of high-level category (Clothes, Electronics,etc.);
note: required for tabby / tamara
reference_id

(string)

The unique id of the item from merchant's side
note: required for tamara
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.
credit

(array)

Array of any credits in invoice as previous user credit or coupons.
name

(string)

Credit type.
value

(number)

Credit value.
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.
debit

(array)

Array of any debits in invoice as taxes or shipment value.
name

(string)

Debit type.
value

(number)

Debit value.
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.
for example installment payment for $1000 in 10 installments
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
the same request as update by reference
3. By token
POST /payment/token/{token}

you can find token in payflowly link

the same request as update by reference

Response

the same response as retrieve a payment

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"

recovery enabled

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

reminder

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 When
GENERATING_PAYMENT_URL After making successful sign request
USER_REDIRECTED_TO_INVOICE_PAGE After application redirect user to payflowly link(GET Method)
USER_VISIT_INVOICE_PAGE After user visit invoice page
USER_CLICK_CHECKOUT After user click checkout in payment page or call payment link (POST Method)s
USER_VISIT_CHECKOUT_PAGE After the user being redirected to the checkout page
USER_PAYMENT_ABANDONED After the abondoned time of the payment without user trying to pay
Payflowly link should be visited or payment link created
USER_PAYMENT_SUCCESS After user made successful payment
USER_PAYMENT_FAILED After user made unsuccessful payment
USER_PAYMENT_EXPIRED After the expiration of the payment deadline without a successful payment being made
USER_RECOVERY_INITIATED After first email is sent to user
USER_RECOVERY_EXPIRED After payment deadline
USER_REMINDER_INITIATED After every reminder mail sent to user
USER_RECOVERY_SUCCESS After user made successful payment in recovery time
USER_REFUND_SUCCESS After user is (partial/complete) refunded
USER_REFUND_FAILED After refund failed
event_data

(object)

if event type is USER_PAYMENT_SUCCESS or USER_PAYMENT_FAILED

payment_response

(object)

the response from payment gateway

if event type is USER_REFUND_SUCCESS or USER_REFUND_FAILED

refund_total

(number)

the refunded amount
refund_status

(string)

the status of refund
refund_response

(object)

response from payment gateway
hash

(string)

A hash is generated to verify the authenticity and integrity of data sent. The process involves:

  • Payload Preparation: The data payload is converted into a JSON string excluding the 'hash' key.
  • Hash Generation: A SHA512 HMAC hash is calculated using:
    • The prepared JSON string as the data to be hashed.
    • The application secret as the HMAC key.

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)

Event When
GENERATING_SUBSCRIPTION_URL After making successful sign request if subscription enabled
SUBSCRIPTION_INITIATED After the user successfully completes the first installment payment.
SUBSCRIPTION_SUCCESS After the user successfully completes all the installment payments.
SUBSCRIPTION_FAILED After user fails to pay a installment payment and it is expired.
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
status flow

Refund Statuses

NO. Status Cases
1 Pending refund is started
2 Success Successful refund
6 Failed Unsuccessful refund
refund status flow

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.
subscription status flow

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).