Register an IPN URL

POST

/URLSetup/RegisterIPN

curl --request POST \
  --url https://cybqa.pesapal.com/pesapalv3/api/URLSetup/RegisterIPN \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "example", "ipn_notification_type": "GET" }'

• Sandbox
• Production

Registers a URL Pesapal calls when an order changes, returning an ipn_id to pass as notification_id when creating orders.

Registration is idempotent by URL: re-registering an existing URL returns the original ipn_id and its original created_date rather than creating a duplicate.

The URL is checked for shape only. It is not resolved, not required to use HTTPS, and never contacted, so a mistyped URL registers successfully and then silently never delivers.

This endpoint is rate limited to roughly one request every 8 seconds, measured from the last success. Exceeding it returns HTTP 409 with no Retry-After header.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

url

required

Checked for shape only. Never contacted.

string

ipn_notification_type

required

Case insensitive. Validated by length before value, so a value longer than 4 characters returns a message about length rather than about the accepted values.

string

Allowed values: GET POST

Responses

200

Returned for both success and failure.

Media typeapplication/json

One of:

object

object

url

string

created_date

UTC. A newly created registration returns seven fractional-second digits and a Z. Reading an existing registration back returns the same instant with trailing zeros trimmed and no Z, so the format is not fixed.

string

ipn_id

required

Pass as notification_id when creating an order.

string format: uuid

notification_type

0 is GET, 1 is POST.

integer

Allowed values: 0 1

ipn_notification_type_description

string

Allowed values: GET POST

ipn_status

1 is Active. No other value has been observed.

integer

ipn_status_decription

Misspelled in the API. Spelling it correctly yields no value.

string

status

string

message

string

object

An application error, returned with HTTP 200.

object

error

required

A populated error. Every field is present and non-null.

object

error_type

required

string

Allowed values: api_error invalid_request_error authentication_error

code

required

Mostly snake_case, but not consistently: InvalidIpnId is PascalCase. Compare exactly.

string

message

required

Multiple validation errors arrive pipe-delimited in one string, and malformed JSON produces leading empty segments.

string

status

Usually "500". Never matches the HTTP status.

string | null

Example

{
  "created_date": "2026-09-04T12:46:57.2509054Z",
  "notification_type": 0,
  "ipn_notification_type_description": "GET"
}

401

No Authorization header was sent.

Media typeapplication/json

Returned by HTTP 401 and 409. The error object is JSON-encoded into a string, so message must be parsed a second time to reach the code.

object

message

string

Example

{
  "message": "{\"error\":{\"error_type\":\"authentication_error\",\"code\":\"invalid_api_credentials_provided\",\"message\":\"Invalid or Missing Credentials Provided\"},\"status\":\"401\"}"
}

409

Rate limited. Roughly one request per 8 seconds is allowed.

Media typeapplication/json

Returned by HTTP 401 and 409. The error object is JSON-encoded into a string, so message must be parsed a second time to reach the code.

object

message

string

Example

{
  "message": "{\"error\":{\"error_type\":\"authentication_error\",\"code\":\"invalid_api_credentials_provided\",\"message\":\"Invalid or Missing Credentials Provided\"},\"status\":\"401\"}"
}