Input and Output Formats


How to Exchange Data With the API

You, the merchant, have collected order information from the customer in your application program and are now ready to send it to the Merchant/400 API to approve the purchase and complete the order. This exchange of order and result information is done via formats and structures that have been created for each of the differing styles of data being transferred. The selected input and output structures are passed to the API as parameters with format identifiers to indicate to the API which structure to use for its internal processing of the passed data. The definitions of the structures and format identifiers may be found for ILE C programs in the wwwmapi.h include member. Definitions for other ILE and OPM programs can be found in the member WWWMAPI in their respective source files (QRPGSRC, QCBLSRC, and QCBLLESRC). ILE RPG data structure definitions may be found in the DWWWMAPI member. These definitions should be copied into your program source for use in your application.

Input Formats and Structures.

Customer, order, credit card, and other information is passed to the Merchant/400 API via the Input Data Buffer parameter and can take the form of the WWWMERCH_INPUT1, WWWMERCH_INPUT2 or WWWMERCH_INPUT999 structures. By specifying MERCH_INPUT1, MERCH_INPUT2 or MERCH_INPUT999 in the Input Data Format parameter, you inform the API that input data is in the WWWMERCH_INPUT1, WWWMERCH_INPUT2 or WWWMERCH_INPUT999 style structures, respectively. The data required by the host service and the transmission method desired will help determine which of these formats to choose for each transaction processed.

The WWWMERCH_INPUT1 structure has the following field elements (Note - The following field elements are formatted using HTML table definitions that are best viewed with a browser that supports tables):

Field Name DataType Length
Description
Host Service Name binary 9,0
This entry is used to further determine the route processing for the transaction. If the transaction is to be processed through Holonet IAT, you must specify the type of service you wish to utilize. You currently have three choices:
  1. MERCH_INPUT1_HOLOPAY - Use the direct HoloPay service
  2. MERCH_INPUT1_CCN - Use the Credit Card Network service
  3. MERCH_INPUT1_ANACOM - Use the Anacom Communications service
If your transaction will not be routed through Holonet, this field is ignored and can contain any of the valid choices.
Transaction Type binary 9,0
Merchant/400 includes the ability to charge an amount to a credit card via a "sale" transaction, and to request authorization for a charged amount, via a "book" transaction, reserving that amount to be charged later by a "ship" transaction. This entry is used to determine the process that will take place (sale, book, ship) for this transaction. If the transaction is to be processed through Anacom Communications, you must specify the type of transaction that this is. You currently have three choices:
  1. MERCH_TRTYPE1_SALE - This is an immediate sale transaction. The amount specified in Order / Charge Amount will be charged to the credit card.
  2. MERCH_TRTYPE1_BOOK - This transaction will authorize the amount specified in Order / Charge Amount and reserve it against the credit limit associated with the card. The authorization and reserve is valid for a thirty (30) day period before it is automatically removed by the card processor. A "ship" transaction must be sent with the Result Code, and possibly Host Reference, from this transaction to actually charge an amount to the credit card.
  3. MERCH_TRTYPE1_SHIP - This transaction will complete a previously issued "book" transaction. During this transaction, the authorization and reserve are modified to match the Order / Charge Amount specified and actually charged to the credit card. When this transaction is successfully completed, the authorization and reserve are removed and the Order / Charge Amount is charged to the credit card. Approval Code is required for this type of transaction.
If your transaction will not be routed through Anacom or DataCash, this field is ignored and can contain any of the valid choices.
Merchant Name character 256
This is the merchant user name used during logon for transaction transfer. It is assigned by the the Internet partner agency when you created your merchant account. This is not the Merchant identification number assigned by your card processor.
Merchant Password character 256
This is the merchant password used during logon for transaction transfer. It is assigned by the the Internet partner agency when you created your merchant account and is associated with your merchant name.
Order ID character 64
A string that uniquely identifies the transaction. This is usually an order number, but can be any set of characters that allows you to track the transaction through each processing service and to your card processor.
Customer Name character 64
The name of the customer for this transaction. This name must match the name found on the credit card.
Customer Address character 128
This is the billing address for the customer card account. It must match the billing address for the credit card that is used for this transaction.
Customer City character 64
Along with the Customer Address, this is the associated bill-to city for the customer card account.
Customer State/Province character 64
The bill-to state or province associated with the customer card account.
Customer Zip/Postal Code character 64
The bill-to zip code or postal code associated with the customer card account.
Customer Country character 64
The bill-to country associated with the customer card account.
Credit Card Number character 64
This is the number for the credit card being used for this transaction. You should not insert hyphens (-) or spaces at any points in the number.
Card Expiration Month packed decimal 3,0
This is the month portion of the credit card expiration date. It is formatted in a "MM" format and must be a number from 1 to 12.
Card Expiration Year packed decimal 5,0
This is the year portion of the credit card expiration date. It is formatted in a "YYYY" format. For example, a credit card that expires in July, 1998 would have a card expiration month of 07 and a card expiration year of 1998.
Order / Charge Amount packed decimal 15,5
This is the amount of the order that is to be charged or authorized to the credit card identified in the credit card number field. This amount is to be valued in the currency of the merchant account at the card processing organization. For example, if your merchant account is set in United States dollars, this amount must be in US dollars. If you typically do business in another currency, you must calculate the conversion amount based on the currency of your merchant account.
Approval Code character 256
This entry, associated with the MERCH_TRTYPE1_SHIP Transaction Type, links this MERCH_TRTYPE1_SHIP transaction to a previous related "book" transaction. The value of this entry emanated from the credit card processor during the original "book" transaction and must match to complete the actual charge transaction.

