For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Credit

Running a Sale

To take a dollar amount from a cardholder’s account, send a CreateSale request to the Credit endpoint.

How it works

Program the POS to take the dollar amount or a partial dollar amount of a sale from the cardholder’s account.

Scenario	Merchant uses the POS to:
Cardholder wants to buy an item from the merchant.	Send a CreateSale request to charge the cardholder for the item.

Payment Sources

Inserted
Swiped
NFC
Keyed

Important Things to Consider

All follow on transactions require storing the reference_id that you generate and include in the request.

Endpoints

Environment	HTTP Method	URL
Partner Integration Test	POST	https://api.pit.paygateway.com/transactions/setup/transport\_keys
Production	POST	https://api.paygateway.com/transactions/setup/transport\_keys

Minimum Required Fields

Field	Type	Size	Description
HTTP Headers			See HTTP Headers section in the Overview
amount	String	4-9	Must be 0.01-999999.99. Does not include cash back or tip amount.
reference_id	String	1-50	A unique identifier used to process follow on transactions. The format is "MER-`{UUID}`" ex. "MER-41e40db1-02c8-4214-b2c8-1399aea79afa".
invoice_number	String	1-25	Alphanumeric, 1-25 characters in length. Merchant-generated invoice number for transaction.
type	String		Must be "sale".
clerk_id	String	1-20	String, 1-20 characters in length. Clerk ID to appear on the receipt.

Sample Request

Content-Type: application/json
Accept: application/json
Date: Mon, 02 Oct 2017 22:21:20 GMT
“Authorization”: “AuthToken {AuthTokenV2}”
X-GP-Request-Id: {request_id}
X-GP-Version: 2019-06-27
X-GP-Api-Key: {API Key}
{
    "payment": {
        "amount": "1.00",
        "reference_id": "MER-310cb80d-be6a-491b-9b01-fe6c0949d974",
        "invoice_number": "1234"
    },
    "transaction": {
        "type": "sale"
    },
    "receipt": {
        "clerk_id": "clerk name"
    }
}

Sample Response

