API Integration Payment21 Button

Transcription

1 API Integration Payment21 Button The purpose of this document is to describe the requirements, usage, implementation and purpose of the Payment21 Application Programming Interface (API). The API will allow merchants to send payment requests through an online, consistently available interface which can integrate well with any existing systems. Version Last updated 07/08/2013 Version No 1.03 Owner Payment21 LLC Document Name Payment21_Button_API Revision History Date: Description: Initials: Version: Deleted path: /interfaces/mmltdonline/ YJ Renamed the user-id and password to api key and api SS 1.03 id Page 1 of 15

2 Confidentiality Notice This document and the information contained herein are for exclusive use of the recipient(s). Unless expressly stated otherwise in the document or with the prior written consent of Payment21, partial or full copies of this document cannot be disclosed to any other persons or entities other than the recipient(s), and subject to acceptance of certain conditions under which access is granted. The content of this document may not be disclosed, in whole or in part in any prospectus, statement or documentation for registration, any documentation that is public domain, financing agreement, and any other agreements or public or private documents. The information contained in this document is for the exclusive use of the person or entity to which it is addressed, containing confidential information and/or privileged information. Any review, retransmission, dissemination or other use by any person or any entity other than the recipient of this document is strictly prohibited. If you have received this document in error, please contact the sender and delete the contents of any , application or computer files. Contact Information Payment21 LLC Development Support 427 N. Tatnall Street, #42034 Wilmington, DE U.S.A. Page 2 of 15

3 Table of Contents 1. Payment21 has several integration methods available Payment21 Button What the merchant s customers will see How to integrate Input Parameters Response Parameters HTML Code API Test Account Appendix API Response & Error Codes Page 3 of 15

4 1. Payment21 has several integration methods available In order to begin accepting check payments online, you must connect your website to our payment gateway. There are several integration methods available to suit our diverse client base. For small and mid-size businesses we offer the following easy methods of integration: 1. Payment21 Button 2. Payment21 Simple API For large scale enterprises & financial institutions we suggest using the main API: 3. Payment21 XML/SOAP API For specified business requests we offer the following methods of integration: 4. Payment21 Recurring Billing 5. Shopping Carts The API's are easy to modify and you will be able to process transactions in a very short time. 1. Payment21 Button: Merchant has to define some HTML-code with SUBMIT action that posts the data to Payment21 side. If you choose Payment21 Button, your customers will be directed to our website to enter their check data, to validate the data and to submit the check. Afterwards the customer is redirected to your site again. The transaction goes directly through Payment21 's check verification and validation process. As soon as the transaction is approved, Payment21 creates a digital check and transmits the data to the bank for deposit. The check writer and the merchant get a confirmation with the transaction information and the status of success or denial of the transaction. 2. Payment21 Simple API: We provide the necessary HTML code of the web form which contains a Check Image. Merchants only have to copy & paste this provided HTML code into their website application. If you choose Payment21 Simple API, your customer will see the check picture to be filled out for the Instant echeck payment directly on your website. Customers have to enter their check data, to validate the data and to submit the check on your page. If you want to display the confirmation page on your site, you can use the redirect option. The customer data will be transferred to Payment21 system for verification, validation and processing. Page 4 of 15

5 3. Payment21 XML/SOAP API: A merchant can access the API by implementing some programming codes in the merchant s website to communicate with our web service via the API. Our XML/SOAP API option is for larger merchants who take advantage of the full-fledged integration service. This solution involves some technical development on the merchant s end, but in return, allows the highest degree of customization. Your Software Developer integrates the XML API call directly in your application. If your customer chooses Payment21 Instant echeck (P21PayByCheck)" as a payment method, the merchant s system creates the XML Request in accordance to the XML Integration Documentation and sends it to the Payment21 web service. Payment21 responds by letting your system know if the information is valid. Your system can then display the confirmation page to the user to confirm the purchase and finalize the transaction. Finally you can display the transaction summary to the user with all payment details as payment confirmation. Benefit for the merchant: full session control and the use of the advanced API Methods to communicate with Payment21 and get more details from the system. At the same time, the merchant has to take into account the relative high integration time and development resources. 4. Payment21 Recurring Billing: The only integration, you need, is to create the HTML FORM with HIDDEN fields pre-filled with customer data. Put the Payment21 Recurring Billing URL into the ACTION-Attribute of your web form and add some HTML-code, that could trigger the SUBMIT Action. This could be a link, an image or some other element. If you are selling subscriptions or would like to allow your customers to pay by installment the Payment21 Recurring Billing is the right solution. Your customer will be directed via a secure connection to Payment21 website. Once the customer data is entered, the system automatically issues an Instant echeck using the predefined recurring billing plan. Options are daily, weekly, bi-weekly, first of the month, last of the month, day of month, quarterly or yearly. The periodic payment can be stopped under the company settings on your ideposit account. The consumer gets an notification to stop further periodic payments. Upon your wish we can inform the customer via about the successful payment. 5. Shopping Carts Payment21 is integrated with several shopping carts allowing quick integration with our payment gateway: CS Cart, Joomla-VirtueMart, oscommerce, opencart, Magento ecommerce Go to for more information. Begin accepting Instant echeck payments in 5 easy steps. Sign up on Page 5 of 15

