Developer FAQ's
Q: How do I install the Ezybonds Payment Button on my website?
A: Before attempting to use the Ezybonds Payment Button on your website insure you are first an Ezybonds Member by acquiring a free Ezybonds Ezyaccount using the button at the top of the page and the Ezyaccount has been "certified" by applying for "Certified Merchant" status using the link in the right hand column. Once "Registered" as a certified merchant you can begin taking payments using the Ezybonds payment system. There are various options for initiating payments on your website and there is "developer documentation" available through the links on the left hand column. The documentation provides a thorough guideline for integrating payment methods on your website including explanations for properly configuring your Ezyaccount for merchant use, PIN CODE accessability, the purpose and necessity of the required Notification Script, a test API for the Notification Script and HTML examples of the form code for the Ezybonds Payment Button.
Q: How can I test the entire process from the user clicking on Ezybonds payment button to the point where the ACKNOWLEDGE notification is sent from my notification url? Is this possible?
A: To properly test the payment process from your merchants payment button there are two ways a purchasing scenario can be emulated between a purchasing visitor with an Ezyaccount and the Certified Merchant's website which has an Ezyaccount:
1. Use the merchant Ezyaccount as both the purchasers Ezyaccount and the merchants Ezyaccount. Good
2. Create a second Ezyaccount. Better
Both method's require funds to exist for use in testing.
Set up a $1 test product which is used on your Payment Button.
Clicking the Payment Button writes that $1 test product to your 'orders' database and generates "invoice id" (or 'orderid') which is added back to the Payment Button form element: <input type="text" name="invoice" value="<%=orderid%>" />
Your "order id" record in your database now has $1 total and your form is sending the "order id" and the "amount" <input type="text" name="amount" value="<%=amount%>" /> (along with all other form information: merchant id, etc.) as part of the form post to the Ezybonds payment URL. The "orderid" and the "amount" now exist both in your database on your server and are received at the API to the Ezybonds server.
The Ezybonds server API starts with the login screen and choices for the purchaser to pay the $1 for the item(s) (represented by the "orderid") from their Ezyaccount.
At this point the Ezybonds process has taken all the form elements from the page request and based on the merchant id has grabbed a PIN CODE from the merchants duplicate PIN CODE block on the Ezybonds server. Along with the PIN CODE and all other posted values it POSTS a CHECK request to the merchants NS based on the NS URL in the merchants Ezyaccount.
In the CHECK request received by the merchants NS it should do the following based on the "invoice" (orderid) it has received back : retrieves from the merchant database the order record and searches for the existence of the "unused" PIN CODE. The PIN CODE should exist in the merchants database and not have been used for any other transaction. The amount in the CHECK request should match exactly the amount retrieved from the merchants database for that order id. The only way the currency could be changed would be by changing the currency type in the original form post before it was posted to Ezybonds so you would want to check that the currency type is the same before Ezybonds recieved the original post and what it is in the "CHECK" request against the currency type in your order id record.
If all conditions match as required by the NS then the NS should log this fact and respond with "CONFIRM", if not it responds with "DECLINE" and the purchaser receives the appropriate message that the merchant has declined their purchase attempt.
Once "CONFIRM" is received by Ezybonds it completes the funds transfer, generates a transaction id and at this time grabs another PIN CODE from the merchants duplicate block in the merchants Ezyaccount and responds back to the merchant NS with the "PAYMENT" request containing a transaction id (trans_id).
During the PAYMENT request the merchant NS checks for the presence of a second matching "unused" PIN CODE in it's own database (and performs any other checks during the "PAYMENT" request) and if all is well responds with "ACKNOWLEDGE". The Ezybonds system will continue sending the PAYMENT notification until it is responded to by "ACKNOWLEDGE".
In spite of whether or not the PAYMENT notification is responded to by the merchant, the transaction will have been completed if the "CONFIRM" response is received during the CHECK notification.
1. Use the merchant Ezyaccount as both the purchasers Ezyaccount and the merchants Ezyaccount. Good
2. Create a second Ezyaccount. Better
Both method's require funds to exist for use in testing.
Set up a $1 test product which is used on your Payment Button.
Clicking the Payment Button writes that $1 test product to your 'orders' database and generates "invoice id" (or 'orderid') which is added back to the Payment Button form element: <input type="text" name="invoice" value="<%=orderid%>" />
Your "order id" record in your database now has $1 total and your form is sending the "order id" and the "amount" <input type="text" name="amount" value="<%=amount%>" /> (along with all other form information: merchant id, etc.) as part of the form post to the Ezybonds payment URL. The "orderid" and the "amount" now exist both in your database on your server and are received at the API to the Ezybonds server.
The Ezybonds server API starts with the login screen and choices for the purchaser to pay the $1 for the item(s) (represented by the "orderid") from their Ezyaccount.
At this point the Ezybonds process has taken all the form elements from the page request and based on the merchant id has grabbed a PIN CODE from the merchants duplicate PIN CODE block on the Ezybonds server. Along with the PIN CODE and all other posted values it POSTS a CHECK request to the merchants NS based on the NS URL in the merchants Ezyaccount.
In the CHECK request received by the merchants NS it should do the following based on the "invoice" (orderid) it has received back : retrieves from the merchant database the order record and searches for the existence of the "unused" PIN CODE. The PIN CODE should exist in the merchants database and not have been used for any other transaction. The amount in the CHECK request should match exactly the amount retrieved from the merchants database for that order id. The only way the currency could be changed would be by changing the currency type in the original form post before it was posted to Ezybonds so you would want to check that the currency type is the same before Ezybonds recieved the original post and what it is in the "CHECK" request against the currency type in your order id record.
If all conditions match as required by the NS then the NS should log this fact and respond with "CONFIRM", if not it responds with "DECLINE" and the purchaser receives the appropriate message that the merchant has declined their purchase attempt.
Once "CONFIRM" is received by Ezybonds it completes the funds transfer, generates a transaction id and at this time grabs another PIN CODE from the merchants duplicate block in the merchants Ezyaccount and responds back to the merchant NS with the "PAYMENT" request containing a transaction id (trans_id).
During the PAYMENT request the merchant NS checks for the presence of a second matching "unused" PIN CODE in it's own database (and performs any other checks during the "PAYMENT" request) and if all is well responds with "ACKNOWLEDGE". The Ezybonds system will continue sending the PAYMENT notification until it is responded to by "ACKNOWLEDGE".
In spite of whether or not the PAYMENT notification is responded to by the merchant, the transaction will have been completed if the "CONFIRM" response is received during the CHECK notification.
Q: How does the Ezybonds payment process detect if a payment process has been tampered with (for example changing currency from EURO to Indian rupee)?
A: All of the form values that represent a purchase or order should be written to the database either ahead of or at the very least at the point of the payment button submitting the form to the Ezybonds payment interface URL. When the notification script receives the CHECK notification all of the values will re-presented for comparison purposes. If any value appears to have been changed then the notification script can "DECLINE" the purchase.
Q: What do the following error messages mean when performing live payment tests to the Ezybonds system and what could cause them?
| Merchant Payment Processing Error | |||||
|
A: While it's not always simple to determine what is causing this error generally it is due one or a combination of the following:
- The merchants certified status has not fully "registered" in the system. Ezymerchants are required to be approved and formally registered with the Ezybonds payment system before it recognizes payment requests from the Ezymerchant's Ezyaccount ID.
- The Notification Script URL has not been entered in the "Ezymerchant" (green) tab of the Ezyaccount admin.
- The Notification Script URL has not been entered correctly in the "Ezymerchant" (green) tab of the Ezyaccount admin.
System Error | |||
| |||
| If this problem persists, please contact Ezybond Admin |
A: This error is displayed under two circumstances:
- There was some sort of network issue where the Ezybonds server could not communicate with the Ezymerchants notification script (ie network timeout).
- The Ezymerchant's notification script returned an invalid response to the CHECK request.
Invalid CHECK response examples:- Unencoded or wrongly encoded characters in the form post from the merchants payment button, received by Ezybonds and posted to the Notification Script such as the following example:
notify_type=CHECK&merchant=123456&amount=1.00¤cy=EUR&invoice=791293277112&product_desc=&product_id=&custom01=&custom02= - Leading and/or trailing spaces on the "CONFIRM", "DECLINE" or "ACKNOWLEDGE" responses.
" CONFIRM" instead of "CONFIRM"
- Unencoded or wrongly encoded characters in the form post from the merchants payment button, received by Ezybonds and posted to the Notification Script such as the following example:
| Purchase Declined | ||
|
A: This error is generally invoked when...
- the Notification Script has found a discrepancy between what values were saved to the merchants' database and the form post values the Ezybonds system received after the payment button was clicked.
- the Notification Script contains logic that detected conditions internal to the merchants website/database and responded with a "DECLINE".