•  

    Developer

    Everything under the sun for you to integrate with fonePaisa

  • Mobile Kits
  • Ecommerce Plugins
  • Integration Kits
  • API documentation

a. Magento

Click here to download

b. OpenCart

Click here to download

c. WooCommerce (Wordpress)

Click here to download
 
   f. Event Espresso (Wordpress)
 

Payment API

1 Overview

The objective of the document is to enable Merchants (or Merchant aggregators) to invoke various apis provided by fonePaisa Application. The APIs are meant for managing the merchants business processes.


2 Pre-requisites for Production

Merchant, on registering with fonePaisa will receive login credentials to the fonePaisa merchant portal. On the portal the merchant needs to generate a (RSA2048) merchant specific private key and api-­key required for signing every message sent to fonePaisa. fonePaisa will only store the public key, the private key needs to be securely stored by the merchant.


3 Test and Production URL

For integration testing purpose, prior to go live;; we will be sharing keys along with the Integration Kit.

The Sand Box Test Base URL: https://test.fonepaisa.com/portal/
The Production Base URL: https://secure.fonepaisa.com/portal/


4 PAYMENT APIs

The fonePaisa payment APIs are provided on HTTP POST in json format.

4.1 Check Status:

The API provides the current status of the payment.
Test URL: https://test.fonepaisa.com/portal/payment/inquire
Production URL: https://secure.fonepaisa.com/portal/payment/inquire

Sl#JSON fieldsDescriptionInput/Output
1 Id Id provided by fonePaisa to the merchant, the verification of the message is done with this entity. Input
2 merchant_id Id provided by fonePaisa to the merchant, In case of merchant aggregator, it will be different from the merchant aggregator Input
3 invoice The reference against which the payment is being collected. Input
4 status
  • Status of payment: Awaiting response 'I'
  • Completed successfully 'C'
  • Partially paid 'P'
  • Request cancelled 'X'
  • Payment reversed 'R'
  • Payment failed :'F'
  • Payment expired :'D'
  • Payment partly reversed :'V'
Output
5 payment_reference The reference provided by fonePaisa Payment Gateway which can be used for settlement. Output
6 sign Details of fields to be included for message hashing given below. Digital signature of the message with desired fields given below Input
7 invoice_amt The invoice amount, for which the request was raised by the merchant Output
8 fee The fee collected from the consumer, based on the payment mode. Output
9 amount Amount collected/to be collected against the invoice. Output
10 addnl_detail Information passed to fonePaisa in addnl_info for any processing to be done in the Merchant application Output
11 error Error code Output
12 error_msg Error Message in case of an error Output

Format of post:


{
“id”:””,
“merchant_id”:””,
“invoice”:””,
“status”:””,
“payment_reference”:””,
“sign”:””,
“invoice_amt”:””,
“fee”:””,
“amount”:””,
“addnl_detail”:””,
“error”:””,
“error_msg”:””
}

Signing Information:

Merchant needs to sign using the hex value of the signature using (SHA512 and RSA2048 private key ) the following string as input:

Fields to be used for signature: api_key#id#merchant_id#invoice#.

A snippet of code in PHP, integration kits of each language is shared separately:

  • //Step 1: create hash input. Ensure amt is in 0.00 format.(2 decimals after decimal)

$hashinput=$input["api_key"]."#".$input["id"].”#”.$input["merchant_id"]."#".$input["invoice"]."#";

  • //Step 2: Read the RSA 2048 key stored

$pkeyid = openssl_pkey_get_private($input["private_key"]);

  • //Step 3: compute signature

openssl_sign($hashinput, $signature, $pkeyid,"sha512");

  • //Step 4: Get the hex value of the signature

$sign=bin2hex ($signature);

  • //Step 5: free the key from memory

openssl_free_key($pkeyid);

Error CodeDescription
7018 Invalid Signature
7019 Id is mandatory field
7020 Id is invalid
7117 Invoice id is invalid
7118 Either fone paisa payment reference or invoice id needs to be provided for reversal.
7074 Invalid Payment Reference, check length
7017 Signature field is mandatory

4.2 Cancel Payment:

The API allows the merchant to cancel the payment done. This payment causes complete cancellation of payment.

Test URL: https://test.fonepaisa.com/portal/payment/cancel

Production URL: https://secure.fonepaisa.com/portal/payment/cancel

