Pesapal.com
  • Noton
  • PCI/DSS Compliant
Home / API / E-commerce / API 2.0 - XML / API Reference

API Reference

This API has since been deprecated. Use our new API 3.0 built using JSON REST APIs. Click here to view this new API.

Test your integration on https://demo.pesapal.com before you take your site live!

1. IPN (Instant Payment Notification)

PesaPal will call the URL you have specified with the following query parameters:

  • pesapal_notification_type=CHANGE
  • pesapal_transaction_tracking_id=<the unique tracking id of the transaction>
  • pesapal_merchant_reference=<the merchant reference>

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.

2. PesaPal API methods

  1. PostPesapalDirectOrderV4

    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.

  2. QueryPaymentStatus

    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.

  3. QueryPaymentStatusByMerchantRef

    Same as QueryPaymentStatus, but only the unique order id genereated by your system is required as the input parameter.

  4. QueryPaymentDetails

    Same as QueryPaymentStatus, but additional information is returned.

back to top



2.1 PostPesapalDirectOrderV4

URL: https://www.pesapal.com/API/PostPesapalDirectOrderV4

Parameters:

  1. oauth_callback= <url to the redirect page>
    This is the page on your site the users will be redirected to, after they have made the payment on PesaPal.
    Example: http://www.mysite.com/processingorder
  2. oauth_consumer_key = <your consumer key>
    When you register as a merchant on PesaPal, you will receive your consumer key and secret via email.
    Please Note: it is very important that you store the consumer secret safely.
  3. oauth_nonce= <a unique id>
    This must be unique for each PesaPal API request you make. Tip: a date-time based value may ensure uniqueness across all your requests.
  4. oauth_signature = <OAuth signatue>
    PesaPal uses the OAuth protocol to authenticate API requests. The request is signed using the Consumer Secret you received at registration.
    You may download OAuth libraries for PHP and .Net from our downloads section. For a list of other OAuth libaries, please visit: http://oauth.net/code/
    More information on OAuth can be found at oauth.net or in the Beginner's Guide to OAuth from Hueniverse.
  5. oauth_signature_method = HMAC-SHA1
  6. oauth_timestamp = <number of seconds since January 1, 1970 00:00:00 GMT, also known as Unix Time>
  7. oauth_version = 1.0
  8. pesapal_request_data = <XML formated order data >

    The following is the schema for the pesapal_request_data xml.

    Note: when testing integration with PesaPal, you may use this schema to validate the XML you generate.
     <!--?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>
    Below are further details on the required and optional attributes/elemets for the pesapal_request_data xml.
  9. Amount = <the total amount of the order>
  10. Description = <the description of the order>
  11. Type = <MERCHANT|ORDER>
    1. MERCHANT: use this by default.
    2. ORDER: use this if your order meets the following requirements:
      1. The order needs to be shipped
      2. The customer has the option to verify the delivery as satisfactory
      3. The payment is held in escrow until the completion of the delivery and acceptance process.

      Please Note: if you use ORDER, it requires you to mark the order as SHIPPED and DELIVERED via your PesaPal merchant console.
  12. Reference = <a unique order id>
    Please Note: this reference MUST be unique for each transaction that is posted to PesaPal. You will use this reference to query the status of the transaction later on, so this value must be stored on your system.
  13. Email = <the email of the customer>

    AND / OR

    PhoneNumber = <the phone number of the customer>
    ONE of Email or PhoneNumber is required.
  14. Currency = <ISO code for the currency>
    By default, this is set to your country's currency. For example, if you registered as a merchant in Kenya, it would be KES (UGX for Uganda, TZA for Tanzania, and so on).

    However, if you wish to transact in a different currency (such as USD), you may specify the three letter ISO code for that currency.

    Please Note: PesaPal will request payment from the customer in the currency you specified where possible. If the payment option the customer selects does not support that currency, PesaPal will convert the amount using the day's exchange rate and present the amount in the local currency to the user.
  15. FirstName = <first name of the customer>
  16. LastName = <last name of the customer>
  17. LineItems = <a list of items purchased by the customer>
    MUST have one or more child elements.

    Example:

     <lineitem uniqueid="1" particulars="Item 1" quantity="6" unitcost="10.00" subtotal="60.00"></lineitem>

    Line Item Attributes:

    1. UniqueId = <unique id of the purchased item>
    2. Particulars = <description of the item>
    3. Quantity = <quantity purchased>
    4. UnitCost = <cost per unit of the purchased item>
    5. SubTotal =

