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.

Running Check Transactions

When you integrate with this API, you can do the following:

Run a check sale
Run a check sale with a token
Refund a check transaction
Refund without linking to a previous check transaction

You must send all requests in JSON and we return all responses in JSON.

Important: You must include the required HTTPS headers in each request. The HTTP method for each request is included in each endpoint table. For more information about what to include in your HTTPS headers, see Authenticating Your Requests.

Running a Check Sale

To take a dollar amount from a customer’s checking account, send a CreateCheckSale request to the relevant endpoint.

How it works

Program your POS to send a CreateCheckSale request to the relevant endpoint.

Note: It takes 7-10 days for checking account transactions to clear.

Scenario	Merchant uses POS to:
A customer wants to purchase goods.	Run a sale with the customer's checking account details.

Payment sources

Keyed

Important things to consider

You must save the reference_id that you create in your request. To run follow-on transactions that link to the original transaction, you must include the reference_id as part of the endpoint URL.
If you want to save the customer’s checking account details to use for future transactions, you must include the create_token field in your request.

Sending your request

Endpoints

Environment	HTTP Method	URL
Partner Integration Test	POST	https://api.pit.paygateway.com/transactions/checksales
Production	POST	https://api.paygateway.com/transactions/checksales

CreateCheckSale request fields

Container	Field	Required?	Type	Size	Description
N/A	reference_id	Required	String	1-50	Unique identifier for a transaction. If you do not create a `reference_id` in your request, our gateway generates one. Note: The format is "MER-", for example, `MER-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX`.
check	account_type	Required	String	1-8	Type of checking account that the customer uses to pay for the goods or services. Possible values are: • `Checking` • `Savings`
account_number	Required	String	1-17	Customer's checking account number.
routing_number	Required	String	9	Number that identifies the customer's bank and branch.
branch_transit_number	Conditional	String	5	For Canadian checking accounts, this number identifies that customer's branch. Note: This number is the first 5 digits at the bottom of a check.
financial_institution_number	Optional	String	3	For Canadian checking accounts, this number identifies the customer's bank.
check_number	Optional	String	1-15	Number that identifies a physical check.
customer	first_name	Required	String	1-50	Customer's first name.
last_name	Required	String	1-50	Customer's last name.
middle_name	Optional	String	1-50	Customer's middle name.
payment	amount	Required	String	4-9	Total dollar amount for the transaction. Value must be between 0.01 and 999999.99.
currency_code	Required	String	3	ISO currency code for the transaction. For a list of possible values, see the AuthtokenV2 'region' Field Dependencies enumeration.
invoice_number	Optional	String	1-25	Invoice number or order number that the merchant assigns to the transaction.

processing_indicators container

Container	Field	Required?	Type	Size	Description
processing_indicators	check_verify	Optional	Boolean	-	If set to `true`, we verify the checking account details.
create_token	Optional	Boolean	-	If set to `true`, we save the customer's checking account details to our vault. Our gateway creates a `token` and send it in the response.

Code examples

Request

Content-Type: application/json
Authorization: AuthToken {AuthTokenV2}
X-GP-Request-Id: {request_id}
X-GP-Version: 2021-04-08
X-GP-Api-Key: \{API Key\}
X-GP-Partner-App-Name: \{Name of integrating application\}
{
  "reference_id": "MER-41e40db1-02c8-4214-b2c8-1399aea79afa",
  "check": {
    "account_type": "Checking",
    "account_number": "001221111221",
    "routing_number": "026009593"
},
  "customer": {
    "first_name": "Joe",
     "last_name": "Doe"
},
  "payment": {
     "amount": "23.09",
     "currency_code": "840"
},
  "transaction": {
    "country_code": "840",
    "entry_class": "WEB"
  }
}

Response