The WWWMERCH_INPUT2 structure has the following field elements (Note - The following field elements are formatted using HTML table definitions that are best viewed with a browser that supports tables):

Field Name DataType Length
Description
Host Service Name binary 9,0
This entry is used to further determine the route processing for the transaction. If the transaction is to be processed through Holonet IAT, you must specify the type of service you wish to utilize. You currently have three choices:
  1. MERCH_INPUT1_HOLOPAY - Use the direct HoloPay service
  2. MERCH_INPUT1_CCN - Use the Credit Card Network service
  3. MERCH_INPUT1_ANACOM - Use the Anacom Communications service
  4. MERCH_INPUT1_DATACASH - Use the DataCash service
If your transaction will not be routed through Holonet, this field is ignored and can contain any of the valid choices.
Transaction Type binary 9,0
Merchant/400 includes the ability to charge an amount to a credit card via a "sale" transaction, and to request authorization for a charged amount, via a "book" transaction, reserving that amount to be charged later by a "ship" transaction. This entry is used to determine the process that will take place (sale, book, ship) for this transaction. If the transaction is to be processed through Anacom Communications or DataCash, you must specify the type of transaction that this is. You currently have three choices:
  1. MERCH_TRTYPE1_SALE - This is an immediate sale transaction. The amount specified in Order / Charge Amount will be charged to the credit card.
  2. MERCH_TRTYPE1_BOOK - This transaction will authorize the amount specified in Order / Charge Amount and reserve it against the credit limit associated with the card. The authorization and reserve is valid for a thirty (30) day period before it is automatically removed by the card processor. A "ship" transaction must be sent with the Result Code, and possibly Host Reference, from this transaction to actually charge an amount to the credit card.
  3. MERCH_TRTYPE1_SHIP - This transaction will complete a previously issued "book" transaction. During this transaction, the authorization and reserve are modified to match the Order / Charge Amount specified and actually charged to the credit card. When this transaction is successfully completed, the authorization and reserve are removed and the Order / Charge Amount is charged to the credit card. Approval Code is required for this type of transaction. Order ID will also be used to contain the previously received Host Reference Code when issuing the "ship" via the DataCash service.
If your transaction will not be routed through Anacom or DataCash, this field is ignored and can contain any of the valid choices.
Merchant Name character 256
This is the merchant user name used during logon for transaction transfer. It is assigned by the the Internet partner agency when you created your merchant account. This is not the Merchant identification number assigned by your card processor.
Merchant Password character 256
This is the merchant password used during logon for transaction transfer. It is assigned by the the Internet partner agency when you created your merchant account and is associated with your merchant name.
Order ID character 64
A string that uniquely identifies the transaction. This is usually an order number, but can be any set of characters that allows you to track the transaction through each processing service and to your card processor. If the book or sale transaction is to be processed via DataCash, this must contain a numeric value between 6 and 9 digits long. In the case of a MERCH_TRTYPE1_SHIP transaction processed via the DataCash service, Order ID will be used to contain the previously received Host Reference Code from the "book" transaction.
Customer Name character 64
The name of the customer for this transaction. This name must match the name found on the credit card.
Customer Address character 128
This is the billing address for the customer card account. It must match the billing address for the credit card that is used for this transaction.
Customer City character 64
Along with the Customer Address, this is the associated bill-to city for the customer card account.
Customer State/Province character 64
The bill-to state or province associated with the customer card account.
Customer Zip/Postal Code character 64
The bill-to zip code or postal code associated with the customer card account.
Customer Country character 64
The bill-to country associated with the customer card account.
Credit Card Number character 64
This is the number for the credit card being used for this transaction. You should not insert hyphens (-) or spaces at any points in the number.
Card Expiration Month packed decimal 3,0
This is the month portion of the credit card expiration date. It is formatted in a "MM" format and must be a number from 1 to 12.
Card Expiration Year packed decimal 5,0
This is the year portion of the credit card expiration date. It is formatted in a "YYYY" format. For example, a credit card that expires in July, 1998 would have a card expiration month of 07 and a card expiration year of 1998.
Card Start Month / Issue Code packed decimal 3,0
This is the month portion of the credit card start date, or the two-digit issue code number for the card. It is formatted in a "MM" or "nn" format and must be a number from 1 to 12 (for start date) or 1 to 99 (for issue code).
Card Start Year packed decimal 5,0
This is the year portion of the credit card start date. It is formatted in a "YYYY" format. For example, a credit card that becomes active in July, 1998 would have a card start month of 07 and a card start year of 1998. In the case of using a card issue number, the start year should be passed with a value of zero (0000).
Order / Charge Amount packed decimal 15,5
This is the amount of the order that is to be charged or authorized to the credit card identified in the credit card number field. This amount is to be valued in the currency of the merchant account at the card processing organization or in the currency indicated in the Currency field. For example, if your merchant account is set in United States dollars only, this amount must be in US dollars. If, on the other hand, you typically do business in other (or varied) currencies, you must use the Currency field and this amount must reflect the currency specified.
Approval Code character 256
This entry, associated with the MERCH_TRTYPE1_SHIP Transaction Type, links this MERCH_TRTYPE1_SHIP transaction to a previous related "book" transaction. The value of this entry emanated from the credit card processor during the original "book" transaction and must match to complete the actual charge transaction.
Currency of Charge Amount character 64
This entry, associated with Order / Charge Amount, indicates the currency or denomination of the amount reflected. This should match the associated codes dictated by the Host Service used for this transaction. You should reference their documentation to determine the valid currencies supported and their associated codes.

