Next: Other APIs

This section guides you through the custom payment API.

How it works?

Service Integration Steps :

STEP 1  Mobile Number Detection


This unique and proprietary feature enables you to provide a single click experience without requiring the customer to enter their mobile number.
It works for customers accessing via carrier partner networks only.

Learn More

STEP 2  Generate  and Send One-Time-Password(OTP) :

Authorization Header :

Authorization Header must be generated and passed in all consent and payment requests.

Header Name: Authorization
Header Value Format: ‘Basic <Base 64 Encoded value <Merchant Key:Application Key>>’

E.g. If merchant key is ‘hac42JpvdXT9Jb9bVzKuzR’ and application key is ‘7ADYdcB3xGxw3psxqKx57m’ then the header value is going to be: ‘Basic aGFjNDJKcHZkWFQ5SmI5YlZ6S3V6Ujo3QURZZGNCM3hHeHczcHN4cUt4NTdt’

Steps to arrive at this value (using merchant-key (hac42JpvdXT9Jb9bVzKuzR) and application-key (7ADYdcB3xGxw3psxqKx57m):

1. Concatenate merchant-key followed by application-key separated by a colon delimiter ‘:’
Result: hac42JpvdXT9Jb9bVzKuzR:7ADYdcB3xGxw3psxqKx57m

2. The value above needs to be encoded in Base-64 format.
Result: aGFjNDJKcHZkWFQ5SmI5YlZ6S3V6Ujo3QURZZGNCM3hHeHczcHN4cUt4NTdt

3. Concatenate the string ‘Basic’ with the Base-64 value generated in step 2 separated by a space character ‘ ‘.
Result: ‘Basic aGFjNDJKcHZkWFQ5SmI5YlZ6S3V6Ujo3QURZZGNCM3hHeHczcHN4cUt4NTdt’

4. Set the resultant string generated in step 3 as the value for the Header with name: ‘Authorization’ .
For End User Consent , iPayy provides API to  generate an OTP and send it to the customer. The OTP is a random pin generated by the iPayy system. This API is available in two variants:

Discovered

If the end user Mobile Number and Operator were detected by the iPayy system at the time of Mobile Number Discovery.

URL: https://api.ipayy.com/v001/c/consent/genotpwd

Request XML:

<consent-generate-otp-discovery>

   <request-token-id> </request-token-id>

   <ipayy-user-token> </ipayy-user-token>

   <currency>INR</currency>

   <item>

      <item-details>

         <price></price>

         <item-id> </item-id>

         <item-name> </item-name>

      </item-details>

   </item>

  <configuration>

     <content-text>

        <success> </success>

        <failure> </failure>

        <lowbalance> </lowbalance>

        <invalidsubscriber> </invalidsubscriber>

    </content-text>

  </configuration>

</consent-generate-otp-discovery>

 

Request Parameters:

XML TagDescription
request-token-idTransaction request id.
The request id is unique for a given merchant and application. The request id should not be repeated for a given merchant and application.(should be unique and between 8-40 character)
currencyCurrency Type
Currently only INR is supported
ipayy-user-tokenUnique token for the msisdn-operator. This token can be used for further Consent requests without doing detection
item-idThe item identification code with which the API needs to be invoked
item-nameThe name of the item with which the API needs to be invoked.
priceThe item price value with which the API needs to be invoked.
configurationAny additional configuration with which the API needs to be invoked.
content-textConfiguration for content to be sent in additional SMS based on transaction state
success: Content to be sent for Billing success
failure: Content to be sent for General failure
lowbalance: Content to be sent for Low balance billing failure
invalidsubscriber: Content to be sent for Invalid subscriber billing failure.

Response XML:

Success Response XML :

Returns a success response for the specified request

<consent-response>

<response-parameter-map>

<entry>

<key>operator-name</key>

<value </value>

</entry>

<entry>

<key>item-id</key>

<value </value>

</entry>

<entry>

<key>price</key>

<value></value>

</entry>

<entry>

<key>status</key>

<value>SUCCESS</value>

</entry>

<entry>

<key>msisdn</key>

<value></value>

</entry>

<entry>

<key>application-name</key>

<value></value>

</entry>

<entry>

<key>item-name</key>

<value> </value>

</entry>

<entry>

<key>ipayy-user-token</key>

<value> </value>

</entry>

<entry>

<key>request-token-id</key>

<value> </value>

</entry>

</response-parameter-map>

</consent-response>

 

Failure Response XML :

Return an error response with the error-code and error-description.

Please refer to the [Error Codes] for more details

<error>

<http-status-code></http-status-code>

<error-response-code></error-response-code>

<error-description></error-description>

</error>

 

UnDiscovered

In case if mobile number or operator name could not be detected by the iPayy system at the time of Mobile Number Discovery.

URL: https://api.ipayy.com/v001/c/consent/genotpwr

Request XML:

<consent-generate-otp-request>

<request-token-id> </request-token-id>

<currency> </currency>

<msisdn></msisdn> OR <customer-code></customer-code>

<operator-name> </operator-name>

<item>

<item-details>

<price></price>

<item-id> </item-id>

<item-name> </item-name>

</item-details>

</item>

<configuration>

<content-text>

<success> </success>

<failure> </failure>

<lowbalance></lowbalance>

<invalidsubscriber> </invalidsubscriber>

</content-text>

</configuration>

</consent-generate-otp-request>

 

Sample Request:

 Request Parameters:

Request ParameterDescription
request-token-idTransaction request id.
The request id is unique for a given merchant and application. The request id should not be repeated for a given merchant and application.(should be unique and between 8-40 character)
msisdnMobile number of the subscriber
customer-codeHashed value of msisdn
operator-nameName of the operator to which subscriber's number belongs to
currencyCurrency Type
Currently only INR is supported
priceThe item price value with which the API needs to be invoked.
item-idThe item identification code with which the API needs to be invoked.
item-nameThe name of the item with which the API needs to be invoked.
configurationAny additional configuration with which the API needs to be invoked
content-textConfiguration for content to be sent in additional SMS based on transaction state
success: Content to be sent for Billing success
failure: Content to be sent for General failure
lowbalance: Content to be sent for Low balance billing failure
invalidsubscriber: Content to be sent for Invalid subscriber billing failure.

Response XML:

Success Response XML :

<consent-response>

<response-parameter-map>

<entry>

<key>operator-name</key>

<value </value>

</entry>

<entry>

<key>item-id</key>

<value </value>

</entry>

<entry>

<key>price</key>

<value></value>

</entry>

<entry>

<key>status</key>

<value>SUCCESS</value>

</entry>

<entry>

<key>msisdn</key>

<value></value>

</entry>

<entry>

<key>application-name</key>

<value></value>

</entry>

<entry>

<key>item-name</key>

<value> </value>

</entry>

<entry>

<key>ipayy-user-token</key>

<value> </value>

</entry>

<entry>

<key>request-token-id</key>

<value> </value>

</entry>

</response-parameter-map>

</consent-response>

 

 

Failure Response:

Return an error response with the error-code and error-description.

Please refer to the [Error Codes] for more details

Failure Response XML :

<error>

<http-status-code></http-status-code>

         <error-response-code></error-response-code>

<error-description></error-description>

</error>

 

 Resend

In case if it is required to resend OTP to the end user

URL: https://api.ipayy.com/v001/c/consent/resendotp

Request XML:

<consent-resend-otp-request>

<request-token-id> </request-token-id>

<currency> </currency>

<item>

<item-details>

<price></price>

<item-id> </item-id>

<item-name> </item-name>

</item-details>

</item>

</consent-resend-otp-request>

 

Response XML:

Success Response XML :

<consent-response>

<response-parameter-map>

<entry>

<key>operator-name</key>

<value </value>

</entry>

<entry>

<key>item-id</key>

<value </value>

</entry>

<entry>

<key>price</key>

<value></value>

</entry>

<entry>

<key>status</key>

<value>SUCCESS</value>

</entry>

<entry>

<key>msisdn</key>

<value></value>

</entry>

<entry>

<key>application-name</key>

<value></value>

</entry>

<entry>

<key>item-name</key>

<value> </value>

</entry>

<entry>

<key>ipayy-user-token</key>

<value> </value>

</entry>

<entry>

<key>request-token-id</key>

<value> </value>

</entry>

</response-parameter-map>

</consent-response>

 

 

Failure Response:

Return an error response with the error-code and error-description.

Please refer to the [Error Codes] for more details

Failure Response XML :

<error>

<http-status-code></http-status-code>

         <error-response-code></error-response-code>

<error-description></error-description>

</error>

 

STEP 3  Invoke iPayy Payment API :


This API is used to invoke the payment process after the OTP has been generated and sent.

URL: https://api.ipayy.com/v001/c/pay/dopayment


Request

Request XML:

<process-payment-request>

<request-token-id> </request-token-id>

<otp-code></otp-code>

<support-phone-number></support-phone-number>

<support-email-address> </support-email-address>

</process-payment-request>

Sample Request XML:

Request Parameters:

Request ParameterDescription
request-token-idRequest ID used for the transaction
otp-codeOTP Code sent to the customer
support-email-addressEmail Address to be used for any future support related to the payment
The contact information shall be included in the SMS. Either Email Address or Phone number is mandatory
support-phone-numberPhone Number to be used for any future support related to the payment
The contact information shall be included in the SMS. Either Email Address or Phone number is mandatory

Billing Success

Success Response XML:

Return a success response with status as success and transaction id

Success Response:
 
<payment-response>
<response-parameter-map>
<entry>
<key>operator-name</key>
<value> </value>
</entry>
<entry>
<key>msisdn</key>
<value></value>
</entry>
<entry>
<key>application-name</key>
<value> </value>
</entry>
<entry>
<key>amount-charged</key>
<value></value>
</entry>
<entry>
<key>payment-status</key>
<value> </value>
</entry>
<entry>
<key>ipayy-user-token</key>
<value> </value>
</entry>
<entry>
<key>transaction-id</key>
<value></value>
</entry>
<entry>
<key>request-token-id</key>
<value></value>
</entry>
<entry>
<key>customer-code</key>
<value> </value>
</entry>
<entry>
<key>currency</key>
<value> </value>
</entry>
</response-parameter-map>
</payment-response>

 

 

 

Billing Failure

Failure Response XML:

Return a failure response with status as failure and failure reason.

Failure Response:
<payment-response>
<response-parameter-map>
<entry>
<key>operator-name</key>
<value> </value>
</entry>
<entry>
<key>msisdn</key>
<value></value>
</entry>
<entry>
<key>application-name</key>
<value> </value>
</entry>
<entry>
<key>amount-charged</key>
<value>0</value>
</entry>
<entry>
<key>payment-status</key>
<value>FAILURE</value>
</entry>
<entry>
<key>failure-reason</key>
<value>LOW_BALANCE</value>
</entry>
<entry>
<key>ipayy-user-token</key>
<value> </value>
</entry>
<entry>
<key>transaction-id</key>
<value></value>
</entry>
<entry>
<key>request-token-id</key>
<value></value>
</entry>
<entry>
<key>customer-code</key>
<value> </value>
</entry>
<entry>
<key>currency</key>
<value> </value>
</entry>
</response-parameter-map>
</payment-response>

 

 

 

 

Error Response

Failure Response XML:

Return an error response with the error-code and error-description.

Please refer to the [Error Codes] for more details

Error Response:
<error>
<http-status-code></http-status-code>
<error-response-code></error-response-code>
<error-description></error-description>
</error>

 

Sample Error Reponse XML:

 

 

Next: Other APIs