Samples:

The following are sample pesapal_request_data XML

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:

  1. pesapal_merchant_reference: this is the reference (a unique order id), that you passed to PesaPal when posting the transaction.

  2. pesapal_transaction_tracking_id: this is the unique tracking id for this transaction on PesaPal.

    You will need to send PesaPal both these values when subsequently querying for payment status or details. So, store the pesapal_merchant_reference against your order in your database.

    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

back to top


2.2 QueryPaymentStatus

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:

  1. oauth_consumer_key = <your consumer key>
  2. oauth_nonce = <a unique id>
  3. oauth_signature = <OAuth signatue>
  4. oauth_signature_method = HMAC-SHA1
  5. oauth_timestamp = <number of seconds since January 1, 1970 00:00:00 GMT, also known as Unix Time>
  6. oauth_version = 1.0
  7. pesapal_merchant_reference = <the Reference you sent to PesaPal when posting the transaction>
    This is the a unique order id that you sent as Reference in the pesapal_request_data XML when posting the transaction.
  8. pesapal_transaction_tracking_id = <the id returned to you by PesaPal (as a query parameter) when redirecting to your website>

Return Value:

The status of the payment is returned as follows:

  1. pesapal_response_data =<PENDING|COMPLETED|FAILED|INVALID>

    A return value of INVALID indicates that the transaction with the Reference you provided could not be found. If you receive a return value of PENDING, you will have to query PesaPal again, until you receive COMPLETED or FAILED as the response.


back to top



2.3 QueryPaymentStatusByMerchantRef

Same as QueryPaymentStatus above, but pesapal_transaction_tracking_id is not required.

URL: https://www.pesapal.com/API/QueryPaymentStatusByMerchantRef

Parameters:

  1. oauth_consumer_key = <your consumer key>
  2. oauth_nonce = <a unique id>
  3. oauth_signature = <OAuth signatue>
  4. oauth_signature_method = HMAC-SHA1
  5. oauth_timestamp = <number of seconds since January 1, 1970 00:00:00 GMT, also known as Unix Time>
  6. oauth_version = 1.0

  7. pesapal_merchant_reference = <the Reference you sent to PesaPal when posting the transaction>

    This is the a unique order id that you sent as Reference in the pesapal_request_data XML when posting the transaction.
    Please note: if you don't ensure that the Reference is unique for each order on your system, you may get INVALID as the response. Because of this, it is recommended that you use QueryPaymentStatus instead.

Return Value:

The status of the payment is returned as follows:

  1. pesapal_response_data =<PENDING|COMPLETED|FAILED|INVALID>

    A return value of INVALID indicates that the transaction with the Reference you provided could not be found. If you receive a return value of PENDING, you will have to query PesaPal again, until you receive COMPLETED or FAILED as the response.


back to top



2.4 QueryPaymentDetails

Same as QueryPaymentStatus above, but the return value contains more information.

URL: https://www.pesapal.com/API/QueryPaymentDetails

Parameters:

  1. oauth_consumer_key = <your consumer key>
  2. oauth_nonce = <a unique id>
  3. oauth_signature = <OAuth signatue>
  4. oauth_signature_method = HMAC-SHA1
  5. oauth_timestamp = <number of seconds since January 1, 1970 00:00:00 GMT, also known as Unix Time>
  6. oauth_version = 1.0
  7. pesapal_merchant_reference = <the Reference you sent to PesaPal when posting the transaction>
    This is the a unique order id that you sent as Reference in the pesapal_request_data XML when posting the transaction.
  8. pesapal_transaction_tracking_id = <the id returned to you by PesaPal (as a query parameter) when redirecting to your website>

Return Value:

Four values are returned as a comma separated string, as follows:

  1. pesapal_response_data = pesapal_transaction_tracking_id,payment_method,payment_status,pesapal_merchant_reference
  2. pesapal_transaction_tracking_id: this is the same as the parameter you sent when making the query
  3. payment_method: the payment method used by the user to make the payment
  4. payment_status: one of <PENDING|COMPLETED|FAILED|INVALID>
  5. pesapal_merchant_reference:this is the same as the parameter you sent when making the query

    Example:
    pesapal_response_data=195035be-56bb-48ba-8439-7e12196cb87e,MPESA,PENDING,12345

    If you receive a return value of PENDING for payment_status, you will have to query PesaPal again, until you receive COMPLETED or FAILED as the response.
Is this article helpful?