The WWWMERCH_INPUT999 structure has the following field elements (Note - The following field elements are formatted using HTML table definitions that are best viewed with a browser that supports tables):

Field Name DataType Length
Description
Bytes Provided binary 9,0
The numeric value of this field represents the amount of space that you have allocated and are prepared to send to the Merchant/400 API. It must be at least the size of the WWWMERCH_INPUT999 structure and should include any additional space needed for the transmit data in the submit input buffer.
Input Body CCSID binary 9,0
This entry is used to inform the Merchant/400 API how the upline host intends to view the data you are transmitting in the <BODY> portions of the submit input buffer. This is an ASCII CCSID that the Merchant/400 API will convert the body information to before transmitting it to the host. A CCSID of 819 is typically used for standard ASCII transmissions in US English.
Results Body CCSID binary 9,0
This entry is used to inform the Merchant/400 API how the upline host intends to send the data you are expecting to receive in the <BODY> portions of the Return Buffer (found in the WWWMERCH_RESULT999 output structure). This is an ASCII CCSID that the Merchant/400 API will convert the body information from after receiving it from the host and before returning it to your application. A CCSID of 819 is typically used for standard ASCII transmissions in US English.
Submit Input Buffer character ????
The Submit Input Buffer field is not really part of the WWWMERCH_INPUT999 structure, but an area that is made available for the transmit data to be sent to the upline host system. This area will contain the HTML form data that you intend to transmit. The data received in this buffer should be in the job's CCSID and will be converted appropriately for transmission. Examples of the data stream in this buffer look something like the following two samples:

  • POST /path/programname.cgi HTTP/1.0\x0D\x25
    Content-type: Application/x-www-form-urlencoded\x0D\x25
    Content-length: 28 \x0D\x25\x0D\x25
    &field1=value1&field2=value2\x0D\x25\x0D\x25

  • GET /path/programname.cgi?field1=value1&field2=value2 HTTP/1.0\x0D\x25\x0D\x25

It is important to note that the inclusion of the \x0D\x25 string is indicative of a set of carriage return (hexadecimal code 0D) and line feed (hexadecimal code 25) characters included in the buffer. These CRLF characters serve to separate the various HTTP heading data elements, to separate the <HEAD> information from the <BODY> information (by way of double CRLF strings), and to complete the transmission stream (also with the use of double CRLF strings).

Output Formats and Structures.

The results of the transaction (success or failure) are received from the Merchant/400 API via the Output Data Buffer parameter and can take the form of the WWWMERCH_RESULT1, WWWMERCH_RESULT2 or WWWMERCH_RESULT999 structure. By specifying MERCH_RESULT1, MERCH_RESULT2 or MERCH_RESULT999 in the Output Data Format parameter, you inform the API that you are expecting output data in the WWWMERCH_RESULT1, WWWMERCH_RESULT2 or WWWMERCH_RESULT999 style structure, respectively. The data expected from the host service and the transmission method desired will help determine which of these formats to choose for each transaction processed.

The WWWMERCH_RESULT1 structure has the following field elements (Note - The following field elements are formatted using HTML table definitions that are best viewed with a browser that supports tables):

