Pesapal.com
  • Noton
  • PCI/DSS Compliant
Home / API / E-commerce / API 3.0 - JSON / SubmitOrderRequest

Submit Order Request Endpoint - Post Request

Once you have received the bearer token, the next step will be the actual request to create a payment request.

A 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.

The 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.

The URL to our SubmitOrderRequest API is either:

Authentication

Bearer Token : Use token generated during authentication.

HTTP request headers

Accept: 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.

Parameter RequiredDescription
Accept Required Should be set to application/json
Content-Type Required Should be set to application/json

Request Parameters

ParameterTypeRequiredDescription
id String Required This refers to your unique merchant reference generated by your system. NOTE: It should be unique at all times for every order request. Maximum - 50 characters
currency String Required This represents the currency you want to charge your customers. ISO Currency Codes
amount Float Required Amount to be processed.
description String Required Represents the description of your order. Maximum - 100 characters
redirect_mode String Optional Accepts values TOP_WINDOW or PARENT_WINDOW.
If left blank, the default value used will be TOP_WINDOW.

This parameter allows you to define where your callback URL will be loaded;
- TOP_WINDOW returns to the topmost window in the hierarchy of windows.
- PARENT_WINDOW returns the immediate parent of a window.
callback_url String Required A valid URL which Pesapal will redirect your clients to processing the payment.
cancellation_url String Optional A valid URL which Pesapal will redirect your clients to incase they click on cancel request while on the Payment link.

If provided, a cancellation link will appear next to the PROCEED button.
notification_id Guid Required This represents an IPN URL which Pesapal will send notifications to after payments have been processed.

You are required to register all IPN URLs after which a corresponding notification_id will be generated. Please refer to the IPN URL registration endpoint.
branch String Optional If your business has multiple stores / branches, you can define the name of the store / branch to which this particular payment will be accredited to.
billing_address Object Required Customer Address Object
Customer Address Object

NameTypeRequiredDescription
phone_number String Optional if email address is provided.
Mandatory if email address is NOT provided.		 Customer's phone number
email_address String Optional if phone number is provided.
Mandatory if phone number is NOT provided.		 Customer's email address
country_code String Optional 2 characters long country code in [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1)
first_name String Optional Customer's first name
middle_name String Optional Customer's middle name
last_name String Optional Customer's last name
line_1 String Optional Customer's main address
line_2 String Optional Customer's alternative address
city String Optional Customer's city
state String Optional Customer's state Maximum - 3 characters
postal_code Integer Optional Customer's postal code
zip_code Integer Optional Customer's zip code

Sample Request
    {
        "id": "AA1122-3344ZZ",
        "currency": "KES",
        "amount": 100.00,
        "description": "Payment description goes here",
        "callback_url": "https://www.myapplication.com/response-page",
        "redirect_mode": "",
        "notification_id": "fe078e53-78da-4a83-aa89-e7ded5c456e6",
        "branch": "Store Name - HQ",
        "billing_address": {
            "email_address": "[email protected]",
            "phone_number": "0723xxxxxx",
            "country_code": "KE",
            "first_name": "John",
            "middle_name": "",
            "last_name": "Doe",
            "line_1": "Pesapal Limited",
            "line_2": "",
            "city": "",
            "state": "",
            "postal_code": "",
            "zip_code": ""
        }
    }

After successfully creating the order, your response will contain a payment URL (redirect_url).

Status 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.

Response Parameters

NameTypeDescription
order_tracking_id String Unique order id generated by Pesapal.
merchant_reference String Your application's unique ID received as part of the SUBMIT ORDER REQUEST.
redirect_url String URL generated that contains the payment instructions. Redirect to this URL or load it within an iframe
error Integer
message String Response message.

Sample Response
    {
        "order_tracking_id": "b945e4af-80a5-4ec1-8706-e03f8332fb04",
        "merchant_reference": "TEST1515111119",
        "redirect_url": "https://cybqa.pesapal.com/pesapaliframe/PesapalIframe3/Index/?OrderTrackingId=b945e4af-80a5-4ec1-8706-e03f8332fb04",
        "error": null,
        "status": "200"
    }

Redirecting your customer to this redirect_url will present them with a list of available payment methods which they can use to make the payment.

You 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.

Once 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.

Callback Details

The following parameter will be appended to your callback URL.

ParameterTypeDescription
OrderTrackingId String Unique order id generated by Pesapal.
OrderNotificationType String Has value CALLBACKURL to represent a callback request
OrderMerchantReference String Your application's unique ID received as part of the SUBMIT ORDER REQUEST.

Sample Callback URL: https://www.myapplication.com/response-page?OrderTrackingId=b945e4af-80a5-4ec1-8706-e03f8332fb04&OrderMerchantReference=TEST1515111119&OrderNotificationType=CALLBACKURL

IPN Details

At the same time, Pesapal will send an alert to your IPN URL informing you of a status change.

The IPN alert will either be a GET or POST request, depending on which HTTP method you selected when registering the IPN URL.

The IPN call will have the following parameters;

ParameterTypeDescription
OrderTrackingId String Unique order id generated by Pesapal.
OrderNotificationType String Has value IPNCHANGE to represent an IPN call.
OrderMerchantReference String Your application's unique ID received as part of the SUBMIT ORDER REQUEST.
Sample GET URL

https://www.myapplication.com/response-page?OrderTrackingId=b945e4af-80a5-4ec1-8706-e03f8332fb04&OrderMerchantReference=TEST1515111119&OrderNotificationType=IPNCHANGE

Sample POST data
   
    {
        "OrderNotificationType":"IPNCHANGE",
        "OrderTrackingId":"b945e4af-80a5-4ec1-8706-e03f8332fb04",
        "OrderMerchantReference":"TEST1515111119"
    }
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.
Is this article helpful?