Test your integration on https://demo.pesapal.com before you take your site live!
PesaPal will call the URL you have specified with the following query parameters:
The response you send to PesaPal must be the same as what you received from PesaPal:
pesapal_notification_type=CHANGE&pesapal_transaction_tracking_id=<the unique tracking id of the transaction>&pesapal_merchant_reference=<the merchant reference>
PesaPal will retry a limited number of times if the expected response is not received.
Use this to post a transaction to PesaPal. PesaPal will present the user with a page which contains the available payment options and will redirect to your site once the user has completed the payment process.
A tracking id will be returned as a query parameter – this can be used subsequently to track the payment status on pesapal for this transaction.
Use this to query the status of the transaction. When a transaction is posted to PesaPal, it may be in a PENDING, COMPLETED or FAILED state. If the transaction is PENDING, the payment may complete or fail at a later stage.
Both the unique order id generated by your system and the pesapal tracking id are required as input parameters.
Same as QueryPaymentStatus, but only the unique order id genereated by your system is required as the input parameter.
Same as QueryPaymentStatus, but additional information is returned.
URL: https://www.pesapal.com/API/PostPesapalDirectOrderV4
Parameters:
<!--?xml version="1.0" encoding="utf-8" ?--> <xs:schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xs="http://www.w3.org/2001/XMLSchema" attributeformdefault="unqualified" elementformdefault="qualified" targetnamespace="http://www.pesapal.com"> <xsd:element name="PesapalDirectOrderInfo"> <xsd:complextype> <xsd:sequence> <xsd:element name="LineItems" minoccurs="0" maxoccurs="1"> <xsd:complextype> <xsd:sequence> <xsd:element minoccurs="1" maxoccurs="unbounded" name="LineItem"> <xsd:complextype> <xsd:attribute name="UniqueId" type="xsd:string" use="required"> </xsd:attribute> <xsd:attribute name="Particulars" type="xsd:string" use="required"> </xsd:attribute> <xsd:attribute name="Quantity" type="xsd:unsignedInt" use="required"> </xsd:attribute> <xsd:attribute name="UnitCost" type="xsd:decimal" use="required"> </xsd:attribute> <xsd:attribute name="SubTotal" type="xsd:decimal" use="required"> </xsd:attribute> </xsd:complextype> </xsd:element> </xsd:sequence> </xsd:complextype> </xsd:element> </xsd:sequence> <xsd:attribute name="Amount" type="xsd:decimal" use="required"> </xsd:attribute> <xsd:attribute name="Currency" use="optional"> <xsd:simpletype> <xsd:restriction base="xs:string"> <xsd:pattern value="[A-Za-z][A-Za-z][A-Za-z]"> </xsd:pattern> </xsd:restriction> </xsd:simpletype> </xsd:attribute> <xsd:attribute name="Description" type="xsd:string" use="required"> </xsd:attribute> <xsd:attribute name="Type" use="required"> <xsd:simpletype> <xsd:restriction base="xsd:string"> <xsd:enumeration value="MERCHANT"> </xsd:enumeration> <xsd:enumeration value="ORDER"> </xsd:enumeration> </xsd:restriction> </xsd:simpletype> </xsd:attribute> <xsd:attribute name="Reference" type="xsd:string" use="required"> </xsd:attribute> <xsd:attribute name="FirstName" type="xsd:string" use="optional"> </xsd:attribute> <xsd:attribute name="LastName" type="xsd:string" use="optional"> </xsd:attribute> <xsd:attribute name="Email" type="xsd:string" use="required"> </xsd:attribute> <xsd:attribute name="PhoneNumber" type="xsd:string" use="optional"> </xsd:attribute> <xsd:attribute name="AccountNumber" type="xsd:string" use="optional"> </xsd:attribute> </xsd:complextype> </xsd:element> </xs:schema>
AND / OR
PhoneNumber = <the phone number of the customer>Example:
<lineitem uniqueid="1" particulars="Item 1" quantity="6" unitcost="10.00" subtotal="60.00"></lineitem>
Line Item Attributes:
Samples:
Sample 1:
<!--?xml version="1.0" encoding="utf-8" ?--> <PesapalDirectOrderInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" amount="100.00" description="Order payment" type="MERCHANT" reference="12" firstname="Foo" lastname="Bar" email="[email protected]" xmlns="http://www.pesapal.com"></PesapalDirectOrderInfo>
Sample 2:
<!--?xml version="1.0" encoding="utf-8" ?--> <PesapalDirectOrderInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" amount="125.00" currency="USD" description="Order payment for order ACD09" type="MERCHANT" reference="ACD09" firstname="Foo" lastname="Bar" email="[email protected]" phonenumber="254722111111" xmlns="http://www.pesapal.com"> <lineitems> <lineitem uniqueid="1" particulars="Item 1" quantity="6" unitcost="10.00" subtotal="60.00"></lineitem> <lineitem uniqueid="2" particulars="Item 2" quantity="1" unitcost="5.00" subtotal="5.00"></lineitem> <lineitem uniqueid="3" particulars="Item 3" quantity="2" unitcost="30.00" subtotal="60.00"></lineitem> </lineitems> </PesapalDirectOrderInfo>
Return Query Parameters
Once the payment process has been completed by the user, PesaPal will redirect to your site using the url you specified in the oauth_callback parameter. The following two values are returned in the query string:
pesapal_merchant_reference: this is the reference (a unique order id), that you passed to PesaPal when posting the transaction.
pesapal_transaction_tracking_id: this is the unique tracking id for this transaction on PesaPal.
Example:
Let's say that the oauth_callback parameter you specified is: http://www.mysite.com/processingorder and the reference you specified is 12345.
PesaPal will redirect to a url with the following format once the payment is completed:
http://www.mysite.com/processingorder? pesapal_transaction_tracking_id=195035be-56bb-48ba-8439-7e12196cb87e&pesapal_merchant_reference=12345
Once the transaction has been posted to PesaPal, you may use QueryPaymentStatus to query the status of the payment.
URL: https://www.pesapal.com/API/QueryPaymentStatus
Parameters:
Return Value:
The status of the payment is returned as follows:
pesapal_response_data =<PENDING|COMPLETED|FAILED|INVALID>
Same as QueryPaymentStatus above, but pesapal_transaction_tracking_id is not required.
URL: https://www.pesapal.com/API/QueryPaymentStatusByMerchantRef
Parameters:
pesapal_merchant_reference = <the Reference you sent to PesaPal when posting the transaction>
Return Value:
The status of the payment is returned as follows:
pesapal_response_data =<PENDING|COMPLETED|FAILED|INVALID>
Same as QueryPaymentStatus above, but the return value contains more information.
URL: https://www.pesapal.com/API/QueryPaymentDetails
Parameters:
Return Value:
Four values are returned as a comma separated string, as follows:
Example:
pesapal_response_data=195035be-56bb-48ba-8439-7e12196cb87e,MPESA,PENDING,12345