Overview

This developer guide is intended for easypasia Open Ecosystem developers to learn how to quickly get started with development.

About easypasia Open Ecosystem

Open Ecosystem is an easypaisa initiative to empower easypaisa merchants and partners to build feature-rich services with minimal efforts. The merchants would be able to leverage on the millions of easypaisa user traffic to unleash the potential of its offering and services.

Capabilities

Below are the available capabilities for the merchant to utilize from the easypaisa Open Ecosystem:

Mini App: This technology allows merchants to embed its own mobile web or applcation into easypaisa’s Mobile App
User Authorization: Capability to allow merchant to request for user consent to provide existing easypaisa user information.
Payment: Capability to allow merchants to request a payment from the easypaisa user.
Promotion: Capability to allow merchants to send a cashback to the easypaisa user.

Prerequisites

Before you start, make sure you have completed the following prerequisites:

Complete your business development discussion with easypaisa BD team to work out business model and product design.
Sign up as a developer by contacting easypaisa’s developer onboarding operations team.
Prepare and demostrate your proposed application demo to our onboarding operations team.
Make sure your proposed application complies with Pakistan’s laws and regulations.

Quick Start

You can find quick start guides in the following sections to start developing your first application.

Mini App

Mini App Quick Start

This tutorial is designed to quickly get you started with developing a Mini App.

The APIs mentioned in this document are mandatory for the integration of Mini App, other than that the APIs are optional.

Overview

Step 0: API Request Format Prerequisite

Review the messaging format (HTTPS Request Format) carefully on header, body and signature requirements. You will need to compose the request message structure in a specific format and signed with your private key in order for the backend server to process your API request.

Step 1: Get Access Token to authenticate the merchant

OpenAPI/v1/Authentications/applyToken Get the access token using merchant ID & Secret.

Use Case: In order to authenticate the merchant and all subsequent API request, use the access token. The access token could be revoked and get a new access token in case the Mini App develop believe the token is compromised.

OpenAPI/v1/Authentications/applyToken
Get the access token using merchant ID & Secret. Use Case: In order to authenticate the merchant and all subsequent API request, use the access token. The access token could be revoked and get a new access token in case the Mini App develop believe the token is compromised.

Step 2：Get Authorization(AuthCode) from User

JSAPI/mp.getUserAuthCode Get Auth Code.

Use Case: Get user’s consent to pass on information scopes (Nickname, gender and etc.) to the Mini App.

Step 3: Get User Info using AuthCode

OpenAPI/v1/Users/inquireUserInfo Get user information using Auth Code.

Use Case: Get user info to create a new Mini App user or recognize a returning user. For example, you could expect the OPEN_ID is always an unique identifier of an EasyPaisa user for the Mini App. Imagine a new user sign-up process, you will always need an unique id, user name, phone number to complete sign-up. This interface will provide all the neccessary values for you to create a new user. From here and on, please maintain your own user session just as how you will for existing website. If you ever lost the user session, start from step 2-3 again to recognize an existing user. This interface helps you to identify an unique EasyPaisa user and pass on the user’s information with their consent.

Step 4: Create a Transaction Request

OpenAPI/v1/Payment/createPayment Create a transaction request to EasyPaisa server.

Use Case: Precreate a transaction request with Mini App’s PaymentOrderID(unique for merchant) to receive a paymentTransactionID(unique for EasyPasia). Subsequently, use the paymentTransactionID received to invoke the EasyPaisa Mobile App to perform user payment authorization.

OpenAPI/v1/Payment/createPayment
Create a transaction request to EasyPaisa server. Use Case: Precreate a transaction request with Mini App’s PaymentOrderID(unique for merchant) to receive a paymentTransactionID(unique for EasyPasia). Subsequently, use the paymentTransactionID received to invoke the EasyPaisa Mobile App to perform user payment authorization.

Step 5: Prompt User for Payment

JSAPI/mp.createPayment Invoke a payment window in EasyPaisa App with the transactionID received in step 4.

Use Case: Prompt the EasyPaisa with precreated transaction. After the user completes the transaction, the user will be returned to the returnURL previously provided in step 4. For example, your order completion page https://merchant.com/OrderID/123

Step 6: That's it!

Congratulations, you have now completed your first Mini App!

Payment Quick Start

This tutorial is designed to quickly get you started with developing payment capabilities through EasyPaisa Wallet. Note: Payment capability can be used alone for merchant’s own application and not only limited to Mini App. For mini app payment please refer to Mini App Quickstart

Overview

Step 0: API Request Format Prerequisite

Step 1: Get Access Token to authenticate the merchant

OpenAPI/v1/authentications/applyToken Get the access token using merchant ID & Secret.

Step 2：Initiate the Payment for a specific user

OpenAPI/v1/payments/createPayment Precreate a payment request to user with order infomration and amount

Use Case: To request user for a specific amount of payment for an order. The merchant will have to create the transaction with an unique PaymentOrderID and PaymentReturnURL in exchange for a PaymentTransactionID and a RedirectURL.

OpenAPI/v1/payments/createPayment
Precreate a payment request to user with order infomration and amount Use Case: To request user for a specific amount of payment for an order. The merchant will have to create the transaction with an unique PaymentOrderID and PaymentReturnURL in exchange for a PaymentTransactionID and a RedirectURL.

Step 3: Redirect the user to the payment confirmation interface

Redirect the user to the RedirectURL provided in step 2 for the user to confirm the payment in EasyPaisa Mobile App or Web. After the payment is completed, the user will be redirected by EasyPaisa to PaymentReturnURL the merchant set in step 2, for example, https://merchant.com/OrderID/123.

Step 4: That's it!

Congratulations, you have now completed requesting a payment from your customer!

Promotion Quick Start

This tutorial is designed to quickly get you started with developing cashback promotion capabilities through EasyPaisa Wallet.

Overview

Step 0: API Request Format Prerequisite

Step 1: Get Access Token to authenticate the merchant

OpenAPI/v1/authentications/applyToken Get the access token using merchant ID & Secret.

Step 2：Initiate the Cashback for a specific user

OpenAPI/v1/promotions/createCashback Send the cashback to a specifc user using his/her phone number

Use Case: In the case that merchants want to incentivise the user with cashback to promo its offering or services.

OpenAPI/v1/promotions/createCashback
Send the cashback to a specifc user using his/her phone number Use Case: In the case that merchants want to incentivise the user with cashback to promo its offering or services.

Step 3: That's it!

Congratulations, you have now completed sending a cashback to your users!

Agreement Pay Quick Start

This tutorial is designed to quickly get you started with developing agreement payment capabilities through EasyPaisa Wallet.Note: agreement payment capability can be used alone for merchant’s own application and not only limited to Mini App. For mini app payment please refer to Mini App Quickstart

Overview

Step 0: API Request Format Prerequisite

Step 1:Get PaymentAuthCode to exchange PaymentToken

OpenAPI/v2/authentications/getPaymentAuthCode.md

The first step in the binding process is to get a auth url through this api, which can be used to jump to the Easypaisa APP or open an H5 signing page.

Step 2:Open authUrl(H5 middle page)

Ep will return authUrl to merchant backend. Merchant’s app can redirect user to EP H5 middle page. The H5 middle page will detect whether the user has the Ep app installed to decide whether to jump to the app or the H5 page

Sample: authUrl:http://x.x.x.x/authentication.htm?authId=FBF16F91-28FB-47EC-B9BE-27B285C23CD3

Step 3:Get PaymentToken For subsequent agreement payment

OpenAPI/v2/authentications/getPaymentToken.md Get the PaymentToken through the paymentAuthCode so that the payment process can initiate the payment with PaymentToken .

Step 4:Payment Pre-check

OpenAPI/v2/Payments/precheckPayment.md The user will perform a payment check before making a payment. If the balance is enough to pay, the payment can be made; if the balance is insufficient, the payment cannot be made.

Step 5:Create payment order

OpenAPI/v2/Payments/createPayment.md Generate a corresponding order in EP background through merchant ID and order information.

OpenAPI/v2/Payments/createPayment.md
Generate a corresponding order in EP background through merchant ID and order information.

Step 6：Inquery payment result

OpenAPI/v2/Payments/inquirePayment.md When an order is created or an error occurs, merchant initiates an order query and obtains the information of the current payment order

OpenAPI/v2/Payments/inquirePayment.md
When an order is created or an error occurs, merchant initiates an order query and obtains the information of the current payment order

Step 7: That's it!

Congratulations, you have now completed requesting a payment from your customer!

Mini App Overview

About Mini App

Mini App is an EasyPaisa technology that enables the developer to embed a mobile web application into the EasyPaisa mobile app. The EasyPaisa users can benefit from the developer’s application use case without installing the developer’s native app. For merchants & developers, mini program provides the following benefits:

Low learning curve as it is based on mobile web technologies. The developers could reuse existing mobile websites and quickly integrate within EasyPaisa
One mobile web project supports both iOS and Android platform.
Built-in components and APIs. The developers could develop native experience using mobile web technologies.
EasyPaisa Authorization could help the developers to ask the user to grant information with user’s consent. Less onboarding friction and one-click sign-up is possible.
Help the developers to reach the millions of EasyPaisa Users

Key Concepts for Mini App

Mini App Container: The container that enables developers’s mobile web application to run inside of the EasyPaisa App. The JS API runs in the Mini App Container’s JS engine.
JS API: The JS API handles client-side requests from developer’s own mobile web application to invoke the EasyPaisa native mobile capabilities such as authorization dialogue, or payment prompts.
Open API: The Open API handles all server-side communication between the developer’s backend and EasyPaisa’s backend.
Authorization Code: Represents the consent of an user for a specific scope or capability (i.e. to provide name, or to sign a contract).
Access Token: The developer could exchange an access token after authenticating its identify . Access Token could be revoked if neccessary and request a new one with authorization code.
Scopes: The scopes of the user information such as name, birthday, gender and etc.
Merchants: Merchants are the legal entities that do business with EasyPaisa, they could have multiple Mini App per merchant.

Overview

Mini Programs offers a set of JS API to achieve various capabilities. For each of the JS API call, the merchant could expect some type of EasyPaisa App user interface interaction. For example, JSAPI/v1/createPayment will create a payment confirmation screen.

For example, payment, user authorization or mobile native capabilities. As illustrated, the EasyPaisa Mini App operates inside of the EasyPaisa App Container via a JS bridge. It allows the merchant to utilize the mobile native capabilities through this implementation. At the same time, EasyPaisa could protect the user’s information by ensuring all pass-through capabilities like GPS locations rights need to be granted by the user’s consent.

mp.getUserAuthCode

mp.getAuthCode

Call the API to obtain the user consent. The wallet app will prompt a consent pop-up to ask user to grant rights to user scopes such as nickname, gender. birthdays and etc. The consent of user is represented by an authorization code (authCode) returned by the API. The authorization code can be later used to inquire user information.

Note: The pop-up box will disappear automatically after 1 minute without any action.

Sample Code

To invoke mp.getUserAuthCode method in HTML

				
					var scopes=[USER_MSISDN,"USER_MSISDN"]
<a onClick="mp.getUserAuthCode(scopes)">Click</a>

To receive the callback in javascript

				
					function getUserAuthCodeResult(jsonResult){
var result=JSON.parse(jsonResult);
alert('status:'+result.status);
alert('authCode:'+result.authCode);
alert('granted scopes:'+result.grantedScopes);
}

Request Parameters

Property	Type	Required	Description
scopes	Array	Yes	The scopes of user authorization grant type: OPEN_ID, UNION_ID, USER_AVATAR, USER_NAME, USER_BIRTHDAY, USER_ADDRESS, USER_CNIC.

Scopes

Scopes granted are based on authorization tiers. This is associated to the merchant entity. For example, only government agency is able to get ask users for granting of CNIC information. OPEN_ID and UNION_ID is always granted for all authorization tiers.

Scopes	Description	Authorization Tiers
OPEN_ID	Authorized to obtain the unique ID per Mini Program Application. Use Case: Obtain the unique identifier to sign up a new user or to recognize a returning user.	Basic
UNION_ID	Authorized to obtain the unique ID per Merchant(Merchant can have multiple Mini Program Application). Use Case: This is a globally unique identifier for user per merchant, this can be used to identified the same user across multiple app by the same merchant.	Basic
USER_NAME	Authorized to obtain the user’s real name	Premium
USER_BIRTHDAY	Authorized to obtain the user’s birthday.	Premium
USER_MSISDN	Authorized to obtain the user’s msisdn.	Premium
USER_ADDRESS	Authorized to obtain the user’s address.	Premium
USER_CNIC	Authorized to obtain the user’s CNIC.	Government

Callback Function

The returned Object has the following attributes:

Property	Type	Description
grantedScopes	Array	The scopes of user authorization grant type: OPEN_ID, UNION_ID, USER_AVATAR, USER_NAME, USER_BIRTHDAY, USER_ADDRESS, USER_CNIC.
status	String	SUCCESS,FAILED,CANCEL

Success callback example

				
					{
    "status":"SUCCESS",
    "authCode":"1591797390204",
    "grantedScopes":['OPEN_ID', 'UNION_ID', 'USER_NICKNAME', 'USER_MSISDN']
}

mp.createPayment

Create a payment transaction request with the precreated paymentTransactionID from /v1/payments/createPayment. It will prompt the user with an EasyPaisa native payment interface to complete payment.

Note: The payment transaction is valid for 30 minutes, after which the order status will automatically change to expired.

Note: The pop-up box will disappear automatically after 1 minute without any action.

Sample Code

To invoke mp.createPayment method in HTML

				
					//paymentTransactionID received from Open API createPayment is 12309458902409
<a onClick="mp.createPayment('12309458902409')">Click</a>

To receive the callback in javascript

				
					function createPaymentResult(jsonResult){
var result=JSON.parse(jsonResult);
alert('paymentTransactionID:'+result.paymentTransactionID);
alert('paymentStatus:'+result.paymentStatus);
alert('paymentCode:'+result.resultCode);
}

Request Parameters

Property	Type	Required	Description
paymentTransactionID	String	No	[Conditionally required either redirectURL or paymentTransactionID] Precreated paymentTransactionID from /v1/payments/createPayment
redirectURL	String	No	[Conditionally required either redirectURL or paymentTransactionID] Precreated redirect URL(actionForm) from /v1/payments/createPayment

Callback Function

The returned Object has the following attributes:

Property	Type	Required	Description
paymentTransactionID	String	Yes	Payment Transaction ID
paymentStatus	String	Yes	S,F,U,E
resultCode	String	Yes	The result code of the payment process.

Result Code

The returned Object has the following attributes:

resultCode	Description
9000	Payment is successful.
4000	Payment failed.
5000	Order is Expired.
6001	User canceled the payment.
6004	Unknown pay result, may be success.

mp.getLocation

Get the current GPS location of the user using mobile native function and pass to javascript engine of Mini App. Developer could invoke this javascript calls in their own web application.

Sample Code

To invoke mp.getLocation method in HTML

				
					<a onClick="mp.getLocation()">Click</a>

To receive the callback in javascript

				
					function getLocationResult(jsonResult){
var result=JSON.parse(jsonResult);
alert('status:'+result.status);
alert('location:'+result.longitude+','+result.latitude);
alert('accuracy:'result.accuracy);
alert('error:'result.errorCode);
}

Callback Function

The returned Object has the following attributes:

Property	Type	Description
longitude	String	Longitude.
latitude	String	Latitude.
accuracy	String	Accuracy, in meters.
status	String	SUCCESS,FAILED,UNKNOWN
errorCode	String	Error code, if success it is null

Error Code

Error	Description	Resolution
11	Make sure the location related rights has been granted.	Prompt the user to enable location permission.
12	Network problem, try again later.	Prompt the user to check the current network.
13	Location failure, try again later.	Prompt the user to try again and check GPS settings.

Idempotency

If a request timeout error occurs when you call an API, you might attempt to resend the request. In this case, you can configure the specified idempotency fields in the request to help avoid unwanted duplication in case of failures and retries.

An API call is idempotent if it has the same result no matter how many times the API call is applied. For example, idempotency can guarantee that the payment is charged only once if the same API payment call is retried multiple times in the case of a timeout error. You can retry the request via using the same idempotency field to guarantee that no more than one charge is created.

Idempotency fields

The following table lists the idempotency fields of specific OpenAPI.

Interface name	Idempotency field	Rule
/v1/payments/createPayment	paymentOrderID	This field is used for the idempotence control. For the payment requests which are initiated with the same paymentOrderID and reach a final status (S or F), the Issuing Participant must return the unique result.

Error Codes

If an error occurs when you call an API, an error response is returned, where the result object indicates the error code (resultCode) and error message (resultMessage). You can use error codes and messages to troublshoot issues.

Error codes are usually classified into the following categories:

• Common error codes: are common for all Mini Program OpenAPIs.
• API-specific error codes: are dedicated to a specific OpenAPI.

Common error codes

The following table lists all common error codes for Mini Program OpenAPIs. If you do not find an error code in the following table, it means that the error code is not common, but dedicated to a specific OpenAPI (see the following API-specific error codes section).