6 2. Payment21 Button The Payment21 Button method provides an offsite check page accessed by a customizable button. Your customer will be redirected via a secure connection to the Payment21 website to enter the check data. You can pass your details using hidden HTML tags including your access, product and customer details by POST method. You can redesign the button to fit your corporate identity. The posted customer data, customer data such as first name, last name, address and contact information, will automatically be populated on the Instant echeck. The check needs to be completed by the customer populating or changing for instance the bank routing number, bank account number and amount. After completing the Instant echeck the check writer provides his/her address, accepts the terms and conditions and explicitly agrees with the payment. The transaction goes directly through the Payment21 check verification and validation process. As soon as the transaction is approved, Payment21 creates a check image or a NACHA-standard ACH file record of the Instant echeck and deposits the check at the bank. The check writer gets a confirmation with the transaction information and the status of success or denial of the transaction. The check writer also gets access information to our Billing Support Module. In this module the check writer can review his transactions and query Payment21 Billing Support by . After submitting the transaction, Payment21 redirects back to merchant's URL or our default URL. If you use your own URL you can allow your customer to continue his visit on your page. 2.1 What the merchant s customers will see Once the API is implemented, the merchant s available payment methods will include another payment option: Instant echeck. After choosing different products or services on the merchant s website and proceeding with the check-out page, customer can select his/her payment option: Page 6 of 15

7 After clicking the Continue button, the API will redirect the customer transactional process to the Payment21 side with the following Instant echeck payment form: After submitting the check details and accepting the terms and conditions and explicitly agreeing with the payment the customer is presented with a Confirmation Page. This Confirmation Page can be customized to your liking. Page 7 of 15

8 If the customer needs to go back for corrections, he can click the Edit check button, which will take him/her back to the Instant echeck form. By submitting the Instant echeck for processing, the completed transaction is forwarded to Payment21 side via API link for check data verification/validation. We offer customizable Verification Loop and Proprietary Mitigation Monitor. Page 8 of 15

9 Once submitted your payment confirmation page is shown. 2.2 How to integrate A merchant can access the API by implementing the POST hidden Parameters from the Payment21 Button (see HTML code below) and send the API-call with them. API Link for the Input parameters to be posted: The web service can be accessed using POST-Parameters with the following link: Input Parameters Field Description Type(Min length, Max length) mm_app_id API ID as assigned by Payment21.com Assigned by Payment21.com mm_app_key API KEY as assigned by Payment21.com Assigned by Payment21.com mm_ip_address Merchant s Server IP address from where simple API form will POST-Parameters Merchant s Server IP address registered with Payment21.com mm_company Merchant company id as assigned by Assigned by Payment21.com Page 9 of 15

