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": "[email protected]",
			"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 NameMandator or OptionalTag DescriptionData Type, Length, Possible Values
profile_idMandatoryMerchant Profile ID
account_idMandatoryMerchant Deposit Account ID
order_idMandatoryMerchant's Batch Reference
requestsOptionalTransfer record requestsJSON Array
JSON array
amountMandatoryTransfer AmountNumeric with support for decimals
merchant_referenceOptionalMerchant specific id or valueAlphanumeric
beneficiary_nameMandatoryBeneficiary NameAlphanumeric
beneficiary_countryMandatory Beneficiary Country CodeISO 3166 - 1 Alpha 2 Code
beneficiary_account_numberMandatoryBeneficiary IBANAlphanumeric - Length as mentioned in https://www.iban.com/structure
beneficiary_bankMandatoryBeneficiary Bank
beneficiary_bank_branchMandatory Beneficiary Bank Branch
beneficiary_emailMandatory Beneficiary Email address
beneficiary_mobile_numberMandatory Beneficiary Mobile Number in E164 format
beneficiary_address1MandatoryBeneficiary Address Line 1
beneficiary_address2Mandatory Beneficiary Address Line 2
transfer_codeMandatoryTransfer Code100 - 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": "[email protected]",
      "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": "[email protected]",
      "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:

  1. pending
  2. paid
  3. processed
  4. failed
  5. 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