resultStatus	resultCode	resultMessage
F	PROCESS_FAIL	System failure
F	TRANSACTION_FAILED	“Dear Customer your transaction has failed. Please try again or contact customer support if the issue persists. “
F	PARAM_ILLEGAL	PARAM_ILLEGAL
F	AMOUNT_ILLEGAL	The amount is invalid.
F	INVALID_API	The called API is invalid or not active.
F	INVALID_SIGNATURE	Signature verification failed!
F	INVALID_MERCHANT	The merchant does not exist.
F	INVALID_CLIENT_ID	The clientId is wrong.
F	INVALID_REQUEST_TIME	The requestTime is wrong.
F	ACCESS_DENIED	There has something wrong in the accessToken.
U	UNKNOWN_EXCEPTION	“An API calling is failed, which is caused by unknown reasons.”
F	ACCOUNT_NOT_REGISTERED	“Dear Customer” Easypaisa account does not exist on this number. Please register your account by downloading the Easypaisa app and try again. “
F	ACCOUNT_NOT_ACTIVE	“Dear Customer your Easypaisa account is inactive. Please contact Easypaisa helpline for further support. Telenor users can call 3737 and non-Telenor users can call 042-111-003-737 from their mobile phone. “
F	RECORD_NOT_FOUND	There has no record been found.

F	DUPLICATE_ORDER_NUMBER	Please use an unduplicated order number
F	PARTNER_NOT_EXIST	Partner information does not exist
F	MINIAPP_NOT_EXIST	Mini-apps information does not exist
F	ILLEGAL_PAYMENT_AMOUNT	Illegal payment amount
F	ILLEGAL_PAYMENT_CURRENCY	Illegal payment currency
F	PAYMENT_ORDERID_NULL	Payment orderId is null
F	ORDERID_ALREADY_EXISTS	Payment orderId already exists
F	ILLEGAL_REQUEST_PARAMETER	Invalid request parameter.
F	ORDER_NOT_EXIST	Order not exist
F	USER_NOT_EXIST	The customer is not exist
F	ILLEGAL_AUTHORIZATION_CODE	Illegal authorization code
F	INQUIRE_SYSTEM_ERROR	“Unknown error,being processed “
F	MSISDN_IS_NOT_VALIDATE	MSISDN should be numic
F	REQUIRED_PARAMETER_IS_MISSING	The required parameters for this request is missing.
F	ILLEGAL_MERCHANT_ID	Invalid merchantId.
F	ILLEGAL_APP_ID	Invalid appId.
F	ILLEGAL_ORDER_ID	Invalid orderId.
F	ILLEGAL_TRAN_ID	Invalid transactionId.
F	ILLEGAL_ORDER_TITLE	Invalid payment order title.
F	ILLEGAL_PRODUCT_CODE	Invalid productCode.
F	ILLEGAL_AUTH_CODE	Invalid authCode.
F	ILLEGAL_RETURN_URL	Invalid payment returnUrl.
F	ILLEGAL_NOTIFY_URL	Invalid payment notifyUrl.
F	ILLEGAL_GRANT_TYPE	Invalid grantType.
F	ILLEGAL_API_KEY	Invalid apiKey.
F	ILLEGAL_EXTEND_INFO	Invalid extendInfo.

Common error codes

For error codes that are dedicated to a specific API, see the Result section in each API specification, for example , the applyToken API specification.

Overview

EasyPaisa Open Platform offers a set of OpenAPIs to achieve various capabilities via backend server API intreactions. For example, the payment capability.

Message structure

Before you make any request, it is important to understand how OpenAPI works and how requests and responses are structured. This section presents general information (such as message structure, message fields, and message transmission) of online message between your system and wallet backend.

Request structure

The following figure illustrates the request structure.

Request URL

The request URL is: https://{host}/api/ {restful_path}

where,

host: includes the host that is the standard domain name assigned by the wallet backend.
resful_path: is the path to the interface, for example, /{version}/payments/pay
version: is the version of OpenAPIs, for example, v1 or v2.

An interface can be uniquely identified by restful_path . For example, the /v1/payments/pay is different from /v2/payments/pay.

Request method

POST method is used to make an HTTP request.

Request header

The request header mainly contains the following fields.

Tip: Field names are case-insensitive.

Header field	Required	Code sample
Signature	Yes	`Signature: algorithm=RSA2048, keyVersion=1, signature=****`
Encrypt	No (It is used only when data includes sensitive information.)	`Encrypt: algorithm=RSA_AES, keyVersion=1, symmetricKey=****`
Content-Type	No	`Content-Type: application/json; charset=UTF-8`
Client-Id	Yes	`Client-Id: ****`
Request-Time	Yes	`Request-Time: 2019-04-04T12:08:56.253+05:00`
Access-Token	No	`Access-Token: f3e2tsdf235sd2ed235tsd23sf2234df2r2234e`

Table. Request header

For details of each header field, see the following description.

Signature

Signature contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value with an equal sign (=).

The following keys can be configured:

algorithm: Specifies the digital signature algorithm that is used to generate the signature. The value is not case-sensitive. Now only RSA2048 is supported.
keyVersion: Specifies the key version that is used to generate or validate the signature. By default, the value is the latest version of the key associated with Client-Id.
signature: Contains the signature value of the request. For details about how to generate a signature, see the Generate a signature section.

Example:

				
					  Signature: algorithm=RSA2048, keyVersion=1, 
    signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGR 
    rWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrT 
    pMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3Jr 
    bRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD% 
    2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%3D%3Dxxxx

Encrypt

This field is required when a message need to be encrypted, especially when sensitive information is included in the message. Encrypt contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value with an equal sign (=).

The following keys can be configured:

• algorithm: Specifies the symmetric key algorithm that is used to encrypt message. The value is not case-sensitive, and currently only RSA_AES is supported.

• keyVersion: Specifies the symmetric key version that is used to encrypt message. By default, the value is the latest version of the key associated with clientId.

• symmetricKey: Contains the encrypted symmetric key.

For example:

				
					Encrypt: algorithm=RSA_AES, keyVersion=1, 
    symmetricKey=bqS8HSmdaRrpKSuPy7CqUlyd8lJurG93xxxx

Content-Type

Optional. Content-Type indicates the media type of the body of the request, as defined by RFC2616. In which, charset is used for generating/validating signature and encrypting/decrypting content.

For example：

				
					Content-Type: application/json; charset=UTF-8

Client-Id

Client-Id is used to represent the acquiring party. In this case, it is distributed by the open platform according to your acquiring channel.

Request-Time

Specifies the time when the request is sent, as defined by RFC3339. Note: This field must be accurate to milliseconds.

				
					 Request-Time: 2019-04-04T12:08:56.253+05:00

Access-Token

Access-Token is used to identify the merchant, all the API except the applyToken require this field to be transmitted in the header.

example:

				
					Access-Token: f3e2tsdf235sd2ed235tsd23sf2234df2r2234e

Request body

The request body contains the detailed request information in a JSON format. Fields enclosed in the request body vary depending on services. For more information, see the specific API specification.

Response structure

The following figures illustrate the response structure:

Response header

The response header carries the information about the response, mainly containing the following fields.

Tip: Field names are case-insensitive.

Header field	Required	Code sample
Signature	Yes	`Signature: algorithm=RSA2048, keyVersion=1, signature=****`
Encrypt	No (It is used only when data includes sensitive information)	`Encrypt: algorithm=RSA_AES, keyVersion=1, symmetricKey=****`
Content-Type	No	`Content-Type: application/json; charset=UTF-8`
traceId	No	`traceId: 0be9923****`
Client-Id	Yes	`Client-Id: ****`
Response-Time	Yes	`Response-Time: 2019-04-04T12:08:56.253+05:00`

Table. Response header

For details of each header field, see the following description.

Signature

Signature contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value with an equal sign (=).

The following keys can be configured:

algorithm: Specifies the digital signature algorithm that is used to generate the signature. The value is not case-sensitive. Now only RSA2048 is supported.
keyVersion: Specifies the key version that is used to generate or validate the signature. By default, the value is the latest version of the key associated with Client-Id.
signature: Contains the signature value of the response.

Example:

				
					  Signature: algorithm=RSA2048, keyVersion=1, 
    signature=KEhXthj4bxxxJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGR 
    rWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrT 
    pMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3Jr 
    bRFvcowQwt0lP1XkoPmSLGpBevxxxDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD% 2FFYDAwSd%2B6%xxxx

Encrypt

This field is required when a response needs to be encrypted. Encrypt contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value with an equal sign (=).

The following keys can be configured:

• algorithm: Specifies the symmetric key algorithm that is used to encrypt a message. The value is not case-sensitive, and currently only RSA_AES is supported.

• keyVersion: Specifies the symmetric key version that is used to encrypt a message. By default, the value is the latest version of the key associated with clientId.

• symmetricKey: Contains the encrypted symmetric key.

For example:

				
					Encrypt: algorithm=RSA_AES, keyVersion=1, symmetricKey=bqS8HSmdaRrpKSuPy7CqUlyd8lJurG93xxxx

Content-Type

Optional. Content-Type indicates the media type of the body of the response, as defined by RFC2616. In which, charset is used for generating/validating the signature and encrypting/decrypting content.

For example：

				
					Content-Type: application/json; charset=UTF-8

traceId

The traceId field is used for troubleshooting when there is something wrong with a request processing. For example, use traceId to identify the specific request that has issues.

Client-Id

Client-Id is used to identify a client, and is associated with the keys that are used for signature and encryption.

Response-Time

Specifies the time when the response is returned, as defined by RFC3339. Note: This field must be accurate to milliseconds.

				
					Response-Time: 2019-04-04T14:08:56.253+05:00

Response body

Response body contains the information responding to the client. Fields in this section vary depending on services. However, the result object, which indicates the result of an API call, is always contained.

When the result status ( resultStatus) is failed, unknown, or accepted, the result code ( resultCode ) means an error code and the result message ( resultMessage ) means an error message, which is used for error handling. For more information about error codes, see the Error codes chapter.

Field	Data type	Required	Description
resultStatus	String	No	Result status. Valid values are:`S` : Successful`F` : Failed`U`: Unknown`A` : accepted, not yet succeed, but can proceed with some actions.
resultCode	String	No	Result code. Max. length: 64 characters
resultMessage	String	No	Result message that describes the result code in details.Max. length: 256 characters

Message transmission workflow

The following figure is an example that illustrates the message transmission workflow in Mini Program.

Overall procedure

Follow the overall procedure to call an API.
Preparations
To prevent some potential errors that you might get in the response, consider the following factors:

- Understand API idempontency

1. Construct a request

Construct a request by complying with the request structure, including the request header and body.
To ensure the message transmission security, perform the following security measures when constructing a request.
1. 1. Encrypt a request when the data includes sensitive information or it is required by clients. If encryption is required, the message body should be encrypted before it is signed.
1. 1. Must sign a request. Message signing and signature validation is mandatory for all requests and responses.
1. Use base64UrlEncode to encode a request to prevent errors or ambiguity that might be caused by special characters enclosed in a request. .

2. Send a request

You can send a request for example via Postman or cURL command.

3. Check the response

The response is returned usually in JSON or XML format. For details about the response, see the Response structure section.

After you receive the response, perform the following actions:

Validate the signature of the response.
Decrypt the response if the request is encrypted.

4. Check the status code

If an error occurs when you call an API, an error response is returned, where the result object indicates the error code and error message for you to troubleshoot issues.

Signature

Before calling an API, signing a request is needed. After sending the request and obtaining the response, need to validate the response signature accordingly.

RSA key

RSA key length needs to be set to 2048bits.

Sign a request

Procedure

Obtain your private key, represented by privateKey, which is used to sign a request.

Construct the content to be signed (Content_To_Be_Signed).

Calculate and generate the signature.

Add the generated signature to the request header.

For details of each step, see the following examples.

Example

1. Obtain your private key to sign the request

Get your private key ready, which is used to generate the signature later.

2. Construct the content to be signed

For example, a request has the following properties:

HTTP_URI : for example, /v1/users/inquireUserInfo.
Client-Id : for example, TEST_5X00000000000000.
Request-Time : for example, 2021-04-01T12:12:12.253+05:00.
Access-Token : for example, f3e2tsdf235sd2ed235tsd23sf2234df2r2234e.
HTTP_BODY : the body looks like the following format.

				
					{
          "authCode": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",  
    }

By complying with the Syntax of Content_To_Be_Signed, the content to be signed (Content_To_Be_Signed) is created as follows:

				
					    POST /v1/users/inquireUserInfo 
    TEST_5X00000000000000.2021-04-01T12:12:12.253+05:00.f3e2tsdf235sd2ed235tsd23sf2234df2r2234e.{
          "authCode": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",  
    }

3. Calculate and generate the signature

Use the sha256withrsa method that involve the proper algorithm and private key to calculate and generate the signature.

				
					    generatedSignature=base64UrlEncode(sha256withrsa(<Content_To_Be_Signed>), <privateKey>))

Content_To_Be_Signed: the content to be signed that is obtained in step 2.

privateKey : the private key value that is obtained in step 1.

sha256withrsa : the algorithm to use, RSA2048.

For example, the generated signature generatedSignature looks as follows:

				
					    KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU% 
    2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9 
    w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8f
    KHsLygX9cuMkQY TGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx

4. Add the generated signature to the request header

a. Assemble a signature string as the following syntax.

				
					    'Signature: algorithm=<algorithm>, keyVersion=<key-version>, signature=<generatedSignature>'

algorithm , keyVersion : see the header of the Message structure chapter.
generatedSignature : the signature that is generated in step 3.

For example:

				
					    'Signature: algorithm=RSA2048, keyVersion=0, 
    signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx'

b. Add the signature string to the request header.

For example：

				
					    -H 'Signature: algorithm=RSA2048, keyVersion=0, 
    signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fk
    i2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YV
    QwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh
    %2BzXV8AQoecJBTrv6p%xxxx'

Syntax of Content_To_Be_Signed

				
					    <HTTP_METHOD><HTTP_URI>
    <Client-Id>.<Request-Time>.<Access-Token>.<HTTP_BODY>

Note: <Client-Id>.<Request-Time>.<Access-Token>.<HTTP_BODY> The . is required even if the field value is empty

HTTP_METHOD : POST
HTTP_URI : For example, if the HTTP URL is https://example.com/api/v1/users/inquireUserInfo, this property is /api/v1/users/inquireUserInfo.
Client-Id : is used to identify a client, and is associated with the keys that are used for signature and encryption. You can get this field from the request header.
Request-Time: Specifies the time when a request is sent, as defined by RFC3339. Note: This field must be accurate to milliseconds. For example, 2019-05-28T12:12:12.253+05:00 . You can get this field from the request header.
Access-Token: Identifies a merchant. You can get this field from applyToken API. The applyToken API does not require this field to be passed in.
HTTP_BODY : the data body of a request.

Send a request

Construct a request by adding the Client-Id, Request-Time, and Signature fields to the request header. After a request is constructed, you can use common tools, like cURL or Postman to send the request. In the following example, cURL is used.

				
					    curl -X POST 
      https://example.com/api/v1/users/inquireUserInfo  
       -H 'Content-Type: application/json'   
       -H 'Client-Id: TEST_5X00000000000000'   
       -H 'Request-Time: 2019-05-28T12:12:12.253+05:00'  
       -H 'Access-Token: f3e2tsdf235sd2ed235tsd23sf2234df2r2234e'  
       -H 'Signature: algorithm=RSA2048, keyVersion=0, signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx'   
       -d  '{
          "authCode": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",  
          "authClientId": "202016726873874774774xxxx"  
          }'

Handle a response

After you receive a response, you need to validate the signature of the response. A response consists of response headers and response body. For example:

The response header sample

				
					 Client-Id: 5X00000000000000 
    Response-Time: 2019-05-28T12:12:14.253+05:00 
    Signature: algorithm=RSA2048, keyVersion=0, signature=p9T2hXxIjek0UOLw3fwlthNsV6ATaioIvu8X1uFx8a9tE87d2XEhqylnf0KjifJ3WhCoMokl GwwlDS3tsSenwnL0Ha6BsXbJvUHRC5qcVlNy5Oq%2FpNqx2%2BKdwbw4eY7tZBDQhMKoaMVSbqbCb3eRBxxxx 
    Trace-Id: 0ba604b41558615600801371953814.0

The response body sample

				
					{"result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"},"userInfo":{"openId":"1000001119398804xxxx","unionId":"123440001119398804xxxx","userMsisdn":"931116874199xxx","userName":"jack","avatar":"http:\/\/example.com\/avatar.htm?avatarId=FBF16F91-28FB-47EC-B9BE-27B285C23CD3xxxx","userAddress":"XX city X street","userCnic":"145125123452142234","extendInfo":"[]"}}

Validate a signature

Obtain the platform public key.
Construct the content to be validated ( Content_To_Be_Validated ).
Get the signature from the response header.
Validate the signature.

For details of each step, see the following examples.

Example

1. Obtain the platform public key

The Client-Id and KeyVersion properties can be obtained from the response header. Merchants send these properties to the wallet, based on which, the wallet returns the public key to the merchant.

2. Construct the content to be validated

Given the response body sample above, by complying with the Syntax of Content_To_Be_Validated, construct the content to be validated (Content_To_Be_Validated) as follows:

				
					    POST /v1/users/inquireUserInfo 
    TEST_5X00000000000000.2021-04-01T12:12:12.253+05:00.{
          "authCode": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",
    }

3. Get the signature from the response header

The target signature string ( target_signature ) is extracted from Signature header of the response. For details about the response header, see the Message structure chapter.

				
					    Signature: algorithm=RSA2048, 
    keyVersion=0, 
    signature=<target_signature>