201
{
    "checksale_id": "000000084343",
    "status": "check_submitted",
    "check": {
        "masked_account_number": "X2121",
        "routing_number": "112000066",
        "check_number": "999000000084343",
        "token": "qh5gnKAp2m"
    },
    "payment": {
        "amount": "3.94",
        "currency_code": "840",
        "type": "check"
    },
    "transaction": {
        "entry_class": "PPD",
        "language": "en-US"
    },
    "links": [
        {
            "checksale_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/checksales/000000084343",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a check sales transaction."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/checksales/000000084343/checkrefunds",
                    "relation": "refund",
                    "method": "POST",
                    "description": "Use this endpoint to create a check refunds transaction associated with a prior check sale using checksale id."
                }
            ]
        },
        {
            "reference_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/checksales/reference_id/MER-5837dbb6-b6a2-444c-bcf3-b7fad889e2cf",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a check sales transaction using reference_id."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/checksales/reference_id/MER-5837dbb6-b6a2-444c-bcf3-b7fad889e2cf/checkrefunds",
                    "relation": "refund",
                    "method": "POST",
                    "description": "Use this endpoint to create a check refund transaction associated with a prior check sale using reference id."
                }
            ]
        }
    ],
    "reference_id": "MER-5837dbb6-b6a2-444c-bcf3-b7fad889e2cf"
}

Running a Check Sale with a Token

To take a dollar amount from a customer’s checking account using a token, send a CreateCheckSale request to the relevant endpoint.

How it works

Program your POS to send a CreateCheckSale request to the relevant endpoint.

Note: It takes 7-10 days for checking account transactions to clear.

Scenario	Merchant uses POS to:
A customer wants to purchase goods.	Run a sale with the customer's checking account details that they have saved in a previous check transaction.

Payment sources

token

Important things to consider

You must save the reference_id that you create in your request. To run follow-on transactions that link to the original transaction, you must include the reference_id as part of the endpoint URL.

Sending your request

Endpoints

Environment	HTTP Method	URL
Partner Integration Test	POST	https://api.pit.paygateway.com/transactions/checksales
Production	POST	https://api.paygateway.com/transactions/checksales

CreateCheckSale request fields

Container	Field	Required?	Type	Size	Description
N/A	reference_id	Required	String	1-50	Unique identifier for a transaction. If you do not create a `reference_id` in your request, our gateway generates one. Note: The format is "MER-", for example, `MER-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX`.
check	account_type	Required	String	1-8	Type of checking account that the customer uses to pay for the goods or services. Possible values are: • `Checking` • `Savings`
token	Conditional	String	1-34	Unique identifier for the customer's checking account details in our vault.
customer	first_name	Required	String	1-50	Customer's first name.
last_name	Required	String	1-50	Customer's last name.
middle_name	Optional	String	1-50	Customer's middle name.
payment	amount	Required	String	4-9	Total dollar amount for the transaction. Value must be between 0.01 and 999999.99.
currency_code	Required	String	3	ISO currency code for the transaction. For a list of possible values, see the AuthtokenV2 'region' Field Dependencies enumeration.
invoice_number	Optional	String	1-25	Invoice number or order number that the merchant assigns to the transaction.
fees	customer_fee_amount	Conditional	String	1-9	If you have configured the gateway to add fees, this is the dollar amount that our gateway adds to the transaction. Note: This applies to transactions in Australia and New Zealand.
transaction	country_code	Required	String	3	Code that represents the country where the transaction originated from. For a list of possible values, see the AuthtokenV2 'region' Field Dependencies enumeration.
entry_class	Required	String	1-3	Standard Entry Class (SEC) that identifies how the customer submitted the check details. When using a token send .

processing_indicators container

Container	Field	Required?	Type	Size	Description
processing_indicators	check_verify	Optional	Boolean	-	If set to `true`, we verify the checking account details.
create_token	Optional	Boolean	-	If set to `true`, we save the customer's checking account details to our vault. Our gateway creates a `token` and send it in the response.

Code examples

Request

