InstaPay

Collect a payment over InstaPay, Egypt's instant payment network, by generating a QR code the customer scans or by pushing a request to pay to a payer address you already know.

InstaPay is a first-class payment method: you select it with paymentMethod.type = "instapay". It is a collection rail, not a card rail, so it has no tokenization, no recurring and no authorize/capture. It does support refund, cancel and transaction force closure.

The flow is:

You initiate a collection — GENERATE_QR for a scan-to-pay QR code, or INITIATE_R2P to push a pay request to a payer address.
The customer approves the request in their bank or wallet app.
Kashier notifies you through the standard server webhook.

Initiate a collection

An InstaPay collection is a Direct API order: you post it to the same POST /v3/orders endpoint used for cards and wallets, and pick the collection method with apiOperation.

Endpoint	Value
TEST-URL	https://test-fep.kashier.io/v3/orders
LIVE-URL	https://fep.kashier.io/v3/orders
Method	POST

Headers

Key	Description
Kashier-Hash	Order hash generated in hashing.
Content-Type	application/json

Operations

Operation	Collection method
`GENERATE_QR`	QR code the customer scans to pay
`INITIATE_R2P`	Request to pay, pushed to a known payer address

You do not choose the provider. InstaPay is selected with paymentMethod.type = "instapay"; which acquirer that resolves to is set up on your account by Kashier, not per request.

InstaPay fields

The paymentMethod.instapay object:

Field	Type	Required	Description
`validity`	String	Yes	Validity period of the collection request. Required for both `GENERATE_QR` and `INITIATE_R2P` — without it the request fails with `request.paymentMethod?.instapay?.validity is required for IPN generate QR`.
`payerAddress`	String	Yes for `INITIATE_R2P`	The payer's InstaPay address. Only sent when the operation is `INITIATE_R2P`.
`tip`	Boolean	No	Set to `true` to allow a tip on the collection.
`convenienceFee`	Number	No	Convenience fee to add to the collection.
`refundSource`	String	No	Carried for refund flows.

Request

{
  "apiOperation": "INITIATE_R2P",
  "interactionSource": "ECOMMERCE",
  "order": {
    "reference": "<your order id>",
    "amount": 100.00,
    "currency": "EGP"
  },
  "paymentMethod": {
    "type": "instapay",
    "instapay": {
      "payerAddress": "payer@instapay",
      "validity": "30"
    }
  },
  "merchantId": "MID-XXXXX-XXX"
}

For a QR collection, send "apiOperation": "GENERATE_QR" and omit paymentMethod.instapay.payerAddress.

Supported operations

Operation	Type
`GENERATE_QR`	Initiate
`INITIATE_R2P`	Initiate
`REFUND`	Post-payment
`CANCEL`	Post-payment
`TRANSACTION_FORCE_CLOSURE`	Post-payment

Tokenization, recurring and authorize/capture are not available on InstaPay. See refunds and void for the shared post-payment contract.

Results and response codes

A successful InstaPay collection reaches you as status: SUCCESS with transactionResponseCode 00 ("Approved") — the same approved code as any other payment. Every other code is a FAILURE and carries the InstaPay code itself, for example 20903.

InstaPay uses its own five-digit code space, separate from the card and ISO codes in payment reason codes. Match on the exact code.

Code	Meaning
`00000`	Success
`20101`	Payer Payment Address is not registered
`20102`	Invalid validity period
`20103`	Declined, Merchant Collection Limits Exceeded
`20201`	Declined by Consumer
`20202`	Declined, Payment Order Expired
`20203`	Declined, Merchant Collection Limits Exceeded
`20204`	Declined by Consumer bank
`20301`	Refund Declined, Applicable Refund amount for this transaction has been exceeded
`20302`	Transaction has already been refunded
`20303`	Invalid Merchant Reference Number
`20304`	Invalid Original Transaction ID
`20305`	Refund Declined, insufficient funds
`20306`	Refund Declined, invalid Merchant Access Permission
`20307`	Refund Declined, Original transaction exceeded refund duration
`20308`	Refund In Progress
`20309`	Refund Declined
`20310`	Refund not concluded, please inquire the refund
`20401`	Invalid Merchant Reference Number
`20402`	Cannot be cancelled, cancellation window has expired. Kindly use refund option
`20501`	Invalid Merchant Reference Number
`20502`	Declined by Consumer
`20503`	Declined, Payment Order Expired
`20504`	Declined, Merchant Collection Limits Exceeded
`20901`	Invalid JSON structure or field format
`20902`	Invalid version number
`20903`	Invalid request signature
`20904`	Your request cannot be processed please try again later
`20905`	Merchant is suspended or blocked, please refer back to your bank
`20906`	Invalid Merchant ID
`20907`	Invalid Acquirer Merchant ID
`20908`	Invalid Acquirer Bank ID
`20909`	Duplicated Merchant Reference Number
`20999`	Service currently not available, Please try again later

Note

Only the 2xxxx codes above are mapped. A code outside this table falls back to the general message set and can arrive as k_default, so treat an unknown InstaPay code as a plain failure rather than looking it up.

Webhooks

InstaPay has no webhook event of its own. Kashier notifies you with the standard server webhook, where event is the operation — pay, refund and so on. See webhooks.

On this page