4. Validate the signature

Use the sha256withrsa_verify method to validate the signature of a response.

Syntax of the sha256withrsa_verify method:

				
					    sha256withrsa_verify(base64UrlDecode(<target_signature>), <Content_To_Be_Validated>, <serverPublicKey>)

target_signature : the signature extracted from the response header, which is obtained from step 3.
Content_To_Be_Validated : the content to be validated that is created from step 2.
serverPublicKey : the platform public key that is obtained from step 1.

Syntax of Content_To_Be_Validated

				
					    <HTTP_METHOD> <HTTP_URI> 
    <Client-Id>.<Response-Time>.<HTTP_BODY>

Note: <Client-Id>.<Request-Time>.<Access-Token>.<HTTP_BODY> The . is required even if the field value is empty

Client-Id : identifies a client. You can get this field from the response header. For example TEST_5X00000000000000
Response-Time: Indicates the time when a response is returned, as defined by RFC3339. Note: This field must be accurate to milliseconds. You can get this field from the response header.
HTTP_BODY : Indicates the data body of the response.

/v1/authentications/applyToken

/v1/authentications
/applyToken

POST /v1/authentications/applyToken

The applyToken interface is used to obtain the access token. This interface is used in the following cases:

The merchant need to identify itself using merchant ID/secret in order for EasyPaisa to distribute an long-live access token for the merchant to perform all capabilities.
In the case which merchant want to refresh the token, first revoke the token then apply token aggain. Or else you could expect the interface to always return the same access token.

Message structure

Request

Property	Data type	Required	Max length	Description
grantType	String	Yes	Max. length: 16 characters.	Indicates the grant type, currently only support PASSWORD.
apiKey	String	No	Max. length: 32 characters.	[Conditionally Required if grantType is PASSWORD] Unique merchant api key distributed by EasyPaisa Open Platform.
extendInfo	String	No	Max. length: 4096 characters.	The extend information,wallet and merchant can put extend info here.

Response

Property	Data type	Required	Max length	Description
result	Result	Yes	–	The request result, which contains information related to the request result, such as status and error codes.
accessToken	String	No	Max. length: 128 characters.	An access token that can be used to access the user resource scope.When authorization application is successful [result.resultStatus == S], the auth client might use accessToken to acccess the corresponding user’s resource scope.
extendInfo	String	No	Max. length: 4096 characters.	The extend information,wallet and merchant can put extend info here.

Result

resultStatus	resultCode	resultMessage
S	SUCCESS	Success.
U	UNKNOWN_EXCEPTION	An API calling is failed, which is caused by unknown reasons.
U	REQUEST_TRAFFIC_EXCEED_LIMIT	The request traffic exceeds the limit.
F	PROCESS_FAIL	A general business failure occurred. Don’t retry.
F	PARAM_ILLEGAL	Illegal parameters exist. For example, a non-numeric input, or an invalid date.
F	ACCESS_DENIED	The access is denied.
F	UNSUPPORTED_GRANT_TYPE	The auth client do not support this grant type.
F	INVALID_API_KEY	The api key provided is invalid.

Result process logic

For different request results, different actions are to be performed. See the following list for details:

If the value of result.resultStatus is S, the merchant authentication request is successful. The merchant can use the access token to access the corresponding services.
If the value of result.resultStatus is F or U, please try again with correct api key.

Sample

Request

A. Retrieving accessToken with apiKey

				
					{
  "grantType": "PASSWORD",
  "apiKey": "2810111301lGZcM9CjlF91WH00039190xxxx",
}

apiKey is provided by the EasyPasia Open Platform.

Response

				
					{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"  
  },
  "accessToken": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",
}

result.resultStatus==S shows that the application is successful.
accessToken is the access token used for all subsequent call initiated by the merchant.

/v1/authentications/revokeToken

/v1/authentications
/revokeToken

POST /v2/authentications/revokeToken

The revokeToken API is used to cancel an access token. Merchant can expect to get a new access token via applyToken API after revoking the previous access token.

Message structure

Request

Property	Data type	Required	Description	Example
apiKey	String	No	The apiKey allocated for a merchant.Max. length: 128 characters.	“202016726873874774774xxxx”
extendInfo	String	No	The extend information. Wallets and merchants can put extending information in this property.Max. length: 4096 characters.	“This is additional information”

Response

Property	Data type	Required	Description	Example
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.	{ “resultCode”:”SUCCESS”, “resultStatus”:”S”, “resultMessage”:”success” }
extendInfo	String	No	The extend information. Wallets and merchants can put extending information in this property.Max. length: 4096 characters.	“This is additional information”

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	The access token is revoked successfully.
U	The API status is unknown. It means access token has failed revoke, and you might want to retry again.
F	It means access token has failed revoke, and you might want to retry again or call our open platform operations team.

Sample

Request

				
					    {
        "apiKey": "2810111301lGZcM9CjlF91WH00039190xxxx",
    }

Response

				
					{"result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"}}

/v1/payments/createPayment

/v1/payments
/createPayment

POST /v1/payments/createPayment

The createPayment API is used to initiate a payment request to easypaisa backend.

The API support following payment mode:

Cashier Payment：This is currently the only supported payment mode. Mini App backend server should first create a transaction with this API before proceeding to prompt user for payment via JSAPI/my.createPayment

Message structure

Request

Property	Data type	Required	Description
merchantID	String	Yes	The unique merchant ID allocated by wallet. Max. length: 32 characters.
appID	String	No	The unique Mini App ID allocated by wallet. Max. length: 32 characters.
productCode	String	No	Wallet will use productCode to get the contract config which include fee, payment limit info. Max. length: 32 characters.
paymentOrderTitle	String	Yes	The order title of this payment. Max. length: 256 characters.
paymentOrderID	String	Yes	The unique ID of a payment generated by merchant. Max. length: 64 characters.This field is used for the idempotence control. For the payment requests which are initiated with the same paymentRequestId and reach a final status (S or F), the Issuing Participant must return the unique result.
paymentAmount	Amount	Yes	Order amount of the payment requested by merchant to wallet user
paymentMethods	PaymentMethod	No	[Reserved for future] The paymentMethod used to collect fund by wallet. i.e. online banking, credit card, wallet balance
paymentAuthCode	String	No	[Reserved for future] The authcode used for auto-debit transactions. i.e. subscription payment Max. length: 128 characters.
paymentMode	PaymentMode	No	Currently only support Cashier Payment mode. The values are in enumeration `CASHIER`.
paymentFactor	paymentFactor	No	Currently only support Cashier Payment mode. The values are in enumeration `CASHIER`.
paymentExpiryTime	String/Datetime	No	The payment order close time defined by merchant, which follows the ISO 8601 standard. By default it’s closed in 90 minutes.
paymentReturnUrl	String	No	The redirect url defined by merchant after the payment is completed. i.e. redirect to order completion page after payment results. Max. length: 1024 characters.
paymentNotifyUrl	String	No	The payment status notify url defined by merchant. i.e. Used for post payment processes. Max retry 3 times. Max. length: 1024 characters.
merchantCategoryCode	String	No	The merchant category code. (ISO 18245). Max. length: 32 characters.
extendInfo	String	No	Extended information for extensibility, merchant could send extended information agreed with wallet in a pre-agreed format. Max. length: 4096 characters.
envInfo	String	No	Environment information for risk strategies

Response

Property	Data type	Required	Description
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.
paymentTransactionID	String	No	The unique ID of a payment generated by Wallet.Max. length: 64 characters.
paymentCreateTime	String/Datetime	No	Payment creation time, which follows the ISO 8601 standard.
actionForm	ActionForm	No	The form to perform next action. Merchant could use this redirectURL to present a payment interface to the user in either EasyPaisa Mobile App(implemented) or Web Page(not yet implemented)
extendInfo	String	No	The extend information,wallet and merchant can put extend info here.Max. length: 4096 characters.

Result process logic

For different request results, different actions are to be performed. See the following list for details:

result.resultStatus = S
That means this transaction is success, merchant/partner can update transaction to success. What need to notice is :
In payment evaluation scenario, ‘S’ just means evaluate success, no real fund transfer.
In authorization payment scenario, ‘S’ just means authorization success, need wait for capture operation to finish the transaction(finish final fund flow).
result.resultStatus = A
That means transaction already accept by wallet. Merchant/partner need continue the next step operation according to actionForm response. Such as display order code to user or redirect to wallet cashier page.
result.resultStatus = F
That means this transaction is failed, the failed reason can refer to result code param. Usually F transactions can not be success again if use the same payment request to call wallet.
result.resultStatus = U
That means unknown exception occur on wallet side. Merchant/partner can inquiry payment result or waiting for payment notification to get the real payment result. What need to notice is :
Payment evaluation scenario can not inquiry.
U status can not set to fail or success on merchant/partner system.
U status can not refund to user by offline(Maybe will make fund loss).

Result

resultStatus	resultCode	resultMessage
S	SUCCESS	Success.
U	UNKNOWN_EXCEPTION	An API calling is failed, which is caused by unknown reasons.
U	REQUEST_TRAFFIC_EXCEED_LIMIT	The request traffic exceeds the limit.
U	PAYMENT_IN_PROCESS	The payment is still under process.
A	ACCEPT	Need next action according to actionForm.
F	REPEAT_REQ_INCONSISTENT	Repeated submit, and requests are inconsistent.
F	PROCESS_FAIL	A general business failure occurred. Don’t retry.
F	INVALID_API	The called API is invalid or not active.
F	PARAM_ILLEGAL	Illegal parameters exist. For example, a non-numeric input, or an invalid date.
F	ACCESS_DENIED	The access is denied.
F	PAYMENT_AMOUNT_EXCEED_LIMIT	Payment amount exceeds limit.
F	USER_NOT_EXIST	User not exist.
F	USER_STATUS_ABNORMAL	The user status is abnormal.
F	USER_BALANCE_NOT_ENOUGH	User balance is not enough for this payment.
F	PARTNER_NOT_EXIST	Partner not exist.
F	PARTNER_STATUS_ABNORMAL	Partner status abnormal.
F	RISK_REJECT	Risk reject.
F	CURRENCY_NOT_SUPPORT	The currency is not supported.
F	ORDER_STATUS_INVALID	Order is in invalid status such closed.
F	INVALID_ACCESS_TOKEN	Invalid accesstoken.
F	USER_AMOUNT_EXCEED_LIMIT	Payment amount exceeds user’s amount limit.
F	EXPIRED_ACCESS_TOKEN	The access token is expired.
F	AUTH_CODE_ALREADY_USED	Auth code already used.
F	INVALID_CODE	Auth code illegal.
F	EXPIRED_AGENT_TOKEN	The access token of mini program is expired.
F	INVALID_AGENT_TOKEN	The access token of mini program is invalid.

Sample

Cashier Payment

For example, a user purchases a 100 PKR merchandise at the merchant/partner(online merchant usually) , merchant/partner call this payment api to create payment order first, wallet will return payment order id and wallet cashier page url to merchant/partner, then merchant/partner can redirect user to wallet cashier page with mp.createPayment api.

Request

				
					{"merchantID":"travel_merchant","appID":"travel_merchant_appID_demo","productCode":"PC_5800000001","paymentOrderTitle":"ApiTesting-Order1","paymentOrderID":"210508000000010","paymentAmount":{"currency":"PKR","value":"167"},"paymentFactor":{"isCashierPayment":true},"paymentReturnUrl":"https:\/\/www.merchant.com\/redirectxxx","paymentNotifyUrl":"https:\/\/www.merchant.com\/paymentNotifyxxx","extendInfo":"{\"customerBelongsTo\":\"siteNameExample\"}","envInfo":{"osType":"IOS","terminalType":"APP"}}

merchantID is the identifier of a merchant/partner, allocated by Wallet.
paymentOrderID is generated by merchant/partner, uniquely identifies the payment. Wallet must make use of paymentOrderID and merchantID for idempotent control. For example, if a payment with paymentOrderID== 2019112719074101000700000077771xxxx and merchantID==P000000000000001xxxx has been processed successfully by Wallet, when merchant/partner* *uses the same paymentOrderID and paymentOrderID for payment, Wallet will respond with successful payment.
productCode defined by wallet, wallet will use productCode to get the contract config which include fee,limit info.
paymentFactor In the Mini App scenario, the PaymentFactor only have the fixed value: isCashierPayment = true
paymentReturnUrl is the url defined by merchant/partner. In cashier payment scenario, after user finished payment in wallet cashier page, wallet will direct back to merchant base on this URL.
paymentNotifyUrl is the url defined by merchant/partner. In cashier payment scenario, after user finished payment in wallet cashier page, wallet will notify merchant the payment result base on this URL.
paymentAmount describes the amount of 100 PKR to be collected by Wallet from user account for this payment.
extendInfo, includes key – customerBelongsTo the e-wallet that the customer uses. Corresponding to the field ‘siteName’ that obtained from the API ‘my.getSiteInfo’, in the Mini Program scenario this is mandatory.

Response

				
					{"paymentTransactionID":"20210518155958063517","paymentCreateTime":"2021-05-18T15:59:58.093","result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"}}

result.resultStatus ==A shows that the payment is accept success. After user finish payment in cashier page, payment will change to success.
paymentTransactionID is generated by Wallet, uniquely identifies the payment.
actionForm will return cashier page url to merchant/partner, after merchant/partner received accept result, will redirect to this URL.

/v1/payments/inquirePayment

/v1/payments
/inquirePayment

POST /v1/payments/inquirePayment

The inquirePayment API is used to inquire the payment result, usually when merchants are not able to receive the payment result after a long period of time.

Note:

After the merchant initiates payment, when the merchant is not able to receive the payment result after a long period of time, it can poll Payment Inquiry interface.
The merchant uses the inquirePayment API to determine the Payment status in the asynchronous Payment processing scenario.
Round-robin interval, recommended once every 5 seconds, up to 30 seconds. Be aware that exccessively polling on this API interface might result in blocking of your API traffic completely

Message structure

Request

Property	Data type	Required	Description	Example
paymentOrderID	String	No	[Conditionally required either paymentOrderID or paymentTransactionID] The unqiue ID of a payment generated by Merchant .Max. length: 64 characters.	“20312172123000019xxxx”
paymentTransactionID	String	No	[Conditionally required either paymentOrderID or paymentTransactionID] The unqiue ID of a payment generated by Wallet.Max. length: 64 characters.	“1022172000000000001xxxx”
extendInfo	String	No	The extend information, wallets and merchants can put extending information in this property.Max. length: 4096 characters.	“This is additional information”

Response

Property	Data type	Required	Description	Example
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.	{ “resultCode”:”SUCCESS”, “resultStatus”:”S”, “resultMessage”:”success” }
paymentTransactionID	String	No	The unqiue ID of a payment generated by Wallet.Max. length: 64 characters.	“20312172123000019xxxx”
paymentOrderID	String	No	The unqiue ID of a payment generated by Merchant.Max. length: 64 characters.	“20200101234567890133333xxxx”
paymentAmount	Amount	No	Order amount for display of user consumption records, payment results page.	{ “value”:”100″, “currency”:”PKR” }
paymentTime	String/Datetime	No	Payment success time, which follows the ISO 8601 standard.	“2020-01-01T12:01:01+08:30”
paymentCreateTime	String/Datetime	No	Payment creation time, which follows the ISO 8601 standard.	“2020-01-01T11:01:01+08:30”
paymentStatus	String	No	SUCCESS – order is succeeded.FAIL – order is failed.PROCESSING – order is not paid or is paid but not finish.CANCELLED – order is cancelled.	“SUCCESS”
paymentResultCode	String	No	The payment result code.Max. length: 64 characters.	“S”
paymentResultMessage	String	No	The payment result message.Max. length: 256 characters.	“Pay Successfully”
extendInfo	String	No	The extensive information. The wallet and merchant can put extensive information in this property.Max. length: 4096 characters.	“This is additional information”

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	The corresponding result.resultCode is “SUCCESS” and the result.resultMessage is “Success”.It means that the payment inquiry is successful, then check the paymentStatus field:if paymentStatus is PROCESSING, it means that the order is not paid or is paid but not finish.if paymentStatus is SUCCESS, it means that the order succeeds.if paymentStatus is FAIL, it means that the order is failed.if paymentStatus is CANCELLED, it means that the order is cancelled.
A	The corresponding result.resultCode is “ACCEPT”; and the result.resultMessage varies based on different situations.
U	The corresponding result.resultCode is “UNKNOWN_EXCEPTION” and result.resultMessage is “An API calling is failed, which is caused by unknown reasons.”. For details, see the Common error codes section. It means that unknown exception occurs on the wallet side. The merchant/partner can try again.
F	The corresponding result.resultCode and result.resultMessage vary based on different situations. For details, see the following Error codes section. It means that the payment inquiry is failed. When resultCode is ORDER_NOT_EXIST, it means that the payment is not yet accepted and can be treated as payment failure. For the other failure reasons, human intervention is recommended.

Error codes

Error codes are usually classified into the following categories:

Common error codes): are common for all Mini Program OpenAPIs.
API-specific error codes: are listed in the following table.

resultStatus	resultCode	resultMessage
F	ORDER_NOT_EXIST	The order does not exist.
F	EXPIRED_AGENT_TOKEN	The agent token of Mini Program is expired.
F	INVALID_AGENT_TOKEN	The agent token of Mini Program is invalid.