Sl#JSON fieldsDescriptionInput/Output
1 Id Id provided by fonePaisa to the merchant, the verification of the message is done with this entity. Input
2 merchant_id Id provided by fonePaisa to the merchant, In case of merchant aggregator, it will be different from the merchant aggregator Input
3 invoice The reference against which the payment is being collected. Input
4 status Status of payment. Status of payment: R-­ Reversed Output
5 payment_reference The reference provided by fonePaisa Payment Gateway which can be used for settlement. Output
6 payment_rev_reference The reference provided by fonePaisa Payment Gateway for reversal Output
7 sign Details of fields to be included for message hashing given below. Digital signature of the message with desired fields given below Input
8 addnl_detail Information passed to fonePaisa in addnl_info for any processing to be done in the Merchant application Output
9 error Error code Output
10 error_msg Error Message in case of an error Output

Format of post:


{
“id”:””,
“merchant_id”:””,
“invoice”:””,
“status”:””,
“payment_reference”:””,
“payment_rev_reference”:””,
“sign”:””,
“addnl_detail”:””,
“error”:””,
“error_msg”:””
}

Signing Information:

Merchant needs to sign using the hex value of the signature using (SHA512 and RSA2048 private key ) the following string as input:

Fields to be used for signature: api_key#id#merchant_id#invoice#.

A snippet of code in PHP, integration kits of each language is shared separately:

  • //Step 1: create hash input. Ensure amt is in 0.00 format.(2 decimals after decimal)

$hashinput=$input["api_key"]."#".$input["id"].”#”.$input["merchant_id"]."#".$input["invoice"]."#";

  • //Step 2: Read the RSA 2048 key stored

$pkeyid = openssl_pkey_get_private($input["private_key"]);

  • //Step 3: compute signature

openssl_sign($hashinput, $signature, $pkeyid,"sha512");

  • //Step 4: Get the hex value of the signature

$sign=bin2hex ($signature);

  • //Step 5: free the key from memory

openssl_free_key($pkeyid);

Error CodeDescription
7018 Invalid Signature
7019 Id is mandatory field
7020 Id is invalid
7117 Invoice id is invalid
7118 Either fone paisa payment reference or invoice id needs to be provided for reversal.
7074 Invalid Payment Reference, check length
7017 Signature field is mandatory

4.3 Refund Payment:

The API allows the merchant to refund a payment done. The merchant can refund a certain amount against an invoice paid.

Test URL Endpoint: https://test.fonepaisa.com/portal/payment/refund

Production URL Endpoint: https://secure.fonepaisa.com/portal/payment/refund

Sl#JSON fieldsDescriptionInput/Output
1 Id Id provided by fonePaisa to the merchant, the verification of the message is done with this entity. Input
2 merchant_id Id provided by fonePaisa to the merchant, In case of merchant aggregator, it will be different from the merchant aggregator Input
3 invoice The reference against which the payment is being collected. Input
4 amt The amount to be refunded to the consumer Input
5 req_id A unique request id from merchant against which the refund needs to be done. Input
6 status Status of payment. Status of payment: R-Reversed V-Partly reversed Output
7 revd_amt Amount already reversed against the invoice. Output
8 payment_reference The reference provided by fonePaisa Payment Gateway which can be used for settlement. Output
9 payment_rev_reference The reference provided by fonePaisa Payment Gateway for reversal Output
10 sign Details of fields to be included for message hashing given below. Digital signature of the message with desired fields given below Input
11 addnl_detail Information passed to fonePaisa in addnl_info for any processing to be done in the Merchant application Output
12 error Error code Output
13 error_msg Error Message in case of an error Output

Format of post:


{
"id": "",
"merchant_id": "",
"invoice": "",
"amt": 0.00,
"req_id": "",
"status": "",
"payment_reference": "",
"payment_rev_reference": "",
"sign": "",
"addnl_detail": "",
"revd_amt": 0.0,
"error": "0000",
"error_msg": "Payment reversed successfully"
}

Signing Information:

Merchant needs to sign using the hex value of the signature using (SHA512 and RSA2048 private key ) the following string as input:

Fields to be used for signature: api_key#id#merchant_id#invoice#req_id#amt.

A snippet of code in PHP, integration kits of each language is shared separately:

  • //Step 1: create hash input. Ensure amt is in 0.00 format.(2 decimals after decimal)