Field Name DataType Length
Description
Bytes Provided binary 9,0
The numeric value of this field represents the amount of space that you have allocated and made available for the returned information from the Merchant/400 API. It must be at least the size of the WWWMERCH_RESULT1 structure and should include additional space for the Return Comment.
Bytes Available binary 9,0
This value will be returned by the Merchant/400 API and contains the size of the actual data returned. If the Bytes Provided field contains a value that is larger, or the same as, the size of the data returned, Bytes Available will reflect the size of the actual data returned. If the Bytes Provided field contains a value that is smaller than the size of the data that could be returned, Bytes Available will reflect the size of the data that could have been returned and the return data will be truncated to the size of the value in Bytes Provided.
Result Code character 256
A string that identifies the results of the transaction. This code is originated from the credit card processor and should be checked and recorded as the approval identification for the transaction. In the case of a "book" transaction, this code should be saved, as it will be required to complete the charge as part of a future "ship" transaction.
Return Comment Length binary 9,0
This field contains the size of the comments returned in the Return Comment area. If the Bytes Provided field contains a value that is large enough to accommodate a Return Comment, this field will reflect the actual size of the comment returned, otherwise no comment will be returned and this field will be set to a value of zero (0).
Return Comment character ????
The Return Comment field is not really part of the WWWMERCH_RESULT1 structure, but an area that is made available for any comments returned by the credit card processor. This area will contain information that is important to why a transaction was denied. If the transaction was successful, this area will contain the string "Success".

The WWWMERCH_RESULT2 structure has the following field elements (Note - The following field elements are formatted using HTML table definitions that are best viewed with a browser that supports tables):

Field Name DataType Length
Description
Bytes Provided binary 9,0
The numeric value of this field represents the amount of space that you have allocated and made available for the returned information from the Merchant/400 API. It must be at least the size of the WWWMERCH_RESULT2 structure and should include additional space for the Return Comment.
Bytes Available binary 9,0
This value will be returned by the Merchant/400 API and contains the size of the actual data returned. If the Bytes Provided field contains a value that is larger, or the same as, the size of the data returned, Bytes Available will reflect the size of the actual data returned. If the Bytes Provided field contains a value that is smaller than the size of the data that could be returned, Bytes Available will reflect the size of the data that could have been returned and the return data will be truncated to the size of the value in Bytes Provided.
Result Code character 256
A string that identifies the results of the transaction. This code is originated from the credit card processor and should be checked and recorded as the approval identification for the transaction. In the case of a "book" transaction, this code should be saved, as it will be required to complete the charge as part of a future "ship" transaction.
Result Host Reference character 256
A string that uniquely identifies the transaction. This code is originated from the DataCash service and should be recorded for future reference and identification for the transaction. In the case of a "book" transaction, this code must be saved, as it will be required to complete the charge as part of a future "ship" transaction.
Return Comment Length binary 9,0
This field contains the size of the comments returned in the Return Comment area. If the Bytes Provided field contains a value that is large enough to accommodate a Return Comment, this field will reflect the actual size of the comment returned, otherwise no comment will be returned and this field will be set to a value of zero (0).
Return Comment character ????
The Return Comment field is not really part of the WWWMERCH_RESULT2 structure, but an area that is made available for any comments returned by the credit card processor. This area will contain information that is important to why a transaction was denied. If the transaction was successful, this area will contain the string "Success".

The WWWMERCH_RESULT999 structure has the following field elements (Note - The following field elements are formatted using HTML table definitions that are best viewed with a browser that supports tables):

Field Name DataType Length
Description
Bytes Provided binary 9,0
The numeric value of this field represents the amount of space that you have allocated and made available for the returned information from the Merchant/400 API. It must be at least the size of the WWWMERCH_RESULT999 structure and should include additional space for the Return Buffer.
Bytes Available binary 9,0
This value will be returned by the Merchant/400 API and contains the size of the actual data returned. If the Bytes Provided field contains a value that is larger, or the same as, the size of the data returned, Bytes Available will reflect the size of the actual data returned. If the Bytes Provided field contains a value that is smaller than the size of the data that could be returned, Bytes Available will reflect the size of the data that could have been returned and the return data will be truncated to the size of the value in Bytes Provided.
Return Buffer Length binary 9,0
This field contains the size of the data returned in the Return Buffer area. If the Bytes Provided field contains a value that is large enough to accommodate a Return Buffer, this field will reflect the actual size of the buffer data returned, otherwise no data will be returned and this field will be set to a value of zero (0).
Return Buffer character ????
The Return Buffer field is not really part of the WWWMERCH_RESULT999 structure, but an area that is made available for any data that is to be returned by the upline host processor. This area will contain information that is important to the results of a transaction. The data received in this buffer will have been converted appropriately (based on the value of the Results Body CCSID in the WWWMERCH_INPUT999 structure) and will be in the job's CCSID when returned to your application.