Sample

Example: A user bought a 100 PKR product on the e-commerce platform, paid by balance and submitted the payment synchronously, asynchronous polling payment results.

Request

A. Inquiry By paymentRequestId

				
					{"paymentTransactionID":"1022172000000000001xxxx"}

B. Inquiry By paymentId

				
					{"paymentOrderID":"20312172123000019xxxx"}

paymentTransactionID the unique Id of a payment generated by Wallet.
paymentOrderID the unique Id of a payment generated by Merchant.

Note: This interface support querying with paymentTransactionID or paymentOrderID.
paymentTransactionID has a higher priority than paymentOrderID, which means that if you offer both paymentTransactionID and paymentOrderID, we will use paymentTransactionID and ignore paymentOrderID.

Response

				
					{"result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"},"paymentTransactionID":"20200101234567890133333xxxx","paymentOrderID":"20200101234567890133333xxxx","paymentTime":"2020-01-01T12:01:01+08:30","paymentAmount":{"value":"100","currency":"PKR"},"paymentStatus":"SUCCESS","paymentResultCode":"S","paymentResultMessage":"Paid Successfully"}

result.resultStatus==S shows that the inquiry is successful.
paymentTransactionID the unique Id of a payment generated by Wallet.
paymentOrderID the unique Id of a payment generated by Merchant.
paymentTime describes the date time of the successful Wallet payment.
paymentAmount describes the payment amount.
paymentStatus describes the payment status.
- paymentStatus.PROCESSING order is not paid or is paid but not finish.
- paymentStatus.SUCCESS order is succeeded.
- paymentStatus.FAIL order is failed.
- paymentStatus.CANCELLED order is cancelled.

/v1/users/inquireUserInfo

/v1/users
/inquireUserInfo

POST /v1/users/inquireUserInfo

The inquireUserInfo API is used for the merchant to get the user related information after obtaining user authorization.

Sample

Query user information via an authCode. The authCode is generated via OAuth after authorization is successful.

Merchant calls this interface with authCode (Step 1)
easypaisa server returns user information the to merchant based on the authCode (Step 2).

Request sample

				
					 {
          "authCode": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",  
    }

Response sample

				
					{"result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"},"userInfo":{"openId":"1000001119398804xxxx","unionId":"123440001119398804xxxx","userMsisdn":"931116874199xxx","userName":"jack","avatar":"http:\/\/example.com\/avatar.htm?avatarId=FBF16F91-28FB-47EC-B9BE-27B285C23CD3xxxx","userAddress":"XX city X street","userCnic":"145125123452142234","extendInfo":"[]"}}

Structure

Request

Property	Data type	Required	Description	Example
authCode	String (128)	Yes	An auth code that can be used to access the user resource scope.	“281010033AB2F588D14B43238637264FCA5AAF35xxxx”
extendInfo	String (4096)	No	the extend information. Wallets and merchants can put extending information in this property.	“This is additional information”

Response

Property	Data type	Required	Description	Example
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.	{ “resultCode”:”SUCCESS”, “resultStatus”:”S”, “resultMessage”:”success” }
userInfo	User	No	User open information.	{ “userId”: “1000001119398804xxxx”, “status”: “ACTIVE”, “nickName”: “Jack”, “userName”: { “fullName”: “Jack Sparrow”, “firstName”: “Jack”, “lastName”: “Sparrow” }, “avatar”: “http://example.com/avatar.htm?avatarId=FBF16F91-28FB-47EC-B9BE-27B285C23CD3xxxx”, “gender”: “MALE”, “birthDate”: “2020-07-25”, “nationality”: “US”, “loginIdInfos”: [ { “loginId”: “1116874199xxx”, “loginIdType”: “MOBILE_PHONE” } ], “contactInfos”: [ { “contactNo”: “1116874199xxx”, “contactType”: “MOBILE_PHONE” } ], “extendInfo”: “{}” }

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	It means user information inquiry is successful, merchant can use the auth code to access the corresponding user resource scope.The corresponding result.resultCode is “SUCCESS” and the result.resultMessage is “Success”.
U	The API status is unknown. AuthClient may guide user to try again.The corresponding result.resultCode is “UNKNOWN_EXCEPTION” and result.resultMessage is “An API calling is failed, which is caused by unknown reasons.”.
F	It means that user information inquiry is failed. The corresponding result.resultCode and result.resultMessage vary based on different situations.

Error codes

Error codes are usually classified into the following categories:

Common error codes: are common for all Mini Program OpenAPIs.
API-specific error codes: are listed in the following table.

resultStatus	resultCode	resultMessage
F	INVALID_AUTH_CODE	The auth code is invalid.
F	INVALID_AUTH_CLIENT	The auth client id is invalid.
F	EXPIRED_AUTH_CODE	The auth code is expired.
F	EXPIRED_AGENT_TOKEN	The agent token of mini program is expired.
F	INVALID_AGENT_TOKEN	The agent token of mini program is invalid.

/v1/promotions/createCashback

/v1/promotions
/createCashback

Cashback

POST /v1/promotions/createCashback The createCashback interface is used to apply for a cashback request for a specific user.

Message structure

Request

Field	Type	Required	Constrains	Description
msisdn	String	Yes	Max length: 64	User msisdn（mobile number）
cashbackOrderID	String	Yes	Max length: 64	The unique ID of a cashback generated by merchant.
cashbackCreateTime	String/Datetime	Yes		Time of trigger event occurring, which follows the ISO8601 standard.
campaignID	String	Yes		Campaign id
cashbackAmount	Amount	Yes		Amount of cashback from merchant to wallet user.
cashbackExpiryTime	String/Datetime	No		[Reserved for Future]The cashback order close time defined by merchant. By default, applications from non-Easypaisa user will not be accepted. which follows the ISO8601 standard.
extendInfo	String	No	Max. length: 4096 characters.	Extended information for extensibility, merchant could send extended information agreed with Easypaisa in a pre-agreed format.
envInfo	String	No	Environment information for risk strategies

Response

Property	Data type	Required	Description
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.
cashbackTransactionID	String	No	The unique ID of a cashback generated by Wallet.
cashbackTime	String/Datetime	No	Cashback success time.
redirectUrl	String	No	The Url redirect is to guide the user to download the Easypaisa App and complete the cashback process.When the returnStatus is A, this field will be returned
extendInfo	String	No	The extend information,wallet and merchant can put extend info here.Max. length: 4096 characters.

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	It means cashback successful.The corresponding result.resultCode is “SUCCESS” and the result.resultMessage is “Success”.
A	[Reserved for Future]The corresponding `result.resultCode` is “ACCEPT”; That means that the cashback is already accepted by Easypaisa. The merchant needs to redirect the user to the `redirectUrl` page and guide the user to complete the cashback process. Return `A`is because the user has not registered the wallet yet, then the user needs to download and register the wallet before `cashbackExpiryTime` and then wallet will automatically send the cashback to the user’s account. Cashback transactions will be cancelled if the `cashbackExpiryTime` is exceeded.
U	The API status is unknown. The corresponding result.resultCode is “UNKNOWN_EXCEPTION” and result.resultMessage is “An API calling is failed, which is caused by unknown reasons.”
F	It means cashback is failed. The corresponding result.resultCode and result.resultMessage vary based on different situations.

Sample

1, Merchant calls this interface (Step 1) 2, Easypaisa add money to user account or wait for user to register 3, Response result

Example

				
					Request = {
  "msisdn": "03455000001",
  "cashbackOrderID": "LCHLC2530159581919051701",
  "cashbackCreateTime": "2021-05-21T12:12:12.253+05:00",
  "cashbackExpiryTime": "2021-05-21T12:12:12.253+05:00",
  "cashbackAmount": {
      "currency": "PKR",
      "value": "100"
  },
  "campaignID": "CAMPAIGN20210521000000050321",
  "extendInfo": "{\"merchantInfo\":\"merchant name\"}"

}

				
					Result = {
    "cashbackTransactionID":"210521115113000001",
    "cashbackOrderID":"LCHLC2530159581919051701",
    "cashbackTime":"2021-05-21T12:12:13.253+05:00",
    "redirectUrl":"https://easypaisa.activ8.digital/how-easypaisa-works/?cashbackOrderId\u003dLCHLC2530159581919051701",
    "result":{
        "resultCode":"SUCCESS",
        "resultStatus":"S",
        "resultMessage":"success"
    }
}

/v1/promotions/inquireCashback

/v1/promotions
/inquireCashback

Cashback

POST /v1/promotions/inquireCashback The inquireCashback is used to inquire about the latest status of a cashback order.

Message structure

Request

Field	Type	Required	Constrains	Description
cashbackOrderID	String	No	Max length: 64	The unique ID of a cashback generated by merchant.
cashbackTransactionID	String	No	Max length: 64	The unique ID of a cashback generated by Wallet.
extendInfo	String	No	Max. length: 4096 characters.	Extended information for extensibility, merchant could send extended information agreed with Easypaisa in a pre-agreed format.

Response

Property	Data type	Required	Description
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.
cashbackStatus	String	No	The latest status about this cashback order.
cashbackOrderID	String	No	The unique ID of a cashback generated by merchant.
cashbackTransactionID	String	No	The unique ID of a cashback generated by Wallet.
cashbackTime	String/Datetime	No	Cashback success time.
cashbackResultMessage	String	No	The cashback result message. Max.length:256 characters.
extendInfo	String	No	The extend information,wallet and merchant can put extend info here.Max. length: 4096 characters.

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	It means cashback successful.The corresponding result.resultCode is “SUCCESS” and the result.resultMessage is “Success”.
A	The corresponding `result.resultCode` is “ACCEPT”; That means that the cashback is already accepted by Easypaisa. The merchant needs to redirect the user to the `redirectUrl` page and guide the user to complete the cashback process. Return `A`is because the user has not registered the wallet yet, then the user needs to download and register the wallet before `cashbackExpiryTime` and then wallet will automatically send the cashback to the user’s account. Cashback transactions will be cancelled if the `cashbackExpiryTime` is exceeded.
U	The API status is unknown. The corresponding result.resultCode is “UNKNOWN_EXCEPTION” and result.resultMessage is “An API calling is failed, which is caused by unknown reasons.”
F	It means cashback is failed. The corresponding result.resultCode and result.resultMessage vary based on different situations.

Example

				
					Request = {
  "cashbackOrderID": "4a68a2db8c4d720b5080166a68269e96",
  "extendInfo": {}
}

result.resultStatus==S shows that the inquiry is successful.
cashbackOrderID the unique Id of a cashback generated by merchant.
cashbackTransactionID the unique Id of a cashback generated by wallet.
cashbackTime describes the date time of the successful wallet cashback.
cashbackResultMessage describes the cashback result message.
cashbackStatus describes the cashback status.
- cashbackStatus.PROCESSING order are being processed or waiting for user registration.
- cashbackStatus.SUCCESS cashback order is succeeded.
- cashbackStatus.FAIL cashback order is failed.
- cashbackStatus.EXPIRED cashback order is expired.

				
					Result = {
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  },
  "cashbackStatus" : "SUCCESS",
  "cashbackOrderID" : "34t2f23d23a5345324523",
  "cashbackTransactionID":"34t2f23d23a5d5adf6d6asd6asd6d6a",
  "cashbackTime" : "2021-04-06 00:00:00",
  "cashbackResultMessage": "Cashback Successfully",
}

Data dictionary

Model

Amount

Property	Data type	Required	Description
currency	String	Yes	The three-character ISO-4217 currency code.Max. length: 3 characters.
value	String	Yes	A string that encloses a positive integer representing how much to charge in the smallest currency unit(e.g., 100 cents to charge \$1.00 or 100 to charge \$100, a zero-decimal currency).Max. length: 16 characters.

ActionForm

Property	Data type	Required	Description
actionFormType	String	No	The action form type. Enum: [ ORDER_CODE , REDIRECTION ]
orderCode	String	No	[Reserved for Future] The order code value. The order code is generated by merchants, which is a QR code with order information for customers to scan.Max. length: 2048 characters.
redirectURL	String	No	The URL to redirect in order to complete payment. This currently only support deeplink payment to pull up the easypaisa payment cashier interface. Max. length: 4096 characters.

EnvInfo

Property	Data type	Required	Description
terminalType	String	No	The terminal type of this request.Enum: TerminalType
osType	String	No	OS type.Enum: OsType
userAgent	String	No	HTTP request user agent.Max. length: 1024 characters.
deviceTokenId	String	No	Token ID of the device if any .Max. length: 128 characters.
clientIp	String	No	IP address of the client device .Max. length: 64 characters.
cookieId	String	No	User cookie ID if any. Max. length: 128 characters.
storeTerminalId	String	No	The store terminal ID.Max. length: 64 characters.
storeTerminalRequestTime	String/Datetime	No	The store terminal request time.Max. length: 32 characters.
extendInfo	String	No	Extend info.Max. length: 4096 characters.

OsType

Key	Description
IOS	iOS.
ANDROID	Android.
WINDOWS	Windows
HARMONY	HARMONYOS（Huawei OS）

TerminalType

Key	Description
MINI_APP	Mini program / Mini H5.
APP	Mobile Application.
WEB	Broswer Web.
WAP	Mobile Wap.
SYSTEM	SYSTEM System Call.

PaymentFactor

Property	Data type	Required	Description
needSurcharge	Boolean	No	An indicator of a surcharge, which appears in the request from APS to Issuing Participant. If the value is TRUE, the fields surchargeAmount and surchargeQuote must be specified. The default value is FALSE.
isPaymentEvaluation	Boolean	No	An indicator of the payment evaluation. If the value is TRUE, the payment is only to evaluate whether the payment can be successful and no actual funds deduction occurs. The default value is FALSE.
isAuthorizationAndPay	Boolean	No	An indicator of whether to do authorization for the agreement payment (Auto Debit) during the payment. The default value is FALSE.
isAuthorizationPayment	Boolean	No	An indicator of whether the payment is an authorization payment.The default value is FALSE.
isDeferredPayment	Boolean	No	An indicator of whether the payment is a deferred payment, in which scenario the user uses the product or service in advance.
needCheckCompliance	Boolean	No	An indicator of whether the payment information must be validated to meet compliances before the payment is processed.
needOtpVerification	Boolean	No	An indicator of whether the payment needs to verify OTP (one time password).
isCrossborderSettlement	Boolean	No	An indicator of whether the payment requires cross-border settlement.
inStorePaymentScenario	Boolean	No	An indicator of PaymentCode/OrderCode/EntryCode .

User

Property	Data type	Required	Description
userId	String	No	The hashed unique identifier allocated for user.Max. length: 64 characters.
status	String	No	User status, Enum: “ACTIVE”, “FROZEN”, “INACTIVE”Max. length: 32 characters.
nickName	String	No	Nick name.Max. length: 256 characters.
userName	UserName	No	User name, fullName and (firstName,middleName,lastName) can not both empty.
userAddresses	Array	No	The user’s address information.
avatar	String	No	Avatar url.Max. length: 256 characters.
gender	String	No	F: female; M: Male.Max. length: 32 characters.
birthDate	String/Datetime	No	Birth date which follows the ISO 8601 standard.Max. length: 32 characters.
nationality	String	No	Nationality, alpha-2 code according to ISO3166. e.g. JP, US.Max. length: 32 characters.
loginIdInfos	Array	No	A list of user login IDs.
contactInfos	Array	No	A list of contact information.
extendInfo	String	No	The extend information,wallet and merchant can put extend info here.Max. length: 4096 characters.

ContactInfo

Property	Data type	Required	Description
contactType	String	Yes	The followings are contact types that are available to all users：MOBILE_PHONE TELEPHONE EMAIL Tips: Developer can add new types, but should consider the compatibility.Max. length: 32 characters.
ContactInfo	String	Yes	The value that corresponds to the contact type that is configured in the contactType field. For example, this field can be mobile phone numer, or e-mail address.Max. length: 64 characters.
extendInfo	String	No	The extensive information for wallets and merchants to add.Max. length: 4096 characters.

Order

Property	Data type	Required	Description
referenceOrderId	String	Yes	The unique identification of the order on the merchant side. It is used for the display of user consumption records, and the subsequent payment operations such as customer complaints and disputes track.Max. length: 64 characters.
orderDescription	String	No	Description of the order used to display user consumption records, etc.Max. length: 256 characters.
orderAmount	Amount	Yes	The amount of an order, like how much to charge in the specified currency unit for an order.
orderCreateTime	String/Datetime	No	Order create time from merchant which follows the ISO 8601 standard.Max. length: 32 characters.
referenceMerchant	Merchant	No	Merchant information.
goods	Goods	No	Goods information.
shipping	Shipping	No	Shipping information.
buyer	Buyer	No	Buyer information.
extendInfo	String	No	Extended infomation data, this field includes information that are not common but needed for special use cases.Max. length: 2048 characters.

Merchant

Property	Data type	Required	Description
referenceMerchantId	String	Yes	Merchant ID.Max. length: 32 characters.
merchantMCC	String	Yes	Merchant MCC.Max. length: 32 characters.
merchantName	String	Yes	Name of Merchant.Max. length: 256 characters.
merchantDisplayName	String	No	Display name of merchant.Max. length: 64 characters.
merchantAddress	Address	No	The address of merchant.
merchantRegisterDate	String/Datetime	No	Merchant register time from merchant which follows the ISO 8601 standard.Max. length: 32 characters.
store	Store	No	Merchant store.

