Processing
Card Charges (Sale & Auth)
To charge a credit or debit card, you will process a sale or an auth transaction. You can follow these transaction types up with a capture (to allow an auth to settle), a void (to cancel a sale or an auth), or a refund (to reverse a sale or a captured auth.) You can add to the Customer Vault using this transaction type to store payment data while charging a card.
Card Validation
You can also check the validity of a card by processing a validate transaction. This will process a 0.00 transaction against the card details provided. You can add to the Customer Vault using this transaction type to store payment data without charging a card.
Unlinked Credits
If you need to return funds to a customer and do not have an original transaction with which to process a refund, or the customer does not have the original card, you can process an unlinked credit.
Response Style Selection
The response style represents which method you wish to receive responses from the gateway, and will decide whether or not you use the AsyncStatus polling API. There are two options:
- Synchronous: You issue your request and wait for a response from the gateway. Due to the customer interaction with the POI device, this could be up to 5 minutes. The transaction will time out after 300 seconds and will need to be restarted. You will receive a transaction ID and a final transaction condition in the response and do not need to do any follow up AsyncStatus polling to determine the results of the transaction.
- Asynchronous: You issue your request and immediately get a GUID in return. You will then use the AsyncStatus Polling API to determine the state of the transaction and final condition with that GUID. This will provide you with the response of the customer's interaction with the POI device once it is complete.
Endpoint
https://secure.networkmerchants.com/api/transact.phpHeaders and Request Data Format
The Payment API accepts either multipart/form-data or application/x-www-form-urlencoded. Depending on which format is used, the Content-Type header should be set to the correct value.
Transaction Processing
POST /api/transact.phpVariable Name | Description |
|---|---|
security_key* | API Security Key assigned to a merchant account. New keys can be generated from the merchant control panel in Settings > Security Keys.Note: Using the 'username' and 'password' variables in the request will result in an error. |
poi_device_id* | The registered terminal ID. Provide on transaction types of sale, auth, credit and validate. |
response_method | The type of response you wish to see returned. Set to 'synchronous' to wait for a final transaction ID. Set to 'asynchronous' to receive an async_status_guid value to poll against. Default: 'synchronous'Values: 'synchronous' or 'asynchronous'Note: You must use the AsyncStatus API if you use 'asynchronous' processing. Please see 'Response Style Selection' above for more information. You can see an example of the response you'll get in the examples below. |
type | The type of transaction to be processed. Values: 'sale', 'auth', 'credit', or 'validate' |
amount | Total amount to be charged. For validate, the amount must be omitted or set to 0.00. Format: x.xx |
first_name | Cardholder's first name. |
last_name | Cardholder's last name. |
company | Cardholder's company. |
address1 | Card billing address. |
address2 | Card billing address, line 2. |
city | Card billing city. |
state | Card billing state. Format: CC |
zip | Card billing zip code. |
country | Card billing country. Country codes are as shown in ISO 3166. Format: CC |
phone | Billing phone number. |
Billing email address.order_description Order description. | |
orderid | Order Id. |
ponumber | Original purchase order. |
tax | The sales tax, included in the transaction amount, associated with the purchase. Format: x.xx |
merchant_defined_field_# | You can pass custom information in up to 20 fields. Format: merchant_defined_field_1=Value |
customer_vault | Associate payment information with a Customer Vault record if the transaction is successful. Values: 'add_customer' or 'update_customer' |
customer_vault_id | Specifies a Customer Vault id. If not set, the payment gateway will randomly generate a Customer Vault id. |
processor_id | If using Multiple MIDs, route to this processor (processor_id is obtained under Settings->Transaction Routing in the Control Panel). |
Request dynamic descriptor details If supplied, these dynamic descriptor values may be used to override the merchant's default descriptor values for this transaction. Depending on the rules of the merchant processor used for the transaction, dynamic descriptor values may be used on the cardholder's billing/bank statement as a part of the description of the transaction.
| Variable Name | Description |
|---|---|
| descriptor | The dynamic descriptor name. Value must match expression: ^[A-Za-z0-9-_ &]60$ |
| descriptor_phone | The dynamic descriptor phone. Value must match expression: ^[A-Za-z0-9-_ &]60$ |
| descriptor_address | The dynamic descriptor address. Value must match expression: ^[A-Za-z0-9-_ &]60$ |
| descriptor_city | The dynamic descriptor city. Value must match expression: ^[A-Za-z0-9-_ &]60$ |
| descriptor_state | The dynamic descriptor state. Value must match expression: ^[A-Za-z0-9-_ &]60$ |
| descriptor_postal | The dynamic descriptor postal code. Value must match expression: ^[A-Za-z0-9-_ &]60$ |
| descriptor_country | The dynamic descriptor country. Value must match expression: ^[A-Za-z0-9-_ &]60$ |
| descriptor_mcc | The dynamic descriptor merchant category code. Value must match expression: ^[A-Za-z0-9-_ &]60$ |
| descriptor_merchant_id | The dynamic descriptor merchant ID. Value must match expression: ^[A-Za-z0-9-_ &]60$ |
| descriptor_url | The dynamic descriptor URL. Value must match expression: ^[A-Za-z0-9-_ &]60$ |
New Response Details
Variable Name | Description |
|---|---|
async_status_guid * | Will contain a GUID for use with polling. Will only return dynamically when 'response_method' is set to 'asynchronous'. Store and use for retrieving the final status of a transaction using the AsyncStatus API. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
verification_method ** | A CVM is a means of checking that the user of a card is the genuine cardholder. The returned value will indicate how the customer was verified. Values: 'signature', 'offline_pin', 'online_pin', 'offline_pin_signature', or 'none' Note: A response with the value of 'signature' indicates the signature should be collected and confirmed by the POS operator. |
transaction_status_information ** | A collection of indicators that the terminal will set to show what processing steps have been performed on the current transaction (e.g. Cardholder Verification, Data Authentication). Example: E800. |
emv_application_id ** | Identifies the EMV application that the terminal used on the transaction as described in ISO/IEC 7816-5. Example: A000000003101001. |
emv_application_label ** | The human readable name associated with the AID according to ISO/IEC 7816-5. Example: Visa International. |
emv_application_preferred_label ** | The human readable name associated with the applicationId in the cardholder’s local language. This value will not always be present. |
*Only applicable/useful when processing asynchronous transactions. Store to poll against using the AsyncStatus API. Note: If you are using synchronous processing method and you have a custom API response set to include this value, you can safely ignore it and do not need to poll the status API with it.
**Additional transaction receipt data returned with EMV/Chip Card transactions.
Examples
Synchronous Sale: In this request, a transaction ID will be returned and the final state will be returned like a typical Payment API response.
...type=sale&poi_device_id=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
&response_method=synchronous&amount=1.00&......response=1&responsetext=Approved&authcode=XXXXX&transactionid=XXXXXXXXXX
&type=sale&response_code=100Synchronous Sale & Add to Vault: In this request, a transaction ID and a Customer Vault ID will be returned and the final state will be returned like a typical Payment API response.
...type=sale&poi_device_id=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
&response_method=synchronous&amount=1.00&customer_vault=add_customer......response=1&responsetext=Approved&authcode=XXXXX&transactionid=XXXXXXXXXX
&type=sale&response_code=100&customer_vault_id=XXXXXXXXXAsynchronous Sale: In this request, a async_status_guid will be returned that you must poll against using the AsyncStatus API.
...type=sale&poi_device_id=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
&response_method=asynchronous&amount=1.00&......response=1&responsetext=Request Accepted&...&response_code=101
&async_status_guid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXAsynchronous Sale + Add to Vault: In this request, a async_status_guid will be returned that you must poll against using the AsyncStatus API. You will not receive a Vault ID in the initial Payment API call.
...type=sale&poi_device_id=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
&response_method=asynchronous&amount=1.00&customer_vault=add_customer......response=1&responsetext=Request Accepted&...&response_code=101
&async_status_guid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXSince the asynchronous response does not return a transaction ID or the status / condition of the transaction, use the async_status_guid value to poll against the terminal itself. See 'AsyncStatus API' below for documentation.
Voids / Captures / Refunds
To void a sale or an auth, capture an auth, or refund a transaction, please follow the documented Payment API methods in a request to your gateway account. You do not need to provide the POI Device ID or response_method variables as there is no device interaction on these types of transactions.
Examples:
Void: In this request, a transaction ID will be returned and the final state will be returned like a typical Payment API response. You do not need to provide the POI Device ID as there is no device interaction on voids.
...type=void&transactionid=XXXXXXXXXX...response=1&responsetext=Transaction Void Successful&authcode=XXXXXX
&transactionid=XXXXXXXXXX&type=void&response_code=100Capture: In this request, a transaction ID will be returned and the final state will be returned like a typical Payment API response. You do not need to provide the POI Device ID as there is no device interaction on captures. You can specify an amount or not. Not specifying an amount will capture the full amount authorized.
...type=capture&transactionid=XXXXXXXXXX&amount=X.XX...response=1&responsetext=Transaction Capture Successful&authcode=XXXXXX
&transactionid=XXXXXXXXXX&type=capture&response_code=100Refund: In this request, a transaction ID will be returned and the final state will be returned like a typical Payment API response. You do not need to provide the POI Device ID as there is no device interaction on refunds. You can specify an amount or not. Not specifying an amount will refund the full amount authorized.
...type=refund&transactionid=XXXXXXXXXX...response=1&responsetext=Approved&authcode=XXXXXX&transactionid=XXXXXXXXXX
&type=refund&response_code=100Updated 15 days ago