API Integration Payment21 Recurring Billing

Transcription

1 API Integration Payment21 Recurring Billing 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 08 th July 2013 Version No 1.02 Owner Payment21 LLC Document Name Payment21_Recurring_Billing_API Revision History Date: Description: Initials: Version: 08 July 2013 Renamed userid and password fields to API ID and SS 1.02 API KEY Page 1 of 18

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 18

3 Table of Contents 1. Payment21 has several integration methods available Payment21 Recurring Billing What the customer will see Billing Support Backoffice "ideposit" How to integrate Input Parameters Response Parameters HTML Code API Test Account Appendix API Response & Error Codes Page 3 of 18

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 18

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 18

6 2. Payment21 Recurring Billing With the Recurring Billing the customer can create a standing order for periodic payments. He has the option to suspend or stop the periodic payment as well. If you are selling subscriptions or would like to allow your customer to pay by installment the Payment21 Recurring Billing is the right solution. The subscription can be predefined/configured under the company settings on your ideposit account. The Recurring Billing allows you to select a predefined recurring billing plan. 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. After the period elapsed the next check item is placed automatically. Payment21 Recurring Billing is easy to use; you have to build the URL with the defined POST parameters. The hidden fields are pre-filled with customer data. The Payment21 Recurring Billing is triggered by the submit action of your web site. You can use any element like a link or button or image to submit. If the customer chooses the Payment21 Recurring Billing, he will be redirected via a secure connection to the Payment21 site. The customer data's are automatically prefilled. The customer has to validate his data, submit the check and then he/she gets redirected to your web page or the page you have set in the parameters. The Payment Application Layout on our side can be changed upon request. 2.1 What the customer will see On the website of the merchants there will be an additional payment method: Instant echeck Recurring Billing When selecting the option Instant echeck Recurring Billing and clicking the Continue button, the customer is redirected to the Payment21 side where the screen will display the Payment21 Recurring Billing page: Page 6 of 18

7 The customer is then presented with a confirmation page. Certain look and feel, color conformity and merchant s required legal information, this form can be customized to the merchant requirement. After looking over all the entries of the Instant echeck payment, the customer can authorize the E-check by clicking the Submit Check button. 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. There are various options for our Customizable Verification Loop and Proprietary Mitigation Monitor that can be set in the Payment21 backoffice module. Page 7 of 18

8 The Payment21 Check Confirmation page Page 8 of 18

9 Payment Confirmation Page: Page 9 of 18

10 2.2 Billing Support The customer is provided with a login to our online Billing Support. On this page he can review all information of his transactions and send us requests to specific transactions. Page 10 of 18

11 2.3 Backoffice "ideposit" The merchant has full access to his mandate in the backoffice system "ideposit". Here he can review all information of the transactions. Here he has many functions and reports available to support his daily business: Reporting: For example: the reporting section shows temporarily approved data and cleared data. All reports are available online in the back office at any time. There is a delay between the temporarily approved (deposited) data and cleared data (cleared by the banking network). Summary Report The Summary Report illustrates the credits and debits affecting the balance held. The open balance is a provisional figure used for accounting purposes only. Received Report The Received Report shows all transactions received from the merchant before they got transmitted, deposited and cleared. It includes R-Requests as well. Return Report The Return Report provides specific statistics relating to returned items. The return rate percentage is the percentage number of returns based on the items cleared on the specified date. Operations: There are several steps where you as a merchant can refuse the transactions in the incomplete items area or per customer request, cancel a pending transaction that has not been transmitted to the bank. On a daily basis, you can choose to confirm transactions that sit in the Incomplete Items area or select to automatically confirm the pending incomplete items by the system. In addition you can review various transaction reports on our Payment21 backoffice module. Page 11 of 18

12 Our backoffice offers a rich array of search criteria: 2.4 How to integrate A merchant can access the API by implementing the POST hidden Parameters from the Payment21 Recurring Billing (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: Page 12 of 18

13 2.5 Input Parameters Field Description Type(Min length, Max length) mm_app_id API ID assigned by Payment21.com Assigned by Payment21.com mm_app_key API KEY 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 Assigned by Payment21.com mm_redirecturl mm_errorurl 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) 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 Number 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_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) mm_toc Accept Terms & Condition (Mandatory in case of ACH transactions) Boolean Page 13 of 18

14 2.6 Response Parameters API will return all the success/failure/exception responses at our end. All type of errors and exceptions will be handled at our end. Note: 1. We set the Check Date/Time with an actual value as it reaches our system. 2. mm_ is the address used to send a confirmation to the customer. That includes all check related information like Transaction Id, Check status, Check amount, account number, check date. This confirmation acts like a payment receipt for the customer. 3. Address validation, Account verification and other rules will apply as per our application s default settings for each customer/merchant. 2.7 HTML Code <! START > <!-- Address to Payment-Button Integration --> <form action=" name="instant echeck (P21PayByCheck)" method="post"> <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=" " /> <!-- Your error URL to go back, if the customer press Cancel Button and abort Payment Process --> <input type="hidden" name="mm_errorurl" value=" " /> <!-- 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 1 line --> <input type="hidden" name="mm_address" value="" /> <!-- To integrate the address 2 line --> <input type="hidden" name="mm_address2" value="" /> <!-- To integrate the last 4 ssn value --> <input type="hidden" name="mm_last4ssn" value="" /> <!-- To integrate the city value --> <input type="hidden" name="mm_city" value="" /> Page 14 of 18

15 <!-- 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="" /> <!-- Do NOT set because amount is setup in back office via Billing Plan(s) <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="" /> <!-- Your Payment Button: could be button, radio-choice, link or image with submit-functionality -- > <input type="submit" name="mm_submit" value="submit" /> </form> <! END > 2.8 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 15 of 18

16 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 16 of 18

17 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 17 of 18

18 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 18 of 18