200
{
  "sale_id": "000000044525",
  "status": "Approved",
  "approval_code": "092995",
  "card": {
    "masked_card_number": "476173XXXXXX0010",
    "expiry_month": "12",
    "expiry_year": "22",
    "type": "Visa"
  },
  "payment": {
    "amount": "1.00",
    "invoice_number": "1234",
    "reference_id": "MER-ca522434-611d-47cb-9e4e-87a2b00f3126",
    "type": "Credit"
  },
  "transaction": {
    "batch_number": "001075"
  },
  "receipt": {
    "text": {
      "customer_receipt": "           ****Duplicate****\n\n      Patrick's Test Company Name\n                Header 2\n\n               Address 11\n               Address 22\n         City State, CA, 55555\n             (555)555-5555\n\nTerminal ID         XXXXXXXXXXXX444\nTrans ID            000000044525\nOrder ID            MER-ca522434-611d-47\n                    cb-9e4e-87a2b00f3126\nReceipt #           1234\nTrans Type          Purchase\nDate/Time           2020-10-16 09:14:50\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Legend        CHIP READ\nEntry Method        CONTACT\nApproval Code       092995\nAC                  E36B810DD9B48CB7\nATC                 0109\nAID                 A0000000031010\nAID NAME            Visa Credit\nTVR                 4200008000\nTSI                 F800\nResp CD             00\nTRN REF #           300290476904062\nVAL CODE            LBSS\n\nTotal Amount        USD$1.00\n\nDescription:_______________________\n\n          Approved - Thank You\n\n X____________________________________\n        Signature: Test/Card 01\n\nBuyer agrees to pay total amount above\naccording to cardholder's agreement with\nissuer.\n\n                Footer 1\n                Footer 2\n\n         ****Customer Copy****\n     Retain this copy for statement\n              verification",
      "merchant_receipt": "           ****Duplicate****\n\n      Patrick's Test Company Name\n                Header 2\n\n               Address 11\n               Address 22\n         City State, CA, 55555\n             (555)555-5555\n\nTerminal ID         XXXXXXXXXXXX444\nTrans ID            000000044525\nOrder ID            MER-ca522434-611d-47\n                    cb-9e4e-87a2b00f3126\nReceipt #           1234\nTrans Type          Purchase\nDate/Time           2020-10-16 09:14:50\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Legend        CHIP READ\nEntry Method        CONTACT\nApproval Code       092995\nAC                  E36B810DD9B48CB7\nATC                 0109\nAID                 A0000000031010\nAID NAME            Visa Credit\nTVR                 4200008000\nTSI                 F800\nResp CD             00\nTRN REF #           300290476904062\nVAL CODE            LBSS\n\nTotal Amount        USD$1.00\n\nDescription:_______________________\n\n          Approved - Thank You\n\n X____________________________________\n        Signature: Test/Card 01\n\nBuyer agrees to pay total amount above\naccording to cardholder's agreement with\nissuer.\n\n                Footer 1\n                Footer 2\n\n         ****Merchant Copy****"
    },
    "id": "44525",
    "attributes": {
      "authorization_agreement": "Buyer agrees to pay total amount above according to cardholder's agreement with issuer.",
      "copy_label_customer": "****Customer Copy**** Retain this copy for statement verification",
      "copy_label_merchant": "****Merchant Copy****",
      "duplicate_label": "****Duplicate****",
      "verbiage": "Approved - Thank You"
    },
    "labeled_attributes": {
      "amount": {
        "label": "Total Amount",
        "value": "USD$1.00"
      },
      "approval_code": {
        "label": "Approval Code",
        "value": "092995"
      },
      "authorization_response_code": {
        "label": "Resp CD",
        "value": "00"
      },
      "card_type": {
        "label": "Card Type",
        "value": "Visa"
      },
      "entry_legend": {
        "label": "Entry Legend",
        "value": "CHIP READ"
      },
      "entry_method": {
        "label": "Entry Method",
        "value": "CONTACT"
      },
      "masked_card_number": {
        "label": "Card Number",
        "value": "XXXXXXXXXXXX0010"
      },
      "merchant_id": {
        "label": "Terminal ID",
        "value": "XXXXXXXXXXXX444"
      },
      "number": {
        "label": "Receipt #",
        "value": "1234"
      },
      "reference_id": {
        "label": "Order ID",
        "value": "MER-ca522434-611d-47cb-9e4e-87a2b00f3126"
      },
      "total_amount": {
        "label": "Total Amount",
        "value": "USD$1.00"
      },
      "transaction_datetime": {
        "label": "Date/Time",
        "value": "2020-10-16 09:14:50"
      },
      "transaction_id": {
        "label": "Trans ID",
        "value": "000000044525"
      },
      "transaction_type": {
        "label": "Trans Type",
        "value": "Purchase"
      },
      "validation_code": {
        "label": "VAL CODE",
        "value": "LBSS"
      }
    }
  },
  "links": [
    {
      "sale_id": [
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/000000044525",
          "relation": "self",
          "method": "GET",
          "description": "Use this endpoint to retrieve a sales transaction."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/000000044525",
          "relation": "self",
          "method": "PATCH",
          "description": "Use this endpoint to update the amount or other values of a previous sales transaction."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/000000044525/voids",
          "relation": "void",
          "method": "PUT",
          "description": "Use this endpoint to void a previous sales transaction."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/000000044525/returns",
          "relation": "return",
          "method": "POST",
          "description": "Use this endpoint to create a returns transaction associated with a previous sales transaction."
        }
      ]
    },
    {
      "reference_id": [
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/reference_id/MER-ca522434-611d-47cb-9e4e-87a2b00f3126",
          "relation": "self",
          "method": "GET",
          "description": "Use this endpoint to retreive a previous sales transaction using reference id."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/reference_id/MER-ca522434-611d-47cb-9e4e-87a2b00f3126",
          "relation": "self",
          "method": "PATCH",
          "description": "Use this endpoint to update the amount or other values of a previous sales transaction using reference id."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/reference_id/MER-ca522434-611d-47cb-9e4e-87a2b00f3126/voids",
          "relation": "void",
          "method": "PUT",
          "description": "Use this endpoint to void a previous sales transaction using reference id."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/reference_id/MER-ca522434-611d-47cb-9e4e-87a2b00f3126/returns",
          "relation": "return",
          "method": "POST",
          "description": "Use this endpoint to create a returns transaction associated with a previous sales using reference id."
        }
      ]
    }
  ]
}

Refunding a Transaction

Moves funds from the Merchant account back to the Cardholder

How it works

Program the POS to credit a dollar amount to a cardholder’s account.

