Welcome to Pesapal API 3.0. Getting started with Pesapal is quick and easy!
\nIn this release, you will learn how to use our API endpoints to access Pesapal services. Our APIs are built on REST(Representational State Transfer) thus our data entities are represented as HTTP resources and are accessed using HTTP verbs GET and POST. Requests and responses are JSON encoded.
\nFind information about integrating your website with Pesapal. This documentation includes sample codes for each API we have.
\nBase URLs
\nError Object
\nIn case an error occurs during any API call, Pesapal will respond with a json string in the following format;
\n{\n \"error\":{\n \"type\": \"error_type\",\n \"code\": \"response_code\",\n \"message\": \"Detailed error message goes here..\"\n }\n}\n\nPesapal's API Authentication requests are done via a POST request.
\nYour Pesapal merchant consumer_key and consumer_secret will be used to generate an access token. This access token is valid for a maximum period of 5 minutes. Use this token (sent as a Bearer Token) to access all other Pesapal API 3.0 endpoints.
\nThe URL to the API service is either:
\nAccept : The response format, which is required for operations with a response body.
Content-Type : The request format, which is required for operations with a request body.
Your live/production consumer_key and consumer_secret will be sent to your merchant email on opening a business/merchant account.
\nPlease click here to open a live/production business account.
\n\n\nClick here for some test credentials to use while connecting to our demo/sandbox API.
\n
{\n \"consumer_key\":\"xxxxx\",\n \"consumer_secret\":\"xxxxxx\"\n}\n\n{\n \"token\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3VzZXJkYXRhIjoiZWQ2MTkwMGYtZGNiMy00NjM2LWIxNGUtY2U1MGQwYzk2M2I1IiwidWlkIjoicWtpbzFCR0dZQVhUdTJKT2ZtN1hTWE5ydW9ac3JxRVciLCJuYmYiOjE2Mjk5NzczNzAsImV4cCI6MTYyOTk4MDk3MCwiaWF0IjoxNjI5OTc3MzcwLCJpc3MiOiJodHRwOi8vY3licWEucGVzYXBhbC5jb20vIiwiYXVkIjoiaHR0cDovL2N5YnFhLnBlc2FwYWwuY29tLyJ9.WGl2uJ68EhEdfrjM1iDveKmSDwO9du0CN9e0j8NtOq4\",\n \"expiryDate\": \"2021-08-26T12:29:30.5177702Z\",\n \"error\": null,\n \"status\": \"200\",\n \"message\": \"Request processed successfully\"\n}\n\nIPN stands for Instant Payment Notification. When a payment is made against a transaction, Pesapal will trigger an IPN call to the notification URL related to this transaction. This notification URL is usually located on your servers. These notifications allows you to be alerted in real time whenever there is a status change for any transaction.
\nAn IPN is particular important as it allows you to be notified incase the following happens:
\nYour client gets disconnected after payment due to internet issues
\nYour client experiences server errors hence Pesapal and your application gets disconnected before callback URL is loaded.
\nYour client exits your application / closes the browser during payment.
\nThe transaction is rejected.
\nAs such, it's mandatory to have IPN configured to allow Pesapal to notify your servers when a status changes. It's also important to note that this IPN URL must be publicly available. In cases where you have strict server rules preventing external systems reaching your end, you must then whitelist all calls from our domain (pesapal.com). Please be informed that IP whitelisting
is not feasible as our IP may change without notice.
Before sending Submit Order Requests to Pesapal API 3.0 you are expected to register your IPN URL. Upon registration, you receive an IPN ID which is a mandatory field (notification_id) when submitting an order request to Pesapal API 3.0. This notification_id uniquely identifies the endpoint Pesapal will send alerts to whenever a payment status changes for each transaction processed via API 3.0
\nThe URL to our IPN registration API is either:
\nSandbox/Demo URL: https://cybqa.pesapal.com/pesapalv3/api/URLSetup/RegisterIPN
\nProduction/Live URL: https://pay.pesapal.com/v3/api/URLSetup/RegisterIPN
\n{\n \"url\": \"https://www.myapplication.com/ipn\",\n \"ipn_notification_type\": \"GET\"\n}\n\n{\n \"url\": \"https://www.myapplication.com/ipn\",\n \"created_date\": \"2022-03-03T17:29:03.7208266Z\",\n \"ipn_id\": \"e32182ca-0983-4fa0-91bc-c3bb813ba750\",\n \"notification_type\": 0,\n \"ipn_notification_type_description\": \"GET\",\n \"ipn_status\": 1,\n \"ipn_status_decription\": \"Active\",\n \"error\": null,\n \"status\": \"200\"\n}\n\nYou can also use our online forms below to register your IPN URLs.
\n\n","urlObject":{"path":["RegisterIPN"],"host":["{{protocol}}{{api-host}}{{api-url}}URLSetup"],"query":[],"variable":[]}},"response":[],"_postman_id":"cc6f853e-0802-4b0d-b8b8-17ed90308189"},{"name":"GetIPNList","id":"d5491782-3526-4c11-9777-93bb6b2e1616","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt-token}}"}]},"isInherited":false},"method":"GET","header":[],"url":"{{protocol}}{{api-host}}{{api-url}}URLSetup/GetIpnList","description":"This endpoint allows you to fetch all registered IPN URLs for a particular Pesapal merchant account.
\nThe URL to our GetIPNList API is either:
\nThe API call is authenticated using the authorization token.
\nNo payload is required.
\n[\n {\n \"url\": \"https://www.myapplication.com/ipn\",\n \"created_date\": \"2022-03-03T17:29:03.7208266Z\",\n \"ipn_id\": \"e32182ca-0983-4fa0-91bc-c3bb813ba750\",\n \"error\": null,\n \"status\": \"200\"\n },\n {\n \"url\": \"https://ipn.myapplication.com/application2\",\n \"created_date\": \"2021-12-05T04:23:45.5509243Z\",\n \"ipn_id\": \"c3bb813ba750-0983-4fa0-91bc-e32182ca\",\n \"error\": null,\n \"status\": \"200\"\n }\n ]\n\nOnce you have received the bearer token, the next step will be the actual request to create a payment request.
\nA good example would be a case where the customer has clicked pay now button on your website. At this point, you call the SubmitOrderRequest and in return you will get a response which contains a payment redirect URL which you then redirect the customer to or load the URL as an iframe within your site in case you don’t want to redirect the customer off your application.
\nThe payment URL will contain the payment methods presented to the customer by Pesapal. After the customer has made the payment, they will be redirected to your callback URL which you will have already provided to us as part of submit order request.
\nThe URL to our SubmitOrderRequest API is either:
\n* Sandbox/Demo URL: https://cybqa.pesapal.com/pesapalv3/api/Transactions/SubmitOrderRequest
* Production/Live URL: https://pay.pesapal.com/v3/api/Transactions/SubmitOrderRequest
Customer billing address details to be included as part of the SUBMIT ORDER REQUEST.
\n{\n \"id\": \"AA1122-3344ZZ\",\n \"currency\": \"KES\",\n \"amount\": 100.00,\n \"description\": \"Payment description goes here\",\n \"callback_url\": \"https://www.myapplication.com/response-page\",\n \"notification_id\": \"fe078e53-78da-4a83-aa89-e7ded5c456e6\",\n \"billing_address\": {\n \"email_address\": \"john.doe@example.com\",\n \"phone_number\": \"\",\n \"country_code\": \"KE\",\n \"first_name\": \"John\",\n \"middle_name\": \"\",\n \"last_name\": \"Doe\",\n \"line_1\": \"\",\n \"line_2\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"postal_code\": \"\",\n \"zip_code\": \"\"\n }\n}\n\nAfter successfully creating the order, your response will contain a payment URL (redirect_url).
\nStatus 200 mean your request to process the payment has been received successfully meaning the order has been successfully created on our systems and you can now redirect your customer to make the payment.
\n{\n \"order_tracking_id\": \"b945e4af-80a5-4ec1-8706-e03f8332fb04\",\n \"merchant_reference\": \"TEST1515111119\",\n \"redirect_url\": \"https://cybqa.pesapal.com/pesapaliframe/PesapalIframe3/Index/?OrderTrackingId=b945e4af-80a5-4ec1-8706-e03f8332fb04\",\n \"error\": null,\n \"status\": \"200\"\n}\n\nRedirecting your customer to this redirect_url will present them with a list of available payment methods which they can use to make the payment.
\nYou can either load this URL outside or within your website (using an Iframe). The advantage of using an iframe is that your customer will not be redirected off the site, hence a seamless payment process.
\nOnce your customer selects their preferred payment method and makes a payment, Pesapal will process the payment and redirect your customers to the callback URL which you had provided as part of the SubmitOrderRequest API call.
\nThe following parameter will be appended to your callback URL.
\nSample Callback URL: https://www.myapplication.com/response-page?OrderTrackingId=b945e4af-80a5-4ec1-8706-e03f8332fb04&OrderMerchantReference=TEST1515111119&OrderNotificationType=CALLBACKURL
\nAt the same time, Pesapal will send an alert to your IPN URL informing you of a status change.
\nThe IPN alert will either be a GET or POST request, depending on which HTTP method you selected when registering the IPN URL.
\nThe IPN call will have the following parameters;
\n\nNB: The callback URL and the IPN calls will NOT have the status of the payment for security reasons. As such, you will be required to fetch the status of the payment using the GetTransactionStatus API once the callback page is loaded and when the IPN URL is triggered.
\n","urlObject":{"path":["SubmitOrderRequest"],"host":["{{protocol}}{{api-host}}{{api-url}}Transactions"],"query":[],"variable":[]}},"response":[],"_postman_id":"90625f77-3a45-4baf-99d7-555a67b2c7f4"},{"name":"DirectMobileMoneySTK","id":"0fcf838d-d27a-4744-8a16-4181bcc6d628","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt-token}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"msisdn\": \"0723241024\",\r\n\t\"payment_method\":\"MpesaKE\",\r\n \"id\": \"TEST-01\",\r\n \"currency\": \"KES\",\r\n \"amount\": \"1\",\r\n \"description\": \"Testing\",\r\n \"callback_url\": \"https://www.google.com\",\r\n \"notification_id\": \"1812f9d2-36f1-4e0a-831b-dc2995b5af9e\",\r\n \"billing_address\": {\r\n \"email_address\": \"lazaro@pesapal.com\",\r\n \"phone_number\": \"0738681691\",\r\n \"country_code\": \"\",\r\n \"first_name\": \"Otieno\",\r\n \"middle_name\": \"\",\r\n \"last_name\": \"Laz\",\r\n \"line_1\": \"\",\r\n \"line_2\": \"\",\r\n \"city\": \"\",\r\n \"state\": \"\",\r\n \"postal_code\": \"\",\r\n \"zip_code\": \"\"\r\n }\r\n}"},"url":"{{protocol}}{{api-host}}{{api-url}}transactions/stk","description":"Once you have received the bearer token, the next step will be the actual request to create a payment request.
\nA good example would be a case where the customer has clicked pay now button on your website. At this point, you call the SubmitOrderRequest and in return you will get a response which contains a payment redirect URL which you then redirect the customer to or load the URL as an iframe within your site in case you don’t want to redirect the customer off your application.
\nThe payment URL will contain the payment methods presented to the customer by Pesapal. After the customer has made the payment, they will be redirected to your callback URL which you will have already provided to us as part of submit order request.
\nThe URL to our SubmitOrderRequest API is either:
\n* Sandbox/Demo URL: https://cybqa.pesapal.com/pesapalv3/api/Transactions/SubmitOrderRequest
* Production/Live URL: https://pay.pesapal.com/v3/api/Transactions/SubmitOrderRequest
Customer billing address details to be included as part of the SUBMIT ORDER REQUEST.
\n{\n \"id\": \"AA1122-3344ZZ\",\n \"currency\": \"KES\",\n \"amount\": 100.00,\n \"description\": \"Payment description goes here\",\n \"callback_url\": \"https://www.myapplication.com/response-page\",\n \"notification_id\": \"fe078e53-78da-4a83-aa89-e7ded5c456e6\",\n \"billing_address\": {\n \"email_address\": \"john.doe@example.com\",\n \"phone_number\": \"\",\n \"country_code\": \"KE\",\n \"first_name\": \"John\",\n \"middle_name\": \"\",\n \"last_name\": \"Doe\",\n \"line_1\": \"\",\n \"line_2\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"postal_code\": \"\",\n \"zip_code\": \"\"\n }\n}\n\nAfter successfully creating the order, your response will contain a payment URL (redirect_url).
\nStatus 200 mean your request to process the payment has been received successfully meaning the order has been successfully created on our systems and you can now redirect your customer to make the payment.
\n{\n \"order_tracking_id\": \"b945e4af-80a5-4ec1-8706-e03f8332fb04\",\n \"merchant_reference\": \"TEST1515111119\",\n \"redirect_url\": \"https://cybqa.pesapal.com/pesapaliframe/PesapalIframe3/Index/?OrderTrackingId=b945e4af-80a5-4ec1-8706-e03f8332fb04\",\n \"error\": null,\n \"status\": \"200\"\n}\n\nRedirecting your customer to this redirect_url will present them with a list of available payment methods which they can use to make the payment.
\nYou can either load this URL outside or within your website (using an Iframe). The advantage of using an iframe is that your customer will not be redirected off the site, hence a seamless payment process.
\nOnce your customer selects their preferred payment method and makes a payment, Pesapal will process the payment and redirect your customers to the callback URL which you had provided as part of the SubmitOrderRequest API call.
\nThe following parameter will be appended to your callback URL.
\nSample Callback URL: https://www.myapplication.com/response-page?OrderTrackingId=b945e4af-80a5-4ec1-8706-e03f8332fb04&OrderMerchantReference=TEST1515111119&OrderNotificationType=CALLBACKURL
\nAt the same time, Pesapal will send an alert to your IPN URL informing you of a status change.
\nThe IPN alert will either be a GET or POST request, depending on which HTTP method you selected when registering the IPN URL.
\nThe IPN call will have the following parameters;
\n\nNB: The callback URL and the IPN calls will NOT have the status of the payment for security reasons. As such, you will be required to fetch the status of the payment using the GetTransactionStatus API once the callback page is loaded and when the IPN URL is triggered.
\n","urlObject":{"path":["stk"],"host":["{{protocol}}{{api-host}}{{api-url}}transactions"],"query":[],"variable":[]}},"response":[],"_postman_id":"0fcf838d-d27a-4744-8a16-4181bcc6d628"},{"name":"GetTransactionStatus","id":"e196c778-3486-4e4c-9266-92925b96991f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt-token}}"}]},"isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"url":"{{protocol}}{{api-host}}{{api-url}}GetTransactionStatus?orderTrackingId={{order-tracking-id}}","description":"Once Pesapal redirect your customer to your callback URL and triggers your IPN URL, you need to check the status of the payment using the OrderTrackingId.
\nThe URL to the API service is either:
\n* Sandbox/Demo URL: https://cybqa.pesapal.com/pesapal/v3/api/Transactions/GetTransactionStatus?orderTrackingId=xxxxxxxxxxxx
\n* Production/Live URL: https://pay.pesapal.com/v3/api/Transactions/GetTransactionStatus?orderTrackingId=xxxxxxxxxxxx
\nWhere xxxxxxxxxxxx represents the OrderTrackingId received as part of the callback [GET] or IPN [POST/GET] params.
\n{\n \"payment_method\": \"Visa\",\n \"amount\": 100,\n \"created_date\": \"2022-04-30T07:41:09.763\",\n \"confirmation_code\": \"6513008693186320103009\",\n \"payment_status_description\": \"Failed\",\n \"description\": \"Unable to Authorize Transaction.Kindly contact your bank for assistance\",\n \"message\": \"Request processed successfully\",\n \"payment_account\": \"476173**0010\",\n \"call_back_url\": \"https://test.com/?OrderTrackingId=7e6b62d9-883e-440f-a63e-e1105bbfadc3&OrderMerchantReference=1515111111\",\n \"status_code\": 2,\n \"merchant_reference\": \"1515111111\",\n \"payment_status_code\": \"\",\n \"currency\": \"KES\",\n \"error\": {\n \"error_type\": null,\n \"code\": null,\n \"message\": null,\n \"call_back_url\": null\n },\n \"status\": \"200\"\n}\n\nOnce you've received the payment details, you are then required to store the same in your system and provide services / services paid for.
\nYour IPN endpoint should then respond to Pesapal with a json string confirming receipt of the IPN call. Part of the json string contains a status parameter that should be set as 200 (meaning request was received and processed) or 500 (meaning IPN request was received but there was an issue completing the process).
\nSample IPN JSON Response String: {\"orderNotificationType\":\"IPNCHANGE\",\"orderTrackingId\":\"d0fa69d6-f3cd-433b-858e-df86555b86c8\",\"orderMerchantReference\":\"1515111111\",\"status\":200}
\nNB: Your callback page should not implement a json response. Instead, redirect the customer to a page on your system showing the payment details.
\n","urlObject":{"host":["{{protocol}}{{api-host}}{{api-url}}GetTransactionStatus"],"query":[{"key":"orderTrackingId","value":"{{order-tracking-id}}"}],"variable":[]}},"response":[],"_postman_id":"e196c778-3486-4e4c-9266-92925b96991f"},{"name":"RecurringPayments","id":"f500d792-87a5-4d60-8543-4b818a59c7c9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt-token}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"account_number\": \"{{account_number}}\",\r\n \"id\": \"\",\r\n \"currency\": \"\",\r\n \"amount\": \"\",\r\n \"description\": \"\",\r\n \"callback_url\": \"\",\r\n \"notification_id\": \"\",\r\n \"billing_address\": {\r\n \"email_address\": \"\",\r\n \"phone_number\": \"\",\r\n \"country_code\": \"\",\r\n \"first_name\": \"\",\r\n \"middle_name\": \"\",\r\n \"last_name\": \"\",\r\n \"line_1\": \"\",\r\n \"line_2\": \"\",\r\n \"city\": \"\",\r\n \"state\": \"\",\r\n \"postal_code\": \"\",\r\n \"zip_code\": \"\"\r\n }\r\n}"},"url":"{{protocol}}{{api-host}}{{api-url}}Transactions/SubmitOrderRequest","description":"Recurring payment is a payment model where customers authorize the business to pull funds from their accounts automatically at regular intervals for the goods and services provided to them on an ongoing basis.
\nWith Pesapal's subscription based payments, customers can set automated card payments on their account where they can be debited automatically at a different set times. Examples of services one can enroll to include cable bills,cell phone bills, gym membership fees, utility bills and magazine subscriptions. These payments can be set to run an various intervals such as daily, weekly, monthly or yearly.
\nEnable our subscription based payments by passing an additional account_number field when sending data to our SubmitOrderRequest endpoint. This account_number should relate to an account number / invoice number that helps you identify the payment.
\nNote: It's critical that you get to understand all other Pesapal API 3.0 endpoints before implementing the recurring feature. Click here to get started.
\nIn adition to the SubmitOrderRequest parameters, include one more param as show below.
\n{\n \"id\": \"AA1122-3344ZZ\",\n \"currency\": \"KES\",\n \"amount\": 100.00,\n \"description\": \"Payment description goes here\",\n \"callback_url\": \"https://www.myapplication.com/response-page\",\n \"notification_id\": \"fe078e53-78da-4a83-aa89-e7ded5c456e6\",\n \"billing_address\": {\n \"email_address\": \"john.doe@example.com\",\n \"phone_number\": \"0723xxxxxx\",\n \"country_code\": \"KE\",\n \"first_name\": \"John\",\n \"middle_name\": \"\",\n \"last_name\": \"Doe\",\n \"line_1\": \"Pesapal Limited\",\n \"line_2\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"postal_code\": \"\",\n \"zip_code\": \"\"\n },\n \"account_number\": \"555-678\"\n} \n\nAfter successfully processing your request using the SubmitOrderRequest endpoint, the customer will be shown an option to opt into the recurring model on the Pesapal iframe during payment. The customer will then configure the frequency (Daily, weekly, monthly, quarterly or yearly), set a start and enddate, and finally enter an amount to be automatically deducted from their card on each payment cycle.
\n![](\"https://developer.pesapal.com/images/card_tokenization.png\")
\n\nOnce the customer has made a successful payment, Pesapal will automatically create a scheduled subscription on their behalf and an email alert will be sent to the provided card billing email that was used during the payment proccess, notifying them of the newly created subscription together with a link they can access a dashboard to manage their subscription.
\nPesapal will NOT store the customer's card details. Instead, Pesapal has implemented the card tokenization technology.
\nCredit card tokenization is the process of de-identifying sensitive cardholder data by converting it to a string of randomly generated numbers called a \"token.\" Similar to encryption, tokenization obfuscates the original data to render it unreadable to a user. Unlike encryption, however, credit card tokenization is irreversible.
\nYes, in cases where your application already handles the process where the customer opts into a subscription based model from your application, Pesapal allows your to send these extra parameters via the API. This ensures that the user does not have to fill in the same details again (on your application and on the Pesapal Iframe).
\nHowever, it's important to note that the customer MUST accept to enroll to your subscription on the iframe. They will however not be able to edit the subscription details on the iframe.
\nIn adition to the account_number parameter included in the SubmitOrderRequest, you are required to send the following parameter.
\n{\n \"id\": \"AA1122-3344ZZ\",\n \"currency\": \"KES\",\n \"amount\": 100.00,\n \"description\": \"Payment description goes here\",\n \"callback_url\": \"https://www.myapplication.com/response-page\",\n \"notification_id\": \"fe078e53-78da-4a83-aa89-e7ded5c456e6\",\n \"billing_address\": {\n \"email_address\": \"john.doe@example.com\",\n \"phone_number\": \"0723xxxxxx\",\n \"country_code\": \"KE\",\n \"first_name\": \"John\",\n \"middle_name\": \"\",\n \"last_name\": \"Doe\",\n \"line_1\": \"Pesapal Limited\",\n \"line_2\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"postal_code\": \"\",\n \"zip_code\": \"\"\n },\n \"account_number\": \"555-678\",\n \"subscription_details\": {\n \"start_date\": \"24-01-2023\",\n \"end_date\": \"31-12-2023\",\n \"frequency\": \"DAILY\"\n }\n} \n\nAfter successfully processing your request using the SubmitOrderRequest endpoint, the customer will be shown an option to opt into the recurring model on the Pesapal iframe during payment. The iframe will this time load without he options to re-select the Frequecy, period and dates.
\n![](\"https://developer.pesapal.com/images/subscriptions.png\")
\n\nYes, customers have the right to cancel their subscription at anytime. Pesapal will send them email alerts a day or two prior to charging their cards. This ensures customers are always aware of all upcoming charges giving them the freedom to opt out or pausing their subscriptions.
\nWe currently support Visa and MasterCard for recurring payments. More card options will be enabled in the near future.
\nOnce a schedule is created and executed successfully, Pesapal will trigger an IPN (Instant Payment Notification) to the IPN endpoint you provided when calling the SubmitOrderRequest endpoint. This IPN call will have the _OrderNotificationType_i> set as RECURRING.
\nSample Callback URL: https://www.myapplication.com/response-page?OrderTrackingId=b945e4af-80a5-4ec1-8706-e03f8332fb04&OrderMerchantReference=555-678&OrderNotificationType=RECURRING
\nThe IPN alert will either be a GET or POST request, depending on which HTTP method you selected when registering the IPN URL. Click here for more details on how to register your IPN endpoint.
\nThe IPN call will have the following parameters;
\n\n\nThe IPN call will NOT have all details of the payment for security reasons. As such, you will be required to fetch the payment using the GetTransactionStatus API once the IPN URL is triggered.
\n
In addition to the normal payment status details received from the GetTransactionStatus endpoint, Pesapal will append an object subscription_transaction_info containing some additional recurring payment data
\n{\n \"payment_method\": \"Visa\",\n \"amount\": 100,\n \"created_date\": \"2022-04-30T07:41:09.763\",\n \"confirmation_code\": \"6513008693186320103009\",\n \"payment_status_description\": \"Failed\",\n \"description\": \"Unable to Authorize Transaction.Kindly contact your bank for assistance\",\n \"message\": \"Request processed successfully\",\n \"payment_account\": \"476173**0010\",\n \"call_back_url\": \"https://test.com/?OrderTrackingId=7e6b62d9-883e-440f-a63e-e1105bbfadc3&OrderMerchantReference=555-678\",\n \"status_code\": 2,\n \"merchant_reference\": \"1515111111\",\n \"payment_status_code\": \"\",\n \"currency\": \"KES\",\n \"subscription_transaction_info\": {\n \"account_reference\": \"555-678\",\n \"amount\": 100,\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"correlation_id\": 111222\n },\n \"error\": {\n \"error_type\": null,\n \"code\": null,\n \"message\": null,\n \"call_back_url\": null\n },\n \"status\": \"200\"\n} \n\nOnce you've fetched the recurring data, you are then required to store the same in your system and provide services / goods as subscribed.
\nYour IPN endpoint should then respond to Pesapal with a json string confirming service delivery. Part of the json string contains a status parameter that should be set as 200 (meaning request was received and processed) or 500 (meaning request was received but there was an issue providing the services).
\nSample JSON Response String: {\"orderNotificationType\":\"RECURRING\",\"orderTrackingId\":\"d0fa69d6-f3cd-433b-858e-df86555b86c8\",\"orderMerchantReference\":\"555-678\",\"status\":200}
\n\n\n","urlObject":{"path":["SubmitOrderRequest"],"host":["{{protocol}}{{api-host}}{{api-url}}Transactions"],"query":[],"variable":[]}},"response":[],"_postman_id":"f500d792-87a5-4d60-8543-4b818a59c7c9"},{"name":"RefundRequest","id":"90380f34-2729-46f3-a613-e1ce0766c781","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt-token}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"confirmation_code\": \"\",\r\n \"amount\": \"\",\r\n \"username\": \"\",\r\n \"remarks\": \"\"\r\n} "},"url":"{{protocol}}{{api-host}}{{api-url}}Transactions/RefundRequest","description":"NB: Constant complains from your customers about service / goods not delivered which were paid using recurring / subscription based payment mode will lead to the subscriptions being terminated and your profile banned from using the feature.
\n
The refund request endpoint allow you to refund a charge that has previously been processed but not yet refunded. Funds will be refunded to the credit / debit card or mobile money wallet that was originally charged.
\nThe ability to process a refund has the following limitations:
\nThe URL to our RequestRefund API is either:
\nBearer Token : Use token generated during authentication.
\nAccept: The response format, which is required for operations with a response body.
Content-Type: The request format, which is required for operations with a request body.
{\n \"confirmation_code\": \"AA11BB22\",\n \"amount\": \"100.00\",\n \"username\": \"John Doe\",\n \"remarks\": \"Service not offered\"\n} \n\nAfter successfully placing a refund request, a request will be sent to our finance team to start processing the refund.
\nStatus 200 mean your request to process the refund has been received successfully. However, please note that this does not mean the refund has been effected. Pesapal has to get the go ahead from the merchant before finalising the refund.
\nStatus 500 mean your request to process the refund was rejected for one reason or another. Refer to the error message for more details.
\n{\n \"status\": \"200\",\n \"message\": \"Refund request successfully\"\n} \n\n\n\n","urlObject":{"path":["RefundRequest"],"host":["{{protocol}}{{api-host}}{{api-url}}Transactions"],"query":[],"variable":[]}},"response":[],"_postman_id":"90380f34-2729-46f3-a613-e1ce0766c781"},{"name":"OrderCancellation","id":"2ea439b0-6674-4669-9885-54cc10fbf836","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt-token}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"order_tracking_id\": \"{{order-tracking-id}}\"\r\n} "},"url":"{{protocol}}{{api-host}}{{api-url}}Transactions/CancelOrder","description":"The refund API uses the confirm code for identification. It's important that you store all payment confirmation codes as returned in the Get Transaction Status Endpoint
\n
The Order Cancellation API enables you to revoke a previously placed order request that remains incomplete on our end. This API facilitates the cancellation of orders that have encountered failures or are pending transactions.
\nHowever, there are certain constraints associated with cancelling a prior request:
\nYou can access our Cancel Order API via the endpoints provided below:
\n**Bearer Token :**Use token generated during authentication.
\nAccept: The response format, which is required for operations with a response body.
Content-Type: The request format, which is required for operations with a request body.
{\n \"order_tracking_id\": \"xxxxxxxxxxxxxxxxxxxxxxx\"\n} \n\nAfter successfully cancelling the request, the order shall be cancelled on our systems preventing a customer from making further payments to an already cancelled order.
\n{\n \"status\": \"200\",\n \"message\": \"Order successfully cancelled.\"\n} \n\n\n\n","urlObject":{"path":["CancelOrder"],"host":["{{protocol}}{{api-host}}{{api-url}}Transactions"],"query":[],"variable":[]}},"response":[],"_postman_id":"2ea439b0-6674-4669-9885-54cc10fbf836"}],"id":"010cc44d-c7ac-4f5b-a684-2fa49bf686ab","_postman_id":"010cc44d-c7ac-4f5b-a684-2fa49bf686ab","description":""}]}The Order Cancellation API uses the Pesapal Order Tracking ID to cancel the order. It's important that you store the Pesapal Order Tracking ID that is sent back to your system during your initial order placement stage i.e. on the submit order request endpoint.
\n