2012 MyanPay Express Checkout Integration Guide MyanPay Myanmar Soft Gate Technology Co, Ltd. 8/20/2012
Getting Started With Express Checkout. 1 Key Features of Express Checkout...1 The Express Checkout Experience....2 Express Checkout Prerequisites...3 Express Checkout Building Blocks...4 Express Checkout Buttons....4 Express Checkout API Operations.....5 Express Checkout Command..5 Express Checkout Token Usage..5 Express Checkout UI Customization...6 Implementing the Simplest Express Checkout Integration...7 Obtaining an Express Checkout Button and MyanPay Mark...7 Before You Start Coding...8 MyanPay API Client-Server Architecture....8 Obtaining API Credentials...9 Creating an API Signature...9 Setting Up the Express Checkout Transaction...10 Obtaining Express Checkout Transaction Details...12 Completing the Express Checkout Transaction...13 Security Issues...14 Testing Express Checkout API...15 Testing SetExpressCheckout API Operation [ Step 1 to 4 ]...16 Testing GetExpressCheckout API Operation [ Step 5 ].....18 Testing DoExpressCheckout API Operation [ Step 6 7 ]...19
Request and Response SetExpressCheckout Request Message...21 SetExpressCheckout Response Message....27 GetExpressCheckout Request Message...28 GetExpressCheckout Response Message......28 DoExpressCheckout Request Message...35 DoExpressCheckout Response Message...36 Trouble Shooting Your Express Checkout Integration...37 Error Handling......37 Logging API Operations........37 Encoding and Decoding Values...37 MyanPay NVP API Basics...38 Myanpay API Client-Server Architecture...38 MyanPay Name-Value Pair API Requests and Responses...38 Multiple API Operations....39 NVP Format...40 Creating an NVP Request....40 Specifying the MyanPay API Operation......40 Specifying an API Credential......41 URL Encoding......41 Executing NVP API Operations...41 Specifying a MyanPay Server...42 Logging API Operations...42 Responding to an NVP Response...42 Common Response Fields...43 Error Responses...43 URL Decoding...43
MyanPay Express Checkout Integration Guide 1 Getting Started With Express Checkout The Express Checkout button gives buyers another way to pay, and it complements your existing payment solution. Online shoppers appreciate the convenience and security of MyanPay, where they can pay with their MyanPay balance or bank account. Key Features of Express Checkout Express Checkout is a fast, easy way for buyers to pay with MyanPay. Express Checkout eliminates one of the major causes of checkout abandonment by giving buyers all the transaction details at once, including order details, shipping options, insurance choices, and tax totals. Studies show that adding the Express Checkout button to your website can increase your sales up. The following web page shows the Express Checkout button side-by-side with an existing checkout button: MyanPay Express Checkout Integration Guide Page 1
MyanPay Express Checkout Integration Guide 2 Use Express Checkout to: Accept payments from any MyanPay account. Eliminate the need for customers to enter personal information, including shipping, billing, or payment information. Keep customers on your site after completing the transaction. Sign up customers to make payments at regular intervals. The Express Checkout Experience Express Checkout makes it easier for buyers to pay online. It also enables you to accept MyanPay while retaining control of the buyer and the overall checkout flow. Consider your buyers experience before implementing Express Checkout. The following diagram show Express Checkout flow: Express Checkout flow In the Express Checkout flow, a buyer: 1. Chooses Express Checkout by clicking Check out with MyanPay 2. Logs into MyanPay to authenticate his or her identity 3. Reviews the transaction on MyanPay NOTE: Optionally, (not shown in the diagram), the buyer can then proceed to review the order on your site. You can also include other checkout steps, including on your Confirm order page. 4. Confirms the order and pays from your site 5. Receives an order confirmation MyanPay Express Checkout Integration Guide Page 2
MyanPay Express Checkout Integration Guide 3 Express Checkout Prerequisites Prerequisites to Express Checkout include the kind of MyanPay accounts you need as well as the required programming skills and experience. If you want to use Express Checkout but do not have the required skills or experience, you should consider using MyanPay Website Payments Standard or a shopping cart provided by MyanPay or a third party. To use Express Checkout, you must have: A Business or Personal account. A Business or Personal account enables you to become merchant for whom MyanPay collects money from buyers for goods or services. MyanPay manages these transactions and charges you a small fee and a percentage of the amount collected from the buyer for each transaction. HTML experience. Probably, you already have an existing website and may have already implemented a checkout experience for the goods or services you sell on your site. You will need to add the Pay with Express Checkout button, as well as another button, called the Express Checkout mark, to your web pages. The Pay with Express Checkout button initiates the MyanPay checkout flow. The mark enables the buyer to choose Express Checkout from the page that specifies the payment method, called the payment page, in case the buyer did not start with Pay with Express Checkout. Programming experience. When the buyer clicks a button, you must provide code that requests a MyanPay server to set up or process the transaction and code to handle the response. MyanPay provides an easy-to-user interface built on the HTTP request-response model. MyanPay also provides sample codes in two programming languages, such as PHP and.net languages like C#. Although you need not know a specific language, you will need to understand programming logic, especially the request-response model, error handling, and the nuances of writing application-level code. NOTE : If the description of the programming experience prerequisite seems confusing (like what s an interface? ), you can still use Express Checkout provided by a shopping cart vendor, including MyanPay, or use another MyanPay product, such as Website Payments Standard. You should not attempt to integrate Express Checkout on your own unless you have sufficient programming experience. A programmer or developer will find Express Checkout easy; a complete novice could lose sales or goods and not even know it. MyanPay Express Checkout Integration Guide Page 3
MyanPay Express Checkout Integration Guide 4 Express Checkout Building Blocks You implement Express Checkout flows with Express Checkout buttons, MyanPay API operations, MyanPay commands, and tokens. The following conceptual diagram identifies the building blocks that you use to integrate Express Checkout on your website: A token is a value assigned by MyanPay that associates the execution of API operations and commands with a specific instance of a user of a user experience flow. NOTE:Tokens Tokens are not shown in diagram. Express Checkout Buttons MyanPay provides buttons and images for you to place on your website. To implement the Express Checkout shopping cart experience, place the following button on your Shopping Cart page: MyanPay Express Checkout Integration Guide Page 4
MyanPay Express Checkout Integration Guide 5 Express Checkout API Operations The MyanPay API provides three API operations for Express Checkout. These API operations set up the transaction, obtain information about the buyer, and handle the payment and complete the transaction. API Operation Description Sets up the Express Checkout transaction. You can specify information to customize the look and feel of the MyanPay site and the information it displays. You must include the following information: SetExpressCheckout GetExpressCheckout DoExpressCheckout URL to the page on your website that MyanPay redirects to after thebuyer logs into MyanPay and approves the payment successfully. URL to the page on your website that MyanPay redirects to if the buyercancels. Total amount of the order or your best estimate of the total. It shouldbe as accurate as possible. Obtains information about the buyer from MyanPay, including shipping information. Completes the Express Checkout transaction, including the actual totalamount of the order. Express Checkout Command MyanPay provides a command that you use when redirecting your buyer s browser to MyanPay. This command enables your buyer to log in to MyanPay to approve an Express Checkout payment. When you redirect your buyer s browser to MyanPay, you must specify the Express Checkout command for Express Checkout. You also specify the token that identifies the transaction, which was returned by the Set Express Checkout API operation. NOTE :To enable MyanPay to redirect back to your website, you must have already invoked thesetexpress Checkout API operation, specifying URLs that MyanPay uses to redirect back to your site. MyanPay redirects to the success URL when the buyer pays on MyanPay;otherwise, MyanPay redirects to the cancel URL. If the buyer approves the payment, MyanPay redirects to the success URL with the following information: The token that was included in the redirect to MyanPay The buyer s unique identifier (Payer ID) If the buyer cancels, MyanPay redirects to the cancel URL with the token that was included in the redirect to MyanPay. Express Checkout Token Usage Express Checkout uses a token to control access to MyanPay and execute Express Checkout API operations. The Set Express Checkout API operation returns a token, which is used by other Express Checkout API operations and by the Express Checkout command to identify the transaction. The life of the token is approximately 3 hours. MyanPay Express Checkout Integration Guide Page 5
MyanPay Express Checkout Integration Guide 6 Express Checkout UI Customization You can customize the appearance of the MyanPay Express Checkout pages. Some changes alter the checkout flow. ExpressCheckout includes options for presenting the checkout pages that appear when the buyer logs into MyanPay during checkout. Some of them make the MyanPay pages look like your own pages, giving the customer a consistent visual presentation: Logo to display Your Brand Name Your customer service number Return URL Cancel URL NOTE: Allof the above customizations can be set in your profile. You set them in an Express Checkout API operation only when you want to override the default provided by your profile. Other options streamline the flow, by allowing the buyer to complete the payment on MyanPay, or change the kind of information that is presented during checkout. On the MyanPay Review page, you can: Include per-item details Include tax, insurance, shipping costs, and shipping discounts Indicate whether the total displayed on the page is exact or an estimate before items such as tax and shipping costs Display a note to the buyer; for example, a note identifying the shipping options are available Allow your buyer to specify instructions to you Assign an invoice number to a payment Other features may be used in specialized cases: Shipping address display and usage MyanPay Express Checkout Integration Guide Page 6
MyanPay Express Checkout Integration Guide 7 Implementing the Simplest Express Checkout Integration Obtaining an Express Checkout Button and MyanPay Mark MyanPay requires that you use the Checkout with MyanPay button and the MyanPay mark image hosted on secure MyanPay servers. When the images are updated, the changes appearautomatically in your application. You must put the Express Checkout button on your checkout page. To obtain an ExpressCheckout Button: 1. Go to the MyanPay Merchant Services Page [https://www.myanpayvirtualbox.com/personal/merchantservices.aspx ] 2. Click the Create ExpressCheckout Button link or button. A page similar to the following one appears 3. Select and copy the image source text from the window below the button. 4. Paste the image source text into your checkout page s HTML source where you want the button to appear on your page. MyanPay Express Checkout Integration Guide Page 7
MyanPay Express Checkout Integration Guide 8 Result When you display your checkout page in the browser, the Check out with MyanPaybuttonshould appear After Completing This Task You will need to place the MyanPaymark image on your payment page. The instructions forobtaining this image are similar to the instructions for obtaining the button. The mark is foundon the same Button Code page (https://www.myanpay-virtualbox.com/personal/expresscheckout/createexpresscheckout.aspx) as the Express Checkout button. Before You Start Coding If you are not familiar with how MyanPay APIs works, read this topic. It provides the minimuminformation you need to be successful using the MyanPay Name-Value Pair API. MyanPay API Client-Server Architecture The MyanPay API uses a client-server model in which your website is a client of the MyanPayserver. A page on your website initiates an action on a MyanPay API server by sending a request to the server. The MyanPay server responds with a confirmation that the requested action was taken or indicates that an error occurred. The response might also contain additional information related to the request. The following diagram shows the basic request-response mechanism. For example, you might want to obtain the buyer s shipping address from MyanPay. You caninitiate a request specifying an API operation to obtain buyer details. The response from themyanpay API server contains information about whether the request was successful. If theoperation succeeds, the response contains the requested information. In this case, the response contains the buyer s shipping address. If the operation fails, the response contains one or more error messages. MyanPay Express Checkout Integration Guide Page 8
MyanPay Express Checkout Integration Guide 9 Obtaining API Credentials To use the MyanPay API, you must have API credentials that identify you as a MyanPay Business or Premier Account holder who is authorized to perform various API operations.although you can use an API signature, MyanPay recommends you use a signature. Creating an API Signature An API signature consists of an API username along with an associated API password and signature, all of which are assigned by MyanPay. You need to include this information wheneveryou execute a MyanPay API operation. You must have a MyanPay Business account to create a signature. To create an API signature: 1. Log in to MyanPay, and then click Profile under My Account. 2. ClickSelling Preferences. 3. ClickView APIAccess. 4. Click Request API Credentials. 5. ClickView API Credentials. ClickDone to complete the process. MyanPay Express Checkout Integration Guide Page 9
MyanPay Express Checkout Integration Guide 10 Setting Up the Express Checkout Transaction To set up an Express Checkout transaction, you must invoke the SetExpressCheckout APIoperation to provide sufficient information to initiate the payment flow and redirect to MyanPay.if the operation was successful. This example site assumes that you have set up the mechanism you will use to communicate with the MyanPay server and have a MyanPay Business account with API credentials. When you test it, you need to use your own credentials. When you set up an Express Checkout transaction, you specify values in the SetExpressCheckout request and then call the API. The values you specify control the MyanPay page flow and the options available to you and your buyers. You should start by setting up a standard Express Checkout transaction, which can be modified to include additional options. Follow these steps to make SetExpressCheckOut API Call [ NVP ] 1. Specify your API credentials. Use the following parameters for a signature: APIUsername = _junio7482443442_myanpayapi APIPassword = Z687FL3W036I06D0 APISignature = b98ql7734zo0fw50mfp4u55p583bklz44zy524eme5ro7hfdzlwq5an2rx8d [ Note ] This credential values are just for sample. You can replace them with your own credential. 2. Specify that you want to execute the SetExpressCheckout API operation and the version you want to use. Method=SetExpressCheckout Version=X.XX 3. Specify the amount of the transaction and passing items list information to MyanPay[ optional ]. Specify the total amount of the transaction if it is known; otherwise, specify the subtotal. Regardless of the specified currency, the format must have a decimal point with exactly two digits to the right. [ See also SetExpressCheckout Request Fields ] PaymentRequest_Amt=youramount 4. Specify the return URL. The return URL is the page to which MyanPay redirects your buyer s browser after the buyer logs into MyanPay and approves the payment. Typically, this is a secure page (https://...) on your site. ReturnUrl= https://www.yourdomain.com/yourreturnurl 5. Specify the cancel URL. The cancel URL is the page to which Myanpay redirects your buyer s browser if the buyer does not approve the payment. Typically, this is the secure page (https://...) on your site from which you redirected the buyer to MyanPay. CancelUrl= https://www.yourdomain.com/yourcancelurl MyanPay Express Checkout Integration Guide Page 10
MyanPay Express Checkout Integration Guide 11 6. Specify the payment action. Although the default payment action is a Sale, it is a best practice to explicitly specify the payment action as one of the following values: PaymentAction= sale After Completing This Task: If calling the SetExpressCheckout API was successful, redirect the buyer s browser to MyanPay and execute the _express-checkout command using the token returned in the SetExpressCheckout response. NOTE: The following example uses the MyanPay Virtual Box server: https://www.myanpay-virtualbox.com/personal/expresscheckout/expresscheckoutlogin/?cmd=express-checkout&token=tokenvalue For PHP Developer In PHP, It Step should be use PHP CURL Function. If you use php_curl function, Modify in your php.ini file.activation of PHP/CURL on windows is starting up notepad (or similar) and removing a semicolon from the following line in php.ini: ; Extension=php_curl.dll If you use XAMPP, Modify "C:\xampp\php\php.ini". Search "php_curl" and remove ";" at front for this line You can see "http://phpbasic.myanpay.com.mm" source code download.in this website, MyanPayReviewOrder.php and MyanPayCallerService.php is use php_curl function. Please see How to use php_curl function. MyanPay Express Checkout Integration Guide Page 11
MyanPay Express Checkout Integration Guide 12 Obtaining Express Checkout Transaction Details To obtain details about an Express Checkout transaction, you can invoke the GetExpressCheckout API operation. This example assumes that MyanPay redirects to your buyer s browser with a valid token after the buyer reviews the transaction on MyanPay. Although you are not required to invoke the GetExpressCheckout API operation, most Express Checkout implementations take this action to obtain information about the buyer. You invoke the GetExpressCheckout API operation from the page specified by return URL, which you set in your call to the SetExpressCheckout API. Typically, you invoke this operation as soon as the redirect occurs and use the information in the response to populate your review page. Follow these steps to make GetExpressCheckOut API Call To obtain a buyer s shipping address and Payer ID: 1. Specify that you want to execute the GetExpressCheckout API operation and the version you want to use. METHOD=GetExpressCheckout VERSION=XX.0 2. Specify your API credentials. Use the following parameters for a signature: ApiUsername =Your_API_username ApiPassword = Your_API_password ApiSignature=Your_API_signature 3. Specify the token returned by MyanPay when it redirects the buyer s browser to your site. MyanPay returns the token to use in the token HTTP request parameter when redirecting to the URL you specified in your call to the SetExpressCheckout API. TOKEN=token Value 4. Execute the GetExpressCheckout API to obtain information about the buyer. 5. Access the fields in the GetExpressCheckout API response. NOTE: Only populated fields are returned in the response. MyanPay Express Checkout Integration Guide Page 12
MyanPay Express Checkout Integration Guide 13 Completing the Express Checkout Transaction To complete an Express Checkout transaction, you must invoke the DoExpressCheckout API operation. This example assumes that MyanPay redirects your buyer s browser to your website with a valid token after you Call the SetExpressCheckout API. Optionally, you may call the GetExpressCheckout API before calling the DoExpressCheckoutAPI. In the simplest case, you set the total amount of the order when you call the SetExpressCheckout API. However, You can change the amount before calling the DoExpressCheckout API if you did not know the total amount When you called thesetexpresscheckout API. This example assumes the simplest case, in which the total amount was specified in the return URL when calling the SetExpressCheckout API. Although you can specify additional options, this example does not use any additional options. Follow these steps to make DoExpressCheckOut API Call 1. Specify that you want to execute the DoExpressCheckout API operation and the version you want to use. Method =DoExpressCheckout Version =XX.0 2. Specify your API credentials. Use the following parameters for a signature: ApiUsername =_junio7482443442_myanpayapi ApiPassword = Z687FL3W036I06D0 ApiSignature=b98qL7734zo0Fw50mFP4u55p583bkLz44ZY524EMe5rO7hfdzlWq5AN2rx8d 3. Specify the token returned by MyanPay when it redirects the buyer s browser to your site. MyanPay returns the token to use in the token HTTP request parameter when redirecting to the URL you specified in your call to the SetExpressCheckout API. TOKEN=MyanPay-ZJ24HP17587PD2BLPFR64C 4. Specify the Payer ID returned by MyanPay when it redirects the buyer s browser to your site. MyanPay returns the Payer ID to use in the token HTTP request parameter when redirectingto the URL you specified in your call to the SetExpressCheckout API. Optionally, you can obtain the Payer ID by calling the GetExpressCheckout API. PAYERID=id 5. Specify the amount of the order including shipping, handling, and tax. Most of the time, this will be the same amount as you specified in your SetExpressCheckout call, adjusted for shipping and taxes.and then you can pass items list information to MyanPay server optionally. [Please see details about advanced request variables for DoExpressCheckout] PaymentRequest_Amt =amount MyanPay Express Checkout Integration Guide Page 13
MyanPay Express Checkout Integration Guide 14 6. Specify the same payment action that you specified in DoExpressCheckout. PaymentAction =Sale 7. Execute the DoExpressCheckout API to obtain information about the buyer. 8. Access the fields in the DoExpressCheckout API response. Security Issues You must always be concerned with protecting sensitive data. This not only includes your API credentials, but also any data exposed in a client s browser, such as data about the transaction stored in cookies. In the simplest examples, such as the ones provided by MyanPay to demonstrate Express Checkout usage, the API credentials may be exposed. Thus, if you copy code from examples or SDKs, you should always review your website for security issues and correct them before you go live with your website. Encrypt all saved information related to the MyanPay transaction. For example, if you keep order status information in a cookie, make sure the information is encrypted. Use a secure transmission protocol, such as HTTPS to transfer information between your site and MyanPay. Do not use HTTP or insecure URL. MyanPay Express Checkout Integration Guide Page 14
MyanPay Express Checkout Integration Guide 15 Testing Express Checkout API You can test your Express Checkout integration in the MyanPayVirtualBox site [ https://www.myanpayvirtualbox.com ]. This example shows how to simulate your web pages using HTTP forms and supplying the values for API operations from these forms. You can use this strategy for your initial testing; however, for more complete testing, you need to replace these forms with your web pages containing your actual code. The following diagram shows the Express Checkout execution flow, which uses the VirtualBoxas the API server. The pages on the left represent your site and firstly read the legend on diagram. The following steps match the circled numbers in the diagram. Perform the actions in each step to test Express Checkout. MyanPay Express Checkout Integration Guide Page 15
MyanPay Express Checkout Integration Guide 16 Testing SetExpressCheckout API Operation [ Step 1 to 4 ] 1. Invoke a form on your site that calls the SetExpressCheckout API on the VirtualBox. To invoke the API, set form fields whose names match the NVP names of the fields you want to set, specify their corresponding values, and then post the form to a MyanPayVirtualBox server, such as https://www.virtualbox-myanpay.com, as shown in the following example: Simple HTML Sample Code [ With Basic Variables ] This sample code simply transmits the parameters and their value to our checkout page using the POST method.we also give the sample codes [ with asp.net, php language ] to post these variables to our MyanPay server programmatically. These variables that are present in the code are the minimum required parameters for the SetExpressCheckout to function properly. If any of those variables are missing or wrong, an error message will be displayed rather than a regular checkout page. <! MyanPay API Credential --> <inputtype= hidden name= UserName value=="_junio2533872781_myanpayapi > <inputtype= hidden name= Password value="53lo66znfw1150zm"> <inputtype= hidden name= Signature value= 1qc6mK4KS5fi6227Q6N6HVN83O4Ga7q0jQg11ue409x87lxl6l92L7uG6H3e > <! Required Fields To Make SetExpressCheckout --> <inputtype= hidden name= Version value=1.1> <inputtype= hidden name= PaymentAction value= sale> <inputtype= hidden name= ReturnUrl value= https://www.yourdomain.com/yourreturnurl > <inputtype= hidden name= CancelUrl value= https://www.yourdomain.com/yourcancelurl > <inputtype= submit name= Method value= SetExpressCheckout > <! Payment Related Fields -- > <inputname= PaymentRequest_Amt value= 10000 > </form> Simple HTML Sample Code [ With Advanced Variables] <formmethod=postaction=https://www.myanpayvirtualbox.com/personal/expresscheckout/expresscheckoutrequesthandler.aspx> <formmethod="post"action="https://www.myanpayvirtualbox.com/personal/expresscheckout/expresscheckoutrequesthandler.aspx"> <! MyanPay API Credential --> <inputtype="hidden"name="apiusername "value="_junio2533872781_myanpayapi"> <inputtype="hidden"name="apipassword"value="53lo66znfw1150zm"> <inputtype="hidden"name="apisignature"value="1qc6mk4ks5fi6227q6n6hvn83o4ga7q0jqg11ue409x87lxl6 l92l7ug6h3e"> <! Required Fields --> <inputtype="hidden"name="version"value="1.1"> <inputtype="hidden"name="paymentaction"value="sale"> <inputtype="hidden"name="returnurl"value="https://www.yourdomain.com/yourreturnurl "> <inputtype="hidden"name="cancelurl"value="https://www.yourdomain.com/yourcancelurl "> MyanPay Express Checkout Integration Guide Page 16
MyanPay Express Checkout Integration Guide 17 <! Item List Information [ Optional ] --> <inputtype="text"size="30"maxlength="32"name="paymentrequest_itemname0"value="myanpayexpresschec kout_book"/> <inputtype="text"name="paymentrequest_itemamt0"size="5"maxlength="32"value="10.00"/> <inputtype="text"size="3"maxlength="32"name="paymentrequest_itemqty0"value="3"/> <inputtype="text"size="3"maxlength="32"name="paymentrequest_itemnumber0"value="10000"/> <inputtype="text"size="20"maxlength="32"name="paymentrequest_itemdesc0"value="size: 8.8-oz"/> <inputtype="text"size="30"maxlength="32"name="paymentrequest_itemname1 "value="softgate CD"/> <inputtype="text"name="paymentrequest_itemamt1"size="5"maxlength="32"value="25.00"/> <inputtype="text"size="3"maxlength="32"name= paymentrequest_itemqty1"value="4"/> <inputtype="text"size="3"maxlength="32"name="paymentrequest_itemnumber"value="10001"/> <inputtype="text"size="20"maxlength="32"name="paymentrequest_itemdesc1"value="size: Two 24-piece boxes"/> <! Shipping Address [ Optional ] -- > <inputtype="text"size="30"maxlength="32"name="paymentrequest_addressline"value="no(9)/a,shin Saw PuPogadaStreet,SanChaung,Yangon"/> <inputtype="text"size="30"maxlength="32"name="paymentrequest_shiptocity"value="sanchaung"/> <inputtype="text"size="30"maxlength="32"name="paymentrequest_shiptostate"value="yangon"/> <! Shipping Option I -- > <inputtype="text"size="30"maxlength="32"name="shippingoptionamount0"value="81.00"/> <inputtype="text"size="30"maxlength="32"name="shippingoptionlabel0 "value="mps"/> <inputtype="text"size="30"maxlength="32"name="shippingoptionname0"value="ups Air"/> <inputtype="text"size="30"maxlength="32"name="shippingoptionisdefault0"value="true"/> <! Shipping Option II -- > <inputtype="text"size="30"maxlength="32"name="shippingoptionamount1"value="31.00"/> <inputtype="text"size="30"maxlength="32"name="shippingoptionlabel1"value="ems"/> <inputtype="text"size="30"maxlength="32"name="shippingoptionname1"value="ground"/> <inputtype="text"size="30"maxlength="32"name="shippingoptionisdefault1"value="false"/> <! Payment Related Fields -- > <inputtype="text"size="30"maxlength="32"name="paymentrequest_shippingtotalamt"value="8.00"/> <inputtype="text"size="3" maxlength="32"name="paymentrequest_shippingdiscamt"value="-3.00"/> <inputtype="text"size="30"maxlength="32"name= paymentrequest_insurancetotalamt"value="1.00"/> <inputtype="text"size="30"maxlength="32"name="paymentrequest_insuranceoptionoffered"value="true"/> <inputname="paymentrequest_taxtotalamt"size="3"value="2.00"> <inputname="paymentrequest_itemtotalamt"size="3"value="130.00"> <inputname="paymentrequest_amt"size="3"value="13.00"> <inputname="max_amount"size="3"value="3.00"> <inputtype="submit"name="method"value="setexpresscheckout"> </form> NOTE: Use an API username from a VirtualBox business test account for which a signature exists. Please refer to see details about advanced variables: Download HTMLSample Code at the following link: https://www.myanpay-virtualbox.com/pub_downloadpage.aspx 2. Review the response string from the SetExpressCheckout API operation. MyanPay responds with a message, such as the one shown below. Note the status, which should include ACK set to Success, and a token that is used in subsequent steps. Ack=success &Build=1.1 MyanPay Express Checkout Integration Guide Page 17
MyanPay Express Checkout Integration Guide 18 &CorrelationID=u405v89yv1w4r &TimeStamp=12%3a00%3a00+AM &Token=MyanPay-0J54W7TQ9FEQ5S31D0KH55 &BuiVersionld=1.1 3. If the operation was successful, use the token and redirect your browser to the VirtualBox to log in, as follows: You may need to decode the URL, which is the opposite of URL encoding, by replacing hexadecimal codes with ASCII codes; for example, you may need to replace %2d in the token with a hyphen ( - ). You must log to a VirtualBoxtest accountthat represents the buyer[ not the seller s business test account that represents you as the merchant ] 4. After logging into the buyer test account, confirm the details. When you confirm, the VirtualBox redirects your browser to the return URL you specified when invoking the SetExpressCheckout API operation, as in the following example: http://www.yourdomain.com/yourreturnurl?token=ec-1nk66318yb717835m&payerid=7akusarz7sat8 Note :: Step1 to step4 will be in SetExpressCheckout API call.continue to call GetExpressCheckOut API Testing GetExpressCheckout API Operation [ Step 5 ] 5.To obtain details about an Express Checkout transaction, you can invoke the GetExpressCheckout API operation. Simple HTML Sample Code [ Just for testing ] https://www.myanpay-virtualbox.com/personal/expresscheckout/expresscheckoutlogin.aspx?cmd=expresscheckout&token=myanpay-gnm31g605dzuls22wzzn54 <formmethod=postaction=https://www.myanpayvirtualbox.com/personal/expresscheckout/getexpresscheckoutrequesthandler.aspx> <! MyanPay API Credential --> <inputtype=hiddenname=apiusernamevalue=="_junio2533872781_myanpayapi > <inputtype=hiddenname=apipasswordvalue="53lo66znfw1150zm"> <inputtype=hiddenname=apisignaturevalue= 1qc6mK4KS5fi6227Q6N6HVN83O4Ga7q0jQg11ue409x87lxl6l92 L7uG6H3e > <!-- Required Fields To Make GetExpressCheckout --> <inputtype="hidden"name="version "value="1.1"> <inputname="token"value="myanpay-0j54w7tq9feq5s31d0kh55"> <inputtype="submit"name="method"value="getexpresscheckout"> </form> ASP.Net Sample Code [ Download these sample code at link ] https://www.myanpay-virtualbox.com/pub_downloadpage.aspx PHP NVP Sample Code [ Download these sample code ] https://www.myanpay-virtualbox.com/pub_downloadpage.aspx MyanPay Express Checkout Integration Guide Page 18
MyanPay Express Checkout Integration Guide 19 Review the response string from the GetExpressCheckout API operation If the operation was successful, the GetExpressCheckoutDetails API returns information about the payer, such as the following information: Ack=success &BusinessCompanyName=business+company+name &DisplayName=Junior+March+One &PayerID=SN6457T257HO1IR &PayerStatus=Verified &PhoneNumber=0973------- &PrimaryEmailAddress=userEmail@gmail.com &Token = MyanPay-0J54W7TQ9FEQ5S31D0KH55 &PaymentRequest_Amt=138.00 &PaymentRequest_ItemTotalAmt=130.00 &PaymentRequest_ShippingTotalAmt=8.00 &PaymentRequest_InsuranceTotalAmt=1.00 &PaymentRequest_ShippingDiscAmt=- 3.0000 &PaymentRequest_HandlingTotalAmt=0 &PaymentRequest_InsuranceOptionOffered=True &PaymentRequest_TaxTotalAmt=2.00 &PaymentRequest_TotalDiscountAmt=0.00 &PaymentRequest_PaymentAction= Sale &PaymentRequest_IsInsuranceOptionAccpetedByUser=False &PaymentRequest_IsShippingOptionDefault=True &PaymentRequest_Desc0=Size%3a+8.8-oz &PaymentRequest_ItemWeightValue0=0 & PaymentRequest_LengthUnitID0=0 &PaymentRequest_HeightUnitID0=0 & PaymentRequest_Name0=MyanPay+ExpressCheckout+Book &PaymentRequest_ItemAmt0=10.00 &PaymentRequest_ItemNumber0=10000 &PaymentRequest_ItemQty0=3 &PaymentReqeust_ItemDesc1=Size%3a+Two+24-piece+boxes &PaymentRequest_ItemWeightUnitID1=0 &PaymentRequest_ItemLengthUnitID1=0 &PaymentRequest_ItemHeightUnitID1=0 &PaymentRequest_ItemName1=SoftGate+CD &PaymentRequest_ItemAmt1=25.00 &PaymentRequest_ItemNumber1=10001 &PaymentRequest_ItemQty1=4 &PaymentRequest_AddressLine=Shan+North &PaymentRequest_ShipToCity=Kutkai &PaymentRequest_ShipToState=Shan+North Note :: Number of response fields and its value are depend on your SetExpressCheckoutAPI operation. Testing DoExpressCheckout API Operation [ Step 6 7 ] 6. Invoke a form on your site that invokes the DoExpressCheckoutPayment API operation on the VirtualBox: Simple HTML Sample Code <formmethod=postaction=https://www.myanpayvirtualbox.com/personal/expresscheckout/getexpresscheckoutrequesthandler.aspx> MyanPay Express Checkout Integration Guide Page 19
MyanPay Express Checkout Integration Guide 20 <!-- API Credentials --> <inputtype="hidden"name= apiusername value="_junio2533872781_myanpayapi"> <inputtype="hidden"name= apipassword value="53lo66znfw1150zm"> <inputtype="hidden"name= apisignature value="1qc6mk4ks5fi6227q6n6hvn83o4ga7q0jqg11ue409x87lxl6l92 L7uG6H3e "> <!-- Required Fields To Make DoExpressCheckout --> <inputtype="hidden"name="version "value="1.1"> <inputtype="hidden"name="payment_action"value="sale"> <inputtype="hidden"name="token"value="myanpay-0j54w7tq9feq5s31d0kh55"> <inputtype="hidden"name="paymentrequest_amount"value="138"> <inputtype="hidden"name="payerid"value="sn6457t257ho1ir"> <inputtype="submit"name="method"value="doexpresscheckout"> </form> Download HTML Sample Code at the following link : https://www.myanpay-virtualbox.com/pub_downloadpage.aspx 7. Review the response string from the DoExpressCheckout API operation.if the operation was successful, the response should include ACK set to Success, as follows: Ack=success &Build=5.1 &CorrelationID=d746de55x7vg0 &Token=MyanPay-0J54W7TQ9FEQ5S31D0KH55 &TimeStamp=10%3a22%3a20+AM &Version=1.1 &PaymentInfo_TransactionID=1766 &PaymentInfo_TransactionType=Send+Money+For+Goods+ &PaymentInfo_OrderTime=10%3a22%3a20+AM &PaymentInfo_AMT=10148 &PaymentInfo_FeeAmt=352 &PaymentInfo_TaxAmt=0 &PaymentInfo_PaymentStatus=Completed Note : We also provides our sample site that use ExpressCheckout NVP API. You can view information about this sample code and download link at https://www.myanpay-virtualbox.com/pub_downloadpage.aspx. MyanPay Express Checkout Integration Guide Page 20
MyanPay Express Checkout Integration Guide 21 SetExpressCheckout Request Message SetExpressCheckout Request Fields Field Required Description Type/Format Method Required Must be SetExpressCheckout. Method = SetExpressCheckout PaymentRequest_Amt ReturnUrl CancelUrl PaymentAction NoShipping Required The expected maximum total amount of the complete order, including shipping cost and tax charges. Required URL to which the buyer s browser is returned after choosing to pay with MyanPay. NOTE :MyanPay recommends that the value be the final review page on which the buyer confirms the order and payment. Required URL to which the buyer is returned if the buyer does not approve the use of MyanPay to pay you. NOTE :MyanPay recommends that the value be the original page on which the buyer choose to pay with MyanPay. Optional How you want to obtain payment. Sale This is a final sale for which you are requesting payment. Optional Determines where or not current transaction needs shipping address fields on the MyanPay pages. For digital goods, this field is set to true.if NoShipping is not included in your request, default value is false. true Current transaction does not need the shipping address on the MyanPay pages. false Current transaction needs the shipping address on the MyanPay pages. Type : Decimal Range : 50 to 100000 kyats PaymentRequest_Amt = 10000 ReturnUrl = http://www.example.com/returnurl.a spx CancelUrl = www.sample.com/cancelurl.aspx PaymentAction = Sale Type : Boolean NoShipping = false MyanPay Express Checkout Integration Guide Page 21
MyanPay Express Checkout Integration Guide 22 CustomShipping Optional Determines whether or not the buyer will use custom delivery address. If CustomShipping value is set to false, we will take the shipping address in MyanPay as buyer s delivery address.if CustomShipping is not included in your request, default value is false. true The buyer will use custom delivery address. false The buyer wil use shipping address in MyanPay. Type : Boolean CustomShipping = true Shipping Options Type Fields ShippingOptionIsDefa ult ShippingOptionName ShippingOptionAmou nt ShippingOptionLabel Optional Default shipping option displayed on the MyanPay pages. true This is the default shipping option. MyanPay displays this option and its amount by default. false This shipping option and its amount are not displayed as the default. NOTE :There must be ONE and ONLY ONE default. It is not OK to have no default. Optional Internal name of the shipping option such as Air, Ground, Expedited, and so forth. Optional Amount of the shipping option. Optional The label for the shipping option as displayed to the buyer. Examples: Air: Next Day, Expedited: 3-5 days, Ground: 5-7 days. These labels can be localized based on the buyer s locale. Type : Boolean ShippingOptionIsDefault = true ShippingOptionName = Ground Type : Decimal ShippingOptionAmount = 1000 ShippingOptionLabel = Air:Next Day Custom Delivery Address Type Fields PaymentRequest_Cus tomdeliveryname Optional The name who received the buyer s goods. Maxiumum Length : 150 PaymentRequest_CustomDeliveryN ame = U Hla MyanPay Express Checkout Integration Guide Page 22
MyanPay Express Checkout Integration Guide 23 PaymentRequest_Cus tomdeliveryemail PaymentRequest_Cus tomdeliveryphonenu mber PaymentRequest_Cus tomdeliveryaddress PaymentRequest_Cus tomdeliverycity PaymentRequest_Cus tomdeliverycountry Seller Info Fields EcHeaderImage EcCustomerServiceNu mber Optional Name of email address of receiver. Optional Phone number of receiver. Optional Address may include home number,streetnumber,township and city. Optional Name of City that the receiver stay. Optional Country that the receiver stay. Optional URL for the image you want to appear at the top left of the payment page. The image has a maximum size of 500 pixels wide by 70 pixels high. MyanPay recommends that you provide an image that is stored on a secure (https) server. If you do not specify an image, the business name displays. Optional Merchant Customer Service number displayed on the MyanPay pages. Maxiumum Length : 150 PaymentRequest_CustomDelive ryemail= uhla99@gmail.com Maxiumum Length : 20 PaymentRequest_CustomDeliveryP honenumber = 09xxxxxxx PaymentRequest_CustomDeliveryA ddress = No.1, Rose Road, Insein Township, Yangon Maxiumum Length : 20 PaymentRequest_CustomDeliveryC ity=yangon Maxumum Length : 20 PaymentRequest_CustomDeliveryC ountry=myanmar EcHeaderImage = www.example.com/header.png EcCustomerServiceNumber = 09xxxxxxx MyanPay Express Checkout Integration Guide Page 23
MyanPay Express Checkout Integration Guide 24 EcBrandName Optional A label that overrides the business name in the MyanPay account on the MyanPay hosted checkout pages. EcBrandName = Your brand name Payment Details Type Fields PaymentRequest_Item TotalAmt PaymentRequest_Ship pingtotalamt PaymentRequest_Insur ancetotalamt PaymentRequest_Ship pingdiscamt PaymentRequest_Insur anceoptionoffered PaymentRequest_Han dlingtotalamt PaymentRequest_TaxT otalamt Optional Sum of cost of all items in this order. MyanPay recommends that you pass the same value in the call to DoExpressCheckoutthat you passed in the call to SetExpressCheckout. Optional Total shipping costs for this order. Optional Total shipping insurance costs for this order. The value must be a nonnegative currency amount or null if insurance options are offered. Optional Shipping discount for this order, specified as a negative number. Optional Indicates whether insurance is available as an option the buyer can choose on the MyanPay Review page. true The Insurance option displays the insurance amount. If true, the total shipping insurance for this order must be a positive number. false The Insurance option displays No,thanks. Optional Total handling costs for this order. Optional Sum of tax for all items in this order. Type : Decimal PaymentRequest_ItemTotalAmt = 6700 Type : Decimal PaymentRequest_ShippingTotalAmt = 500 Type : Decimal PaymentRequest_InsuranceTotalA mt = 300 Type : Decimal PaymentRequest_ShippingDiscAmt = -200 Type : Boolean PaymentRequest_InsuranceOpti onoffered = true Type : Decimal PaymentRequest_HandlingTotal Amt = 500 Type : Decimal PaymentRequest_HandlingTotal Amt = 300 MyanPay Express Checkout Integration Guide Page 24
MyanPay Express Checkout Integration Guide 25 PaymentRequest_Desc PaymentRequest_Cust om Optional Description of items the buyer is purchasing. Optional A free-form field for your own use. Maximum Length : 50 PaymentRequest_Desc = Your description Maximum Length : 255 PaymentRequest_Custom = Your custom value PaymentRequest_InvN um Optional Your own invoice or tracking number. Maximum Length : 127 PaymentRequest_InvNum = Your invoice number NoteToBuyer PaymentRequest_Tran sactionid Optional Displays a note to buyers in the cart review area below the total amount. Use the note to tell buyers about items in the cart, such as your return policy or that the total excludes shipping and handling. Optional Transaction identification number of the transaction that was created. NOTE :This field is only returned after a successful transaction for DoExpressCheckout has occurred. NoteToBuyer=Your message Maximum Length : 50 PaymentRequest_InvNum = Your invoice number Payment Details Item Type Fields PaymentRequest_Item Namen PaymentRequest_Item Descriptionn PaymentRequest_Item Amtn PaymentRequest_Item Numbern Optional Item name. You can specify up to multiple items, where n represents index of items. Optional Item description You can specify up to multiple items, where n represents index of items. Optional Cost of item.you can specify up to multiple items, where n represents index of items. Optional Item number. You can specify up to multiple items, where n represents index of items. Maximum Length : 50 PaymentRequest_ItemName = Your item name Maximum Length : 50 PaymentRequest_ItemDescripti on = Your item description Type : Decimal PaymentRequest_ItemAmt = 1000 Maximum Length : 50 PaymentRequest_ItemNumber = 1000 MyanPay Express Checkout Integration Guide Page 25
MyanPay Express Checkout Integration Guide 26 PaymentRequest_Item Qtyn Optional Item quantity. You can specify up to multiple items, where n represents index of items. Type : int PaymentRequest_ItemQty = 3 PaymentRequest_Item WeightValuen, PaymentRequest_Item WeightUnitn PaymentRequest_Item LengthValuen, PaymentRequest_Item LengthUnitn PaymentRequest_Item WidthValuen, PaymentRequest_Item WidthUnitn PaymentRequest_Item HeightValuen, PaymentRequest_Item HeightUnitn PaymentRequest_Item Urln Optional Item weight corresponds to the weight of the item. You can pass thisdata to the shipping carrier as is without having to make an additional databasequery. You can specify up to multiple items, where n represents index of items. Optional Item length corresponds to the length of the item. You can pass thisdata to the shipping carrier as is without having to make an additional databasequery. You can specify up to multiple items, where n represents index of items. Optional Item width corresponds to the width of the item. You can pass thisdata to the shipping carrier as is without having to make an additional databasequery. You can specify up to multiple items, where n represents index of items. Optional Item height corresponds to the height of the item. You can pass thisdata to the shipping carrier as is without having to make an additional databasequery. You can specify up to multiple items, where n represents index of items. Optional URL for the item. You can specify up to multiple items, where n represents index of items. PaymentRequest_ItemWeightValue = 10 Maximum Length : 20 PaymentRequest_ItemWeightUnit = Kg PaymentRequest_ItemLengthValue = 10 Maximum Length : 20 E.g.PaymentRequest_ItemWeightU nit = Inches PaymentRequest_ItemWidthValue = 10 Maximum Length : 20 PaymentRequest_ItemWidthUnit = Inches PaymentRequest_ItemHeightVal ue = 10 Maximum Length : 20 PaymentRequest_ItemHeightUnit = Inches Maximum Length : 150 PaymentRequest_ItemUrl = Your item url MyanPay Express Checkout Integration Guide Page 26
MyanPay Express Checkout Integration Guide 27 PaymentRequest_Item Categoryn Optional Indicates whether an item is digital or physical. For digital goods, this field isrequired and must be set to Digital. You can specify up to multiple items, where n represents index of items. It is one of the following values: Digital Physical PaymentRequest_ItemCategory = Your item category Buyer Details Fields EcBuyerId EcBuyerUserName EcBuyerRegistrationD ate Optional The unique identifier provided by marketplaces site for this buyer. The value may or may not be the same as the username of MyanPay. Optional The user name of the user at the marketplaces site. Optional The registration date of the user at the marketplaces site. EcBuyerId = Your buyer Id EcBuyerUserName = Your buyer name EcBuyerName = Your registration date ( MM/DD/YYYY) SetExpressCheckout Response Message SetExpressCheckoutReponse Fields Field Description Type/Format Token A time stamped token by which you identify to MyanPay that you are processing this payment with Express Checkout. The token expires after three hours. If you set the token in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request. Maximum Length : 63 Token = MyanPay- U2DWK0SI4C7C5AOBX856T7 MyanPay Express Checkout Integration Guide Page 27
MyanPay Express Checkout Integration Guide 28 GetExpressCheckout Request Message GetExpressCheckout Request Fields Field Required Description Type/Format Method Required Must be DoExpressCheckout. Method = DoExpressCheckout Token Required A time stamped token, the value of which was returned by SetExpressCheckout response. Maximum Length : 63 Token=MyanPay- U2DWK0SI4C7C5AOBX856T7 GetExpressCheckout Response Message GetExpressCheckout Response Fields Field Description Type/Format Token PaymentRequest_Amt The time stamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckout request. The expected maximum total amount of the complete order, including shipping cost and tax charges. Maximum Length : 63 Token=MyanPay- U2DWK0SI4C7C5AOBX856T7 Type : Decimal Range : 50 to 100000 Kyats PaymentRequest_Amt = 10000 PaymentAction NoShipping How you want to obtain payment. Sale This is a final sale for which you are requesting payment. Determines where or not current transaction needs shipping address fields on the MyanPay pages. For digital goods, this field is set to true.if NoShipping is not included in your request, default value is false. true Current transaction does not need the shipping address on the MyanPay pages. false Current transaction needs the shipping address on the MyanPay pages. PaymentAction = Sale Type : Boolean NoShipping = false MyanPay Express Checkout Integration Guide Page 28
MyanPay Express Checkout Integration Guide 29 CustomShipping Determines whether or not the buyer will use custom delivery address. If CustomShipping value is set to false,we will take the shipping address in MyanPay as buyer s delivery address.if CustomShipping is not included in your request, default value is false. True The buyer will use custom delivery address. False The buyer will use shipping address in MyanPay. Type : Boolean CustomShipping = true Shipping Options Type Fields ShippingOptionIsDefa ult ShippingOptionName ShippingOptionAmou nt Default shipping option displayed on the MyanPay pages. true This is the default shipping option. MyanPay displays this option and its amount by default. false This shipping option and its amount are not displayed as the default. NOTE :There must be ONE and ONLY ONE default. It is not OK to have no default. Internal name of the shipping option such as Air, Ground, Expedited, and so forth. Amount of the shipping option. Type : Boolean ShippingOptionIsDefault = true ShippingOptionName = Ground Type : Decimal ShippingOptionAmount = 1000 ShippingOptionLabel The label for the shipping option as displayed to the buyer. Examples: Air: Next Day, Expedited: 3-5 days, Ground: 5-7 days. These labels can be localized based on the buyer s locale. ShippingOptionLabel = Air:Next Day MyanPay Shipping Address Type Fields PaymentRequest_Shi ptocity PaymentRequest_Shi ptostate PaymentRequest_Add ressline Name of city. It is required if using a shipping address. State or province. It is required if using a shipping address. Address Line may include home number,streetnumber,township and city. Maximum Length : 70 PaymentRequest_ShipToCity = Pathein Maximum Length : 50 PaymentRequest_ShipToState = Ayeyawadi Maximum Length : 500 PaymentRequest_AddressLine= No.2,Rose Street,Pathein MyanPay Express Checkout Integration Guide Page 29
MyanPay Express Checkout Integration Guide 30 Custom Delivery Address Type Fields PaymentRequest_Cus tomdeliveryname PaymentRequest_Cus tomdeliveryemail PaymentRequest_Cus tomdeliveryphonenu mber PaymentRequest_Cus tomdeliveryaddress PaymentRequest_Cus tomdeliverycity PaymentRequest_Cus tomdeliverycountry The name who received the buyer s goods. Name of email address of receiver. Phone number of receiver. Address may include home number, street number, township and city. Name of City that the receiver stay. Country that the receiver stay. Maxiumum Length : 150 PaymentRequest_CustomDeliveryN ame= U Hla Maxiumum Length : 150 PaymentRequest_CustomDeliveryE mail= uhla99@gmail.com Maxiumum Length : 20 PaymentRequest_CustomDeliveryP honenumber = 09xxxxxxx PaymentRequest_CustomDeliveryA ddress = No.1, Rose Road, Insein Township, Yangon Maxiumum Length : 20 PaymentRequest_CustomDeliveryCi ty=yangon Maxumum Length : 20 PaymentRequest_CustomDeliveryC ountry=myanmar Payment Details Type Fields PaymentRequest_Ite mtotalamt PaymentRequest_Shi ppingtotalamt Sum of cost of all items in this order. MyanPay recommends that you pass the same value in the call to DoExpressCheckout that you passed in the call to SetExpressCheckout. Total shipping costs for this order. Type : Decimal PaymentRequest_ItemTotalAmt = 6700 Type : Decimal PaymentRequest_ShippingTotalAmt = 500 MyanPay Express Checkout Integration Guide Page 30
MyanPay Express Checkout Integration Guide 31 PaymentRequest_Ins urancetotalamt PaymentRequest_Shi ppingdiscamt PaymentRequest_Ins uranceoptionoffered PaymentRequest_Han dlingtotalamt PaymentRequest_Tax TotalAmt PaymentRequest_Des c PaymentRequest_Cus tom PaymentRequest_Inv Num Total shipping insurance costs for this order. The value must be a non-negative currency amount or null if insurance options are offered. Shipping discount for this order, specified as a negative number. Indicates whether insurance is available as an option the buyer can choose on the MyanPay Review page. true The Insurance option displays the string Yes and the insurance amount. If true, the total shipping insurance for this order must be a positive number. false The Insurance option displays No. Total handling costs for this order. Sum of tax for all items in this order. Description of items the buyer is purchasing. A free-form field for your own use. Your own invoice or tracking number. Type : Decimal PaymentRequest_InsuranceTotalA mt = 300 Type : Decimal PaymentRequest_ShippingDiscAmt = -200 Type : Boolean PaymentRequest_InsuranceOption Offered = true Type : Decimal PaymentRequest_HandlingTotalAmt = 500 Type : Decimal PaymentRequest_HandlingTotalAmt = 300 Maximum Length : 50 PaymentRequest_Desc = Your description Maximum Length : 255 PaymentRequest_Custom = Your custom value Maximum Length : 127 PaymentRequest_InvNum = Your invoice number MyanPay Express Checkout Integration Guide Page 31
MyanPay Express Checkout Integration Guide 32 PaymentRequest_Tra nsactionid Transaction identification number of the transaction that was created. NOTE :This field is only returned after a successful transaction for DoExpressCheckout has occurred. Maximum Length : 50 PaymentRequest_InvNum = Your invoice number Shipping Options Type Fields ShippingOptionIsDefa ult ShippingOptionName ShippingOptionAmou nt ShippingOptionLabel Default shipping option displayed on the MyanPay pages. True This is the default shipping option. MyanPay displays this option and its amount by default. False This shipping option and its amount are not displayed as the default. NOTE :There must be ONE and ONLY ONE default. It is not OK to have no default. Internal name of the shipping option such as Air, Ground, Expedited, and so forth. Amount of the shipping option. The label for the shipping option as displayed to the buyer. Examples: Air: Next Day, Expedited: 3-5 days, Ground: 5-7 days. These labels can be localized based on the buyer s locale. Type : Boolean ShippingOptionIsDefault = true ShippingOptionName = Ground Type : Decimal ShippingOptionAmount = 1000 ShippingOptionLabel = Air:Next Day Payment Details Item Type Fields PaymentRequest_Ite mnamen PaymentRequest_Ite mdescriptionn Item name. You can specify up to multiple items, where n represents index of items. Item description. You can specify up to multiple items, where n represents index of items. Maximum Length : 50 PaymentRequest_ItemName = Your item name Maximum Length : 50 PaymentRequest_ItemDescription = Your item description MyanPay Express Checkout Integration Guide Page 32
MyanPay Express Checkout Integration Guide 33 PaymentRequest_Ite mamtn PaymentRequest_Ite mnumbern PaymentRequest_Ite mqtyn Cost of item. You can specify up to multiple items, where n represents index of items. Item number. You can specify up to multiple items, where n represents index of items. Item quantity. You can specify up to multiple items, where n represents index of items. Type : Decimal PaymentRequest_ItemAmt = 1000 Maximum Length : 50 PaymentRequest_ItemNumber = 1000 Type : int PaymentRequest_ItemQty = 3 PaymentRequest_Ite mtaxamtn PaymentRequest_Ite mweightvaluen, PaymentRequest_Ite mweightunitn PaymentRequest_Ite mlengthvaluen, PaymentRequest_Ite mlengthunitn PaymentRequest_Ite mwidthvaluen, PaymentRequest_Ite mwidthunitn Item sales tax. You can specify up to multiple items, where n represents index of items. Item weight corresponds to the weight of the item. You can pass thisdata to the shipping carrier as is without having to make an additional databasequery.you can specify up to multiple items, where n represents index of items. Item length corresponds to the length of the item. You can pass thisdata to the shipping carrier as is without having to make an additional databasequery.you can specify up to multiple items, where n represents index of items. Item width corresponds to the width of the item. You can pass thisdata to the shipping carrier as is without having to make an additional databasequery.you can specify up to multiple items, where n represents index of items. Type : Decimal PaymentRequest_ItemTaxAmt = 150 Maximum Length : 50 PaymentRequest_ItemWeightValue = 10 PaymentRequest_ItemWeightUnit = Kg Maximum Length : 50 PaymentRequest_ItemLengthValue = 10 PaymentRequest_ItemWeightUn it = Inches Maximum Length : 50 PaymentRequest_ItemWidthValue = 10 PaymentRequest_ItemWidthUnit = Inches MyanPay Express Checkout Integration Guide Page 33
MyanPay Express Checkout Integration Guide 34 PaymentRequest_Ite mheightvaluen, PaymentRequest_Ite mheightunitn PaymentRequest_Ite murln PaymentRequest_Ite mcategoryn Item height corresponds to the height of the item. You can pass thisdata to the shipping carrier as is without having to make an additional databasequery.you can specify up to multiple items, where n represents index of items. URL for the item. You can specify up to multiple items, where n represents index of items. Indicates whether an item is digital or physical. For digital goods, this field isrequired and must be set to Digital. You can specify up to multiple items, where n represents index of items. It is one of the following values: Digital Physical Maximum Length : 50 PaymentRequest_ItemHeightValue = 10 PaymentRequest_ItemHeightUnit = Inches Maximum Length : 150 PaymentRequest_ItemUrl = Your item url PaymentRequest_ItemCategory = Your item category Buyer Details Fields EcBuyerId The unique identifier provided by marketplaces site for this buyer. The value may or may not be the same as the username of MyanPay. EcBuyerId = Your buyer Id EcBuyerName The user name of the user at the marketplaces site. EcBuyerRegistrationD ate The registration date of the user at the marketplaces site. EcBuyerName = Your buyer name EcBuyerName = Your registration date Payer Information Fields BusinessCompanyNa me Buyer s company name. It is required when the buyer account is business account. Maximum Length : 50 MyanPay Express Checkout Integration Guide Page 34
MyanPay Express Checkout Integration Guide 35 DisplayName Buyer s business name. Maximum Length : 40 PayerId Unique MyanPay Customer Account identification number. Type : int PayerStatus Status of buyer. It is one of the following values: verified unverified PhoneNumber Buyer s contact phone number. Maximum Length : 50 PrimaryEmailAdress Email address of buyer. DoExpressCheckout Request Message DoExpressCheckout Request Fields Field Required Description Type/Format Method Required Must be DoExpressCheckout. Method = DoExpressCheckout Token Required A time stamped token by which you identify to MyanPay that you are processing this payment with Express Checkout. The token expires after three hours. If you set the token in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request. PaymentAction Optional How you want to obtain payment. Sale This is a final sale for which you are requesting payment. Maximum Length : 63 Token = MyanPay- U2DWK0SI4C7C5AOBX856T7 PaymentAction = Sale PayerId Required Unique MyanPay Customer Account identification number. PaymentRequest_Amt Required The expected maximum total amount of the complete order, including shipping cost and tax charges. Length : 20 PayerId = Your payer Id Type : Decimal Range : 50 to 100000 Kyats PaymentRequest_Amt = 10000 MyanPay Express Checkout Integration Guide Page 35
MyanPay Express Checkout Integration Guide 36 DoExpressCheckout Response Message DoExpressCheckout Response Fields Field Description Type/Format Token PaymentInfo_Amt A time stamped token by which you identify to MyanPay that you are processing this payment with Express Checkout. The token expires after three hours. If you set the token in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request. The expected maximum total amount of the complete order, including shipping cost and tax charges. Maximum Length : 63 Token = MyanPay- U2DWK0SI4C7C5AOBX856T7 Type : Decimal PaymentInfo_TransactionID Unique transaction ID of the payment. Type : Int PaymentInfo_TransactionType Transaction type of the payment. PaymentInfo_OrderTime Transaction order time of the payment. Type : DateTime PaymentInfo_PaymentStatus Transaction payment status of the payment. PaymentInfo_TaxAmt Transaction tax amount of the payment. Type : Decimal PaymentInfo_FeeAmt Transaction fee amount of the payment. Type : Decimal MyanPay Express Checkout Integration Guide Page 36
MyanPay Express Checkout Integration Guide 37 Trouble Shooting Your Express Checkout Integration If you have trouble with your integration, there are several things you can check first. Error Handling The response message contains an ACK value. Unless ACK=Success, you must check furtherfor an error or warning message. You must check each response from the MyanPay server for an indication that an error occurred. Because there are several warning and failure values, the safest way to check the response is to check for ACK=Success. If the ACK returns any other value, you must examine the response for error numbers and messages. A non-successful response can contain more than one error number and message. Error fields start with ERRORCODE. There are two messages for each error number, ErrorShortMessage and ErrorDetailMessage; for example some error code for ErrorShortMessageMessage anderrordetailmessage is PaymentRequest_Amt value is wrong. IMPORTANT:Because error numbers are not guaranteed to be unique, you must use both the number and the messages to determine the appropriate action to take when an error occurs. Some errors are transitory in nature and you can retry the operation; for example, an error thatindicates a problem with MyanPay. If the problem persists for more than an hour, it is probablyrelated to your Express Checkout implementation because MyanPay servers are up and running almost all of the time. Some errors indicate problems with the buyer s account; for example, the funding source is no longer valid or the buyer s account is restricted in some way. The error message has enough information to create a message on your website that tells the buyer how to resolve the issue. Often, you simply prompt the buyer to choose a different funding source. Because these kinds of problems can indicate a risk issue, you do not want to ship goods until the issue has been resolved. Other errors indicate a problem with your integration, such as accepting invalid input on your website and passing it in your request message to MyanPay. You need to perform sufficient testing using the Virtualbox to prevent problems from arising after going live. Logging API Operations You should log basic information from the request and response messages of each MyanPay API operation you execute. You must log the Correlation ID from the response message, whichidentifies the API operation to MyanPay. All responses to MyanPay API operations contain information that may be useful for debugging purposes. In addition to logging the Correlation ID from the response message, you can log other information, such as the transaction ID and timestamp, to enable you to review a transaction on the MyanPay website or through the API. You could implement a scheme that logs the entire request and response in a verbose mode; however, you should never log the password from a request. Encoding and Decoding Values You must encode and decode all values sent in API operations. Only encode the value and notthe name in NVP. You must encode all request field values in a request to MyanPay and decode all field values in the response. You must encode and decode individual values; do not encode or decode the entire message. Browsers often attempt to encode and decode messages that are redirected to or from them; however, you must verify that encoding and decoding is done correctly and only to field values. MyanPay Express Checkout Integration Guide Page 37
MyanPay Express Checkout Integration Guide 38 MyanPay NVP API Basics The Name-Value Pair (NVP) API provides parameter-based association between request andresponse fields of a message and their values. The request message is sent from your website by the API, and a response message is returned by MyanPay using a client-server model in which your site is a client of the MyanPay server. NOTE: The MyanPay API also uses name-value pairs to provide parameter-based association between request and response fields of a message and their values; however, the MyanPay API is not the same as the NVP API. Myanpay API Client-Server Architecture The MyanPay API uses a client-server model in which your website is a client of the MyanPay server. A page on your website initiates an action on a MyanPay API server by sending a request to the server. The MyanPay server responds with a confirmation that the requested action was taken or indicates that an error occurred. The response might also contain additional information related to the request. The following diagram shows the basic requestresponse mechanism. For example, you might want to obtain the buyer s shipping address from MyanPay. You caninitiate a request specifying an API operation to obtain buyer details. The response from the MyanPay API server contains information about whether the request was successful. If theoperation succeeds, the response contains the requested information. In this case, the response contains the buyer s shipping address. If the operation fails, the response contains one or more error messages. MyanPay Name-Value Pair API Requests and Responses To perform a MyanPay NVP API operation, you send an NVP-formatted request to a MyanPay NVP server and interpret the response. In the following diagram, your website generates a request. The request is executed on a MyanPay server and the response is returned to your site. The Requestidentifies: The name of the API operation, specified by method=name, to be performed and its version NOTE: After the method parameter, you can specify the parameters in any order. Credentials that identify the MyanPay account making the request MyanPay Express Checkout Integration Guide Page 38
MyanPay Express Checkout Integration Guide 39 Request-specific information that controls the API operation to be performed A MyanPay API server performs the operation and returns a response. The Response contains: An acknowledgement status that indicates whether the operation was a success or failure and whether any warning messages were returned Information that can be used by MyanPay to track execution of the API operation Response-specific information required to fulfil the request Multiple API Operations Some of the features, such as Express Checkout, require you to call multiple API operations.typically, these features require you to: 1. Invoke an API operation, such as SetExpressCheckout, that sets up the return URL to which MyanPay redirects your buyer s browser after the buyer finishes on MyanPay. Othersetup actions also can be performed by this API operation. 2. Invoke additional API operations after receiving the buyer s permission on MyanPay, for example, GetExpressCheckout or DoExpressCheckout. The following diagram shows the execution flow between your site and MyanPay Token Usage Typically, the API operation that sets up a redirection to MyanPay returns a token. This token ispassed as a parameter in the redirect to MyanPay. The token also might be required in relatedapi operations. MyanPay Express Checkout Integration Guide Page 39
MyanPay Express Checkout Integration Guide 40 NVP Format NVP is a way of specifying names and values in a string. NVP is the informal name for thequery in the URI specification. The NVP string is appended to the URL.An NVP string conforms to the following guidelines The name is separated from the value by an equal sign (=). For example: FIRSTNAME=Sandar Name-value pairs are separated by an ampersand (&). For example: FIRSTNAME=Sandar&MIDDLENAME=Win&LASTNAME=Myint The values for each value in an NVP string are URL-encoded. Name-value pairs are separated by an ampersand (&). For example: FIRSTNAME= Sandar&MIDDLENAME=Win&LASTNAME=Myint The values for each value in an NVP string are URL-encoded. Creating an NVP Request The Name-Value Pair request format specifies the API operation to perform, credentials that authorize Myanpay to access your account, and fields containing additional information to be used in the request. Specifying the MyanPay API Operation For the NVP version of the MyanPay API, you must specify the name of the MyanPay API operation to execute in each request along with the version of the API operation. The following diagram shows the API operation part of an NVP request A method specifies the MyanPay operation you want to execute, and each method is associatedwith a version. Together, the method and version define the exact behaviour of the APIoperation. Typically, the behaviour of an API operation does not change between versions;however, you should carefully retest your code whenever you change a version. To specify a method and version number: 1. Choose the MyanPay API operation you want to use. METHOD=operation 2. Choose the appropriate version. In most cases, you should use the latest version of the API operation. VERSION=version_number MyanPay Express Checkout Integration Guide Page 40
MyanPay Express Checkout Integration Guide 41 Specifying an API Credential You must specify API credentials in each request to execute a MyanPay API operation.when you execute a MyanPay API operation, you use credentials, such as a signature, toauthenticate that you are requesting the API operation. The following diagram shows the APIcredentials part of an NVP request. IMPORTANT: You must protect the values for USER, PWD, and SIGNATURE in yourimplementation. Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user that executes your ecommerce application can access it. To enable MyanPay to authenticate your request: 1. Specify the API username associated with your account. ApiUserName =Your_API_username 2. Specify the password associated with the API username. ApiPassword =Your_API_password 3. Specify the API signature ApiSignature =Your_API_signature URL Encoding All requests to execute MyanPay API operations sent using HTTP must be URL-encoded. Theencoding ensures that you can transmit special characters, characters that are not allowed in aurl, and characters that have special meaning in a URL, such as the equal sign andampersand. The MyanPay NVP API uses the HTTP protocol to send requests and receive responses from a MyanPay API server. You must encode all data sent using the HTTP protocol because data that is not encoded could be misinterpreted as part of the HTTP protocol instead of part of therequest. Most programming languages provide a way to encode strings in this way. You should consistently URL-encode the complete API request; otherwise, you may find that unanticipated data causes an error. NOTE: An HTTP form is automatically URL-encoded by most browsers. For example, consider the following NVP string: NAME=SandarWin&COMPANY=R. H. Moore & Associates It is encoded as follows: NAME=Sandar+Win&COMPANY=R%2E+H%2E+Moore+%26+Associates Executing NVP API Operations You execute a MyanPay NVP API operation by submitting an HTTPS POST request to a MyanPay API server, or by using CURL or another mechanism to provide secure access between the buyer s browser and the MyanPay API server. For example, you might implement a system in which the buyer s browser remains a client of your server and your server becomes a client of the MyanPay API server. MyanPay Express Checkout Integration Guide Page 41
MyanPay Express Checkout Integration Guide 42 Specifying a MyanPay Server You execute a MyanPay API operation by submitting the request to a MyanPay API server.to execute a MyanPay NVP API operation, submit the request to one of the following endpoints: Server end point https://www.myanpay-virtualbox.com/ https://www.myanpayvirtualbox.com/personal/expresscheckout/express CheckOutRequestHandler.aspx https://www.myanpayvirtualbox.com/personal/expresscheckout/getexpress CheckOutRequestHandler.aspx https://www.myanpayvirtualbox.com/personal/expresscheckout/doexpress CheckOutRequestHandler.aspx Description MyanPay virtual box site for testing MyanPay account s features and Express checkout MyanPay virtual box for use with API signatures; use for testing with SetExpressCheckOut Operation. MyanPay virtual box for use with API signatures; use for testing with GetExpressCheckOut Operation. MyanPay virtual box for use with API signatures; use for testing with DoExpressCheckOut Operation. NOTE: You must use different API credentials for each server end point. Typically, you obtainapi credentials when you test in the MyanPay virtual box and then obtain another set ofcredentials for the production server. You must change each API request to use thenew credentials when you go live. Logging API Operations You should log basic information from the request and response messages of each MyanPay API operation you execute. You must log the Correlation ID from the response message, whichidentifies the API operation to MyanPay. All responses to MyanPay API operations contain information that may be useful for debugging purposes. In addition to logging the Correlation ID from the response message, you can log other information, such as the transaction ID and timestamp, to enable you to review a transaction on the MyanPay website or through the API. Responding to an NVP Response The Name-Value Pair response consists of the answer to the request as well as common fieldsthat identify the API operation and how it was executed.the following diagram shows fields in the response to a MyanPay NVP API operation: MyanPay Express Checkout Integration Guide Page 42
MyanPay Express Checkout Integration Guide 43 Common Response Fields The MyanPayAPI always returns common fields in addition to fields that are specific to the requested MyanPay API operation. A MyanPayAPI response includes the following fields Field ACK CORRELATIONID TIMESTAMP VERSION BUILD Description Acknowledgement status, which is one of the following values: Success indicates a successful operation. SuccessWithWarning indicates a successful operation; however, there are messages returned in the response that you should examine. Failure indicates the operation failed; the response also contains one or more error messages explaining the failure. FailureWithWarning indicates that the operation failed and that there are messages returned in the response that you should examine. Correlation ID, which uniquely identifies the transaction to MyanPay. The date and time that the requested API operation was performed. The version of the API. The sub-version of the API. Error Responses If the ACK value is not Success, API response fields may not be returned. An error responsehas the following general format. Format of an Error Response Response Fields onerror ACK=fail&TIMESTAMP=date/timeOfResponse& CORRELATIONID=debuggingToken&VERSION=VersionNo& BUILD=buildNumber&L_ERRORCODE0=errorCode& SHORTMESSAGE=shortMessage& LONGMESSAGE=longMessage URL Decoding All responses to HTTP POST operations used by the MyanPay NVP API must be decoded.the MyanPay NVP API uses the HTTP protocol to send requests and receive responses from a MyanPay API server. You must decode all data returned using the HTTP protocol so that it canbe displayed properly. Most programming languages provide a way to decode strings. Note: Myanpay VirtualBox site ( https://www.myanpay-virtualbox.com) is just for testing purpose. If you want to use MyanPay in your web site, you need to use https://www.myanpay.com.mm instead of https://www.myanpayvirtualbox.com. Note: MyanPay Virtual Box Website သည developer မ စမ သပ အသ ပ ရန အတ က သ ဖစ သည လ ၾက မင မ Website တ င အမ န တကယ င ၾက ဖင အသ ပ မည ဆ ပ ကhttps://www.myanpayvirtualbox.comအစ https://www.myanpay.com.mmက ပ င လ အသ ပ ရမည ဖစ သည MyanPay Express Checkout Integration Guide Page 43