Content-Type: application/json
Authorization: AuthToken {AuthTokenV2}
X-GP-Request-Id: {request_id}
X-GP-Version: 2021-04-08
X-GP-Api-Key: \{API Key\}
X-GP-Partner-App-Name: \{Name of integrating application\}
{
  "reference_id": "MER-41e40db1-02c8-4214-b2c8-1399aea79afa",
  "check": {
    "account_type": "Checking",
    "token": "xxXXXxXXxX"
},
  "customer": {
    "first_name": "Joe",
     "last_name": "Doe"
},
  "payment": {
     "amount": "23.09",
     "currency_code": "840"
},
  "transaction": {
    "country_code": "840",
    "entry_class": "PPD"
  }
}

Response

201
{
    "checksale_id": "000000084350",
    "status": "check_submitted",
    "check": {
        "masked_account_number": "X2121",
        "routing_number": "112000066",
        "check_number": "999000000084350"
    },
    "payment": {
        "amount": "3.89",
        "currency_code": "840",
        "type": "check"
    },
    "transaction": {
        "entry_class": "PPD",
        "language": "en-US"
    },
    "links": [
        {
            "checksale_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/checksales/000000084350",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a check sales transaction."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/checksales/000000084350/checkrefunds",
                    "relation": "refund",
                    "method": "POST",
                    "description": "Use this endpoint to create a check refunds transaction associated with a prior check sale using checksale id."
                }
            ]
        },
        {
            "reference_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/checksales/reference_id/MER-6a738380-d5b6-49f8-a80a-c078b67e32cf",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a check sales transaction using reference_id."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/checksales/reference_id/MER-6a738380-d5b6-49f8-a80a-c078b67e32cf/checkrefunds",
                    "relation": "refund",
                    "method": "POST",
                    "description": "Use this endpoint to create a check refund transaction associated with a prior check sale using reference id."
                }
            ]
        }
    ],
    "reference_id": "MER-6a738380-d5b6-49f8-a80a-c078b67e32cf"
}

Refunding a Check Sale

To return a dollar amount to a customer’s checking account, send a CreateCheckRefund request to the relevant endpoint.

How it works

Program your POS to send a CreateRefund request to the relevant endpoint. To identify the transaction you want to refund, send the reference_id of the original transaction in the endpoint URL for the CreateRefund request. For example: https://api.paygateway.com/transactions/checksales/reference\_id/**MER-41e40db1-02c8-4214-b2c8-1399aea79afa**/checkrefunds

Scenario	Merchant uses POS to:
A customer wants to return goods.	1. Find the original transaction. 2. Return the dollar amount of the original transaction to the customer's checking account.

Payment sources

reference_id

Important things to consider

You don't need to include the customer's checking account details in the request.

Sending your request

Endpoints

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

CreateCheckRefund request fields

Container	Field	Required?	Type	Size	Description
check	account_type	Required	String	1-8	Type of checking account that the customer uses to pay for the goods or services. Possible values are: • `Checking` • `Savings`
payment	amount	Required	String	4-9	Dollar amount of the refund. Value must be between 0.01 and 999999.99.
transaction	entry_class	Required	String	1-3	Standard Entry Class (SEC) that identifies how the customer submitted the check details. For a list of possible values, see the entry_class enumeration.

Code examples

Request

Content-Type: application/json
Authorization: AuthToken {AuthTokenV2}
X-GP-Request-Id: {request_id}
X-GP-Version: 2021-04-08
X-GP-Api-Key: \{API Key\}
X-GP-Partner-App-Name: \{Name of integrating application\}
{
  "check": {
    "account_type": "Checking"
  },
  "payment": {
    "amount": "23.09"
  },
  "transaction": {
    "entry_class": "PPD"
  }
}

Response

201
{
    "checkrefund_id": "000000084341",
    "status": "check_submitted",
    "check": {
        "masked_account_number": "X2121",
        "routing_number": "112000066",
        "check_number": "999000000084341"
    },
    "payment": {
        "amount": "1.18",
        "type": "check"
    },
    "transaction": {
        "entry_class": "PPD"
    },
    "links": [
        {
            "checkrefund_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/checkrefunds/000000084341",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a check refund transaction using checkrefund_id."
                }
            ]
        },
        {
            "reference_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/checkrefunds/reference_id/MER-f2e44e6e-ee1c-4e49-a1a1-71c2904d6d09",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a check refund transaction using reference_id."
                }
            ]
        }
    ],
    "reference_id": "MER-f2e44e6e-ee1c-4e49-a1a1-71c2904d6d09"
}