Address

Property	Data type	Required	Description
region	String	Yes	Alpha-2 code according to ISO3166. e.g. JP, US.Max. length: 2 characters.
state	String	No	State/County/Province.Max. length: 8 characters.
city	String	No	City/District/Suburb/Town/Village.Max. length: 32 characters.
address1	String	No	Address line 1(Street address/PO Box/Company name).Max. length: 256 characters.
address2	String	No	Address line 2(Apartment/Suite/Unit/Building).Max. length: 256 characters.
zipCode	String	No	ZIP or postal code.Max. length: 32 characters.

Overview

easypaisa Open Platform offers a set of OpenAPIs to achieve various capabilities via backend server API intreactions. For example, the agreement payment capability.

Message structure

The following figure illustrates the request structure.

Request URL

The request URL is: https://{host}/api/v2/{restful_path}

where,

host: includes the host that is the standard domain name assigned by the wallet backend.
resful_path: is the path to the interface, for example, /{version}/payments/pay
version: is the version of OpenAPIs, for example, v1 or v2.

An interface can be uniquely identified by restful_path . For example, the /v1/payments/pay is different from /v2/payments/pay.

Request method

POST method is used to make an HTTP request.

Request header

The request header mainly contains the following fields.

Tip: Field names are case-insensitive.

Header field	Required	Code sample
Signature	Yes	`Signature: algorithm=RSA2048, keyVersion=1, signature=****`
Encrypt	No (It is used only when data includes sensitive information.)	`Encrypt: algorithm=RSA_AES, keyVersion=1, symmetricKey=****`
Content-Type	No	`Content-Type: application/json; charset=UTF-8`
App-Id	Yes	`App-Id: ****`
Request-Time	Yes	`Request-Time: 2019-04-04T12:08:56.253+05:30`

The request header mainly contains the following fields.

Tip: Field names are case-insensitive.

Signature

Signature contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value with an equal sign (=).

The following keys can be configured:

algorithm: Specifies the digital signature algorithm that is used to generate the signature. The value is not case-sensitive. Now only RSA2048 is supported.
keyVersion: Specifies the key version that is used to generate or validate the signature. By default, the value is the latest version of the key associated with App-Id.
signature: Contains the signature value of the request. For details about how to generate a signature, see the Generate a signature section.

Example:

				
					    Signature: algorithm=RSA2048, keyVersion=1, 
    signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGR 
    rWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrT 
    pMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3Jr 
    bRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD% 
    2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%3D%3Dxxxx

Encrypt

The following keys can be configured:

• algorithm: Specifies the symmetric key algorithm that is used to encrypt message. The value is not case-sensitive, and currently only RSA_AES is supported.

• keyVersion: Specifies the symmetric key version that is used to encrypt message. By default, the value is the latest version of the key associated with clientId.

• symmetricKey: Contains the encrypted symmetric key.

For example:

				
					    Encrypt: algorithm=RSA_AES, keyVersion=1, 
    symmetricKey=bqS8HSmdaRrpKSuPy7CqUlyd8lJurG93xxxx

Content-Type

For example：

				
					Content-Type: application/json; charset=UTF-8

App-Id

The app-ID identifies the channel from which the request comes, and obtains the corresponding public key for verification.

Request-Time

Specifies the time when the request is sent, as defined by RFC3339. Note: This field must be accurate to milliseconds.

				
					  Request-Time: 2019-04-04T12:08:56.253+05:00

Request body

The request body contains the detailed request information in a JSON format. Fields enclosed in the request body vary depending on services. For more information, see the specific API specification.

Response structure

The following figures illustrate the response structure:

Request header

The response header carries the information about the response, mainly containing the following fields.

Tip: Field names are case-insensitive.

Header field	Required	Code sample
Signature	Yes	`Signature: algorithm=RSA2048, keyVersion=1, signature=****`
Encrypt	No (It is used only when data includes sensitive information)	`Encrypt: algorithm=RSA_AES, keyVersion=1, symmetricKey=****`
Content-Type	No	`Content-Type: application/json; charset=UTF-8`
traceId	No	`traceId: 0be9923****`
App-Id	Yes	`App-Id: ****`
Response-Time	Yes	`Response-Time: 2019-04-04T12:08:56.253+05:00`

Table. Response header

For details of each header field, see the following description.

Signature

Signature contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value with an equal sign (=).

The following keys can be configured:

algorithm: Specifies the digital signature algorithm that is used to generate the signature. The value is not case-sensitive. Now only RSA2048 is supported.
keyVersion: Specifies the key version that is used to generate or validate the signature. By default, the value is the latest version of the key associated with App-Id.
signature: Contains the signature value of the response.

Example:

				
					    Signature: algorithm=RSA2048, keyVersion=1, 
    signature=KEhXthj4bxxxJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGR 
    rWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrT 
    pMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3Jr 
    bRFvcowQwt0lP1XkoPmSLGpBevxxxDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD% 2FFYDAwSd%2B6%xxxx

Encrypt

The following keys can be configured:

• algorithm: Specifies the symmetric key algorithm that is used to encrypt a message. The value is not case-sensitive, and currently only RSA_AES is supported.

• keyVersion: Specifies the symmetric key version that is used to encrypt a message. By default, the value is the latest version of the key associated with App-Id.

• symmetricKey: Contains the encrypted symmetric key.

For example:

				
					Encrypt: algorithm=RSA_AES, keyVersion=1, symmetricKey=bqS8HSmdaRrpKSuPy7CqUlyd8lJurG93xxxx

**Content-Type**

For example：

				
					Content-Type: application/json; charset=UTF-8

traceId

The traceId field is used for troubleshooting when there is something wrong with a request processing. For example, use traceId to identify the specific request that has issues.

App-Id

The app-ID identifies the channel from which the request comes, and obtains the corresponding public key for verification.

Response-Time

Specifies the time when the response is returned, as defined by RFC3339. Note: This field must be accurate to milliseconds.

				
					Response-Time: 2019-04-04T14:08:56.253+05:00

### <span id="Response_body">Response body </span>

Field	Data type	Required	Description
resultStatus	String	No	Result status. Valid values are:`S` : Successful`F` : Failed`U`: Unknown`A` : accepted, not yet succeed, but can proceed with some actions.
resultCode	String	No	Result code. Max. length: 64 characters
resultMessage	String	No	Result message that describes the result code in details.Max. length: 256 characters

Message transmission workflow

The following figure is an example that illustrates the message transmission workflow in Mini Program.

Overall procedure

Follow the overall procedure to call an API.

Preparations

To prevent some potential errors that you might get in the response, consider the following factors:

Understand API idempontency

1. Construct a request

Construct a request by complying with the request structure, including the request header and body.

To ensure the message transmission security, perform the following security measures when constructing a request.

Encrypt a request when the data includes sensitive information or it is required by clients. If encryption is required, the message body should be encrypted before it is signed.
Must sign a request. Message signing and signature validation is mandatory for all requests and responses.
Use base64UrlEncode to encode a request to prevent errors or ambiguity that might be caused by special charaters enclosed in a request. .

2. Send a request

You can send a request for example via Postman or cURL command.

3. Check the response

The response is returned usually in JSON or XML format. For details about the response, see the Response structure section.

After you receive the response, perform the following actions:

Validate the signature of the response.
Decrypt the response if the request is encrypted.

4. Check the status code

If an error occurs when you call an API, an error response is returned, where the result object indicates the error code and error message for you to troubleshoot issues.

Signature

Before calling an API, signing a request is needed. After sending the request and obtaining the response, need to validate the response signature accordingly.

RSA key

RSA key length needs to be set to 2048bits.

Sign a request

Procedure

Obtain your private key, represented by privateKey, which is used to sign a request.
Construct the content to be signed (Content_To_Be_Signed).
Calculate and generate the signature.
Add the generated signature to the request header.

For details of each step, see the following examples.

1. Obtain your private key to sign the request

Get your private key ready, which is used to generate the signature later.

2. Construct the content to be signed

For example, a request has the following properties:

HTTP_URI : for example, /v1/users/inquireUserInfo.
App-Id : for example, TEST_5X00000000000000.
Request-Time : for example, 2021-04-01T12:12:12.253+05:00.
HTTP_BODY : the body looks like the following format.

				
					{"paymentAuthCode":"281010033AB2F588D14B43238637264FCA5AAF35xxxx"}

By complying with the Syntax of Content_To_Be_Signed, the content to be signed (Content_To_Be_Signed) is created as follows:

				
					    POST /v2/generatePaymentToken 
    TEST_5X00000000000000.2021-04-01T12:12:12.253+05:00.f3e2tsdf235sd2ed235tsd23sf2234df2r2234e.{
          "authCode": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",  
    }

3. Calculate and generate the signature

Use the sha256withrsa method that involve the proper algorithm and private key to calculate and generate the signature.

				
					    generatedSignature=base64UrlEncode(sha256withrsa(<Content_To_Be_Signed>), <privateKey>))

Content_To_Be_Signed: the content to be signed that is obtained in step 2.
privateKey : the private key value that is obtained in step 1.
sha256withrsa : the algorithm to use, RSA2048.

For example, the generated signature generatedSignature looks as follows:

				
					    KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU% 
    2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9 
    w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8f
    KHsLygX9cuMkQY TGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx

4. Add the generated signature to the request header

a. Assemble a signature string as the following syntax.

				
					    'Signature: algorithm=<algorithm>, keyVersion=<key-version>, signature=<generatedSignature>'

algorithm , keyVersion : see the header of the Message structure chapter.
generatedSignature : the signature that is generated in step 3.

For example:

				
					    'Signature: algorithm=RSA2048, keyVersion=0, 
    signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx'

b. Add the signature string to the request header.

For example：

				
					    -H 'Signature: algorithm=RSA2048, keyVersion=0, 
    signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fk
    i2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YV
    QwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh
    %2BzXV8AQoecJBTrv6p%xxxx'

Send a request

Construct a request by adding the App-Id, Request-Time, and Signature fields to the request header. After a request is constructed, you can use common tools, like cURL or Postman to send the request. In the following example, cURL is used.

				
					    curl -X POST 
      https://example.com/api/v1/users/inquireUserInfo  
       -H 'Content-Type: application/json'   
       -H 'App-Id: TEST_5X00000000000000'   
       -H 'Request-Time: 2019-05-28T12:12:12.253+05:00'   
       -H 'Signature: algorithm=RSA2048, keyVersion=0, signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx'   
       -d  '{
          "paymentAuthCodeAuthCode": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",  
          "appId": "202016726873874774774xxxx"  
          }'

Handle a response

After you receive a response, you need to validate the signature of the response. A response consists of response headers and response body. For example:

The response header sample

				
					    App-Id: 5X00000000000000 
    Response-Time: 2019-05-28T12:12:14.253+05:00 
    Signature: algorithm=RSA2048, keyVersion=0, signature=p9T2hXxIjek0UOLw3fwlthNsV6ATaioIvu8X1uFx8a9tE87d2XEhqylnf0KjifJ3WhCoMokl GwwlDS3tsSenwnL0Ha6BsXbJvUHRC5qcVlNy5Oq%2FpNqx2%2BKdwbw4eY7tZBDQhMKoaMVSbqbCb3eRBxxxx 
    Trace-Id: 0ba604b41558615600801371953814.0

the response body sample

				
					{"result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"},"userInfo":{"openId":"1000001119398804xxxx","unionId":"123440001119398804xxxx","userMsisdn":"931116874199xxx","userName":"jack","avatar":"http:\/\/example.com\/avatar.htm?avatarId=FBF16F91-28FB-47EC-B9BE-27B285C23CD3xxxx","userAddress":"XX city X street","userCnic":"145125123452142234","extendInfo":"[]"}}

Validate a signature

Obtain the platform public key.
Construct the content to be validated ( Content_To_Be_Validated ).
Get the signature from the response header.
Validate the signature.

For details of each step, see the following examples.

Response Example

1. Obtain the platform public key

The App-Id and KeyVersion properties can be obtained from the response header. Merchants send these properties to the wallet, based on which, the wallet returns the public key to the merchant.

2. Construct the content to be validated

Given the response body sample above, by complying with the Syntax of Content_To_Be_Validated, construct the content to be validated (Content_To_Be_Validated) as follows:

				
					    POST /v2/generatePaymentToken 
    TEST_5X00000000000000.2021-04-01T12:12:12.253+05:00.{
          "authCode": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",
    }

2. Construct the content to be validated

The target signature string ( target_signature ) is extracted from Signature header of the response. For details about the response header, see the Message structure chapter.

				
					    Signature: algorithm=RSA2048, 
    keyVersion=0, 
    signature=<target_signature>

target_signature : the signature extracted from the response header, which is obtained from step 3.
Content_To_Be_Validated : the content to be validated that is created from step 2.
serverPublicKey : the platform public key that is obtained from step 1.

Syntax of Content_To_Be_Validated

				
					    <HTTP_METHOD> <HTTP_URI> 
    <App-Id>.<Response-Time>.<HTTP_BODY>

Note: <App-Id>.<Request-Time>.<HTTP_BODY> The . is required even if the field value is empty

- HTTP_METHOD :POST
- HTTP_URI: For example, if the HTTP URL is https://example.com/api/v1/users/inquireUserInfo, this property is /api/v1/users/inquireUserInfo.
- App-Id: The app-ID identifies the channel from which the request comes, and obtains the corresponding public key for verification.
- Response-Time: Indicates the time when a response is returned, as defined by RFC3339. Note: This field must be accurate to milliseconds. You can get this field from the response header.
- HTTP_BODY : Indicates the data body of the response.

Data dictionary

Model

Amount

Property	Data type	Required	Description
currency	String	Yes	The three-character ISO-4217 currency code.Max. length: 3 characters.
value	String	Yes	A string that encloses a positive integer representing how much to charge in the smallest currency unit(e.g., 100 cents to charge \$1.00 or 100 to charge \$100, a zero-decimal currency).Max. length: 16 characters.

PaymentFactor

Property	Data type	Required	Description
needSurcharge	Boolean	No	An indicator of a surcharge, which appears in the request from APS to Issuing Participant. If the value is TRUE, the fields surchargeAmount and surchargeQuote must be specified. The default value is FALSE.
isPaymentEvaluation	Boolean	No	An indicator of the payment evaluation. If the value is TRUE, the payment is only to evaluate whether the payment can be successful and no actual funds deduction occurs. The default value is FALSE.
isAuthorizationAndPay	Boolean	No	An indicator of whether to do authorization for the agreement payment (Auto Debit) during the payment. The default value is FALSE.
isAuthorizationPayment	Boolean	No	An indicator of whether the payment is an authorization payment.The default value is FALSE.
isDeferredPayment	Boolean	No	An indicator of whether the payment is a deferred payment, in which scenario the user uses the product or service in advance.
needCheckCompliance	Boolean	No	An indicator of whether the payment information must be validated to meet compliances before the payment is processed.
needOtpVerification	Boolean	No	An indicator of whether the payment needs to verify OTP (one time password).
isCrossborderSettlement	Boolean	No	An indicator of whether the payment requires cross-border settlement.
inStorePaymentScenario	Boolean	No	An indicator of PaymentCode/OrderCode/EntryCode .

ActionForm

Property	Data type	Required	Description
actionFormType	String	No	The action form type. Enum: [ ORDER_CODE , REDIRECTION ]
orderCode	String	No	[Reserved for Future] The order code value. The order code is generated by merchants, which is a QR code with order information for customers to scan.Max. length: 2048 characters.
redirectURL	String	No	The URL to redirect in order to complete payment. This currently only support deeplink payment to pull up the EasyPaisa payment cashier interface. Max. length: 4096 characters.

EnvInfo

Property	Data type	Required	Description
needSurcharge	Boolean	No	An indicator of a surcharge, which appears in the request from APS to Issuing Participant. If the value is TRUE, the fields surchargeAmount and surchargeQuote must be specified. The default value is FALSE.
isPaymentEvaluation	Boolean	No	An indicator of the payment evaluation. If the value is TRUE, the payment is only to evaluate whether the payment can be successful and no actual funds deduction occurs. The default value is FALSE.
isAuthorizationAndPay	Boolean	No	An indicator of whether to do authorization for the agreement payment (Auto Debit) during the payment. The default value is FALSE.
isAuthorizationPayment	Boolean	No	An indicator of whether the payment is an authorization payment.The default value is FALSE.
isDeferredPayment	Boolean	No	An indicator of whether the payment is a deferred payment, in which scenario the user uses the product or service in advance.
needCheckCompliance	Boolean	No	An indicator of whether the payment information must be validated to meet compliances before the payment is processed.
needOtpVerification	Boolean	No	An indicator of whether the payment needs to verify OTP (one time password).
isCrossborderSettlement	Boolean	No	An indicator of whether the payment requires cross-border settlement.
inStorePaymentScenario	Boolean	No	An indicator of PaymentCode/OrderCode/EntryCode .

User

Property	Data type	Required	Description
actionFormType	String	No	The action form type. Enum: [ ORDER_CODE , REDIRECTION ]
orderCode	String	No	[Reserved for Future] The order code value. The order code is generated by merchants, which is a QR code with order information for customers to scan.Max. length: 2048 characters.
redirectURL	String	No	The URL to redirect in order to complete payment. This currently only support deeplink payment to pull up the easypaisa payment cashier interface. Max. length: 4096 characters.