Scenario	Merchant uses the POS to:
Merchant wants to credit funds to a cardholder.	Send a Return request to send the funds back to the Cardholder.

Payment Sources

Inserted
Swiped
NFC
Keyed

Important Things to Consider

All follow on transactions require storing the reference_id that you generate and include in the request.
Funds can be credited back to any account the cardholder chooses.

Endpoints

Environment	Call	HTTP Method	URL
Partner Integration Test	Staging Call	POST	https://api.pit.paygateway.com/transactions/setup/transport\_keys
Production	Staging Call	POST	https://api.paygateway.com/transactions/setup/transport\_keys
Partner Integration Test	Device Call	GET	https://`{hostname}`:8443/v2/pos?Format=`{format}`&TransportKey=`{transport_key}`
Production	Device Call	GET	https://`{hostname}`:8443/v2/pos?Format=`{format}`&TransportKey=`{transport_key}`
Partner Integration Test	Query Call	GET	https://api.pit.paygateway.com/transactions/returns/reference\_id/`{reference_id}`?generate\_receipt=true
Production	Query Call	GET	https://api.paygateway.com/transactions/returns/reference\_id/`{reference_id}`?generate\_receipt=true

Minimum Required Fields

Field	Type	Size	Description
HTTP Headers			See HTTP Headers section in the Overview
amount	String	4-9	Must be 0.01-999999.99. Does not include cash back or tip amount.
reference_id	String	1-50	A unique identifier used to process follow on transactions. The format is "MER-`{UUID}`" ex. "MER-41e40db1-02c8-4214-b2c8-1399aea79afa".
invoice_number	String	1-25	Alphanumeric, 1-25 characters in length. Merchant-generated invoice number for transaction.
type	String		Must be "return".
clerk_id	String	1-20	String, 1-20 characters in length. Clerk ID to appear on the receipt.

Sample Request

Content-Type: application/json
Accept: application/json
Date: Mon, 02 Oct 2017 22:21:20 GMT
“Authorization”: “AuthToken {AuthTokenV2}”
X-GP-Request-Id: {request_id}
X-GP-Version: 2019-06-27
X-GP-Api-Key: {API Key}
{
    "payment": {
        "amount": "1.01",
        "reference_id": "MER-1ba033c3-3db3-4259-b070-3a4f50cfd965",
        "invoice_number": "1234"
    },
    "transaction": {
        "type": "return"
    },
    "receipt": {
        "clerk_id": "clerk name"
    }
}

Sample Response