Refunding a Check Sale without Linking to a Previous Transaction

To return a dollar amount to a customer’s checking account without linking to a previous transaction, send a CreateCheckRefund request to the relevant endpoint.

How it works

Program your POS to send a CreateCheckRefund request to the relevant endpoint.

Scenario	Merchant uses POS to:
A customer wants to return goods.	Return a dollar amount to the customer's checking account.

Payment sources

Keyed

Important things to consider

You must include the customer's checking account details in the request.

Sending your request

Endpoints

Environment	HTTP Method	URL
Partner Integration Test	POST	https://api.pit.paygateway.com/transactions/checkrefunds
Production	POST	https://api.paygateway.com/transactions/checkrefunds

CreateCheckRefund request fields

Container	Field	Required?	Type	Size	Description
N/A	reference_id	Required	String	1-50	Unique identifier for a transaction. If you do not create a `reference_id` in your request, our gateway generates one. Note: The format is "MER-", for example, `MER-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX`.
check	account_type	Required	String	1-8	Type of checking account that the customer uses to pay for the goods or services. Possible values are: • `Checking` • `Savings`
account_number	Required	String	1-17	Customer's checking account number.
routing_number	Required	String	9	Number that identifies the customer's bank and branch.
branch_transit_number	Conditional	String	5	For Canadian checking accounts, this number identifies that customer's branch. Note: This number is the first 5 digits at the bottom of a check.
financial_institution_number	Optional	String	3	For Canadian checking accounts, this number identifies the customer's bank.
check_number	Optional	String	1-15	Number that identifies a physical check.
customer	first_name	Required	String	1-50	Customer's first name.
last_name	Required	String	1-50	Customer's last name.
middle_name	Optional	String	1-50	Customer's middle name.
payment	amount	Required	String	4-9	Total dollar amount for the transaction. Value must be between 0.01 and 999999.99.
currency_code	Required	String	3	ISO currency code for the transaction. For a list of possible values, see the AuthtokenV2 'region' Field Dependencies enumeration.
invoice_number	Optional	String	1-25	Invoice number or order number that the merchant assigns to the transaction.

Code examples

Request

Content-Type: application/json
Authorization: AuthToken {AuthTokenV2}
X-GP-Request-Id: {request_id}
X-GP-Version: 2021-04-08
X-GP-Api-Key: \{API Key\}
X-GP-Partner-App-Name: \{Name of integrating application\}
{
  "reference_id": "MER-41e40db1-02c8-4214-b2c8-1399aea79afa",
  "check": {
    "account_number": "12121",
    "routing_number": "112000066",
    "account_type": "Checking"
  },
  "customer": {
    "first_name": "John",        
    "last_name": "Smith"
  },
  "payment": {
    "amount": "23.09",
    "currency_code": "840"
  },
  "transaction": {
    "country_code": "840",
    "entry_class": "PPD"
  }
}

Response

201
{
    "checkrefund_id": "000000084353",
    "status": "check_submitted",
    "check": {
        "masked_account_number": "X2121",
        "routing_number": "112000066",
        "check_number": "999000000084353"
    },
    "payment": {
        "amount": "3.89",
        "currency_code": "840",
        "type": "check"
    },
    "transaction": {
        "entry_class": "PPD",
        "language": "en-US"
    },
    "links": [
        {
            "checkrefund_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/checkrefunds/000000084353",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a check refund transaction using checkrefund_id."
                }
            ]
        },
        {
            "reference_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/checkrefunds/reference_id/MER-50bc5eb9-37e5-4e04-ad49-bfd71d820303",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a check refund transaction using reference_id."
                }
            ]
        }
    ],
    "reference_id": "MER-50bc5eb9-37e5-4e04-ad49-bfd71d820303"
}

Enumerations

AuthtokenV2 'region' Field Dependencies

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

entry_class