/v2/authentications/applyToken

/v2/authentications
/applyToken

POST /v2/authentications/applyToken The applyToken interface is used to obtain the access token. This interface is used in the following cases:

The merchant need to identify itself using merchant ID/secret in order for EasyPaisa to distribute an long-live access token for the merchant to perform all capabilities.
In the case which merchant want to refresh the token, first revoke the token then apply token aggain. Or else you could expect the interface to always return the same access token.

Message structure

Request

Property	Data type	Required	Max length	Description
grantType	String	Yes	Max. length: 16 characters.	Indicates the grant type, currently only support PASSWORD.
apiKey	String	No	Max. length: 32 characters.	[Conditionally Required if grantType is PASSWORD] Unique merchant api key distributed by EasyPaisa Open Platform.
extendInfo	String	No	Max. length: 4096 characters.	The extend information,wallet and merchant can put extend info here.

Response

Property	Data type	Required	Max length	Description
result	Result	Yes	–	The request result, which contains information related to the request result, such as status and error codes.
accessToken	String	No	Max. length: 128 characters.	An access token that can be used to access the user resource scope.When authorization application is successful [result.resultStatus == S], the auth client might use accessToken to acccess the corresponding user’s resource scope.
extendInfo	String	No	Max. length: 4096 characters.	The extend information,wallet and merchant can put extend info here.

Result

resultStatus	resultCode	resultMessage
S	SUCCESS	Success.
U	UNKNOWN_EXCEPTION	An API calling is failed, which is caused by unknown reasons.
U	REQUEST_TRAFFIC_EXCEED_LIMIT	The request traffic exceeds the limit.
F	PROCESS_FAIL	A general business failure occurred. Don’t retry.
F	PARAM_ILLEGAL	Illegal parameters exist. For example, a non-numeric input, or an invalid date.
F	ACCESS_DENIED	The access is denied.
F	UNSUPPORTED_GRANT_TYPE	The auth client do not support this grant type.
F	INVALID_API_KEY	The api key provided is invalid.

Result process logic

For different request results, different actions are to be performed. See the following list for details:

If the value of result.resultStatus is S, the merchant authentication request is successful. The merchant can use the access token to access the corresponding services.
If the value of result.resultStatus is F or U, please try again with correct api key.

Sample

Request

A. Retrieving accessToken with apiKey

				
					{
  "grantType": "PASSWORD",
  "apiKey": "2810111301lGZcM9CjlF91WH00039190xxxx",
}

apiKey is provided by the EasyPasia Open Platform.

Response

				
					{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"  
  },
  "accessToken": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",
}

result.resultStatus==S shows that the application is successful.
accessToken is the access token used for all subsequent call initiated by the merchant.

/v2/authentications/revokeToken

/v2/authentications
/revokeToken

POST /v2/authentications/revokeToken

The revokeToken API is used to cancel an access token. Merchant can expect to get a new access token via applyToken API after revoking the previous access token.

Message structure

Request

Property	Data type	Required	Description	Example
apiKey	String	No	The apiKey allocated for a merchant.Max. length: 128 characters.	“202016726873874774774xxxx”
extendInfo	String	No	The extend information. Wallets and merchants can put extending information in this property.Max. length: 4096 characters.	“This is additional information”

Response

Property	Data type	Required	Description	Example
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.	{ “resultCode”:”SUCCESS”, “resultStatus”:”S”, “resultMessage”:”success” }
extendInfo	String	No	The extend information. Wallets and merchants can put extending information in this property.Max. length: 4096 characters.	“This is additional information”

Result

resultStatus	resultCode	resultMessage
S	SUCCESS	Success.
U	UNKNOWN_EXCEPTION	An API calling is failed, which is caused by unknown reasons.
U	REQUEST_TRAFFIC_EXCEED_LIMIT	The request traffic exceeds the limit.
F	PROCESS_FAIL	A general business failure occurred. Don’t retry.
F	PARAM_ILLEGAL	Illegal parameters exist. For example, a non-numeric input, or an invalid date.
F	ACCESS_DENIED	The access is denied.
F	UNSUPPORTED_GRANT_TYPE	The auth client do not support this grant type.
F	INVALID_API_KEY	The api key provided is invalid.

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	The access token is revoked successfully.
U	The API status is unknown. It means access token has failed revoke, and you might want to retry again.
F	It means access token has failed revoke, and you might want to retry again or call our open platform operations team.

Sample

Request

				
					    {
        "apiKey": "2810111301lGZcM9CjlF91WH00039190xxxx",
    }

Response

				
					{"result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"}}

/v2/payments/createPayment

/v2/payments
/createPayment

POST /v2/payments/createPayment

The createPayment API is used to initiate a payment request to EasyPaisa backend.

The API support following payment mode:

Cashier Payment：This is currently the only supported payment mode. Mini App backend server should first create a transaction with this API before proceeding to prompt user for payment via JSAPI/my.createPayment

Message structure

Request

Property	Data type	Required	Description
merchantID	String	Yes	The unique merchant ID allocated by wallet. Max. length: 32 characters.
appID	String	No	The unique Mini App ID allocated by wallet. Max. length: 32 characters.
productCode	String	No	Wallet will use productCode to get the contract config which include fee, payment limit info. Max. length: 32 characters.
paymentOrderTitle	String	Yes	The order title of this payment. Max. length: 256 characters.
paymentOrderID	String	Yes	The unique ID of a payment generated by merchant. Max. length: 64 characters.This field is used for the idempotence control. For the payment requests which are initiated with the same paymentRequestId and reach a final status (S or F), the Issuing Participant must return the unique result.
paymentAmount	Amount	Yes	Order amount of the payment requested by merchant to wallet user
paymentMethods	PaymentMethod	No	[Reserved for future] The paymentMethod used to collect fund by wallet. i.e. online banking, credit card, wallet balance
paymentAuthCode	String	No	[Reserved for future] The authcode used for auto-debit transactions. i.e. subscription payment Max. length: 128 characters.
paymentToken	String	No	The token the user needs to pay [Note: this field is not required if the payment mode is a CASHIER, but is required if the payment mode is Agreement Pay]. Max. length: 128 characters.
msisdn	String	No	The user’s cell phone number.[Note: this field is not required if the payment mode is a CASHIER, but is required if the payment mode is Agreement Pay].Max. length: 20 characters.
paymentMode	PaymentMode	Yes	Currently only support Cashier Payment mode and Agreement Pay. The values are in enumeration `Agreement Pay` or `CASHIER`.
paymentFactor	paymentFactor	No	Currently only support Cashier Payment mode. The values are in enumeration `Agreement Pay` or `CASHIER`.
paymentExpiryTime	String/Datetime	No	The payment order close time defined by merchant, which follows the ISO 8601 standard. By default it’s closed in 90 minutes.
paymentReturnUrl	String	No	The redirect url defined by merchant after the payment is completed. i.e. redirect to order completion page after payment results. Max. length: 1024 characters.
paymentNotifyUrl	String	No	The payment status notify url defined by merchant. i.e. Used for post payment processes. Max retry 3 times. Max. length: 1024 characters.
merchantCategoryCode	String	No	The merchant category code. (ISO 18245). Max. length: 32 characters.
extendInfo	String	No	Extended information for extensibility, merchant could send extended information agreed with wallet in a pre-agreed format. Max. length: 4096 characters.
envInfo	EnvInfo	No	Environment information for risk strategies

Response

Property	Data type	Required	Description
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.
paymentTransactionID	String	No	The unique ID of a payment generated by Wallet.Max. length: 64 characters.
paymentCreateTime	String/Datetime	No	Payment creation time, which follows the ISO 8601 standard.
orderStatus	String	No	Payment status of merchant orders. Max. length: 20 characters. This is returned only in the Agreement Pay mode.
actionForm	ActionForm	No	The form to perform next action. Merchant could use this redirectURL to present a payment interface to the user in either EasyPaisa Mobile App(implemented) or Web Page(not yet implemented)
extendInfo	String	No	The extend information,wallet and merchant can put extend info here.Max. length: 4096 characters.

Result

resultStatus	resultCode	resultMessage
S	SUCCESS	Success.
U	UNKNOWN_EXCEPTION	An API calling is failed, which is caused by unknown reasons.
U	REQUEST_TRAFFIC_EXCEED_LIMIT	The request traffic exceeds the limit.
F	PROCESS_FAIL	A general business failure occurred. Don’t retry.
F	PARAM_ILLEGAL	Illegal parameters exist. For example, a non-numeric input, or an invalid date.
F	ACCESS_DENIED	The access is denied.
F	UNSUPPORTED_GRANT_TYPE	The auth client do not support this grant type.
F	INVALID_API_KEY	The api key provided is invalid.

Result process logic

For different request results, different actions are to be performed. See the following list for details:

result.resultStatus = S
That means this transaction is success, merchant/partner can update transaction to success. What need to notice is :
In payment evaluation scenario, ‘S’ just means evaluate success, no real fund transfer.
In authorization payment scenario, ‘S’ just means authorization success, need wait for capture operation to finish the transaction(finish final fund flow).
result.resultStatus = A
That means transaction already accept by wallet. Merchant/partner need continue the next step operation according to actionForm response. Such as display order code to user or redirect to wallet cashier page.
result.resultStatus = F
That means this transaction is failed, the failed reason can refer to result code param. Usually F transactions can not be success again if use the same payment request to call wallet.
result.resultStatus = U
That means unknown exception occur on wallet side. Merchant/partner can inquiry payment result or waiting for payment notification to get the real payment result. What need to notice is :
Payment evaluation scenario can not inquiry.
U status can not set to fail or success on merchant/partner system.
U status can not refund to user by offline(Maybe will make fund loss).

Result

resultStatus	resultCode	resultMessage
S	SUCCESS	Success.
U	UNKNOWN_EXCEPTION	An API calling is failed, which is caused by unknown reasons.
U	REQUEST_TRAFFIC_EXCEED_LIMIT	The request traffic exceeds the limit.
U	PAYMENT_IN_PROCESS	The payment is still under process.
A	ACCEPT	Need next action according to actionForm.
F	REPEAT_REQ_INCONSISTENT	Repeated submit, and requests are inconsistent.
F	PROCESS_FAIL	A general business failure occurred. Don’t retry.
F	INVALID_API	The called API is invalid or not active.
F	PARAM_ILLEGAL	Illegal parameters exist. For example, a non-numeric input, or an invalid date.
F	ACCESS_DENIED	The access is denied.
F	PAYMENT_AMOUNT_EXCEED_LIMIT	Payment amount exceeds limit.
F	USER_NOT_EXIST	User not exist.
F	USER_STATUS_ABNORMAL	The user status is abnormal.
F	USER_BALANCE_NOT_ENOUGH	User balance is not enough for this payment.
F	PARTNER_NOT_EXIST	Partner not exist.
F	PARTNER_STATUS_ABNORMAL	Partner status abnormal.
F	RISK_REJECT	Risk reject.
F	CURRENCY_NOT_SUPPORT	The currency is not supported.
F	ORDER_STATUS_INVALID	Order is in invalid status such closed.
F	INVALID_ACCESS_TOKEN	Invalid accesstoken.
F	USER_AMOUNT_EXCEED_LIMIT	Payment amount exceeds user’s amount limit.
F	EXPIRED_ACCESS_TOKEN	The access token is expired.
F	AUTH_CODE_ALREADY_USED	Auth code already used.
F	INVALID_CODE	Auth code illegal.
F	EXPIRED_AGENT_TOKEN	The access token of mini program is expired.
F	INVALID_AGENT_TOKEN	The access token of mini program is invalid.

Sample

Cashier Payment

Request

				
					{"merchantID":"travel_merchant","appID":"travel_merchant_appID_demo","productCode":"PC_5800000001","paymentOrderTitle":"ApiTesting-Order1","paymentOrderID":"210508000000010","paymentAmount":{"currency":"PKR","value":"167"},"paymentFactor":{"isCashierPayment":true},"paymentReturnUrl":"https:\/\/www.merchant.com\/redirectxxx","paymentNotifyUrl":"https:\/\/www.merchant.com\/paymentNotifyxxx","extendInfo":"{\"customerBelongsTo\":\"siteNameExample\"}","envInfo":{"osType":"IOS","terminalType":"APP"}}

merchantID is the identifier of a merchant/partner, allocated by Wallet.
paymentOrderID is generated by merchant/partner, uniquely identifies the payment. Wallet must make use of paymentOrderID and merchantID for idempotent control. For example, if a payment with paymentOrderID== 2019112719074101000700000077771xxxx and merchantID==P000000000000001xxxx has been processed successfully by Wallet, when merchant/partner* *uses the same paymentOrderID and paymentOrderID for payment, Wallet will respond with successful payment.
productCode defined by wallet, wallet will use productCode to get the contract config which include fee,limit info.
paymentFactor In the Mini App scenario, the PaymentFactor only have the fixed value: isCashierPayment = true
paymentReturnUrl is the url defined by merchant/partner. In cashier payment scenario, after user finished payment in wallet cashier page, wallet will direct back to merchant base on this URL.
paymentNotifyUrl is the url defined by merchant/partner. In cashier payment scenario, after user finished payment in wallet cashier page, wallet will notify merchant the payment result base on this URL.
paymentAmount describes the amount of 100 PKR to be collected by Wallet from user account for this payment.
extendInfo, includes key – customerBelongsTo the e-wallet that the customer uses. Corresponding to the field ‘siteName’ that obtained from the API ‘my.getSiteInfo’, in the Mini Program scenario this is mandatory.

Response

				
					{"paymentTransactionID":"20210518155958063517","paymentCreateTime":"2021-05-18T15:59:58.093","result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"}}

result.resultStatus ==A shows that the payment is accept success. After user finish payment in cashier page, payment will change to success.
paymentTransactionID is generated by Wallet, uniquely identifies the payment.
actionForm will return cashier page url to merchant/partner, after merchant/partner received accept result, will redirect to this URL.

Result process logic

For different request results, different actions are to be performed. See the following list for details:

If the value of result.resultStatus is S, will return “orderStatus” , “paymentTransactionID” and “paymentCreateTime” in the ResponseBody .
If the value of result.resultStatus is F or U, please try again with correct api key.

Cashier Payment

Request

				
					{"merchantID":"grocers_merchant","appID":"grocers","paymentOrderTitle":"ApiTesting-Order","paymentMode":"Agreement Pay","paymentOrderID":"8395629385","paymentAmount":{"currency":"PKR","value":"10"},"paymentToken":"0000003051","msisdn":"03467242892","paymentReturnUrl":"https:\/\/www.merchant.com\/redirectxxx","paymentNotifyUrl":"https:\/\/www.merchant.com\/paymentNotifyxxx","extendInfo":"{\"customerBelongsTo\":\"siteNameExample\"}","envInfo":{"osType":"IOS","terminalType":"APP"}}

Response

resultStatus == S

				
					{"orderStatus":"S","paymentTransactionID":"3278910","paymentCreateTime":"2021-07-26T15:59:58.093","result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"}}

/v2/payments/queryPayment

/v2/payments
/queryPayment

POST /v2/payments/queryPayment

The inquirePayment API is used to inquire the payment result, usually when merchants are not able to receive the payment result after a long period of time.

Note:

After the merchant initiates payment, when the merchant is not able to receive the payment result after a long period of time, it can poll Payment Inquiry interface.
The merchant uses the inquirePayment API to determine the Payment status in the asynchronous Payment processing scenario.
Round-robin interval, recommended once every 5 seconds, up to 30 seconds. Be aware that exccessively polling on this API interface might result in blocking of your API traffic completely

Message structure

Request

Property	Data type	Required	Description	Example
paymentOrderID	String	No	[Conditionally required either paymentOrderID or paymentTransactionID] The unqiue ID of a payment generated by Merchant .Max. length: 64 characters.	“20312172123000019xxxx”
paymentTransactionID	String	No	[Conditionally required either paymentOrderID or paymentTransactionID] The unqiue ID of a payment generated by Wallet.Max. length: 64 characters.	“1022172000000000001xxxx”
extendInfo	String	No	The extend information, wallets and merchants can put extending information in this property.Max. length: 4096 characters.	“This is additional information”

Response

Property	Data type	Required	Description	Example
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.	{ “resultCode”:”SUCCESS”, “resultStatus”:”S”, “resultMessage”:”success” }
paymentTransactionID	String	No	The unqiue ID of a payment generated by Wallet.Max. length: 64 characters.	“20312172123000019xxxx”
paymentOrderID	String	No	The unqiue ID of a payment generated by Merchant.Max. length: 64 characters.	“20200101234567890133333xxxx”
paymentAmount	Amount	No	Order amount for display of user consumption records, payment results page.	{ “value”:”100″, “currency”:”PKR” }
paymentTime	String/Datetime	No	Payment success time, which follows the ISO 8601 standard.	“2020-01-01T12:01:01+08:30”
paymentCreateTime	String/Datetime	No	Payment creation time, which follows the ISO 8601 standard.	“2020-01-01T11:01:01+08:30”
paymentStatus	String	No	SUCCESS – order is succeeded.FAIL – order is failed.PROCESSING – order is not paid or is paid but not finish.CANCELLED – order is cancelled.	“SUCCESS”
paymentResultCode	String	No	The payment result code.Max. length: 64 characters.	“S”
paymentResultMessage	String	No	The payment result message.Max. length: 256 characters.	“Pay Successfully”
extendInfo	String	No	The extensive information. The wallet and merchant can put extensive information in this property.Max. length: 4096 characters.	“This is additional information”