200
{
  "return_id": "000000044528",
  "status": "Approved",
  "approval_code": "007656",
  "card": {
    "masked_card_number": "476173XXXXXX0010",
    "expiry_month": "12",
    "expiry_year": "22",
    "type": "Visa"
  },
  "payment": {
    "amount": "1.01",
    "reference_id": "MER-1ba033c3-3db3-4259-b070-3a4f50cfd965",
    "type": "Credit"
  },
  "transaction": {
    "batch_number": "001075"
  },
  "receipt": {
    "text": {
      "customer_receipt": "           ****Duplicate****\n\n      Patrick's Test Company Name\n                Header 2\n\n               Address 11\n               Address 22\n         City State, CA, 55555\n             (555)555-5555\n\nTerminal ID         XXXXXXXXXXXX444\nTrans ID            000000044528\nOrder ID            MER-1ba033c3-3db3-42\n                    59-b070-3a4f50cfd965\nTrans Type          Return\nDate/Time           2020-10-16 09:29:42\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Legend        CHIP READ\nEntry Method        CONTACT\nApproval Code       007656\nTRN REF #           300290485827042\nVAL CODE            FPML\n\nTotal Amount        USD$1.01\n\nDescription:_______________________\n\n          Approved - Thank You\n\n X____________________________________\n               Signature\n\n                Footer 1\n                Footer 2\n\n         ****Customer Copy****\n     Retain this copy for statement\n              verification",
      "merchant_receipt": "           ****Duplicate****\n\n      Patrick's Test Company Name\n                Header 2\n\n               Address 11\n               Address 22\n         City State, CA, 55555\n             (555)555-5555\n\nTerminal ID         XXXXXXXXXXXX444\nTrans ID            000000044528\nOrder ID            MER-1ba033c3-3db3-42\n                    59-b070-3a4f50cfd965\nTrans Type          Return\nDate/Time           2020-10-16 09:29:42\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Legend        CHIP READ\nEntry Method        CONTACT\nApproval Code       007656\nTRN REF #           300290485827042\nVAL CODE            FPML\n\nTotal Amount        USD$1.01\n\nDescription:_______________________\n\n          Approved - Thank You\n\n X____________________________________\n               Signature\n\n                Footer 1\n                Footer 2\n\n         ****Merchant Copy****"
    },
    "id": "44528",
    "attributes": {
      "copy_label_customer": "****Customer Copy**** Retain this copy for statement verification",
      "copy_label_merchant": "****Merchant Copy****",
      "duplicate_label": "****Duplicate****",
      "verbiage": "Approved - Thank You"
    },
    "labeled_attributes": {
      "amount": {
        "label": "Total Amount",
        "value": "USD$1.01"
      },
      "approval_code": {
        "label": "Approval Code",
        "value": "007656"
      },
      "card_type": {
        "label": "Card Type",
        "value": "Visa"
      },
      "entry_legend": {
        "label": "Entry Legend",
        "value": "CHIP READ"
      },
      "entry_method": {
        "label": "Entry Method",
        "value": "CONTACT"
      },
      "masked_card_number": {
        "label": "Card Number",
        "value": "XXXXXXXXXXXX0010"
      },
      "merchant_id": {
        "label": "Terminal ID",
        "value": "XXXXXXXXXXXX444"
      },
      "reference_id": {
        "label": "Order ID",
        "value": "MER-1ba033c3-3db3-4259-b070-3a4f50cfd965"
      },
      "total_amount": {
        "label": "Total Amount",
        "value": "USD$1.01"
      },
      "transaction_datetime": {
        "label": "Date/Time",
        "value": "2020-10-16 09:29:42"
      },
      "transaction_id": {
        "label": "Trans ID",
        "value": "000000044528"
      },
      "transaction_type": {
        "label": "Trans Type",
        "value": "Return"
      },
      "validation_code": {
        "label": "VAL CODE",
        "value": "FPML"
      }
    }
  },
  "links": [
    {
      "return_id": [
        {
          "href": "https://api.pit.paygateway.com/transactions/returns/000000044528",
          "relation": "self",
          "method": "GET",
          "description": "Use this endpoint to retrieve a previously completed returns transaction."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/returns/000000044528/voids",
          "relation": "void",
          "method": "PUT",
          "description": "Use this endpoint to void a previously completed returns transaction."
        }
      ]
    },
    {
      "reference_id": [
        {
          "href": "https://api.pit.paygateway.com/transactions/returns/reference_id/MER-1ba033c3-3db3-4259-b070-3a4f50cfd965",
          "relation": "self",
          "method": "GET",
          "description": "Use this endpoint to retrieve a previously completed returns transaction using reference id."
        }
      ]
    }
  ]
}

Voiding a Previous Sale

Cancels a transaction and removes it from an open Batch.

How it works

Program the POS to Void a Credit Sale transaction. Specify the reference_id sent with a previously approved transaction.

Scenario	Merchant uses the POS to:
Cardholder wants to cancel a previous transaction in an open Batch	Send a Void request to cancel the previous sale

Payment Sources

Keyed

Important Things to Consider

The transaction in question must be in an open Batch. Transactions in a closed Batch cannot be voided and must be refunded.
The amount must match the amount of the previously approved transaction.

Endpoints

Environment	HTTP Method	URL
Partner Integration Test	PUT	https://api.pit.paygateway.com/transactions/sales/reference\_id/`{reference_id}`/voids
Production	PUT	https://api.paygateway.com/transactions/sales/reference\_id/`{reference_id}`/voids

These are the minimum required fields.

Field	Description
HTTP Headers	See HTTP Headers section in the Overview
amount	Must be 0.01-999999.99.

Sample Request

Content-Type: application/json
Accept: application/json
Date: Mon, 02 Oct 2017 22:21:20 GMT
“Authorization”: “AuthToken {AuthTokenV2}”
X-GP-Request-Id: {request_id}
X-GP-Version: 2019-06-27
X-GP-Api-Key: {API Key}
{
    "payment": {
        "amount": "1"
    }
  }
}

Sample Response

