Getting Started
In order to use the below API you need to have a Clickpay account. You can sign up. for a free account here.
Once you complete sign up and Log in to you Clickpay dashboard, Go to Developers page > Key management, where you can find the profile id and server key using in this collection.
PayOuts API
The "CreateBatch" API is used to create a batch. "Add More Requests to Batch" API is used to submit additional transfer requests. "CloseBatch" API is to submit the Batch for approval and processing. "Query" API is to check the status of the payout.
All requests are made using server-to-server calls, with JSON format data
All requests must be sent using HTTP POST to the Clickpay transaction API endpoint
Authorization Header
You will need your server key in order to make any of the API requests in this collection. This is not the same as the client key that is used within the managed payment pages. Authentication is done by including your server key in the Authorization:' header for the request.
(Authorization Type: API key)
Server key is available in your Clickpay Merchant Dashboard > Developers Section Key Management
Great Batch
Request Method : POST
https://secure.clickpay.com.sa/payout/batch/new
Header : Authorization: Server API Key (Required)
Body:
{
"profile_id": 45154,
"account_id": 654,
"order_id": "Payout-API-20240825",
"requests": [
{
"amount": 2,
"beneficiary_name": "Riyas Razak",
"beneficiary_country": "SA",
"beneficiary_account_number": "SA30050000001",
"beneficiary_bank": "ALIMNA",
"beneficiary_bank_branch": "",
"beneficiary_email": "clickpay@alinma.com",
"beneficiary_mobile_number": "+96651111111",
"beneficiary_address1": "Riyadh",
"beneficiary_address2": "",
"transfer_code": 100
}
]
}Response:
{
"batch_id": 12,
"profile_id": 48264,
"account_id": 5154,
"currency": "SAR",
"total": "0",
"count": 0,
"order_id": "Payout-API-20220211",
"status": "New",
"trace": "PMNT0201.62376344.00074C2A"
}| Tag Name | Mandator or Optional | Tag Description | Data Type, Length, Possible Values |
|---|---|---|---|
| profile_id | Mandatory | Merchant Profile ID | |
| account_id | Mandatory | Merchant Deposit Account ID | |
| order_id | Mandatory | Merchant's Batch Reference | |
| requests | Optional | Transfer record requests | JSON Array |
JSON array | |||
| amount | Mandatory | Transfer Amount | Numeric with support for decimals |
| merchant_reference | Optional | Merchant specific id or value | Alphanumeric |
| beneficiary_name | Mandatory | Beneficiary Name | Alphanumeric |
| beneficiary_country | Mandatory | Beneficiary Country Code | ISO 3166 - 1 Alpha 2 Code |
| beneficiary_account_number | Mandatory | Beneficiary IBAN | Alphanumeric - Length as mentioned in https://www.iban.com/structure |
| beneficiary_bank | Mandatory | Beneficiary Bank | |
| beneficiary_bank_branch | Mandatory | Beneficiary Bank Branch | |
| beneficiary_email | Mandatory | Beneficiary Email address | |
| beneficiary_mobile_number | Mandatory | Beneficiary Mobile Number in E164 format | |
| beneficiary_address1 | Mandatory | Beneficiary Address Line 1 | |
| beneficiary_address2 | Mandatory | Beneficiary Address Line 2 | |
| transfer_code | Mandatory | Transfer Code | 100 - Salary 101 - Pension 102 - General Cash Management 103 - Donation |
Add More Requests to Batch
Request Method: POST
URL: https://secure.clickpay.com.sa/payout/batch/add
Header : Authorization: Server API Key (Required)
Body:
{
"batch_id": 30143,
"profile_id": {{profile_id}},
"account_id": {{account_id}},
"order_id": "Payout-API-1",
"requests": [
{
"amount": 101,
"beneficiary_name": "riyas razak",
"beneficiary_country": "SE",
"beneficiary_account_number": "SE3550000000054910000003",
"beneficiary_bank": "ESSESESS",
"beneficiary_bank_branch": "",
"beneficiary_email": "support@clickpay.com",
"beneficiary_mobile_number": "+971585436859",
"beneficiary_address1": "Riyadh",
"beneficiary_address2": "",
"transfer_code": 100
},
{
"amount": 155,
"beneficiary_name": "Rami Hegazi",
"beneficiary_country": "SE",
"beneficiary_account_number": "SE3550000000054910000003",
"beneficiary_bank": "ESSESESS",
"beneficiary_bank_branch": "",
"beneficiary_email": "clickpay@alinma.com",
"beneficiary_mobile_number": "+971585436859",
"beneficiary_address1": "Riyadh",
"beneficiary_address2": "",
"transfer_code": 101
}
]
}Close Batch
Request Method: POST
URL: https://secure.clickpay.com.sa/payout/batch/close
Header:
Authorization: Server API Key (Required)
Body:
{
"batch_id": 6,
"profile_id": 45154,
"account_id": 654,
"count": 1,
"total": 1 /// Multiple Batch use sub_total
}Query
Request Method: POST
URL: https://secure.clickpay.com.sa/payout/batch/query
Header:
Authorization: Server API Key (Required)
Body:
{
"batch_id": 30173,
"profile_id": {{profile_id}},
"account_id": {{account_id}}
}Query a single request in a batch
Request Method: POST
URL: https://secure.clickpay.com.sa/payout/batch/query
Header:
Authorization: Server API Key (Required)
Body:
{
"batch_id": 30173,
"profile_id": {{profile_id}},
"account_id": {{account_id}},
"entry_id": 10031
}Response:
{
"entry_id": 10029,
"amount": "201.01",
"fee": "0.63",
"total": "201.64",
"beneficiary_account_number": "SA3305000068200027493000",
"status": "Failed",
"protocol_message": "Unrecoverable integration error"
}Query batch with status
{{status}} can be checked for the following statuses:
- pending
- paid
- processed
- failed
- rejected
Request Method: POST
URL: https://secure.clickpay.com.sa/payout/batch/query/{{status}}
Header:
Authorization: Server API Key (Required)
Body:
{
"batch_id": 30173,
"profile_id": {{profile_id}},
"account_id": {{account_id}}
}Response:
{
"batch_id": 30,
"profile_id": 48264,
"account_id": 5154,
"order_id": "KSA Payout-API TestCase",
"status": "Completed",
"requests": [
{
"entry_id": 52,
"amount": "120.88",
"fee": "0.63",
"total": "121.51",
"beneficiary_account_number": "SA2710000005100002955109",
"status": "Paid",
"protocol_message": "INITIATED"
},
{
"entry_id": 54,
"amount": "800.88",
"fee": "1.45",
"total": "802.33",
"beneficiary_account_number": "AE070331234567890123456",
"status": "Paid",
"protocol_message": "INITIATED"
}
],
"trace": "PMNT0202.62ECCF3C.000226B4"
}Reporting
For viewing the deposit please select the deposit account in your dashboard
Once open Deposit section will be able to see the payouts with their status
For exporting the payouts batch click on the ref
Once opened you will be able to see export to xls option as in below screenshot
For IPN log click the next icon as below screenshot
