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 Credit Transactions

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

Run a sale
Save card details to our vault
Run a sale with a token
Void a transaction
Refund a transaction
Query a 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 the HTTPS headers, see Authenticating Your Requests.

Running a Sale

To take a dollar amount from a customer's account, send a CreateSale request to the relevant endpoint.

Note: If you want to run a sale using a customer's saved payment details, you must run a sale with a token.

How it works

Program the POS to send a CreateSale request to the relevant endpoint.

Scenario	Merchant uses the POS to:
A customer wants to purchase goods.	Take a dollar amount from the customer's account.

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 card 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/creditsales
Production	POST	https://api.paygateway.com/transactions/creditsales

CreateSale 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`, our gateway generates one. Note: The format is "MER-", for example, MER-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
card	temporary_token	Required	String	1-34	Temporary identifier for the card details. Our gateway generates this when the customer submits their payment details. Note: You can use this token only once.
customer	billing_address	Required	Container	-	Container that includes information about the customer's billing address. See the billing_address container.
title	Optional	String	1-10	Customer's title.
first_name	Optional	String	1-50	Customer's first name.
last_name	Optional	String	1-50	Customer's last name.
middle_name	Optional	String	1-50	Customer's middle name.
business_name	Optional	String	1-50	Name of the customer's business. Note: If the customer is a business, use this field instead of the `title`, `first_name`, `last_name`, and `middle_name` fields.
email	Optional	String	1-50	Customer's email address.
phone	Optional	String	2-50	Customer's phone number.
note	Optional	String	1-40	Extra information that you can add about the customer.
payment	amount	Required	Required	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 AuthtokenV2 'region' Field Dependenciess enumerations.
gratuity_amount

billing_address container

Field	Required?	Type	Size	Description
line1	Required	String	1-50	First line of the customer's address.
postal_code	Required	String	1-9	Postal code of the customer's address.
line2	Optional	String	1-50	Second line of the customer's address.
city	Optional	String	1-50	City of the customer's address.
state	Optional	String	1-50	State or province of the customer's address. Note: Do not include this in your request for New Zealand addresses.
country	Optional	String	1-50	Country of the customer's address.

processing_indicators container

Field	Required?	Type	Size	Description
address_verification_service	Required	Boolean	-	If set to `true`, we run AVS on the transaction. Our gateway returns the AVS information in the response. Note: The default for this fields is `false`. If set to `true`, the card issuer must also support AVS.
generate_receipt	Required	Boolean	-	If set to `true`, the POS generates a customer copy and a merchant copy of the receipt for the transaction.
allow_duplicate	Optional	Boolean	-	If set to `true`, we allow you to send duplicate transactions. The default time frame to block duplicate transactions is 15 minutes.
create_token	Optional	Boolean	-	If set to `true`, we save the card details to our vault. Our gateway creates a `token` and returns it in the response.
partial_approval	Optional	Boolean	-	If set to `true`, we allow you to accept partial approvals.

address container

Field	Required?	Type	Size	Description
line1	Optional	String	1-50	First line of the customer's address.
line2	Optional	String	1-50	Second line of the customer's address.
city	Optional	String	1-50	City of the customer's address.
state	Optional	String	1-50	State or province of the customer's address. Note: Do not include this in your request for New Zealand addresses.
country	Optional	String	1-50	Country of the customer's address.
postal_code	Optional	String	1-9	Postal code of the customer's address.

Code examples

Request

Response

Saving Card Details to our Vault

To save a customer's card details to our vault or to verify that a customer's account is valid, send a CreateAuth request.

Note: This transaction is also known as a zero dollar authorization or an address verification transaction.

How it works

Program the POS to send a CreateAuth request to the relevant endpoint. Depending on your request, our gateway returns the following:

If you send true for the create_token field, our gateway tokenizes the customer's card details and returns the token in the response.
If you send true for the address_verification_service field, our gateway runs an AVS check and returns the result in the response.

Scenario	Merchant uses the POS to:
A merchant wants to save a customer's card details to use for future transactions.	Run an authorization for $0.00.

Payment sources

Keyed

Important things to consider

If the transaction declines, our gateway still generates a token.
You can't send a CreateAuth request for more than $0.00.

Sending your request

Endpoints

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

CreateAuth 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`, our gateway generates one. Note: The format is "MER-", for example, MER-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
card	temporary_token	Required	String	1-34	Temporary identifier for the card details. Our gateway generates this when the customer submits their payment details. Note: You can use this token only once.
customer	billing_address	Required	Container	-	Container that includes information about the customer's billing address. See the billing_address container.
title	Optional	String	1-10	Customer's title.
first_name	Optional	String	1-50	Customer's first name.
last_name	Optional	String	1-50	Customer's last name.
middle_name	Optional	String	1-50	Customer's middle name.
business_name	Optional	String	1-50	Name of the customer's business. Note: If the customer is a business, use this field instead of the `title`, `first_name`, `last_name`, and `middle_name` fields.
email	Optional	String	1-50	Customer's email address.
phone	Optional	String	2-50	Customer's phone number.
note	Optional	String	1-40	Extra information that you can add about the customer.
payment	currency_code	Required	String	3	ISO currency code for the transaction. For a list of possible values, see AuthtokenV2 'region' Field Dependencies enumeration.
amount	Required	String	4-9	Total dollar amount for the transaction. Value must be between 0.01 and 999999.99.
gratituity_amount