Value	Name	Description	Industry type
PPD	Prearranged Payment and Deposit Entry Note: When running a sale with saved checking account details, send `PPD`.	A single or recurring transaction between a business and a customer.	Retail or MOTO
TEL	Telephone-Initiated Entry	A single telephone transaction.	MOTO
WEB	Internet-Initiated Entry	A single online transaction.	e-Commerce
CCD	Corporate Credit or Debit Entry	A single or recurring transaction between businesses.	Retail, MOTO, or e-Commerce

Disclosure Text for Customers

Web Authorization Language

The payment amount of "charge_total" will be electronically debited from your account. I authorize "merchant_name" to electronically debit the account listed above for the amount of this purchase. If this item is dishonored or returned for any reasons, I authorize an additional debit to the account listed above for 25.00 USD or the maximum amount allowed by law, whichever is greater. By clicking on the button below, I agree to the terms of this agreement and authorize this purchase.

Click the payment_button button to complete the transaction. Remember to record this transaction in your check register. When your transaction has been completed successfully you will have the option to print, save, or email your receipt for this purchase."

I understand that this authorization will remain in full force and effect until I notify COMPANY [insert manner of revocation, i.e., in writing, by phone, location, address, etc.] that I wish to revoke this authorization. I understand that COMPANY requires at least [X days/weeks] prior notice in order to cancel this authorization.

TEL Authorization Language

TEL transactions are by definition those that are authorized over the telephone granting a business permission to debit a consumer’s personal checking or savings account. NACHA permits these transactions if the customer initiates the call, or if the merchant initiates the call and there is a pre‐existing relationship between the customer and the merchant (a contract in place, or the customer has done business with the merchant in the last 2 years).

TEL transactions are used when a merchant obtains the bank account information and permission to charge the account from a customer over the phone. Transactions are either one-time or recurring.

There are two ways to authorize a TEL transaction, which may be used together or separately.

Voice Recording
Notify the caller that the call is being recorded
Clearly state the particulars of the transaction—Use the following as a template:

Single Transaction Script

I want to confirm that today {insert current date} you are authorizing {insert your company name} to initiate a one‐time ACH debit from your bank account for {amount} on {date}. If you have any questions about this debit you can reach us at {insert your business phone number}. Please say “I agree” to authorize this transaction.

Send an email receipt as described (Optional)
Save the authorization recording for at least 90 days and up to 2 years (if you don’t send receipts).
Email, Mail, or Fax Confirmation (You must prove the confirmation was sent, you’re not required to prove it was received)
Send an email, fax, or mailed confirmation BEFORE the transaction is submitted to the bank
Make sure the email contains the customer’s name, the last 4 digits of the bank account number, the transaction amount, the date it was authorized, the date it will be processed, and a number where the customer can contact you
Keep a copy of the receipt on file (for emails, CC or BCC to your email address) for 2 years

Recurring TEL Transaction Script

I want to confirm that today {insert current date} you {insert the customer’s full name} are authorizing {insert your company name} to initiate a recurring ACH debit from your {insert bank name} bank account ending in {insert last 4 digits of bank account #} for {amount, or how amount is to be calculated; i.e. for your monthly greens fees, not to exceed 500 USB} on {schedule frequency, i.e. the 15th of each month} starting on {insert start date} and ending on {insert end date, or “when you notify us to terminate the schedule.”} If you have any questions about this schedule, or if you would like to cancel or change the schedule, you can reach us at {insert your business phone number}. Please say “I agree” to authorize this transaction.

Send an email, fax, or mailed confirmation BEFORE the first scheduled transaction is submitted to be processed. The notification must include the following:
- The Recurring Transaction Amount (or how the variable amount will be calculated)
- The Date the Recurring Schedule was authorized
- The schedule on which payments will be generated, including the start date and end date, if any.
- Your Company Name
- The Customer’s Bank Account that will be debited (At least bank name and last 4 digits of acct #)
- A telephone number where your company may be contacted during regular business hours
- An email address that is monitored during regular business hours
- Keep a copy of the receipt on file (for emails, CC to your email address) for 2 years after the last payment on the schedule is processed

PPD