10 mm_redirecturl mm_errorurl Field Payment21.com Description This is Merchant s site URL to re-direct the page after successfully submission of check. This is Merchant s site URL to re-direct the page after Error in submission of check or by pressing Cancel. mm_updatedby Merchant UpdatedBy name. (Default: xxxx) String(1,50) mm_partnertransid Merchant partner transaction id (Optional) String(0,36) mm_merchantcustomerid Merchant customer id (Optional) String(0,36) mm_merchanttransid Merchant transaction id (Optional) String(0,36) mm_firstname Customers First Name String(1,50) mm_lastname Customers Last Name String(1,50) Type(Min length, Max length) Standard Web URL format. Prefix by or Standard Web URL format. Prefix by or mm_dateofbirth Customer date of birth Date yyyy-mm-dd mm_address Customer address field one String(1,50) mm_address2 Customer address field two (Optional) String(0,50) mm_last4ssn Customer last 4 digits of Social Security String(4,4) mm_city Customer address city String(1,50) mm_state Customer address state code String(2,2) mm_zipcode 5 digit zip code of the county String(1,5) mm_country Country field, for example US String(2,50) (Default: US) mm_passportnr Customer Passport number (Optional) String(0,200) mm_driverlicensenr Customer Driving License Number (Optional) String(0,200) mm_driverlicensenr Customer Driving License Number (Optional) String(0,200) mm_phone mm_ Customer Phone Number (Format should be in xxx xxx xxxx) Customer address. This is the confirmation that sends to customer. includes all check related information like Transaction Id, Check status, Check amount, account number, check date. String(12,12) + regular expression Standard regular expression for mm_amount Check Amount String(1,50) converted to decimal mm_routingcode Customer bank routing number String(9,9) mm_accountnr Customer bank account number String(1,20) mm_checknr Check Number String(1,10) Page 10 of 15

11 2.4 Response Parameters The API will return all the success/failure/exception responses. All types of errors and exceptions will be handled at our end. Note: 1. We set the Check date and time to the current date and time the check reaches our system. 2. mm_ is the confirmation parameter that is used to send an to the customer. That includes all check related information like Transaction Id, Check status, Check amount, account number, check date. This confirmation is like a payment receipt for the customer. 3. Address validation, account verification and other business rules can be configured to your individual needs. Defaults setting are provided initially. 2.5 HTML Code <! START > <!-- Address to Payment-Button Integration --> <form action=" name="paybycheck" method="post"> <!- Replace below with your company information provided by Payment21 after signup --> <input type="hidden" name="mm_company" value="687" /> <input type="hidden" name="mm_app_id" value="abccompany" /> <input type="hidden" name="mm_app_key" value="abc12345" /> <input type="hidden" name="mm_ip_address" value=" " /> <!-- Your success URL to go back to your side --> <input type="hidden" name="mm_redirecturl" value=" /p21safecheck/makepayment.aspx /> <!-- Your error URL to go back, if the customer press Cancel Button and abort Payment Process --> <input type="hidden" name="mm_errorurl" value=" p21safecheck/makepayment.aspx" /> <!-- to integrate updatedby (optional) --> <input type="hidden" name="mm_updatedby" value="xxxx" /> <!-- to integrate customerid on merchant side (optional) --> <input type="hidden" name="mm_merchantcustomerid" value="" /> <!-- to integrate transactionid on merchant side (if null - it would be checknr.) --> <input type="hidden" name="mm_merchanttransid" value="" /> <input type="hidden" name="mm_country" value="us" /> <!-- To integrate the firstname value --> <input type="hidden" name="mm_firstname" value="" /> <!-- To integrate the lastname value --> <input type="hidden" name="mm_lastname" value="" /> <!-- To integrate the date of birth value in format yyyy-mm-dd --> <input type="hidden" name="mm_dateofbirth" value="" /> <!-- To integrate the Address Line1 value --> <input type="hidden" name="mm_address" value="" /> <!-- To integrate the Appartment or Suite or 2nd line address --> <input type="hidden" name="mm_address2" value="" /> <!-- To integrate the last 4 ssn value --> <input type="hidden" name="mm_last4ssn" value="" /> Page 11 of 15

12 <!-- To integrate the city value --> <input type="hidden" name="mm_city" value="" /> <!-- To integrate the state value --> <input type="hidden" name="mm_state" value="" /> <!-- To integrate the zip code value --> <input type="hidden" name="mm_zipcode" value="" /> <!-- To integrate the passport nr value --> <input type="hidden" name="mm_passportnr" value="" /> <!-- To integrate the driver license nr value --> <input type="hidden" name="mm_driverlicensenr" value="" /> <!-- To integrate the phone nr value in Format xxx xxx xxxx --> <input type="hidden" name="mm_phone" value="" /> <!-- To integrate the amount value --> <input type="hidden" name="mm_amount" value="" /> <!-- To integrate the routing code value --> <input type="hidden" name="mm_routingcode" value="" /> <!-- To integrate the account no. value --> <input type="hidden" name="mm_accountnr" value="" /> <!-- To integrate the check no. value --> <input type="hidden" name="mm_checknr" value="" /> <!-- To integrate the address --> <input type="hidden" name="mm_ " value="" /> <!-- The Payment Button could be button, radio-choice, link or image with submit-functionality --> <input type="submit" name="mm_submit" value="submit" /> </form> <! END > 2.6 API Test Account For testing and initial set-up please use the following credentials: API ID (mm_app_id) abccompany API KEY (mm_app_key) abc12345 Company ID (mm_company) 687 Page 12 of 15