billing_address container

Field	Required?	Type	Size	Description
line1	Required	String	1-50	First line of the customer's address.
postal_code	Required	String	1-9	Postal code of the customer's address.
line2	Optional	String	1-50	Second line of the customer's address.
city	Optional	String	1-50	City of the customer's address.
state	Optional	String	1-50	State or province of the customer's address. Note: Do not include this in your request for New Zealand addresses.
country	Optional	String	1-50	Country of the customer's address.

processing_indicators container

Field	Required?	Type	Size	Description
address_verification_service	Required	Boolean	-	If set to `true`, we run AVS on the transaction. Our gateway returns the AVS information in the response. Note: The default for this fields is `false`. If set to `true`, the card issuer must also support AVS.
create_token	Required	Boolean	-	If set to `true`, we save the card details to our vault. Our gateway creates a `token` and returns it in the response.
generate_receipt	Required	Boolean	-	If set to `true`, the POS generates a customer copy and a merchant copy of the receipt for the transaction.
allow_duplicate	Optional	Boolean	-	If set to `true`, we allow you to send duplicate transactions. The default time frame to block duplicate transactions is 15 minutes.
partial_approval	Optional	Boolean	-	If set to `true`, we allow you to accept partial approvals.

address container

Field	Required?	Type	Size	Description
line1	Optional	String	1-50	First line of the customer's address.
line2	Optional	String	1-50	Second line of the customer's address.
city	Optional	String	1-50	City of the customer's address.
state	Optional	String	1-50	State or province of the customer's address. Note: Do not include this in your request for New Zealand addresses.
country	Optional	String	1-50	Country of the customer's address.
postal_code	Optional	String	1-9	Postal code of the customer's address.

Code examples

Request

Response

Running a Sale with a Token

To take a dollar amount from a customer's account using saved card details, send a CreateSale request to the relevant endpoint.

How it works

Program the POS to take the dollar amount for the transaction using the token for the saved card.

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

Payment sources

token

Sending your request

Endpoints

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