200
{
  "sale_id": "000000001659",
  "status": "Voided",
  "card": {
    "masked_card_number": "476173XXXXXX0010",
    "expiry_month": "12",
    "expiry_year": "22",
    "type": "Visa"
  },
  "payment": {
    "amount": "1.00",
    "reference_id": "MER-41e40db1-02c8-4214-b2c8-1399aea79afa",
    "type": "Credit"
  },
  "transaction": {
    "batch_amount": "37572.29",
    "batch_number": "000070"
  },
  "links": [
    {
      "sale_id": [
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/000000001659",
          "relation": "self",
          "method": "GET",
          "description": "Use this endpoint to retrieve a sales transaction."
        }
      ]
    },
    {
      "reference_id": [
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/reference_id/MER-41e40db1-02c8-4214-b2c8-1399aea79afa",
          "relation": "self",
          "method": "GET",
          "description": "Use this endpoint to retreive a previous sales transaction using reference id."
        }
      ]
    }
  ]
}

Refunding a Previous Sale

Moves funds from the Merchant account back to the Cardholder

How it works

Program the POS to Refund an amount back to the Cardholder. Specify the reference_id sent with a previously approved transaction.

Scenario	Merchant uses the POS to:
Cardholder wants to return an item	Send a Return request to send the funds back to the Cardholder

Payment Sources

Keyed

Important Things to Consider

If the transaction in question is still in an open batch it should be voided rather than refunded. Refunds should only be used for transactions that have already settled and can no longer be voided.

Endpoints

Environment	HTTP Method	URL
Partner Integration Test	POST	https://api.pit.paygateway.com/transactions/sales/reference\_id/`{reference_id}`/returns
Production	POST	https://api.paygateway.com/transactions/sales/reference\_id/`{reference_id}`/returns

These are the minimum required fields.

Field	Description
HTTP Headers	See HTTP Headers section in the Overview
amount	Must be 0.01-999999.99.

Sample Request

Content-Type: application/json
Accept: application/json
Date: Mon, 02 Oct 2017 22:21:20 GMT
“Authorization”: “AuthToken {AuthTokenV2}”
X-GP-Request-Id: {request_id}
X-GP-Version: 2019-06-27
X-GP-Api-Key: {API Key}
{
  "payment": {
    "amount": "1"
  },
  "transaction": {}
}

Sample Response

200
{
  "return_id": "000000001665",
  "status": "Approved",
  "approval_code": "016294",
  "card": {
    "masked_card_number": "476173XXXXXX0010",
    "expiry_month": "12",
    "expiry_year": "22",
    "type": "Visa"
  },
  "payment": {
    "amount": "1.00",
    "type": "Credit"
  },
  "transaction": {
    "batch_amount": "38686.99",
    "batch_number": "000070"
  },
  "links": [
    {
      "return_id": [
        {
          "href": "https://api.pit.paygateway.com/transactions/returns/000000001665",
          "relation": "self",
          "method": "GET",
          "description": "Use this endpoint to retrieve a previously completed returns transaction."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/returns/000000001665/voids",
          "relation": "void",
          "method": "PUT",
          "description": "Use this endpoint to void a previously completed returns transaction."
        }
      ]
    }
  ]
}

Querying a Previous Sale

A lookup call to get results from a previously processed transaction.

How it works

Specify the reference_id sent with a previously approved transaction

Endpoints

Environment	HTTP Method	URL
Partner Integration Test	GET	https://api.pit.paygateway.com/transactions/sales/reference\_id/`{reference_id}`
Production	GET	https://api.paygateway.com/transactions/sales/reference\_id/`{reference_id}`

These are the minimum required fields.

Field	Description
HTTP Headers	See HTTP Headers section on the Overview page.

Sample Request

//NOTE: There is no body in this request, just the headers

Content-Type: application/json
Accept: application/json
Date: Mon, 02 Oct 2017 22:21:20 GMT
“Authorization”: “AuthToken {AuthTokenV2}”
X-GP-Request-Id: {request_id}
X-GP-Version: 2019-06-27
X-GP-Api-Key: {API Key}

Sample Response