Result Process Logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	The corresponding result.resultCode is “SUCCESS” and the result.resultMessage is “Success”.It means that the payment inquiry is successful, then check the paymentStatus field:if paymentStatus is PROCESSING, it means that the order is not paid or is paid but not finish.if paymentStatus is SUCCESS, it means that the order succeeds.if paymentStatus is FAIL, it means that the order is failed.if paymentStatus is CANCELLED, it means that the order is cancelled.
A	The corresponding result.resultCode is “ACCEPT”; and the result.resultMessage varies based on different situations.
U	The corresponding result.resultCode is “UNKNOWN_EXCEPTION” and result.resultMessage is “An API calling is failed, which is caused by unknown reasons.”. For details, see the Common error codes section. It means that unknown exception occurs on the wallet side. The merchant/partner can try again.
F	The corresponding result.resultCode and result.resultMessage vary based on different situations. For details, see the following Error codes section. It means that the payment inquiry is failed. When resultCode is ORDER_NOT_EXIST, it means that the payment is not yet accepted and can be treated as payment failure. For the other failure reasons, human intervention is recommended.

Error codes

Error codes are usually classified into the following categories:

Common error codes: are common for all Mini Program OpenAPIs.
API-specific error codes: are listed in the following table.

resultStatus	resultCode	resultMessage
F	ORDER_NOT_EXIST	The order does not exist.
F	EXPIRED_AGENT_TOKEN	The agent token of Mini Program is expired.
F	INVALID_AGENT_TOKEN	The agent token of Mini Program is invalid.

Sample

Example: A user bought a 100 PKR product on the e-commerce platform, paid by balance and submitted the payment synchronously, asynchronous polling payment results.

Request

A. Inquiry By paymentRequestId

				
					{"paymentTransactionID":"1022172000000000001xxxx"}

B. Inquiry By paymentId

				
					{"paymentOrderID":"20312172123000019xxxx"}

paymentTransactionID the unique Id of a payment generated by Wallet.
paymentOrderID the unique Id of a payment generated by Merchant.

Note:

This interface support querying with paymentTransactionID or paymentOrderID.
paymentTransactionID has a higher priority than paymentOrderID, which means that if you offer both paymentTransactionID and paymentOrderID, we will use paymentTransactionID and ignore paymentOrderID.

Response

				
					{"result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"},"paymentTransactionID":"20200101234567890133333xxxx","paymentOrderID":"20200101234567890133333xxxx","paymentTime":"2020-01-01T12:01:01+08:30","paymentAmount":{"value":"100","currency":"PKR"},"paymentStatus":"SUCCESS","paymentResultCode":"S","paymentResultMessage":"Paid Successfully"}

result.resultStatus==S shows that the inquiry is successful.
paymentTransactionID the unique Id of a payment generated by Wallet.
paymentOrderID the unique Id of a payment generated by Merchant.
paymentTime describes the date time of the successful Wallet payment.
paymentAmount describes the payment amount.
paymentStatus describes the payment status.
- paymentStatus.PROCESSING order is not paid or is paid but not finish.
- paymentStatus.SUCCESS order is succeeded.
- paymentStatus.FAIL order is failed.
- paymentStatus.CANCELLED order is cancelled.

Sample

Cashier Payment

Request

				
					{"merchantID":"travel_merchant","appID":"travel_merchant_appID_demo","productCode":"PC_5800000001","paymentOrderTitle":"ApiTesting-Order1","paymentOrderID":"210508000000010","paymentAmount":{"currency":"PKR","value":"167"},"paymentFactor":{"isCashierPayment":true},"paymentReturnUrl":"https:\/\/www.merchant.com\/redirectxxx","paymentNotifyUrl":"https:\/\/www.merchant.com\/paymentNotifyxxx","extendInfo":"{\"customerBelongsTo\":\"siteNameExample\"}","envInfo":{"osType":"IOS","terminalType":"APP"}}

merchantID is the identifier of a merchant/partner, allocated by Wallet.
paymentOrderID is generated by merchant/partner, uniquely identifies the payment. Wallet must make use of paymentOrderID and merchantID for idempotent control. For example, if a payment with paymentOrderID== 2019112719074101000700000077771xxxx and merchantID==P000000000000001xxxx has been processed successfully by Wallet, when merchant/partner* *uses the same paymentOrderID and paymentOrderID for payment, Wallet will respond with successful payment.
productCode defined by wallet, wallet will use productCode to get the contract config which include fee,limit info.
paymentFactor In the Mini App scenario, the PaymentFactor only have the fixed value: isCashierPayment = true
paymentReturnUrl is the url defined by merchant/partner. In cashier payment scenario, after user finished payment in wallet cashier page, wallet will direct back to merchant base on this URL.
paymentNotifyUrl is the url defined by merchant/partner. In cashier payment scenario, after user finished payment in wallet cashier page, wallet will notify merchant the payment result base on this URL.
paymentAmount describes the amount of 100 PKR to be collected by Wallet from user account for this payment.
extendInfo, includes key – customerBelongsTo the e-wallet that the customer uses. Corresponding to the field ‘siteName’ that obtained from the API ‘my.getSiteInfo’, in the Mini Program scenario this is mandatory.

Response

				
					{"paymentTransactionID":"20210518155958063517","paymentCreateTime":"2021-05-18T15:59:58.093","result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"}}

result.resultStatus ==A shows that the payment is accept success. After user finish payment in cashier page, payment will change to success.
paymentTransactionID is generated by Wallet, uniquely identifies the payment.
actionForm will return cashier page url to merchant/partner, after merchant/partner received accept result, will redirect to this URL.

Result process logic

For different request results, different actions are to be performed. See the following list for details:

If the value of result.resultStatus is S, will return “orderStatus” , “paymentTransactionID” and “paymentCreateTime” in the ResponseBody .
If the value of result.resultStatus is F or U, please try again with correct api key.

Cashier Payment

Request

				
					{"merchantID":"grocers_merchant","appID":"grocers","paymentOrderTitle":"ApiTesting-Order","paymentMode":"Agreement Pay","paymentOrderID":"8395629385","paymentAmount":{"currency":"PKR","value":"10"},"paymentToken":"0000003051","msisdn":"03467242892","paymentReturnUrl":"https:\/\/www.merchant.com\/redirectxxx","paymentNotifyUrl":"https:\/\/www.merchant.com\/paymentNotifyxxx","extendInfo":"{\"customerBelongsTo\":\"siteNameExample\"}","envInfo":{"osType":"IOS","terminalType":"APP"}}

Response

resultStatus == S

				
					{"orderStatus":"S","paymentTransactionID":"3278910","paymentCreateTime":"2021-07-26T15:59:58.093","result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"}}

/v2/users/inquireUserInfo

/v2/users
/inquireUserInfo

POST /v2/users/inquireUserInfo

The inquireUserInfo API is used for the merchant to get the user related information after obtaining user authorization.

Sample

Query user information via an authCode. The authCode is generated via OAuth after authorization is successful.

Merchant calls this interface with authCode (Step 1)
Easypaisa server returns user information the to merchant based on the authCode (Step 2).

Request sample

				
					    {
          "authCode": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",  
    }

Response sample

				
					{"result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"},"userInfo":{"openId":"1000001119398804xxxx","unionId":"123440001119398804xxxx","userMsisdn":"931116874199xxx","userName":"jack","avatar":"http:\/\/example.com\/avatar.htm?avatarId=FBF16F91-28FB-47EC-B9BE-27B285C23CD3xxxx","userAddress":"XX city X street","userCnic":"145125123452142234","extendInfo":"[]"}}

Structure

Request

Property	Data type	Required	Description	Example
authCode	String (128)	Yes	An auth code that can be used to access the user resource scope.	“281010033AB2F588D14B43238637264FCA5AAF35xxxx”
extendInfo	String (4096)	No	the extend information. Wallets and merchants can put extending information in this property.	“This is additional information”

Response

Property	Data type	Required	Description	Example
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.	{ “resultCode”:”SUCCESS”, “resultStatus”:”S”, “resultMessage”:”success” }
userInfo	User	No	User open information.	{ “userId”: “1000001119398804xxxx”, “status”: “ACTIVE”, “nickName”: “Jack”, “userName”: { “fullName”: “Jack Sparrow”, “firstName”: “Jack”, “lastName”: “Sparrow” }, “avatar”: “http://example.com/avatar.htm?avatarId=FBF16F91-28FB-47EC-B9BE-27B285C23CD3xxxx”, “gender”: “MALE”, “birthDate”: “2020-07-25”, “nationality”: “US”, “loginIdInfos”: [ { “loginId”: “1116874199xxx”, “loginIdType”: “MOBILE_PHONE” } ], “contactInfos”: [ { “contactNo”: “1116874199xxx”, “contactType”: “MOBILE_PHONE” } ], “extendInfo”: “{}” }

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	It means user information inquiry is successful, merchant can use the auth code to access the corresponding user resource scope.The corresponding result.resultCode is “SUCCESS” and the result.resultMessage is “Success”.
U	The API status is unknown. AuthClient may guide user to try again.The corresponding result.resultCode is “UNKNOWN_EXCEPTION” and result.resultMessage is “An API calling is failed, which is caused by unknown reasons.”.
F	It means that user information inquiry is failed. The corresponding result.resultCode and result.resultMessage vary based on different situations.

Error codes

Error codes are usually classified into the following categories:

Common error codes: are common for all Mini Program OpenAPIs.
API-specific error codes: are listed in the following table.

resultStatus	resultCode	resultMessage
F	INVALID_AUTH_CODE	The auth code is invalid.
F	INVALID_AUTH_CLIENT	The auth client id is invalid.
F	EXPIRED_AUTH_CODE	The auth code is expired.
F	EXPIRED_AGENT_TOKEN	The agent token of mini program is expired.
F	INVALID_AGENT_TOKEN	The agent token of mini program is invalid.

/v2/promotions/createCashback

/v2/promotions
/createCashback

Cashback

POST /v2/promotions/createCashback The createCashback interface is used to apply for a cashback request for a specific user.

Message structure

Request

Field	Type	Required	Constrains	Description
msisdn	String	Yes	Max length: 64	User msisdn（mobile number）
cashbackOrderID	String	Yes	Max length: 64	The unique ID of a cashback generated by merchant.
cashbackCreateTime	String/Datetime	Yes		Time of trigger event occurring, which follows the ISO8601 standard.
campaignID	String	Yes		Campaign id
cashbackAmount	Amount	Yes		Amount of cashback from merchant to wallet user.
cashbackExpiryTime	String/Datetime	No		[Reserved for Future]The cashback order close time defined by merchant. By default, applications from non-Easypaisa user will not be accepted. which follows the ISO8601 standard.
extendInfo	String	No	Max. length: 4096 characters.	Extended information for extensibility, merchant could send extended information agreed with Easypaisa in a pre-agreed format.
envInfo	EnvInfo	No	Environment information for risk strategies

Response

Property	Data type	Required	Description
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.
cashbackTransactionID	String	No	The unique ID of a cashback generated by Wallet.
cashbackTime	String/Datetime	No	Cashback success time.
redirectUrl	String	No	The Url redirect is to guide the user to download the Easypaisa App and complete the cashback process.When the returnStatus is A, this field will be returned
extendInfo	String	No	The extend information,wallet and merchant can put extend info here.Max. length: 4096 characters.

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

Field	Type	Required	Constrains	Description
msisdn	String	Yes	Max length: 64	User msisdn（mobile number）
cashbackOrderID	String	Yes	Max length: 64	The unique ID of a cashback generated by merchant.
cashbackCreateTime	String/Datetime	Yes		Time of trigger event occurring, which follows the ISO8601 standard.
campaignID	String	Yes		Campaign id
cashbackAmount	Amount	Yes		Amount of cashback from merchant to wallet user.
cashbackExpiryTime	String/Datetime	No		[Reserved for Future]The cashback order close time defined by merchant. By default, applications from non-Easypaisa user will not be accepted. which follows the ISO8601 standard.
extendInfo	String	No	Max. length: 4096 characters.	Extended information for extensibility, merchant could send extended information agreed with Easypaisa in a pre-agreed format.
envInfo	EnvInfo	No	Environment information for risk strategies

Sample

1, Merchant calls this interface (Step 1) 2, Easypaisa add money to user account or wait for user to register 3, Response result

Example

				
					Request = {
  "msisdn": "03455000001",
  "cashbackOrderID": "LCHLC2530159581919051701",
  "cashbackCreateTime": "2021-05-21T12:12:12.253+05:00",
  "cashbackExpiryTime": "2021-05-21T12:12:12.253+05:00",
  "cashbackAmount": {
      "currency": "PKR",
      "value": "100"
  },
  "campaignID": "CAMPAIGN20210521000000050321",
  "extendInfo": "{\"merchantInfo\":\"merchant name\"}"

}

				
					Result = {
    "cashbackTransactionID":"210521115113000001",
    "cashbackOrderID":"LCHLC2530159581919051701",
    "cashbackTime":"2021-05-21T12:12:13.253+05:00",
    "redirectUrl":"https://easypaisa.activ8.digital/how-easypaisa-works/?cashbackOrderId\u003dLCHLC2530159581919051701",
    "result":{
        "resultCode":"SUCCESS",
        "resultStatus":"S",
        "resultMessage":"success"
    }
}

/v2/promotions/inquireCashback

Cashback

POST /v2/promotions/inquireCashback The inquireCashback is used to inquire about the latest status of a cashback order.

Message structure

Request

Field	Type	Required	Constrains	Description
cashbackOrderID	String	No	Max length: 64	The unique ID of a cashback generated by merchant.
cashbackTransactionID	String	No	Max length: 64	The unique ID of a cashback generated by Wallet.
extendInfo	String	No	Max. length: 4096 characters.	Extended information for extensibility, merchant could send extended information agreed with Easypaisa in a pre-agreed format.

Response

Property	Data type	Required	Description
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.
cashbackStatus	String	No	The latest status about this cashback order.
cashbackOrderID	String	No	The unique ID of a cashback generated by merchant.
cashbackTransactionID	String	No	The unique ID of a cashback generated by Wallet.
cashbackTime	String/Datetime	No	Cashback success time.
cashbackResultMessage	String	No	The cashback result message. Max.length:256 characters.
extendInfo	String	No	The extend information,wallet and merchant can put extend info here.Max. length: 4096 characters.

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	It means cashback successful.The corresponding result.resultCode is “SUCCESS” and the result.resultMessage is “Success”.
A	The corresponding `result.resultCode` is “ACCEPT”; That means that the cashback is already accepted by Easypaisa. The merchant needs to redirect the user to the `redirectUrl` page and guide the user to complete the cashback process. Return `A`is because the user has not registered the wallet yet, then the user needs to download and register the wallet before `cashbackExpiryTime` and then wallet will automatically send the cashback to the user’s account. Cashback transactions will be cancelled if the `cashbackExpiryTime` is exceeded.
U	The API status is unknown. The corresponding result.resultCode is “UNKNOWN_EXCEPTION” and result.resultMessage is “An API calling is failed, which is caused by unknown reasons.”
F	It means cashback is failed. The corresponding result.resultCode and result.resultMessage vary based on different situations.

Sample

				
					Request = {
  "cashbackOrderID": "4a68a2db8c4d720b5080166a68269e96",
  "extendInfo": {}
}

				
					Result = {
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  },
  "cashbackStatus" : "SUCCESS",
  "cashbackOrderID" : "34t2f23d23a5345324523",
  "cashbackTransactionID":"34t2f23d23a5d5adf6d6asd6asd6d6a",
  "cashbackTime" : "2021-04-06 00:00:00",
  "cashbackResultMessage": "Cashback Successfully",
}

result.resultStatus==S shows that the inquiry is successful.

cashbackOrderID the unique Id of a cashback generated by merchant.

cashbackTransactionID the unique Id of a cashback generated by wallet.

cashbackTime describes the date time of the successful wallet cashback.

cashbackResultMessage describes the cashback result message.

cashbackStatus describes the cashback status.

cashbackStatus.PROCESSING order are being processed or waiting for user registration.

cashbackStatus.SUCCESS cashback order is succeeded.

cashbackStatus.FAIL cashback order is failed.

cashbackStatus.EXPIRED cashback order is expired.

/v2/authorizations/getPaymentAuthCode

/v2/authorizations
/getPaymentAuthCode

POST /v2/authorizations/getPaymentAuthCode

The first step in the binding process is to get a auth url through this api, which can be used to jump to the Easypaisa APP or open an H5 signing page.

Message structure

Request

Property	Data type	Required	Max length	Description
authRedirectUrl	String	Yes	–	After signing up, you can jump back to Daraz by this url.
scopes	String Array	Yes	–	Authorization scopes. Valid values are [AGREEMENT_PAY]
authState	String	Yes	Max. length: 32 characters.	Authorization statement that is generated by the AuthClient binding unique id .
envInfo	EnvInfo	Yes	Max. length: 4096 characters.	Environment info.
extendInfo	String	No	Max. length: 4096 characters.	The extend information.

Response

Property	Data type	Required	Max length	Description
result	Result	Yes	–	The request result, which contains information related to the request result, such as status and error codes.
authUrl	String	No	Max. length: 32 characters.	Return when resultStatus is A. Url for redirection to H5 middle page.
paymentAuthCode	String	No	Max. length: 32 characters.	Return when resultStatus is S. A temporary code generated for getPaymentToken.

