mycropay® application programming interface  - XML (MAPI-XML) provides merchants the ability to process real-time transactions through the Internet. MAPI-XML gateway processes XML requests sent using HTTP protocol over SSL (Secure Sockets Layer technology which is used to encrypt confidential transactions) connections (HTTPS). MAPI-XML supports SSL 3.0 and below, both 128-bit and 40-bit clients.

To use MAPI-XML, merchant software should connect to https://www.mycropay.net/ipg/Ipg Connections have to be made using port 443, the standard port for HTTPS.
NOTE: Connecting to the gateway's numeric IP address directly will cause SSL error messages.
To confirm that MAPI-XML gateway is up and responding to requests, https://www.mycropay.net/ipg/Ipg may be checked using an Internet browser.

Transaction Session
The XML-based Internet Payment Markup Language (IPML) request is sent to the https://www.mycropay.net/ipg/Ipg URL in a form of HTTP GET or HTTP POST transaction.
HTTP GET request: https://www.mycropay.net/ipg/Ipg?IPML_request_string
(IPML_request_string must be URL-encoded)
HTTP POST request: the content type of the request should be "text/xml".
IPML_request_string is sent as a body of HTTP POST message.

IPML Request Request must start with <?xml version="1.0" encoding="UTF-8" ?> XML header
followed by <transaction ...> ... </transaction> top-level element.

Elements (see Table 1):

1. <transaction type='type' id_code='id_code' crypt_key='crypt_key' password='password' host='host' port='port' get_enhanced_response='Y'>
   
   <transaction ...> is the first tag in the request after the <?xml ….> header. Request is closed by the </transaction> tag.
   
   Attributes:
   type - transaction type (see Table 2)
   id_code - merchant's ID code
   crypt_key - merchant's encryption key
   password - merchant's password
   host - IP address of MAPI host
   port - MAPI service port
   get_enhanced_response - to provide enhanced response
2. <card>credit_card_number</card>
   credit_card_number - credit card number
3. <cvv2>cvv2</cvv2>
   cvv2 - credit card verification value/code
4. <expiration>credit_card_expiration_date</expiration>
   credit_card_expiration_date - credit card expiration date
5. <amount>amount</amount>
   amount - charge or credit amount in cents
6. <r_flag>r_flag</r_flag>
   r_flag - type of recurrence for charge
   
   Values
   S = single
   I = initial
   R = recurring
7. <reference>reference</reference>
   reference - reference string provided by the merchant
8. <tracking>tracking_number</tracking>
   tracking_number - tracking number of the previous open transaction
9. <frequency>frequency_code</frequency>
   frequency_code - code for frequency of recurring charges (see Table 3)
10. <first_charge>date_of_first_recurring_charge</first_charge>
    date_of_first_recurring_charge - date of first recurring charge
11. <charge_num>number_of_recurring_charges</charge_num>
    number_of_recurring_charges - number of recurring charges
12. <memo>comment_string</memo>
    comment_string - user-defined comment string for recurring charges
13. <first_name>first_name</first_name>
    first_name - first name as it appears on a credit card
14. <last_name>last_name</last_name>
    last_name - last name as it appears on a credit card
15. <address1>address_line_1</address1>
    address_line_1 - credit card billing address, first line
16. <address2>address_line_2</address2>
    address_line_2 - credit card billing address, second line
17. <address>address</address>
    address - bank account address as it appears on a statement
18. <city>city</city>
    city - billing or bank account address, city
19. <state>state</state>
    state - billing or bank account address, state
20. <zip>zip</zip>
    zip - billing or bank account address, ZIP
21. <country>country</country>
    country - billing or bank acount address, country
22. <check type='check_type'> check_number</check>
    check_type - type of the check
    check_number - check number
23. <routing>routing_number</routing>
    routing_number - bank routing number
24. <account_no>account_number</account_no>
    account_number - check account number
25. <company>company_name</company>
    company_name - company name (for business accounts only)
26. <phone>phone_number</phone>
    phone_number - check holder's phone number
27. <dl>driver's_license</dl>
    driver's_license - check holder's driver's license
28. <dl_state>driver's_license_state</dl_state>
    driver's_license_state - driver's license state
29. <dob>date_of_birth</dob>
    date_of_birth - check holder's date of birth

IPML Response Response starts with <?xml version="1.0" encoding="UTF-8" ?> XML header followed by <response> ... </response> top-level element.

Elements:

1. <response state='state'>
   
   <response ...> is the first tag in the response after the <?xml ….> header. Response is closed by the </response> tag.
   
   state - state of transaction: 0 - succeed, 10 - processing error
2. <code>response_code</code>
3. <tracking>transaction_tracking_number</tracking>
4. <reference>reference</reference>
5. <processor_response_detail>respose_detail</processor_response_detail>
6. <efalcon_score>efalcon_score</efalcon_score>
7. <approval_code>approval_code</approval_code>
8. <error>error_explanation</error>

Table 1, IPML Request Elements

Format: A - alpha, N - numeric, A/N - alpha-numeric
Req:      R - required, O - optional, C - optional for credit card and required for ACH