200
{
  "sale_id": "000000001659",
  "status": "Approved - CSC Mismatch",
  "approval_code": "050327",
  "cardsecurity_response": "unavailable",
  "card": {
    "masked_card_number": "476173XXXXXX0010",
    "expiry_month": "12",
    "expiry_year": "22",
    "type": "Visa"
  },
  "payment": {
    "amount": "1.00",
    "reference_id": "MER-41e40db1-02c8-4214-b2c8-1399aea79afa",
    "type": "Credit"
  },
  "transaction": {
    "batch_number": "000071"
  },
  "links": [
    {
      "sale_id": [
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/000000001659",
          "relation": "self",
          "method": "GET",
          "description": "Use this endpoint to retrieve a sales transaction."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/000000001659",
          "relation": "self",
          "method": "PATCH",
          "description": "Use this endpoint to update the amount or other values of a previous sales transaction."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/000000001659/voids",
          "relation": "void",
          "method": "PUT",
          "description": "Use this endpoint to void a previous sales transaction."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/000000001659/returns",
          "relation": "return",
          "method": "POST",
          "description": "Use this endpoint to create a returns transaction associated with a previous sales transaction."
        }
      ]
    },
    {
      "reference_id": [
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/reference_id/MER-41e40db1-02c8-4214-b2c8-1399aea79afa",
          "relation": "self",
          "method": "GET",
          "description": "Use this endpoint to retreive a previous sales transaction using reference id."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/reference_id/MER-41e40db1-02c8-4214-b2c8-1399aea79afa",
          "relation": "self",
          "method": "PATCH",
          "description": "Use this endpoint to update the amount or other values of a previous sales transaction using reference id."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/reference_id/MER-41e40db1-02c8-4214-b2c8-1399aea79afa",
          "relation": "void",
          "method": "PUT",
          "description": "Use this endpoint to void a previous sales transaction using reference id."
        },
        {
          "href": "https://api.pit.paygateway.com/transactions/sales/reference_id/MER-41e40db1-02c8-4214-b2c8-1399aea79afa/returns",
          "relation": "return",
          "method": "POST",
          "description": "Use this endpoint to create a returns transaction associated with a previous sales using reference id."
        }
      ]
    }
  ]
}

Data Structures

Regional Payment Type Support

Region	Payment Types Supported
US	Credit, Prepaid, Check
CA	Credit, Prepaid, Check
AU	Credit, Check (Direct Debit)
NZ	Credit, Check (Direct Debit) note: this does not support American Express or diners credit cards
UK	Credit

AuthtokenV2 'region' Field Dependencies

AuthTokenV2 'region' Value	'language' Value	'country_code' Value	'currency_code' Value
US	en-US	840	840
CA	en-CA (default)	124	124
CA	fr-CA	124	124
AU	en-AU	036	036
NZ	en-GB	554	554
UK	en_GB	826	840, 756, 978

Additional Optional Fields

card

Field	Type	Size	Description
token	String	1-34	Payment instrument token generated by the payment gateway. If token is sent, "create_token" cannot be "true".
temporary_token	String	1-36	Temporary payment instrument token generated by the payment gateway. This is a one time use only token for sale and auth transactions. Either temporary_token or token (and not both) can be sent in a request.

payment

Field	Type	Size	Description
gratuity_amount	String	1-7	Gratuity amount included in the total amount for transaction.
invoice_number	String	1-25	Merchant-generated invoice number for transaction.
amount	String	4-9	Total amount requested for the transaction. Includes any tip and tax amount. For US and CA transactions, this amount should include any customer fees to be charged(if applicable) and this will be the total amount charged to the card or account. For AU and NZ transactions, customer fees if configured for the merchant in the gateway will be added to this amount to determine total amount charged to the card or account. Allowed range is 0.01-999999.99.
reference_id	String	1-50	Reference ID for transaction. This can be a merchant-generated unique identifier for the transaction. The reference_id in the request will be echoed back in the transaction response. This reference_id can also be used for follow-on transactions. If reference_id is not passed with the request, one will be generated by the payment gateway and returned in the response.
currency_code	String	3	ISO currency code for transaction. Possible values: 840 (US or UK), 124 (CA), 036 (AU), 554 (NZ), 756 (UK), 978 (UK)

transaction

Field	Type	Size	Description
language	String	1-5	Language for transaction. Unless overridden by EMV chip in payment card, POS device prompts and receipts will be generated in this language. Possible values: en-US (US), en-CA (Canada), fr-CA (Canada), en-AU (Australia), en-NZ (New Zealand), en-GB (UK)
soft_descriptor	String	1-17	Merchant defined value for displaying the store information, such as name and phone number, that will appear on the cardholder’s credit card statement. Not used for regions AU and NZ.
country_code	String	3	ISO country code where transaction originated. Possible values: 840 (US), 124 (CA), 036 (AU), 554 (NZ), 826 (UK).

processing_indicators