$hashinput=$input["api_key"]."#".$input["id"].”#”.$input["merchant_id"]."#".$input["invoice"].”#”.$input["amt"].”#”;

  • //Step 2: Read the RSA 2048 key stored

$pkeyid = openssl_pkey_get_private($input["private_key"]);

  • //Step 3: compute signature

openssl_sign($hashinput, $signature, $pkeyid,"sha512");

  • //Step 4: Get the hex value of the signature

$sign=bin2hex ($signature);

  • //Step 5: free the key from memory

openssl_free_key($pkeyid);

Fields to be used for signature: api_key#id#merchant_id#invoice#

The following payment errors may occur from fonePaisa Payment Setup

Error CodeDescription
7018 Invalid Signature
7019 Id is mandatory field
7020 Id is invalid
7124 Request id is mandatory.
7125 Request id length should be less than 32
7117 Invoice id is invalid
7118 Either fone paisa payment reference or invoice id needs to be provided for reversal.
7074 Invalid Payment Reference, check length
7126 Amount to be reversed is mandatory
7017 Signature field is mandatory

4.4 Payment Request:

The API allows the merchant to raise a payment request. The merchant can raise a payment request against an invoice, the SMS/email will be sent to the consumer with the details of the payment request. This is useful where the merchant is aware of the consumer details like mobile no /email and have a relationship with the consumer. The messages can be customized for each merchant.

Test URL Endpoint: https://test.fonepaisa.com/portal/payment/request

Production URL Endpoint: https://secure.fonepaisa.com/portal/payment/request

Sl#JSON fieldsDescriptionInput/Output
1 Id Id provided by fonePaisa to the merchant, the verification of the message is done with this entity.Mandatory field. Input
2 merchant_id Id provided by fonePaisa to the merchant, In case of merchant aggregator, it will be different from the merchant aggregator.Mandatory field. Input
3 sign Details of fields to be included for message hashing given below. Digital signature of the message with desired fields given below. Mandatory field. Input
4 valid_for_mins Life span of transaction. If not provided default validity of the transaction end of next day. Input
5 consumer_mobile Consumer mobile number. (either consumer mobile number or email Id Mandatory field) Input
6 consumer_email Consumer email ID. (either consumer mobile number or email Id Mandatory field) Input
7 agent_mob Agent mobile number. Input
8 agent_email Agent email ID. Input
9 amount The amount to be collected from the consumer to agent.(Mandatory field) Input
10 invoice_id The reference against which the payment is being collected. Input
11 resp_code Error code in case of an error. Output
12 resp_msg Error Message in case of an error. Output
13 user_id Agent user ID. Input
14 store_id Agent store ID. Input
15 Status Status of the request. S:Success,F:Failure Output
16 payment_reference The reference provided by fonePaisa Payment Gateway which can be used for settlement. Output
17 addnl_info Information passed to fonePaisa in addnl_info for any processing to be done in the Merchant application Input

Format of post:


{
"id":"1",
"merchant_id":"M0001",
"sign":"",
"valid_for_mins":"",
"consumer_mobile":"",
"consumer_email":"",
"agent_email":"",
"agent_mob":"",
"amount":,
"invoice_id":"",
"resp_code":"",
"resp_msg":"",
"user_id":"",
"store_id":"",
"status":"",
"payment_reference":"",
"addnl_info": "{\"store_name\":\"THE FIRST STORE\",\"store_id\":\"ST00001\"}"
}

Signing Information:

Merchant needs to sign using the hex value of the signature using (SHA512 and RSA2048 private key ) the following string as input:


Fields to be used for signature: api_key#id#merchant_id#invoice_id#.

A snippet of code in PHP, integration kits of each language is shared separately:

  • //Step 1: create hash input.

$hashinput=$input["api_key"]."#".$input["id"].”#”.$input["merchant_id"]."#".$input["invoice_id"];

  • //Step 2: Read the RSA 2048 key stored

$pkeyid = openssl_pkey_get_private($input["private_key"]);

  • //Step 3: compute signature

openssl_sign($hashinput, $signature, $pkeyid,"sha512");

  • //Step 4: Get the hex value of the signature

$sign=bin2hex ($signature);

  • //Step 5: free the key from memory

openssl_free_key($pkeyid);

Fields to be used for signature: api_key#id#merchant_id#invoice#


The following payment errors may occur from fonePaisa Payment Setup