Result

resultStatus	resultCode	resultMessage
S	SUCCESS	Success.
A	ACCEPT	Need next action according to actionForm.
U	UNKNOWN_EXCEPTION	An API calling is failed, which is caused by unknown reasons.
F	PROCESS_FAIL	A general business failure occurred. Don’t retry.
F	PARAM_ILLEGAL	Illegal parameters exist. For example, a non-numeric input, or an invalid date.
F	AUTHSTATE_ILLEGAL	The authState is invalid.
F	REPEAT_REQ_INCONSISTENT	Repeated requests are inconsistent.
F	TOKEN_GENERATED	The paymentToken already generated.
F	SCOPE_NOT_SUPPORT	This scope not support for yet.
F	EXPIRED_AUTHORIZATION	Authorization belong to this authState already expired.

Result process logic

For different request results, different actions are to be performed. See the following list for details:

If the value of result.resultStatus is S, will return “paymentAuthCode” in the ResponseBody. The merchant can use the “paymentAuthCode” to apply “paymentToken”.

If the value of result.resultStatus is A, will return “authUrl” in the ResponseBody. The merchant can use the “authUrl” to open sign agreement page.

If the value of result.resultStatus is F or U, please try again with correct api key.

Sample

Request

				
					{"appID":"GDC_agreement_pay","authRedirectUrl":"http:\/\/xxx.com","scopes":["AGREEMENT_PAY"],"authState":"testAuthState","envInfo":{"terminalType":"APP","osType":"ANDROID","osVersion":"10","userAgent":"Mozilla\/5.0 (Windows NT 10.0; Win64; x64)"}}

Response

resultStatus == A

authUrl is the Url for redirection to H5 middle page.

				
					{"authUrl":"http:\/\/deploy.urenw.com\/ep\/deeplink\/test.html?authid=F6BAFE930D1D4B75AB76978C1A4A10D7","result":{"resultCode":"ACCEPT","resultStatus":"A","resultMessage":"Need next action according to actionForm."}}

resultStatus == S

paymentAuthCode is the temporary code generated for getPaymentToken.

				
					{"paymentAuthCode":"20210726110410000000000923746688","result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"}}

/v2/authorizations/queryPaymentAuthCode

/v2/authorizations
/queryPaymentAuthCode

POST /v2/authorizations/queryPaymentAuthCode

Query the paymentAuthCode generation result and status via this API.

Message structure

Request

Property	Data type	Required	Max length	Description
scopes	String Array	Yes	–	Authorization scopes. Valid values are [AGREEMENT_PAY]
authState	String	Yes	Max. length: 32 characters.	Authorization statement that is generated by the AuthClient binding unique id .

Response

Property	Data type	Required	Max length	Description
result	Result	Yes	–	The request result, which contains information related to the request result, such as status and error codes.
status	String	Yes	–	Current status of paymentAuthCode.
paymentAuthCode	String	No	Max. length: 32 characters.	The value of paymentAuthCode.

Result

resultStatus	resultCode	resultMessage
S	SUCCESS	Success.
U	UNKNOWN_EXCEPTION	An API calling is failed, which is caused by unknown reasons.
F	PROCESS_FAIL	A general business failure occurred. Don’t retry.
F	PARAM_ILLEGAL	Illegal parameters exist. For example, a non-numeric input, or an invalid date.
F	AUTHSTATE_ILLEGAL	The authState is invalid.
F	SCOPE_NOT_SUPPORT	This scope not support for yet.
F	EXPIRED_AUTHORIZATION	Authorization belong to this authState already expired.

Result

Status	Comment
INIT	Initialization status, paymentAuthCode has not been generated and the paymentAuthCode value should be empty.
GENERATED	paymentAuthCode has been generated.
USED	paymentAuthCode has already been used.
EXPIRED	paymentAuthCode has expired.

Sample

Request

				
					{"authState":"testAuthState","appId":"GDC_agreement_pay","scopes":["AGREEMENT_PAY"]}

Response

				
					{"paymentAuthCode":"20210726110410000000000923746688","status":"GENERATED","result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"}}

/v2/authorizations/getPaymentToken

/v2/authorizations/get
PaymentToken

POST /v2/authorizations/getPaymentToken

Get the PaymentToken through the paymentAuthCode so that the payment process can initiate the payment with PaymentToken .

Request

Property	Data type	Required	Max length	Description
paymentAuthCode	String	Yes	64 characters	Get the PaymentToken through the PaymentAuthCode [Conditionally Required if grantType is AUTHORIZATION_CODE]
grantType	String Array	Yes	64 characters	Authorization scopes. Valid values are [AGREEMENT_PAY]
extendInfo	String	No	Max. length: 4096 characters.	The extend information.

Response

Property	Data type	Required	Max length	Description
result	Result	Yes	–	Request common message.
paymentToken	String	Yes	–	Access payment token. token to be stored.
msisdn	String	Yes	–	EP User msisdn.
extendInfo	String	No	–	The extend information.

Result

resultStatus	resultCode	resultMessage
S	SUCCESS	Success.
F	PARAM_ILLEGAL	Illegal parameters exist. For example, paymentAuthCode is null.
F	GRANTTYPE_NOT_SUPPORT	Grant type not support reasons.
F	PAYMENT_AUTH_CODE_INVALID	PaymentAuthCode is invalid.
F	PAYMENT_AUTH_CODE_EXPIRED	PaymentAuthCode already expired.
F	UNKNOWN_EXCEPTION	An API calling is failed, which is caused by unknown reasons.

Note: If a merchant does not get the PaymentToken due to a special exception during the getPaymentToken Api request (e.g. network outage, etc.), the merchant can call the getPaymentToken Api repeatedly within a certain period of time to get the PaymentToken (this period is 30 minutes by default).

Sample

Request

				
					{"paymentAuthCode":"123456","grantType":["AGREEMENT_PAY"],"extendInfo":""}

Response

resultStatus == S

				
					{"paymentToken":"31241241253reqwfsa231as","msisdn":"17723235555","result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"Success."}}

/v2/payments/preCheck

/v2/payments
/preCheck

POST /v2/payments/preCheck

The preCheck API is used when the user will perform payment checks before making a payment. If the balance is enough to pay, the payment can be made; if the balance is insufficient, the payment cannot be made.

Message structure

Request

Property	Data type	Required	Description	Example
mobileAccountNo	String	Y	User phone number . The Mobile Numbers passed must be 11 digits in length and must start with 03.	“03xxxxxxxxx”
paymentAmount	Amount	Y	Order amount of the payment requested by merchant to wallet user.	{ “value”:”100″, “currency”:”PKR” }
paymentToken	String	Y	The token the user needs to pay. Max. length: 64 characters.	“XCGNhuy”
paymentOrderTitle	String	Y	The order title of this payment. Max. length: 128 characters.	“ASUS ZenBook Pro Duo 15 OLED UX582”
paymentOrderID	String	N	The unique ID of a payment generated by merchant. This field is used for the idempotence control. For the payment requests which are initiated with the same paymentRequestId and reach a final status (S or F), the Issuing Participant must return the unique result. Max. length: 64 characters.	“ABC-01”
extendInfo	String	N	The extend information,wallet and merchant can put extend info here. Max. length: 4096 characters.	“This is additional information”

Response

Property	Data type	Required	Description	Example
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.	{ “resultCode”:”SUCCESS”, “resultStatus”:”S”, “resultMessage”:”success” }
preCheckReusltCode	String	No	The check reuslt code before payment.Max. length: 64 characters.	“003”
preCheckResultMessage	String	No	The check reuslt message before payment.Max. length: 256 characters.	“Insufficient Balance”
extendInfo	String	No	The extensive information. The wallet and merchant can put extensive information in this property.Max. length: 4096 characters.	“This is additional information”

Result Process Logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	The corresponding result.resultCode is “SUCCESS” and the result.resultMessage is “Success”.It means that the pre check payment is successful.
U	An API calling is failed, which is caused by unknown reasons.
F	The corresponding result.resultCode and result.resultMessage vary based on different situations. For details, see the following Error codes section. It means that the pre check payment is failed.

Error codes

Error codes are usually classified into the following categories:

API-specific error codes: are listed in the following table.

resultStatus	resultCode	resultMessage
F	INVALID_MERCHANT	The merchant does not exist.
F	OPS_STORE_ID_IS_NULL	Ops store id is null
F	MINIAPP_PRECHECK_ERR	This result message comes from OPS
F	ILLEGAL_PAYMENT_TOKEN	Invalid paymentToken
F	ILLEGAL_ORDER_ID	Invalid orderID
F	ILLEGAL_MOBILE_ACCOUNT_NO	Invalid mobile account NO
F	ILLEGAL_PAYMENT_AMOUNT_RSP_DTO	MiniApp preCheck process is error

Sample

Example: A user checks whether the user can use EP payment before selecting the payment method after selecting the product.

Example

				
					Request = {
  "mobileAccountNo": "03453101535",
  "paymentToken": "XCGNhuy",
  "paymentOrderTitle": "ASUS ZenBook Pro Duo 15 OLED UX582",
  "paymentOrderID": "ABC-01",
  "paymentAmount": { 
      "value":"100",  
      "currency":"PKR"
  },
  "extendInfo": {}
}

mobileAccountNo User phone number .
paymentToken The token the user needs to pay.
paymentOrderTitle The order title of this payment.
paymentOrderID The unique ID of a payment generated by merchant. This field is used for the idempotence control. For the payment requests which are initiated with the same paymentRequestId and reach a final status (S or F), the Issuing Participant must return the unique result.
paymentAmount Order amount of the payment requested by merchant to wallet user.
extendInfo The extend information,wallet and merchant can put extend info here.

				
					Result = {
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  },
 "preCheckReusltCode": "003",
 "preCheckResultMessage": "Insufficient Balance"
}

result.resultStatus==S shows that the preCheck is successful.
preCheckReusltCode The check reuslt code before payment.
preCheckResultMessage The check reuslt message before payment.

preCheckReusltCode	preCheckResultMessage
0000	Success
0001	System Error
0002	Required Field Missing
0003	Invalid Mobile Number
0004	Invalid Store
0005	Invalid Amount
0006	Invalid Token
0007	Invalid Signature
0008	Bad Credentials
0009	Account does not exist
0010	Account is inactive
0011	Store Not Active
0012	Pinless Not Enabled
0013	Expired Token
0014	Insufficient Balance
0015	Key Not Uploaded

/v2/refund/merchantRefund

/v2/refund
/merchantRefund

POST /v2/refund/merchantRefund

When a user initiates a refund request, the OPS interface is called through the API to complete the refund request

Message structure

Request

Property	Data type	Required	Max length	Description
merchantID	String	Yes	Max length: 32 characters..	The unique merchant ID allocated by wallet.
paymentOrderID	String Array	Yes	Max length: 32	Order reference number generated by the merchant
orderDate	Char	Yes		MDate on which order was placed.
refundAmount	Numeric	Yes	Max value is“999,999.99”	Total amount to be reversed .
refundReason	String	No	Max. length: 4096 characters	Reasons for the refund.
extendInfo	String	No	Max. length: 4096 characters.	The extend information.

Response

Property	Data type	Required	Max length	Description
result	Result	Yes	–	The request result, which contains information related to the request result, such as status and error codes.

Result

resultStatus	resultCode	resultMessage
S	SUCCESS	Success.
U	UNKNOWN_EXCEPTION	An API calling is failed, which is caused by unknown reasons.
F	PARAM_ILLEGAL	Illegal parameters exist. For example, a non-numeric input, or an invalid date.

Error codes

Error codes are usually classified into the following categories:

API-specific error codes: are listed in the following table.

resultStatus	resultCode	resultMessage
F	PARAM_ILLEGAL	Illegal parameter.
F	ILLEGAL_ORDER_ID	Invalid orderID
F	ILLEGAL_REFUND_AMOUNT	Invalid refundAmount

Sample

Request

				
					{"merchantID":"123644","paymentOrderID":"117233","refundAmount":"3.2","refundDate":"2021-07-21","refundReason":"Taken more"}

Response

resultStatus == S

				
					{"result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"}}

/v2/risk/OTPSend

POST /v2/risk/OTPSend

This API is provide for merchant send OTP validation to the customer.

Message structure

Request

Property	Data type	Required	Max length	Description
msisdn	String	Yes	11	Customer’s mobile phone number.
eventType	String	Yes	64	The type of event. Fixed: PAYMENT

Response

Property	Data type	Required	Max length	Description
result	Result	Yes	–	The request result, which contains information related to the request result, such as status and error codes.
verifyRequestId	String	Yes	–	To verify, carry the verifyRequestId with the request.
remainSendTimes	String	No	–	The remain send times of current OTP verify process.

Result

resultStatus	resultCode	resultMessage
S	SUCCESS	Success.
F	PARAM_VALID_FAIL	The request param valid failed.
F	REACHED_SEND_TIMES_LIMIT	The number of OTPSend requests exceeded the limit.
F	REQUEST_TOO_OFTEN	The request send too often.
U	UNKNOWN_EXCEPTION	An API calling is failed, which is caused by unknown reasons.

Result process logic

For different request results, different actions are to be performed. See the following list for details:

If the value of result.resultStatus is S, the OTP code is send to customer success.
If the value of result.resultStatus is F, and remainSendTimes>0, please try again with correct api key.
If the value of result.resultStatus is U, the API is disabled by system error.

Sample

Request

				
					{"msisdn":"03469908470","eventType":"PAYMENT"}

Response

				
					{"result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"Success"},"verifyRequestId":"OTPVerifyID2ee763f37d07430cb9d88daf9959d283","remainSendTimes":"3"}

/v2/risk/OTPVerify

POST /v2/risk/OTPVerify

This API is provide for merchant verify customer’s OTP number.

Message structure

Request

Property	Data type	Required	Max length	Description
verifyRequestId	String	Yes	64	To verify, carry the verifyRequestId with the request.
otpCode	String	Yes	64	the otpCode of user input

Response

Property	Data type	Required	Max length	Description
result	Result	Yes	–	The request result, which contains information related to the request result, such as status and error codes.
remainVerifyTimes	String	No	–	Remain verify times of current OTP verify progress.

Result

resultStatus	resultCode	resultMessage
S	SUCCESS	Success
F	OTP_CODE_EXPIRED	The OTP code is expired
F	VERIFY_REQUEST_ID_INVALID	The verifyRequestId is invalid
F	REACHED_VERIFY_TIMES_LIMIT	The number of OTPVerify requests exceeded the limit
F	OTP_CODE_INVALID	The OTP code is invalid
U	UNKNOWN_EXCEPTION	An API calling is failed, which is caused by unknown reasons.

Result process logic

For different request results, different actions are to be performed. See the following list for details:

If the value of result.resultStatus is S, the OTP code verify succeed.
If the value of result.resultStatus is F, and remainVerifyTimes>0, please try again with correct api key.
If the value of result.resultStatus is U, the API is disabled by system error.

Sample

Request

				
					{"verifyRequestId":"OTPVerifyID2ee763f37d07430cb9d88daf9959d283","otpCode":"032457"}

Response

				
					{"result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"Success"},"remainVerifyTimes":"3"}

get the

easypaisa app

Overview

About easypasia Open Ecosystem

Capabilities

Prerequisites

Quick Start

Table of Contents

Mini App Quick Start

Overview

Step 0: API Request Format Prerequisite

Step 1: Get Access Token to authenticate the merchant

Step 2：Get Authorization(AuthCode) from User

Step 3: Get User Info using AuthCode

Step 4: Create a Transaction Request

Step 5: Prompt User for Payment

Step 6: That's it!

Table of Contents

Payment Quick Start

Overview

Step 0: API Request Format Prerequisite

Step 1: Get Access Token to authenticate the merchant

Step 2：Initiate the Payment for a specific user

Step 3: Redirect the user to the payment confirmation interface

Step 4: That's it!

Table of Contents

Promotion Quick Start

Overview

Step 0: API Request Format Prerequisite

Step 1: Get Access Token to authenticate the merchant

Step 2：Initiate the Cashback for a specific user

Step 3: That's it!

Table of Contents

Agreement Pay Quick Start

Overview

Step 0: API Request Format Prerequisite

Step 1:Get PaymentAuthCode to exchange PaymentToken

Step 2:Open authUrl(H5 middle page)

Step 3:Get PaymentToken For subsequent agreement payment

Step 4:Payment Pre-check

Step 5:Create payment order

Step 6：Inquery payment result

Step 7: That's it!

Table of Contents

Mini App Overview

About Mini App

Key Concepts for Mini App

Table of Contents

Overview

mp.getUserAuthCode

mp.getAuthCode

Sample Code

Request Parameters

Scopes

Callback Function

Success callback example

Table of Contents

mp.createPayment

mp.createPayment

Sample Code

Request Parameters

Callback Function

Result Code

Table of Contents

mp.getLocation

mp.getLocation

Sample Code

Callback Function

Error Code

Table of Contents

Idempotency

Idempotency fields

Table of Contents

Error Codes

Common error codes

Common error codes

Table of Contents

Overview

Message structure

Request structure

/v1/authentications
/applyToken

/v1/authentications
/revokeToken

/v1/payments
/createPayment

/v1/payments
/inquirePayment