13 3. Appendix 3.1 API Response & Error Codes Response & Error Codes Message -1 Not well formed XML -2 Invalid character or value -3 Cannot find customer -4 Given SSN differs from Customer SSN -5 Given Date of Birth differs from the Customer Date of Birth -6 Check amount exceeds your individual limit -7 Cannot accept new Check -8 Amount exceeds weekly limit -9 Amount exceeds monthly limit -10 Amount exceeds 90 days limit -11 Insufficient funds -12 Error communication with account verification service -13 Invalid dollar amount -14 The checking account number supplied is invalid -15 The routing number supplied is invalid -16 No bank account found -17 The Check number has a STOP PAYMENT hold: possible lost or stolen item -18 No electronic debits or ACH Transactions on this account are allowed -19 The account is located, but unable to accept MICR check activity: no checks or drafts -20 Non-sufficient funds -21 Uncollected funds: the account of today is less than, or equal to zero -22 Not a bank account, no debits permission -23 The account is located, open and active, but financial institution reports some bad status code -24 The account is subject to levy, garnishment, government reclamation, lien, court order or other restriction of limited account -25 The bank has listed the account as being closed -26 The bank does not participate in the verification network -27 Verification service reports: Vendor Unavailable -28 Verification service reports: Vendor Error -29 Account cannot be located, status is suppressed due to internal conditions of the contributor -30 A temporary error occurred while processing the request, please try later again -31 Check number is invalid -32 Account number is invalid or any other bad status code -33 Account declined. Possible reasons: the account is closed, has a stop payment hold or insufficient funds, no bank account, no debit permission Page 13 of 15

14 Response & Error Codes Message -34 Cannot find company approval codes -35 Cannot find company record -36 Cannot find return code -37 No return code -38 Address verification failed -39 Unknown error -40 Amount exceeds first deposit limit -41 Customer is already blacklisted -42 Customer is suspended -43 Waiting on the first check to clear -44 Number of checks exceeds weekly limit -45 Check number already used -46 Account is blacklisted -47 No connection to verification service -48 Waiting for open check -49 Error updating customer -50 Payment21 Instant echeck Application Error -51 Error inserting company information -52 Error updating company information -53 Error getting transaction history -54 Error voiding check -55 Error confirming check -56 Error getting reject history -57 Error recording bounced check -58 Error updating cleared check -59 Error updating bounced check -60 Invalid Login: request username, password and whitelist your IPs -61 Error creating customer -62 Number of checks or amount exceed the 8 hours limit -63 Number of checks or amount exceed the 16 hours limit -64 Number of checks or amount exceed the 24 hours limit -65 Number of checks or amount exceed the 48 hours limit -66 Number of checks or amount exceed the 168 hours limit -67 Number of checks or amount exceed the 720 hours limit -68 Number of checks or amount exceed the 2160 hours limit -70 Number of checks in hour or day limit or number of account was exceeded -72 Number of checks or amount exceed the 72 hours limit -73 The given state is blocked -100 General error -74 Minimum Deposit Limit Error Page 14 of 15

15 Response & Error Codes Message -75 Decline - Account Closed -76 Do Not Honor -77 Error authorizing check -78 Honor with identification -79 Approved (VIP) -80 Decline - Bankruptcy -81 Decline - Stop Payment -82 Decline - Other -83 Warning - Over Velocity Amount For Day -84 Warning - Over Velocity Count For Day -85 Warning - Over Velocity Amount For Period -86 Warning - Over Velocity Count For Period -87 Error - Format Error -88 Invalid Merchant -999 SUSPICIOUS ACTIVITY -71 Number of accounts exceeds limit -94 Increase of Amount exceeds limit -95 Verified And Accepted Transaction Page 15 of 15