Error CodeDescription
7009 The message is not authorized, can be issue with the api or the hash message generated.
7006 Unable to service request.
7019 Institution Id is mandatory.
7160 Invalid email id.
9033 A payment exists against this reference.
7021 User Id is invalid.
9059 Invoice amount should be positive.
7117 Invalid Invoice ID (These chatacters are not allowed[\"';,#]).
7159 Store id invalid.
7163 Valid for minute cannot be set in past.
7021 User id invalid.

Payment Gateway

1 Overview

The objective of the document is to enable institutions to allow their relationships to deposit money in their wallet, A reference needs to be passed from the institution for querying on the completion of payment, the payment details (card details etc..) are captured in the fonePaisa Payment Gateway and then forwarded to the banks for completion of payment.


2 Pre-requisites for Production

Institution, on registering with fonePaisa will receive login credentials to the fonePaisa institution portal. On the portal the institution needs to generate a (RSA2048) institution specific private key and api-­key required for signing every message sent to fonePaisa. fonePaisa will only store the public key, the private key needs to be securely stored by the institution.

The fonePaisa public key will be displayed on the portal which needs to be used for verifying the messages sent by fonePaisa to the callback url provided by institution.


3 Test and Production URL

For integration testing purpose, prior to go live;; we will be sharing keys along with the Integration Kit.

Test URL: https://test.fonepaisa.com/pg/pay
Production URL: https://secure.fonepaisa.com/pg/pay


4 ONLINE PAYMENT

An online life cycle payment will happen based on the following flow:

payment flow
payment flow

The institution needs to invoke the initiate payment with the invoice details and the receive the confirm payment response on a call back url and complete the payment life cycle.

4.1 Initiate Payment:

The following fields are involved in invoking an initiate payment request.

SlField NameTypeSizeMandatoryDescription
1. Id String 16 Y Id provided by fonePaisa to the merchant,the verification of the message is done with this entity.
2. merchant_id String 16 Y Id provided by fonePaisa to the merchant, In case of merchant aggregator, it will be different from the merchant aggregator
3. merchant_display String 64 Y The display of the merchant to be shown on the fonePaisa PG UI.
4. invoice String 32 Y The reference against which the payment is being collected.
5. mobile_no String 13 N The mobile no of the consumer
6. email String 128 N The eMail id of the consumer
7. invoice_amt Number   Y The invoice amount to be collected from the consumer.
8. note Number 256 N Remarks about the invoice.
9. payment_types String 32 N Payment types can be set to only allow certain payment types. Eg. only payment from credit card / debit card is allowed then pass ‘|CC|DC|’. This is set up at the Id and Merchant Id level, however , this can be set at each request level. Payment Types: CC-­Credit Card DC-­Debit Card OW-­Wallet NB – Net Banking
10. callback_url String   Y The url to be called in case the payment is successful
11. callback_failure_url String   Y The url to be called in case the payment is unsuccessful
12. addnl_info String 2048 N Additional information. (in JSON format, can be set which will be passed to the merchant as part of confirm payment)
13. sign String   Y The signature of the message.

Signing Information:

Institution needs to sign using the hex value of the signature using (SHA512 and RSA2048 private key ) the following string as input:

api_key#id#merchant_id#invoice#invoice_amt#

A snippet of code in PHP, integration kits of each language is shared separately:

  • //Step 1: create hash input. Ensure Invoice amt is in 0.00 format.(2 decimals after decimal)

$hashinput=$input["api_key"]."#".$input["id"]."#".$input["merchant_id"]."#".$input["invoice"]."#".$input["invoice_amt"]."#";

  • //Step 2: Read the RSA 2048 key stored

$pkeyid = openssl_pkey_get_private($input["private_key"]);

  • //Step 3: compute signature

openssl_sign($hashinput, $signature, $pkeyid,"sha512");

  • //Step 4: Get the hex value of the signature

$hexsign=bin2hex ($signature);

  • //Step 5: free the key from memory

openssl_free_key($pkeyid);

4.2 Confirm Payment:

The following fields are involved in the confirm payment response sent by fonePaisa:

SlField NameTypeSizeMandatoryDescription
1 Id String 16 NA Id provided by fonePaisa to the merchant,the verification of the message is done with this entity.
2 merchant_id String 16 NA Id provided by fonePaisa to the merchant, In case of merchant aggregator, it will be different from the merchant aggregator
3 amount Number   NA The total amount collected from the consumer.
4 merchant_display String 64 NA The display of the merchant to be shown on the fonePaisa PG UI.
5 invoice String 32 NA The reference against which the payment is being collected.
6 payment_reference String 32 NA The reference provided by fonePaisa Payment Gateway which can be used for settlement.
7 status String 1 NA
  • S-­ Success
  • F-­ Failure
  • X-­ Cancel
8 addnl_detail String   NA Information passed to fonePaisa in addnl_info for any processing to be done in the Merchant application
9 error String   NA Error code
10 error_msg String   NA Error Message in case of an error
11 sign String   NA Signature of the message
12 fee Amount   NA Fee collected from the consumer based on the payment option selected.
13 Invoice_amt amount   NA The amount for which the payment request was initiated.

Signing Information:

Institution needs to verify the message by checking against the sign:

#invoice#payment_reference#

A snippet of code in PHP, integration kits of each language is shared separately:

  • //Step 1: Construct the hash input

$hashinput="#".$input["invoice"]."#".$input["payment_reference"]."#";

  • //Step 2: get the binary value of the input signature

$signature=bin2hex($input["sign"]);

  • //Step 2: get the fonePaisa public key shared with the institution

$pubkeyid = openssl_pkey_get_public($input["public_key"]);

  • //Step 3:Verify the signature.

$ok = openssl_verify($hashinput, $signature,

$pubkeyid,"sha512WithRSAEncryption");

if ($ok == 1) {

$retval=true;

}

  • // Step 4: free the key from memory

openssl_free_key($pubkeyid);

5 ERROR CODE AND DESCRIPTION

The following payment errors may occur from fonePaisa Payment Setup

Error CodeError Description
1001 Request not setup
1002 Payment cannot be done as the data for the institution not setup.
1003 Unauthorized Request.
1004 Message is invalid.
1005 Payment amount not entered
1006 Invoice details not entered
1007 Institution not entered
1008 Callback URL not provided
1009 Invalid amount
1010 Message not signed
1011 Unknown Caller
1012 Invalid Institution
1013 Invalid URL
1014 Payment type not supported for the institution
1015 Institution Id not entered Page 8 of 9
1016 User Id not entered
1017 Wallet address not entered
1018 Invalid request
1019 Please try after sometime
1020 Please try after sometime
1021 Please try after sometime
1022 Unable to sign message.
1023 Invalid response.
1024 Token not provided
1025 Input contains prohibited characters
1026 Payment Failed.
1027 Invalid Transaction
1028 SYSTEM_ERROR,Please try after sometime
1029 Unable to make a request to the call back url
1030 Invalid inputs for getting payment status
1032 Payment address not provided
1033 Credit card not entered
1034 Card Name not entered
1035 Expiry Date not entered
1036 CVV not entered
1037 Invalid Card No
1038 Invalid Card Expiry Date
1039 Invalid CVV
1040 Debit Card Not Entered
1041 Bank not supported for NetBanking
1042 Wallet not supported for Institution
1043 Bank Name not entered
1044 Wallet details not entered
1046 Invalid Configuration. Please try after some time
1047 Unable to retrieve confirmation details.
1048 Invalid transaction.
1049 Transaction status not available.
1050 Transaction status is invalid.
1051 Mobile Number not entered.
1053 Invalid preferences  
1054 SYSTEM ERROR. Please try after some time
1055 Please try after some time
1056 OTP not entered. Page 9 of 9
1057 Please enter correct Mobile No/PIN.
1058 Please enter correct Mobile No/PIN.
1059 Invalid number.
1060 Do not support more that two payment options.
1061 Payment type not supported.
1062 Payment type combination not supported.
1063 Total split amount does not match total.
1064 Invalid invoice.
1065 Invalid institution.
1066 User preference not known.
1067 Unable to reverse payment.
1068 Invalid payment reference.
1076 Invalid note
1080 Invalid invoice date
1081 Invalid invoice upto date
1082 Invalid PG reversal transaction id
1083 Invalid Payment reversal transaction id
1084 Payment exists against the reference
1085 Unable to initiate payment
1086 Invalid Mobile No
1087 Invalid eMail
1088 Payment is already cancelled
1089 Payment is not successful
1090 Reversal of Payment is not successful
1091 Invalid Additional details
1092 Unable to verify the payment.
1093 Payment is in progress, please try again in a few minutes.
1094 Payment is not in active state, it has either been paid or rejected
1095 Payment does not exist