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.
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>
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
<consent-generate-otp-discovery> <request-token-id>IZ71vZBE6t</request-token-id> <ipayy-user-token>c443cdgy7jfdfsda1b018ca7a3dd973bf1b4839abbb7b9aa</ipayy-user-token> <currency>INR</currency> <item> <item-details> <price>1.00</price> <item-id>voGi</item-id> <item-name>Nike Air</item-name> </item-details> </item> <configuration> <content-text> <success>Billing is success</success> <failure>Billing has failed</failure> <lowbalance>Billing has failed due to low balance</lowbalance> <invalidsubscriber>Billing has failed as subscriber is invalid</invalidsubscriber> </content-text> </configuration> </consent-generate-otp-discovery> |
Request Parameters:
| XML Tag | Description |
|---|---|
| request-token-id | Transaction 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) |
| currency | Currency Type Currently only INR is supported |
| ipayy-user-token | Unique token for the msisdn-operator. This token can be used for further Consent requests without doing detection |
| item-id | The item identification code with which the API needs to be invoked |
| item-name | The name of the item with which the API needs to be invoked. |
| price | The item price value with which the API needs to be invoked. |
| configuration | Any additional configuration with which the API needs to be invoked. |
| content-text | Configuration 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>
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
<consent-response> <response-parameter-map> <entry> <key>operator-name</key> <value>IDEA</value> </entry> <entry> <key>item-name</key> <value>Nike Air Shoes</value> </entry> <entry> <key>item-id</key> <value>voGi</value> </entry> <entry> <key>price</key> <value>1.00</value> </entry> <entry> <key>status</key> <value>SUCCESS</value> </entry> <entry> <key>msisdn</key> <value>919876543210</value> </entry> <entry> <key>application-name</key> <value>new app</value> </entry> <entry> <key>ipayy-user-token</key> <value>c443cdgy7jfdfsda1b018ca7a3dd973bf1b4839abbb7b9aa</value> </entry> <entry> <key>request-token-id</key> <value>IZ71vZBE6t</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>
|
1 2 3 4 5 |
<error> <http-status-code>400</http-status-code> <error-response-code>IRQ0101</error-response-code> <error-description> A required resource could not be found with the specified parameters</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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
<consent-generate-otp-request> <request-token-id>IZ71vZBE6t</request-token-id> <msisdn>9876543219</msisdn> <operator-name>Airtel</operator-name> <currency>INR</currency> <item> <item-details> <price>1.00</price> <item-id>voGi</item-id> <item-name>Nike Air</item-name> </item-details> </item> <configuration> <content-text> <success>Billing is success</success> <failure>Billing has failed</failure> <lowbalance>Billing has failed due to low balance</lowbalance> <invalidsubscriber>Billing has failed as subscriber is invalid</invalidsubscriber> </content-text> </configuration> </consent-generate-otp-request> |
Request Parameters:
| Request Parameter | Description |
|---|---|
| request-token-id | Transaction 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) |
| msisdn | Mobile number of the subscriber |
| customer-code | Hashed value of msisdn |
| operator-name | Name of the operator to which subscriber's number belongs to |
| currency | Currency Type Currently only INR is supported |
| price | The item price value with which the API needs to be invoked. |
| item-id | The item identification code with which the API needs to be invoked. |
| item-name | The name of the item with which the API needs to be invoked. |
| configuration | Any additional configuration with which the API needs to be invoked |
| content-text | Configuration 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>
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
<consent-response> <response-parameter-map> <entry> <key>operator-name</key> <value>IDEA</value> </entry> <entry> <key>item-name</key> <value>Nike Air Shoes</value> </entry> <entry> <key>item-id</key> <value>voGi</value> </entry> <entry> <key>price</key> <value>1.00</value> </entry> <entry> <key>status</key> <value>SUCCESS</value> </entry> <entry> <key>msisdn</key> <value>919876543210</value> </entry> <entry> <key>application-name</key> <value>new app</value> </entry> <entry> <key>ipayy-user-token</key> <value>c443cdgy7jfdfsda1b018ca7a3dd973bf1b4839abbb7b9aa</value> </entry> <entry> <key>request-token-id</key> <value>IZ71vZBE6t</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>
|
1 2 3 4 5 |
<error> <http-status-code>400</http-status-code> <error-response-code>IRQ0101</error-response-code> <error-description> A required resource could not be found with the specified parameters</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:
|
1 2 3 4 5 6 |
<process-payment-request> <request-token-id>IZ71vZBE6t</request-token-id> <otp-code>7321</otp-code> <support-phone-number>917689023415</support-phone-number> <support-email-address>abc@gmail.com</support-email-address> </process-payment-request> |
Request Parameters:
| Request Parameter | Description |
|---|---|
| request-token-id | Request ID used for the transaction |
| otp-code | OTP Code sent to the customer |
| support-email-address | Email 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-number | Phone 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
<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.
<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>
<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-code></error-response-code>
<error-description></error-description>
Sample Error Reponse XML:
|
1 2 3 4 5 |
<error> <http-status-code>401</http-status-code> <error-response-code>ICR0201</error-response-code> <error-description>The iPayy PIN / OTP token did not match.</error-description> </error> |