CreateSale 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`, our gateway generates one. Note: The format is "MER-", for example, MER-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
card	token	Required	String	1-34	Identifier for the saved card details.
customer	billing_address	Required	Container	-	Container that includes information about the customer's billing address. See the billing_address container.
title	Optional	String	1-10	Customer's title.
first_name	Optional	String	1-50	Customer's first name.
last_name	Optional	String	1-50	Customer's last name.
middle_name	Optional	String	1-50	Customer's middle name.
business_name	Optional	String	1-50	Name of the customer's business. Note: If the customer is a business, use this field instead of the `title`, `first_name`, `last_name`, and `middle_name` fields.
email	Optional	String	1-50	Customer's email address.
phone	Optional	String	2-50	Customer's phone number.
note	Optional	String	1-40	Extra information that you can add about the customer.
payment	currency_code	Required	String	3	ISO currency code for the transaction. For a list of possible values, see AuthtokenV2 'region' Field Dependencies enumeration.
amount	Required	String	4-9	Total dollar amount for the transaction. Value must be between 0.01 and 999999.99.
gratituity_amount	Optional	String	1-7	Dollar amount to include as a tip in the transaction.

billing_address container

Field	Required?	Type	Size	Description
line1	Required	String	1-50	First line of the customer's address.
postal_code	Required	String	1-9	Postal code of the customer's address.
line2	Optional	String	1-50	Second line of the customer's address.
city	Optional	String	1-50	City of the customer's address.
state	Optional	String	1-50	State or province of the customer's address. Note: Do not include this in your request for New Zealand addresses.
country	Optional	String	1-50	Country of the customer's address.

processing_indicators container

Field	Required?	Type	Size	Description
address_verification_service	Required	Boolean	-	If set to `true`, we run AVS on the transaction. Our gateway returns the AVS information in the response. Note: The default for this fields is `false`. If set to `true`, the card issuer must also support AVS.
generate_receipt	Required	Boolean	-	If set to `true`, the POS generates a customer copy and a merchant copy of the receipt for the transaction.
allow_duplicate	Optional	Boolean	-	If set to `true`, we allow you to send duplicate transactions. The default time frame to block duplicate transactions is 15 minutes.
create_token	Optional	Boolean	-	If set to `true`, we save the card details to our vault. Our gateway creates a `token` and returns it in the response.
partial_approval	Optional	Boolean	-	If set to `true`, we allow you to accept partial approvals.

address container

Field	Required?	Type	Size	Description
line1	Optional	String	1-50	First line of the customer's address.
line2	Optional	String	1-50	Second line of the customer's address.
city	Optional	String	1-50	City of the customer's address.
state	Optional	String	1-50	State or province of the customer's address. Note: Do not include this in your request for New Zealand addresses.
country	Optional	String	1-50	Country of the customer's address.
postal_code	Optional	String	1-9	Postal code of the customer's address.

Code examples

Request

Response

Voiding a Sale

To cancel a transaction that is in an open batch, send a CreateVoid request to the relevant endpoint.

How it works

Program the POS to send a CreateVoid request to the relevant endpoint. To identify the transaction you want to cancel, send the reference_id of the original transaction in the endpoint URL for the CreateVoid request. For example, https://api.pit.paygateway.com/transactions/creditsales/reference\_id/**MER-41e0db1-02c8-4214-b2c8-1399aea79afa**/voids.

When you successfully send a request, our gateway removes the transaction from the open batch, which means the processor doesn't take the dollar amount from the customer's account.

Scenario	Merchant uses the POS to:
A customer wants to return goods. The merchant has not closed the batch that contains the original transaction.	1.Find the original transaction. 2. Cancel the transaction to stop the customer from being charged.

Payment sources

reference_id

Important things to consider

The dollar amount for the CreateVoid transaction must match the dollar amount of the original transaction.

Sending your request

Endpoints

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

CreateVoid request fields

Container	Field	Required?	Type	Size	Description
payment	amount	Required	String	4-9	Total dollar amount of the original transaction. Value must be between 0.01 and 999999.99.
gratuity_amount	Optional	String	1-7	Dollar amount that was tip in the original transaction.
invoice_number	Optional	String	1-25	Invoice number or order number that the merchant assigned to the transaction.
currency_code	Optional	String	3	ISO currency code for the transaction. For a list of possible values, see AuthtokenV2 'region' Field Dependencies enumeration.

Code examples

Request

Response

Refunding a Transaction

To return a dollar amount to a customer's account, send a CreateRefund request to the relevant endpoint.

How it works

Program the 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.pit.paygateway.com/transactions/creditsales/reference\_id/**MER-41e0db1-02c8-4214-b2c8-1399aea79afa**/returns.

When you successfully send a request, our gateway sends the refund to the processor to return the dollar amount to the customer's account.

Note: You should refund only transactions that are in a closed batch. If the original transaction is in an open batch, you should send a CreateVoid request.

Scenario	Merchant uses the POS to:
A customer wants to return goods. The merchant has closed the batch that contains the original transaction.	1. Find the original transaction. 2. Return the dollar amount of the original transaction to the customer's account.

Payment sources

reference_id

Important things to consider

You can refund a partial amount, however, the total dollar amount for all partial refunds cannot be higher than the total dollar amount for the original transaction.

Sending your request

Endpoints

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

CreateRefund request fields

Container	Field	Required?	Type	Size	Description
payment	amount	Required	String	4-9	Dollar amount that you want to return to the customer's account. Value must be between 0.01 and 999999.99.
gratuity_amount	Optional	String	1-7	Dollar amount that was tip in the original transaction.
invoice_number	Optional	String	1-25	Invoice number or order number that the merchant assigned to the transaction.
currency_code	Optional	String	3	ISO currency code for the transaction. For a list of possible values, see AuthtokenV2 'region' Field Dependencies enumeration.

Code examples

Request

Response

Querying a Transaction

To view the details of a previous transaction, send a CreateQuery request to the relevant endpoint.

How it works

Program the POS to send a CreateQuery request to the relevant endpoint. To identify the original transaction, send the reference_id of the original transaction in the endpoint URL for the CreateQuery request. For example, https://api.pit.paygateway.com/transactions/card/sales/reference\_id/**MER-41e0db1-02c8-4214-b2c8-1399aea79afa**.

Scenario	Merchant uses the POS to:
A transaction has timed out and the merchant wants to confirm if it was processed.	Find the transaction and view the transaction details.

Payment sources

reference_id

Important things to consider

You can refund a partial amount, however, the total dollar amount for all partial refunds cannot be higher than the total dollar amount for the original transaction.

Sending your request

Endpoints

Environment	HTTP Method	URL
Partner Integration Test	GET	https://api.pit.paygateway.com/transactions/creditsales/reference\_id/{reference_id}?generate\_receipt=true
Production	GET	https://api.paygateway.com/transactions/creditsales/reference\_id/{reference_id}?generate\_receipt=true

Note: Do not include a body in this request. You need to send only the HTTPS headers.

Code examples

Request

Response

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

Ecommerce_indicator

Values	Description
1	Mail order or telephone order
2	Recurring billing
3	Instalment billing
5	Contactless payment (NFC)
7	SSL, DES, 3DES, or RAS