Field	Type	Size	Description
address_verification_service	Boolean	N/A	Indicator to trigger AVS for the request. If set to 'true' and supported by the card issuer, AVS will be performed based on the street address (line 1 and 2) and/or postal code sent in the billing address section of the request. This field defaults to false.
allow_duplicate	Boolean	N/A	Boolean indicator to allow duplicate transactions from the same terminal using the same card and for the same amount within a pre-defined, configurable time period, defaulted to 15 minutes. Default behavior is to reject duplicates.
create_token	Boolean	N/A	Boolean indicator to create a payment instrument token for recurring or account-on-file use.
ecommerce_indicator	String	1	Ecommerce indicator identifying type of ecommerce transaction. Applicable only for card-not-present transactions in US and CA only. For card not present transactions in other regions, this element is not applicable. Possible values: 1 (Mail/Telephone Order), 2 (Recurring), 3 (Installment), 5 (NFC), 7 (SSL, DES, 3DES, RSA)
generate_receipt	Boolean	N/A	Boolean indicator to generate customer and merchant receipt for the transaction.
partial_approval	Boolean	N/A	Boolean indicator to enable partial approvals.

shipping

Field	Description	Accepted Values
date	Date shipped.	String, 10

address

Field	Description	Accepted Values
line1	Address line 1.	String, 1-50
line2	Address line 2.	String, 1-50
city	Address city	String, 1-50
state	State or province. Not available for NZ addresses.	String, 1-50
country	Address country.	String, 1-50
postal_code	Postal code for setup transport keys.	String, 1-9

customer

Field	Description	Accepted Values
title	Customer title.	String, 1-10
first_name	Customer first name.	String, 1-50
middle_name	Customer middle name.	String, 1-50
last_name	Customer last name.	String, 1-50
business_name	Customer Business name. If the customer is a business, use this element instead of the title, first_name, middle_name and last_name fields to pass the customer name.	String, 1-50
email	Valid email address.	String, 1-50
phone	Customer phone number.	String, 2-50
note	Note text added to customer object	1-40

billing_address

Field	Description	Accepted Values
line1	Address line 1.	String, 1-50
line2	Address line 2.	String, 1-50
city	Address city	String, 1-50
state	State or province. Not available for NZ addresses.	String, 1-50
country	Address country.	String, 1-50
postal_code	Postal code for setup transport keys.	String, 1-9

receipt

Field	Description	Accepted Values
clerk_id	Clerk ID to appear on the receipt.	String, 1-20

The following sample illustrates the structural definition for all possible fields in each request. Many of these fields will conflict with each other, refer to the above tables for more information.

{
  "card": {
    "temporary_token":"{fa8859e6-eec1-4289-a20b-de5ffc84c9da}",
    "token":"{EnzMcSVlkP}"
  },
  "customer": {
    "title": "{Mr}",
    "first_name": "{Joe}",
    "middle_name": "{Henry}",
    "last_name": "{Doe}",
    "business_name": "{ABC Company LLC}",
    "email": "{joe.doe@gmail.com}",
    "phone": "{345-090-2334}",
    "note": "{This is a sample note}",
    "billing_address": {
      "line1": "{2600 NW}",
      "line2": "{23th Street}",
      "city": "{Lindon}",
      "state": "{Utah}",
      "country": "{USA}",
      "postal_code": "{84042}"
    }
  },
  "payment": {
    "amount": "{23.09}",
    "currency_code": "{840}",
    "reference_id": "{MER-7414ae80-f0f4-40c3-9c6c-f2983857dd86}",
    "gratuity_amount": "{10.00}",
    "invoice_number": "{239087}"
  },
  "shipping": {
    "date": "{2018-09-14}",
    "address": {
      "line1": "{2600 NW}",
      "line2": "{23th Street}",
      "city": "{Lindon}",
      "state": "{Utah}",
      "country": "{USA}",
      "postal_code": "{84042}"
    }
  },
  "transaction": {
    "country_code": "{840}",
    "language": "{en-US}",
    "soft_descriptor": "{ABC Grocery, Lindon}",
    "processing_indicators": {
      "address_verification_service": "{true}",
      "allow_duplicate": "{true}",
      "create_token": "{true}",
      "ecommerce_indicator": "{2}",
      "generate_receipt": "{true}",
      "partial_approval": "{true}"
    }
  },
  "receipt":{
    "clerk_id":"{Al090-John Doe}"
  }
}