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.

Card Not Present

Verifying a payment card

To verify a customer’s card details, send a POST request to the relevant endpoint.

Because the card is not present, the request must include either the customer's payment details or their corresponding token.

The token is either temporary (generated through PayFields and can be used for one transaction only) or permanent (represents the customer's saved payment details in our vault and can be used for unlimited transactions).

Important: The value for the amount parameter can only be 0.00.

Endpoints

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

Request

Important: Some objects have the same names, however, the parameters may be different. For more information, go to Object naming.

Object	Parameter	Type	Size	Required	Description
N/A	reference_id	String	1-50	Required	Unique identifier for the transaction. This is an alphanumeric value that the merchant creates, for example, `XAZR863990`.
card	card_number	String	13-19	Conditional	Primary account number (PAN) on the payment card.
card_security_code	String	1-4	Optional	Three-digit code or four-digit code that is printed on the payment card. Also known as: • Card verification value (CVV) • Card verification code (CVC)
cardholder_name	String	2-26	Optional	The cardholder's name that is printed on the payment card. When generating a receipt, this value is printed on the signature line of the receipt. For integrations in Australia or New Zealand, if you send a value for card_number, you must send a value for cardholder_name.
expiry_month	String	2	Conditional	Month that the card expires, in MM format.
expiry_year	String	2	Conditional	Year that the card expires, in YY format.
temporary_token	String	1-34	Conditional	Single-use token for the customer's card details. Note: If you send a value for the temporary_token parameter, do not send values for the following parameters: • card_number • expiry_month • expiry_year • token
token	String	1-40	Conditional	Unique alphanumeric value that identifies the card details in our vault. If you send a value for the token parameter, do not send values for the following parameters: • card_number • expiry_month • expiry_year • temporary_token
three_ds	Object	-	Conditional	Object that contains authentication information for transactions that use 3D Secure. For a list of parameters, see the three_ds object.
customer	id	String	1-225	Optional	Customer's ID from the Customer Experience (CX) application.
title	String	1-10	Optional	Customer’s title. You can send an alphanumeric value. Note: If the customer is a business, do not send this parameter. Send the business_name parameter.
first_name	String	1-50	Conditional	Customer’s first name. Notes: • If the customer is a business, do not send this parameter. Send the business_name parameter. • The combined length of the values for the following parameters must not exceed 50 characters:titlefirst_namemiddle_namelast_name • title • first_name • middle_name • last_name
middle_name	String	1-50	Optional	Customer’s middle name. Note: If the customer is a business, do not send this parameter. Send the business_name parameter.
last_name	String	1-50	Conditional	Customer’s last name. Notes: • If the customer is a business, do not send this parameter. Send the business_name parameter. • The combined length of the values for the following parameters must not exceed 50 characters:titlefirst_namemiddle_namelast_name • title • first_name • middle_name • last_name
business_name	String	1-50	Optional	Business name. Note: If the customer is not a business, send a value for each of the following parameters: • title • first_name • middle_name • last_name
email	String	1-50	Optional	Customer's email address.
note	String	1-250	Optional	Note that the merchant adds about the customer.
phone	String	2-50	Optional	Customer's phone number.
billing_address	Object	-	Optional	Object that includes the customer's billing address. For a list of parameters, see the address object.
payment	amount	String	1-9	Required	Total amount for the transaction. The value can only be `0.00.`
currency_code	String	Explicit	Required	ISO currency code for the transaction. For a list of possible values, see the currency code enumeration.
invoice_number	String	1-25	Optional	Alphanumeric invoice number or order number that the merchant creates and assigns to the transaction. Note: Send this parameter for integrations only in the US or Canada.
shipping	date	String	10	Optional	Date that the merchant shipped the item. The value must be in the format YYYY-MM-DD, for example, `2021-09-14`. Note Do not send this parameter for integrations in Australia or New Zealand.
address	Object	-	Optional	Objects that contains the customer's shipping address. For a list of parameters, see the address object. Note: Do not send this parameter for integrations in Australia or New Zealand.
transaction	country_code	String	3	Required	Code that represents the country where the transaction originated. For a list of possible values, see the country code enumeration.
ecommerce_indicator	String	Explicit	Optional	Code that represents the type of transaction and how the merchant collected the customer's card details. For a list of possible values, see the eCommerce indicator enumeration. Note: Send this parameter for integrations in the US and Canada only, and when the card is not present.
language	String	1-5	Optional	Language for the text that displays on your payment page and receipts. For a list of possible values, see the language enumeration. Note: If the customer uses an EMV card, the language registered to the card may override the language on the payment page and receipt.
soft_descriptor	String	1-17	Optional	Descriptor that displays on a customer's card statement. For example, `ABC Grocery, Lindon`. Note: Do not send this parameter for integrations in Australia or New Zealand.
processing_indicator	Object	-	Optional	Object that includes options for additional actions. For a list of parameters, see the processing_indicators object.
receipt	clerk_id	String	1-20	Required	Clerk ID that the merchant wants to display on the receipt. This is an alphanumeric value that the merchant assigns to a clerk, for example, `Al090-John Doe`. Note: Do not send this parameter for integrations in Australia or New Zealand.

three_ds object

Parameter	Type	Size	Required?	Description
authentication_id	String	1-50	Conditional	Unique identifier used in transactions that use 3D Secure to authenticate the customer's identity. In the UK, if the transaction uses 3D Secure, you must send a value for authentication_id.

address object

Parameter	Type	Size	Required?	Description
line1	String	1-50	Optional	First line of the customer's address.
line2	String	1-50	Optional	Second line of the customer's address.
city	String	1-50	Optional	City of the customer's address. Note: For Australia and New Zealand, use the suburb of the customer's address for this parameter.
state	String	1-50	Optional	State or province of the customer's address. Note: Do not send this parameter for integrations in New Zealand.
country	String	1-50	Optional	Country of the customer's address.
postal_code	String	1-20	Optional	Postal code or zip code of the customer's address.

processing_indicators object

Parameter	Type	Size	Required?	Description
address_verification_service	Boolean	Explicit	Optional	If set to `true`, the issuing bank verifies that the billing address matches the address that they have on file for the cardholder. Notes: • Some issuing banks don't support this function. • Send this parameter for integrations in the US or Canada only.
create_token	Boolean	Explicit	Optional	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	Boolean	Explicit	Optional	If set to `true`, we generate a receipt and return it in the receipt object of the response. Note: Send this parameter for integrations in the US or Canada only.
partial_approval	Boolean	Explicit	Optional	If set to `true`, we allow partial approvals. Note: Send this parameter for integrations in the US or Canada only.

Request body example

{
    "reference_id": "MER-26395a60-08db-4eb3-b5ba-42275c281e72",
    "card": {
        "card_number":"4761739001010010",
        "expiry_month":"12",
        "expiry_year":"25",
        "cardholder_name":"test name"
    },
    "payment": {
        "amount": "0.00",        
        "currency_code": "840"
    },
    "transaction": {
        "country_code": "840",
        "processing_indicators":{
        	"create_token":true            
        }
    }
}

Response

Object	Field	Type	Description
N/A	creditauth_id	String	Unique identifier that our gateway generated for the transaction.
status	String	Indicates the status of the transaction. For a list of possible values, see the transaction status enumeration.
approval_code	String	Approval code for the transaction from the processor. Note: For integrations in Australia or New Zealand, our gateway returns a value of `NA.`
avs_response	String	Response code from an address verification service (AVS) lookup. For a list of possible values, see the AVS response enumeration.
avs_response_description	String	Text that describes the response code that the processor returned in the avs_response field.
cardsecurity_response	String	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
processor_response	String	Response from the processor that describes the status of the transaction.
reference_id	String	Unique identifier that the merchant created for the transaction. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: This is the reference_id that you can include in the endpoint URL for follow-on transactions.
card	masked_card_number	String	Masked card number of the card that the customer used for the transaction. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • For integrations in Australia or New Zealand, our gateway masks all digits except the last four digits. • If our gateway cannot return a masked card number, it returns a value of .

fees object

Field	Type	Description
customer_fee_amount	String	For integrations in Australia or New Zealand, these are the total fees that the customer paid for the transaction.

text object

Field	type	Description
customer_receipt	String	Text for the customer’s receipt, which contains the details of the transaction.
merchant_receipt	String	Text for the merchant’s receipt, which contains the details of the transaction.

attributes object

Field	Type	Name
authorization_agreement	String	Text that describes the merchant's authorization agreement, for example, `I agree to pay the total amount according to the card issuer agreement.`
call_issuer	String	Text that displays if the merchant needs to call the issuing bank, for example, `CALL ISSUER`.
copy_label_customer	String	Text that identifies the receipt as the customer's copy.
copy_label_merchant	String	Text that identifies the receipt as the merchant's copy.
merchant_address	String	Address of the merchant's store.
merchant_footer	String	Text that appears on the footer of the receipt.
merchant_header	String	Text that appears on the header of the receipt.
merchant_name	String	Name of the merchant's store.
merchant_phone	String	Phone number of the merchant's store.
merchant_policy	String	Text that describes the merchant's policies, for example, a return policy.
verbiage	String	Additional text that the merchant can include on the receipt, for example, `Approved - Thank You.`

labeled_attributes object

Our gateway returns a label field and a value field for each object. For example, our gateway returns the following for the amount object:
"amount":
{
"label": "Total Amount",
"value": "0.00 USD"
}

Object	Description
amount	Total amount of the transaction.
approval_code	Approval code for the transaction from the processor.
authorization_response_code	Response code for the authorization.
avs_response_code	Response code that indicates the result of an AVS check.
batch_number	Unique identifier of the batch.
card_balance	Remaining balance of a prepaid card.
cardsecurity_response_code	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
clerk_id	Clerk ID that the merchant wants to display on the receipt. This is an alphanumeric value that the merchant assigns to a clerk, for example, `Al090-John Doe`.
entry_legend	Indicates how the payment terminal read the card details. The value is one of the following: • `CHIP READ` • `MAGSTRIPE` • `MANUAL`
entry method	Indicates how the user entered the card details. The value is one of the following: • `Contact` • `Contactless` • `Manual` • `Swipe`
gratuity_amount	Amount that was included as a tip in the transaction.
masked_card_number	Masked card number of the card that the customer used for the transaction. Depending on the location of the POS, our gateway returns a different masked card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • For integrations in Australia or New Zealand, our gateway masks all digits except the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA.`
merchant_id	Unique identifier of the merchant.
original_auth_code	The authorization code of the transaction.
payment_type	Type of payment for the transaction. For a list of possible values, see the payment type enumeration.

Successful response example

{
    "creditauth_id": "000000000116",
    "status": "approved",
    "approval_code": "941655",
    "processor_response": "DEVELOPMENT APPROVAL",
    "card": {
        "masked_card_number": "476173XXXXXX0010",
        "cardholder_name": "test name",
        "expiry_month": "12",
        "expiry_year": "25",
        "token": "ObT5udy7Ub",
        "type": "visa"
    },
    "payment": {
        "amount": "0.00",
        "currency_code": "840",
        "type": "credit"
    },
    "transaction": {
        "entry_type": "keyed",
        "language": "en-US"
    },
    "reference_id": "MER-26395a60-08db-4eb3-b5ba-42275c281e72"
}

Unsuccessful response schema

Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see Status and error codes.
message	String	Text that describes the error.
detail	Object	Information that specifies the error’s location in the message body. Our gateway returns this object only when you receive an HTTP status code of 400. For a list of fields, see the detail object.
info	String	A link to our website for more information.

Field	Type	Description
description	string	Text that provides specific information about the error.
data_path	String	Location of the error, for example, transaction/country_code.

Unsuccessful response example

{
  "error": {
    "code": "server_error",
    "message": "Server error. Please contact OpenEdge support",
    "detail": [
      {
        "description": "Invalid type: number (expected string)",
        "data_path": "/payment/currency_code"
      }
    ],
    "info": "https://developers.paygateway.com/errors"
  }
}

Running a credit authorization

To run a credit authorization, send a POST request to the relevant endpoint.

Because the card is not present, the request must include the customer's payment details.
Important: Use the creditauth_id or reference_id from this request to capture the credit authorization.

Endpoints

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

Request

Object	Parameter	Type	Size	Required?	Description
-	reference_id	String	1-50	Required	Unique identifier for the transaction. This is an alphanumeric value that the merchant creates, for example, XAZR863990.
card	card_number	String	13-19	Conditional	Primary account number (PAN) on the payment card.
cardholder_name	String	2-26	Conditional	The cardholder's name that is printed on the payment card. When generating a receipt, this value is printed on the signature line of the receipt. For integrations in Australia or New Zealand, if you send a value for card_number, you must send a value for cardholder_name.
expiry_month	String	2	Conditional	Month that the card expires, in MM format.
expiry_year	String	2	Conditional	Year that the card expires, in YY format.
temporary_token	String	1-34	Conditional	Single-use token for the customer’s card details. Note: If you send a value for the temporary_token parameter, do not send values for the following parameters: • card_number • expiry_month • expiry_year • token
payment	amount	String	1-9	Required	Total amount for the transaction.
currency_code	String	Explicit	Required	ISO currency code for the transaction. For a list of possible values, see the currency code enumeration.
transaction	country_code	String	3	Required	Code that represents the country where the transaction originated. For a list of possible values, see the country code enumeration.
processing_indicators	Object	-	Optional	Object that includes options for additional actions. For a list of parameters, see the processing_indicators object.

processing_indicators object

Parameter	Type	Size	Required?	Description
create_token	Boolean	Explicit	Optional	If set to true, we save the card details to our vault. Our gateway creates a token and returns it in the response.

Request Body Example

{
    "reference_id": "MER-26395a60-08db-4eb3-b5ba-42275c281e72",
    "card": {
        "card_number":"4761739001010010",
        "expiry_month":"12",
        "expiry_year":"25",
        "cardholder_name":"test name"
    },
    "payment": {
        "amount": "50.00",        
        "currency_code": "840"
    },
    "transaction": {
        "country_code": "840",
        "processing_indicators":{
        	"create_token":true            
        }
    }
}

Response

Object	Field	Type	Description
-	creditsale_id	String	Unique identifier that our gateway generated for the transaction.
status	String	Indicates the status of the transaction. For a list of possible values, see the transaction status enumeration.
approval_code	String	Approval code for the transaction from the processor. Note: For integrations in Australia or New Zealand, our gateway returns a value of NA.
processor_response	String	Response from the processor that describes the status of the transaction.
reference_id	String	Unique identifier that the merchant created for the transaction. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: This is the reference_id that you can include in the endpoint URL for follow-on transactions.
card	masked_card_number	String	Masked card number of the card that the customer used for the sale. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • For integrations in Australia or New Zealand, our gateway masks all digits except the last four digits. • If our gateway cannot return a masked card number, it returns a value of NA.
cardholder_name	String	Name that appears on the customer’s card.
expiry_month	String	Month that the card expires, in MM format. If our gateway cannot return an expiry month, it returns a value of NA.
expiry_year	String	Year that the card expires, in YY format. If our gateway cannot return an expiry year, it returns a value of NA.
token	String	Unique reference for the customer's payment details that they stored in our vault. Note: Do not send this token in follow-on transactions as it is not yet compliant with card brand regulations.
type	String	Name of the card brand that issued the card. For a list of possible values, see the card type enumeration.
payment	amount	String	Total amount taken from the customer’s account.
currency_code	String	ISO currency code for the transaction. For a list of possible values, see the currency code enumeration.

fees object

Parameter	Type	Size	Description
customer_fee_amount	String	1-9	If customer fees have been configured for the merchant account, this is the total fee amount applied to the amount submitted in the transaction.
surcharge_amount	Numeric	Variable	For US credit transactions, this is the surcharge amount applied to the amount submitted in the transaction request if surcharge fees have been configured for the merchant in the gateway. It is a dollar amount the merchant charged the cardholder as a surcharge for paying using a credit card.

Response Sample

{
  "creditauth_id": "0000012345678903266",
  "status": "approved",
  "approval_code": "ADB123",
  "avs_response": "full_match",
  "avs_response_description": "Match - Street Address",
  "cardsecurity_response": "match",
  "processor_response": "APPROVAL ADB123",
  "reference_id": "XAZR863990",
  "card": {
    "masked_card_number": "XXXXXXXXXXX5538",
    "cardholder_name": "Joe Doe",
    "expiry_month": "03",
    "expiry_year": "23",
    "token": "EnzMcSVlkP",
    "type": "visa",
    "balance": "12.09"
  },
  "payment": {
    "amount": "10.00",
    "currency_code": "840",
    "fees": {
      "customer_fee_amount": "01.03",
      "surcharge_amount": "00.03"
    },
    "invoice_number": "239087",
    "type": "credit"
  },
  "transaction": {
    "entry_type": "contactless",
    "language": "en-US"
  },
  "receipt": {
    "id": "72845",
    "text": {
      "customer_receipt": "\\nBatch #             000161\\nTrans ID            000000141687\\nOrder ID            PAYAPIa0155b35-420c-\\n                    46a5-9b0a-f01ac0004a\\n                    76\\nReceipt #           123456890\\nTrans Type          Return\\nClerk ID            Al090\\nDate/Time           2018-12-10 21:56:16\\nCard Type           Visa\\nCard Number         XXXXXXXXXXXX2222\\nEntry Legend        MAG STRIPE\\nEntry Method        CONTACTLESS\\nApproval Code       577279\\n\\nTotal Amount        USD$132.00\\n\\n          Approved - Thank You\\n\\n X____________________________________\\n           Signature: Joe Doe\\n\\n         ****Customer Copy****\\n     Retain this copy for statement\\n              verification",
      "merchant_receipt": "\\nBatch #             000161\\nTrans ID            000000141687\\nOrder ID            PAYAPIa0155b35-420c-\\n                    46a5-9b0a-f01ac0004a\\n                    76\\nReceipt #           123456890\\nTrans Type          Return\\nClerk ID            Al090\\nDate/Time           2018-12-10 21:56:16\\nCard Type           Visa\\nCard Number         XXXXXXXXXXXX2222\\nEntry Legend        MAG STRIPE\\nEntry Method        CONTACTLESS\\nApproval Code       577279\\n\\nTotal Amount        USD$132.00\\n\\n          Approved - Thank You\\n\\n X____________________________________\\n           Signature: Joe Doe\\n\\n         ****Merchant Copy****"
    },
    "attributes": {
      "authorization_agreement": "I agree to pay above total amount according to card issuer agreement",
      "call_issuer": "CALL ISSUER",
      "copy_label_customer": "****Customer Copy**** Retain this copy for statement verification",
      "copy_label_merchant": "MERCHANT COPY",
      "merchant_address": "2578 West 600 North",
      "merchant_footer": "Thank you. Come again.",
      "merchant_header": "ABC Grocery",
      "merchant_name": "ABC Stores",
      "merchant_phone": "901-492-7269",
      "merchant_policy": "Generally, merchandise purchased in store or online can be returned or exchanged within ninety (90) days of purchase with or without a receipt",
      "verbiage": "Approved - Thank You"
    },
    "labeled_attributes": {
      "amount": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "approval_code": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "authorization_response_code": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "avs_response_code": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "batch_number": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "card_balance": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "card_type": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "cardsecurity_response_code": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "clerk_id": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "entry_legend": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "entry_method": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "gratuity_amount": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "masked_card_number": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "merchant_id": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "original_auth_code": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "payment_type": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "number": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "reference_id": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "subtotal_amount": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "total_amount": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "transaction_datetime": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "transaction_id": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "transaction_type": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "validation_code": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "application_cryptogram": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "application_identifier": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "application_label": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "application_preferred_name": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "application_transaction_counter": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      }
    }
  }
}

Unsuccessful response schema

Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see Status and error codes.
message	String	Text that describes the error.
detail	Object	Information that specifies the error’s location in the message body. Our gateway returns this object only when you receive an HTTP status code of 400. For a list of fields, see the detail object.
info	String	A link to our website for more information.

detail object

Field	Type	Description
description	String	Text that provides specific information about the error.
data_path	String	Location of the error, for example, transaction/country_code.

Unsuccessful response example

{
  "error": {
    "code": "server_error",
    "message": "Server error. Please contact OpenEdge support",
    "detail": [
      {
        "description": "Invalid type: number (expected string)",
        "data_path": "/payment/currency_code"
      }
    ],
    "info": "https://developers.paygateway.com/errors"
  }
}

Capturing a credit authorization

The endpoint you POST to depends on whether you identify the authorization using the creditauth_id (generated by the gateway) or the reference_id (generated by the merchant’s POS).

Endpoints

Using the creditauth_id

Environment	Method	URL
Test	POST	https://api.pit.paygateway.com/transactions/creditauths/{creditauth_id}/creditcaptures
Production	POST	https://api.paygateway.com/transactions/creditauths/{creditauth_id}/creditcaptures

Using the reference_id

Environment	Method	URL
Test	POST	https://api.pit.paygateway.com/transactions/creditauths/reference\_id/{reference_id}/creditcaptures
Production	POST	https://api.paygateway.com/transactions/creditauths/reference\_id/{reference_id}/creditcaptures

Request

Important: Some objects have the same names, but their parameters may differ. For more information, go to Object naming.

Object	Parameter	Type	Size	Required?	Description
payment	amount	String	1-9	Required	Total amount for the transaction.
transaction	processing_indicators	Object	-	Optional	Object that includes options for additional actions. For a list of parameters, see the processing_indicators object.

processing_indicators object

Parameter	Type	Size	Required?	Description
generate_receipt	Boolean	Explicit	Optional	If set to true, we generate a receipt and return it in the receipt object of the response. Note: Send this parameter for integrations in the US or Canada only.

{
     "payment": {
	 "amount": "5.65"	
     },
     "transaction": {
	 "processing_indicators": {
	     "generate_receipt":true
		}
	}
}'

Successful response schema

Response

Object	Field	Type	Description
-	capture_id	String	Unique identifier that our gateway generated for the transaction.
status	String	Indicates the status of the transaction. For a list of possible values, see the transaction status enumeration.
approval_code	String	Approval code for the transaction from the processor. Note: For integrations in Australia or New Zealand, our gateway returns a value of NA.
card	masked_card_number	String	Masked card number of the card that the customer used for the sale. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • For integrations in Australia or New Zealand, our gateway masks all digits except the last four digits. • If our gateway cannot return a masked card number, it returns a value of NA.
expiry_month	String	Month that the card expires, in MM format. If our gateway cannot return an expiry month, it returns a value of NA.
expiry_year	String	Year that the card expires, in YY format. If our gateway cannot return an expiry year, it returns a value of NA.
type	String	Name of the card brand that issued the card. For a list of possible values, see the card type enumeration.
payment	amount	String	Total amount taken from the customer’s account.
type	String	Type of payment for the transaction. For a list of possible values, see the payment type enumeration.
transaction	batch_amount	String	Amount in the open batch.
batch_number	String	Unique identifier for the open batch.
receipt	id	String	Unique alphanumeric value that our gateway assigned to the receipt.
text	Object	Object that contains text for the customer copy and the merchant copy of the receipt. For a list of fields, see the text object.
attributes	Object	Object that contains details of text that the receipt can include. For a list of fields, see the attributes object.
labeled_attributes	Object	Object that contains details of the transaction. For a list of fields, see the labeled_attributes object

text object

Field	Type	Description
customer	String	Text for the customer’s receipt, which contains the details of the sale.
merchant_receipt	String	Text for the merchant’s receipt, which contains the details of the sale.

attributes object

Field	Type	Description
copy_label_customer	String	Text that identifies the receipt as the customer's copy.
copy_label_merchant	String	Text that identifies the receipt as the merchant's copy.
verbiage	String	Additional text that the merchant can include on the receipt, for example, Approved - Thank You.

labelled_attributes object

Our gateway returns a label field and a value field for each object. For example, our gateway returns the following for the amount object:

"amount":
      {
        "label": "Total Amount",
        "value": "99.45 USD"
      }

Object	Description
amount	Total amount of the sale.
approval_code	Approval code for the sale from the processor.
batch_number	Unique identifier of the batch.
card_type	Type of card the customer used for the sale.
entry_method	Indicates how the user entered the card details. The value is one of the following: • Contact • Contactless • Manual • Swipe
masked_card_number	Masked card number of the card that the customer used for the sale. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • For integrations in Australia or New Zealand, our gateway masks all digits except the last four digits. • If our gateway cannot return a masked card number, it returns a value of NA.
reference_id	Unique identifier that the merchant created for the sale. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: This is the reference_id that you can include in the endpoint URL for follow-on transactions.
total_amount	Total amount of the updated sale. Our gateway returns either a value or a blank line.
transaction_datetime	Date and time of the updated sale that the processor returns, in YYYY-MM-DDThh:mm:ssZ format, for example, 2019-12-15T13:00:00Z.
transaction_id	Unique ID our gateway assigned to the sale.
transaction_type	Type of transaction the merchant ran.

capture_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the capture_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • return - The transaction uses the returns endpoint. • self - The transaction uses the same type of endpoint as the original request. • void - The transaction uses the void endpoint.
method	String	HTTP method for sending the request. The value is one of the following: • GET • PATCH • POST • PUT
description	String	Text that describes how to use the endpoint URL our gateway provided in the href field. For example, Use this endpoint to retrieve a previous sales transaction using a sale id.

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the reference_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • return - The transaction uses the returns endpoint. • self - The transaction uses the same type of endpoint as the original request. • void - The transaction uses the void endpoint.
method	String	HTTP method for sending the request. The value is one of the following: • GET • PATCH • POST • PUT
description	String	Text that describes how to use the endpoint URL our gateway provided in the href field. For example, Use this endpoint to retrieve a previous sales transaction using a sale id.

Successful response example

{
    "capture_id": "000000000526",
    "status": "approved",
    "approval_code": "030855",
    "card": {
        "masked_card_number": "476173XXXXXX0010",
        "expiry_month": "12",
        "expiry_year": "25",
        "type": "visa"
    },
    "payment": {
        "amount": "5.65",
        "type": "credit"
    },
    "transaction": {
        "batch_amount": "11.18",
        "batch_number": "000012"
    },
    "receipt": {
        "text": {
            "customer_receipt": "\nBatch #             000012\nTrans ID            000000000526\nOrder ID            MER-5082bf04-5e16-4a\n                    e1-b7e4-f387ae0e2c65\nTrans Type          Pre-Authorization\n                    Completion\nDate/Time           2023-12-14 04:50:38\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Method        MANUAL\nApproval Code       030855\n\nTotal Amount        USD$5.65\n\n          Approved - Thank You\n\n X____________________________________\n          Signature: test name\n\n         ****Customer Copy****",
            "merchant_receipt": "\nBatch #             000012\nTrans ID            000000000526\nOrder ID            MER-5082bf04-5e16-4a\n                    e1-b7e4-f387ae0e2c65\nTrans Type          Pre-Authorization\n                    Completion\nDate/Time           2023-12-14 04:50:38\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Method        MANUAL\nApproval Code       030855\n\nTotal Amount        USD$5.65\n\n          Approved - Thank You\n\n X____________________________________\n          Signature: test name\n\n         ****Merchant Copy****"
        },
        "id": "527",
        "attributes": {
            "copy_label_customer": "****Customer Copy****",
            "copy_label_merchant": "****Merchant Copy****",
            "verbiage": "Approved - Thank You"
        },
        "labeled_attributes": {
            "amount": {
                "label": "Total Amount",
                "value": "USD$5.65"
            },
            "approval_code": {
                "label": "Approval Code",
                "value": "030855"
            },
            "batch_number": {
                "label": "Batch #",
                "value": "000012"
            },
            "card_type": {
                "label": "Card Type",
                "value": "Visa"
            },
            "entry_method": {
                "label": "Entry Method",
                "value": "MANUAL"
            },
            "masked_card_number": {
                "label": "Card Number",
                "value": "XXXXXXXXXXXX0010"
            },
            "reference_id": {
                "label": "Order ID",
                "value": "MER-5082bf04-5e16-4ae1-b7e4-f387ae0e2c65"
            },
            "total_amount": {
                "label": "Total Amount",
                "value": "USD$5.65"
            },
            "transaction_datetime": {
                "label": "Date/Time",
                "value": "2023-12-14 04:50:38"
            },
            "transaction_id": {
                "label": "Trans ID",
                "value": "000000000526"
            },
            "transaction_type": {
                "label": "Trans Type",
                "value": "Pre-Authorization Completion"
            }
        }
    },
    "links": [
        {
            "capture_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/captures/000000000526",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retreive a previously completed captures transaction."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/captures/000000000526",
                    "relation": "self",
                    "method": "PATCH",
                    "description": "Use this endpoint to update the amount or other values of a previously completed captures transaction."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/captures/000000000526/voids",
                    "relation": "void",
                    "method": "PUT",
                    "description": "Use this endpoint to void a previously completed captures transaction."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/captures/000000000526/returns",
                    "relation": "return",
                    "method": "POST",
                    "description": "Use this endpoint to create a returns transaction associated with a previously completed captures transaction."
                }
            ]
        },
        {
            "reference_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/captures/reference_id/MER-5082bf04-5e16-4ae1-b7e4-f387ae0e2c65",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a previously completed captures transaction using reference id."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/captures/reference_id/MER-5082bf04-5e16-4ae1-b7e4-f387ae0e2c65",
                    "relation": "self",
                    "method": "PATCH",
                    "description": "Use this endpoint to update the amount or other values of a previously completed captures transaction using reference id."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/captures/reference_id/MER-5082bf04-5e16-4ae1-b7e4-f387ae0e2c65/voids",
                    "relation": "void",
                    "method": "PUT",
                    "description": "Use this endpoint to void a previously completed captures transaction using reference id."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/captures/reference_id/MER-5082bf04-5e16-4ae1-b7e4-f387ae0e2c65/returns",
                    "relation": "return",
                    "method": "POST",
                    "description": "Use this endpoint to create a returns transaction associated with a previously completed captures transaction using reference id."
                }
            ]
        }
    ],
    "reference_id": "MER-5082bf04-5e16-4ae1-b7e4-f387ae0e2c65"
}

Unsuccessful response schema

Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see Status and error codes.
message	String	Text that describes the error.
detail	Object	Information that specifies the error’s location in the message body. Our gateway returns this object only when you receive an HTTP status code of 400. For a list of fields, see the detail object.
info	String	A link to our website for more information.

detail object

Field	Type	Description
description	String	Text that provides specific information about the error.
data_path	String	Location of the error, for example, transaction/country_code.

Unsuccessful response example

{
    "error": {
        "code": "invalid_input",
        "message": "Invalid amount.",
        "info": "https://developers.api.pit.paygateway.com/errors"
    }
}

Running a credit sale

If the merchant can’t access the customer’s physical card, send a POST request to the relevant endpoint to take a payment from the customer’s account.

Because the card is not present, the request must include either the customer's payment details or their corresponding token.

Important: Use the creditsale_id or reference_id from this request to identify a credit sale transaction in the following transactions:

Endpoints

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

Request

Important: Some objects have the same names, however, the parameters may be different. For more information, see Object naming.

Object	Parameter	Type	Size	Required?	Description
N/A	reference_id	String	1-50	Required	Unique identifier for the sale. This is an alphanumeric value that the merchant creates, for example, `XAZR863990`.
card	card_number	String	13-19	Conditional	Primary account number (PAN) on the front of the payment card. Send this value when including card details.
cardholder_name	String	2-26	Conditional	The cardholder's name that is printed on the card. When generating a receipt, this value is printed on the signature line of the receipt. For NZ and AU transactions, if you send a value for card_number, you must send a value for cardholder_name.
expiry_month	String	2	Conditional	Month that the card expires, in MM format. Send this value when including card details.
expiry_year	String	2	Conditional	Year that the card expires, in YY format. Send this value when including card details.
temporary_token	String	1-36	Conditional	Temporary identifier for the card details. Our gateway generates this temporary token when the customer submits their payment details. Note: You can use this token only once.
token	String	1-40	Conditional	Unique alphanumeric value that identifies the card details in our vault.
card_security_code	String	1-4	Optional	Three-digit code or four-digit code that is printed on the payment card. Also known as: • Card verification value (CVV) • Card verification code (CVC)
three_ds	Object	-	Conditional	Object that contains authentication information for transactions that use 3D Secure. For a list of parameters, see the three_ds object.
customer	id	String	1-255	Optional	Customer's ID from the Customer Experience (CX) application.
title	String	1-10	Optional	Customer’s title. You can send an alphanumeric value. Note: If the customer is a business, do not send this parameter. Send the business_name parameter.

three_ds object

Parameter	Type	Size	Required?	Description
authentication_id	String	1-50	Conditional	Unique identifier used in transactions that use 3-D Secure to authenticate the customer's identity. In the UK, if the transaction uses 3-D Secure, you must send a value for the authentication_id parameter.

address object

Parameter	Type	Size	Required?	Description
line1	String	1-50	Optional	First line of the customer's address.
line2	String	1-50	Optional	Second line of the customer's address.
city	String	1-50	Optional	City of the customer's address.
state	String	1-50	Optional	State or province of the customer's address.
country	String	1-50	Optional	Country of the customer's address.
postal_code	String	1-20	Optional	Postal code or zip code of the customer's address.

processing_indicators object

Parameter	Type	Size	Required?	Description
allow_duplicate	Boolean	Explicit	Optional	If set to `true`, you can send duplicate requests. The default time frame to block duplicate transactions is 15 minutes.
address_verification_service	Boolean	Explicit	Optional	If set to `true,` the issuing bank verifies that the billing address matches the address that they have on file for the cardholder. Note: Some issuing banks don't support this function.
create_token	Boolean	Explicit	Optional	If set to `true`, our gateway saves the card details to our vault. Our gateway creates a token and returns it in the response.
generate_receipt	Boolean	Explicit	Optional	If set to `true`, our gateway generate a receipt and returns it in the receipt object of the response.
partial_approval	Boolean	Explicit	Optional	If set to `true`, our gateway allows partial approval

Request body example

{
    "reference_id": "MER-d096c579-9bc5-4798-a3e0-29c76737e918",
    "card": {
        "card_number":"4761739001010010",
        "expiry_month":"12",
        "expiry_year":"25",
        "cardholder_name":"test name"
    },
    "payment": {
        "amount": "4.08",        
        "currency_code": "840"
    },
    "transaction": {
        "country_code": "840",
        "processing_indicators":{
        	"allow_duplicate":true            
        }
    }
}

Response

Object	Field	Type	Description
N/A	creditsale_id	String	Unique identifier that our gateway generated for the sale. Note: This is the creditsale_id that you can include in the endpoint URL for follow-on transactions.
status	String	Indicates the status of the sale. For a list of possible values, see the status enumeration.
approval_code	String	Approval code for the sale from the processor. Note: For integrations in Australia or New Zealand, our gateway returns a value of `NA`.
avs_response	String	Response code from an address verification service (AVS) lookup. For a list of possible values, see the AVS response enumeration.
avs_response_description	String	Text that describes the response code that the processor returned in the avs_response field.
cardsecurity_response	String	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
processor_response	String	Response from the processor that describes the status of the transaction.
reference_id	String	Unique identifier that the merchant created for the sale. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: This is the reference_id that you can include in the endpoint URL for follow-on transactions.
card	masked_card_number	String	Masked card number of the card that the customer used for the sale. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • For integrations in Australia or New Zealand, our gateway masks all digits except the last four digits.• If our gateway cannot return a masked card number, it returns a value of .

fees object

Field	Type	Size	Description
customer_fee_amount	String	1-9	If customer fees have been configured for the merchant account, this is the total fee amount applied to the amount submitted in the transaction.
surcharge_amount	Numeric	Variable	For US credit transactions, this is the surcharge amount applied to the amount submitted in the transaction request if surcharge fees have been configured for the merchant in the gateway. It is a dollar amount the merchant charged the cardholder as a surcharge for paying using a credit card.

text object

Field	Type	Description
customer_receipt	String	Text for the customer’s receipt, which contains the details of the sale.
merchant_receipt	String	Text for the merchant’s receipt, which contains the details of the sale.

attributes object

Field	Type	Description
authorization_agreement	String	Text that describes the merchant's authorization agreement, for example, `I agree to pay the total amount according to the card issuer agreement`.
call_issuer	String	Text that displays if the merchant needs to call the issuing bank, for example, `CALL ISSUER`.
copy_label_customer	String	Text that identifies the receipt as the customer's copy.
copy_label_merchant	String	Text that identifies the receipt as the merchant's copy.
merchant_address	String	Address of the merchant's store.
merchant_footer	String	Text that appears on the footer of the receipt.
merchant_header	String	Text that appears on the header of the receipt.
merchant_name	String	Name of the merchant's store.
merchant_phone	String	Phone number of the merchant's store.
merchant_policy	String	Text that describes the merchant's policies, for example, a return policy.
verbiage	String	Additional text that the merchant can include on the receipt, for example, `Approved - Thank You`.

labelled_attributes object

Object	Description
amount	Total amount of the sale.
approval_code	Approval code for the sale from the processor.
authorization_response_code	Response code for an authorization.
avs_response_code	Response code that indicates the result of an AVS check.
batch_number	Unique identifier of the batch.
card_balance	Remaining balance of a prepaid card.
card_type	Type of card the customer used for the sale.
cardsecurity_response_code	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
clerk_id	Clerk ID that the merchant wants to display on the receipt. This is an alphanumeric value that the merchant assigns to a clerk, for example, Al090-John Doe.
entry_legend	Indicates how the payment terminal read the card details. The value is one of the following: • `CHIP READ` • `MAGSTRIPE` • `MANUAL`
entry_method	Indicates how the user entered the card details. The value is one of the following: • `Contact` • `Contactless` • `Manual` • `Swipe`
gratuity_amount	Amount that was included as a tip in the sale.
masked_card_number	Masked card number of the card that the customer used for the sale. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • For integrations in Australia or New Zealand, our gateway masks all digits except the last four digits. • If our gateway cannot return a masked card number, it returns a value of NA.
merchant_id	Unique identifier for the merchant.
original_auth_code	The authorization code of the sale.
payment_type	Type of payment for the sale. For a list of possible values, see the payment type enumeration.

creditsale_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the creditsale_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the request. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL our gateway provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a sale id.`

reference_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the reference_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the request. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL our gateway provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a reference id.`

Successful response example

{
  "creditsale_id": "0000012345678903266",
  "status": "approved",
  "approval_code": "ADB123",
  "avs_response": "full_match",
  "avs_response_description": "Match - Street Address",
  "cardsecurity_response": "match",
  "processor_response": "APPROVAL ADB123",
  "reference_id": "XAZR863990",
  "card": {
    "masked_card_number": "XXXXXXXXXXX5538",
    "cardholder_name": "Joe Doe",
    "expiry_month": "03",
    "expiry_year": "23",
    "token": "EnzMcSVlkP",
    "type": "visa",
    "balance": "12.09"
  },
  "payment": {
    "amount": "23.09",
    "currency_code": "840",
    "fees": {
      "customer_fee_amount": "10.03",
      "surcharge_amount": "10.00"
    },
    "gratuity_amount": "10.00",
    "invoice_number": "239087",
    "type": "credit",
    "purchase_order": {
      "po_number": "2343445",
      "tax_amount": "20.01"
    }
  },
  "transaction": {
    "batch_amount": "12.09",
    "batch_number": "001333",
    "entry_type": "contactless",
    "language": "en-US"
  },
  "receipt": {
    "id": "72845",
    "text": {
      "customer_receipt": "\\nBatch #             000161\\nTrans ID            000000141687\\nOrder ID            PAYAPIa0155b35-420c-\\n                    46a5-9b0a-f01ac0004a\\n                    76\\nReceipt #           123456890\\nTrans Type          Return\\nClerk ID            Al090\\nDate/Time           2018-12-10 21:56:16\\nCard Type           Visa\\nCard Number         XXXXXXXXXXXX2222\\nEntry Legend        MAG STRIPE\\nEntry Method        CONTACTLESS\\nApproval Code       577279\\n\\nTotal Amount        USD$132.00\\n\\n          Approved - Thank You\\n\\n X____________________________________\\n           Signature: Joe Doe\\n\\n         ****Customer Copy****\\n     Retain this copy for statement\\n              verification",
      "merchant_receipt": "\\nBatch #             000161\\nTrans ID            000000141687\\nOrder ID            PAYAPIa0155b35-420c-\\n                    46a5-9b0a-f01ac0004a\\n                    76\\nReceipt #           123456890\\nTrans Type          Return\\nClerk ID            Al090\\nDate/Time           2018-12-10 21:56:16\\nCard Type           Visa\\nCard Number         XXXXXXXXXXXX2222\\nEntry Legend        MAG STRIPE\\nEntry Method        CONTACTLESS\\nApproval Code       577279\\n\\nTotal Amount        USD$132.00\\n\\n          Approved - Thank You\\n\\n X____________________________________\\n           Signature: Joe Doe\\n\\n         ****Merchant Copy****"
    },
    "attributes": {
      "authorization_agreement": "I agree to pay above total amount according to card issuer agreement",
      "call_issuer": "CALL ISSUER",
      "copy_label_customer": "****Customer Copy**** Retain this copy for statement verification",
      "copy_label_merchant": "MERCHANT COPY",
      "merchant_address": "2578 West 600 North",
      "merchant_footer": "Thank you. Come again.",
      "merchant_header": "ABC Grocery",
      "merchant_name": "ABC Stores",
      "merchant_phone": "901-492-7269",
      "merchant_policy": "Generally, merchandise purchased in store or online can be returned or exchanged within ninety (90) days of purchase with or without a receipt",
      "verbiage": "Approved - Thank You"
    },
    "labeled_attributes": {
      "amount": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "approval_code": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "authorization_response_code": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "avs_response_code": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "batch_number": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "card_balance": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "card_type": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "cardsecurity_response_code": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "clerk_id": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "entry_legend": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "entry_method": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "gratuity_amount": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "masked_card_number": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "merchant_id": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "original_auth_code": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "payment_type": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "number": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "reference_id": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "subtotal_amount": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "total_amount": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "transaction_datetime": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "transaction_id": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "transaction_type": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "validation_code": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "application_cryptogram": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "application_identifier": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "application_label": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "application_preferred_name": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      },
      "application_transaction_counter": {
        "label": "Total Amount",
        "value": "$99.45 USD"
      }
    }
  },
  "links": [
    {
      "creditsale_id": [
        {
          "href": "https://api.paygateway.com/cnp-payments/sales/000000106821",
          "relation": "self",
          "method": "POST",
          "description": "Use this endpoint to retrieve a previous sales transaction using reference id."
        }
      ],
      "reference_id": [
        {
          "href": "https://api.paygateway.com/cnp-payments/sales/000000106821",
          "relation": "self",
          "method": "POST",
          "description": "Use this endpoint to retrieve a previous sales transaction using reference id."
        }
      ]
    }
  ]
}

Unsuccessful response schema

Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see the Error response codes.
message	String	Text that describes the error.
detail	Object	Information that specifies the error’s location in the message body. Our gateway returns this object only when you receive an HTTP status code of 400. For a list of fields, see the detail object.
info	String	A link to our website for more information.

detail object

Field	Type	Description
description	String	Text that provides specific information about the error.
data_path	String	Location of the error, for example, transaction/country_code.

Unsuccessful response example

{
    "error": { 
        "code": "invalid_input",
        "message": "Invalid input data",
        "detail": [
            {
                "description": "Value not allowed: 000",
                "data_path": "/transaction/country_code"
            },
            {
                "description": "Country code not allowed for region in request.",
                "data_path": "/transaction/country_code"
            }
        ],
        "info": "

Updating a sale

To update the details of a credit sale in the open batch, send a PATCH request to the relevant endpoint.

You can update the following details:

Amount
Gratuity amount
Invoice number

Important:

You can update a sale only when it is in an open batch.
You can’t update the details of a debit sale.

Endpoints

The endpoint you use depends on whether you identify the sale using the creditsale_id (generated by the gateway) or the reference_id (generated by the merchant's POS).

Using the creditsale_id

Environment	HTTP method	URL
Test	PATCH	https://api.pit.paygateway.com/transactions/creditsales/{creditsale_id}
Production	PATCH	https://api.paygateway.com/transactions/creditsales/{creditsale_id}

Using the reference_id

Environment	HTTP method	URL
Test	PATCH	https://api.pit.paygateway.com/transactions/creditsales/reference\_id/{reference_id}
Production	PATCH	https://api.paygateway.com/transactions/creditsales/reference\_id/{reference_id}

Request

Important: Some objects have the same names, however, the parameters may be different. For more information, see Object naming.

Object	Parameter	Type	Size	Required?	Description
payment	amount	String	1-9	Optional	Updated amount that the merchant wants to take from the customer’s account. The value includes two decimal places, for example, `10.00`. For integrations in the US or Canada, this value should include customer fees. For integrations in Australia or New Zealand, our gateway automatically adds any customer fees to this value. The minimum value is `0.01`.
gratuity_amount	String	1-7	Optional	Updated amount that the merchant wants to include as a tip. Note: Send this parameter for integrations only in the US or Canada.
invoice_number	String	1-25	Optional	Updated invoice number or order number that the merchant creates and assigns to the sale. Note: Send this parameter for integrations only in the US or Canada.
transaction	processing_indicators	Object	-	Optional	Object that includes options for additional actions. For a list of parameters, see the processing_indicators object.

processing_indicators object

Parameter	Type	Size	Required?	Description
allow_duplicate	Boolean	Explicit	Optional	If set to `true`, you can send duplicate requests. The default time frame to block duplicate transactions is 15 minutes. Note: Send this parameter for integrations in the US or Canada only.
generate_receipt	Boolean	Explicit	Optional	If set to `true`, our gateway generates a receipt and returns it in the receipt object of the response. Note: Send this parameter for integrations in the US or Canada only.

Request body example

{
  "payment": {
    "amount": "4.22"
  }
}

Response

Object	Field	Type	Description
N/A	creditsale_id	String	Unique identifier that our gateway generated for the updated sale. Note: This is the creditsale_id that you can include in the endpoint URL for follow-on transactions.
reference_id	String	Unique identifier that the merchant created for the updated sale. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: This is the reference_id that you can include in the endpoint URL for follow-on transactions.
status	String	Indicates the status of the updated sale. For a list of possible values, see the status enumeration.
approval_code	String	Approval code for the updated sale from the processor.
card	masked_card_number	String	Masked card number of the card that the customer used for the updated sale. Depending on the location of the POS, our gateway masks different parts of the card number: • For US or Canadian transactions, our gateway masks all digits except the first six and the last four. • For Australian or New Zealand transactions, our gateway masks all digits except the last four. • If our gateway cannot return a masked card number, it returns a value of `NA`.
expiry_month	String	Month that the card expires, in MM format. If our gateway cannot return an expiry month, it returns a value of `NA`.
expiry_year	String	Year that the card expires, in YY format. If our gateway cannot return an expiry year, it returns a value of `NA`.
type	String	Name of the card brand that issued the card. For a list of possible values, see the card type enumeration. If our gateway cannot return a card type, it returns a value of `NA`.
payment	amount	String	Total amount taken from the customer’s account.
gratuity_amount	String	Amount that was included as a tip in the updated sale.

text object

Field	Type	Description
customer_receipt	String	Text for the customer’s receipt, which contains the details of the updated sale.
merchant_receipt	String	Text for the merchant’s receipt, which contains the details of the updated sale.

attributes object

Field	Type	Description
authorization_agreement	String	Text that describes the merchant's authorization agreement, for example, `I agree to pay the total amount according to the card issuer agreement`.
call_issuer	String	Text that displays if the merchant needs to call the issuing bank, for example, `CALL ISSUER`.
copy_label_customer	String	Text that identifies the receipt as the customer's copy.
copy_label_merchant	String	Text that identifies the receipt as the merchant's copy.
merchant_address	String	Address of the merchant's store.
merchant_footer	String	Text that appears on the footer of the receipt.
merchant_header	String	Text that appears on the header of the receipt.
merchant_name	String	Name of the merchant's store.
merchant_phone	String	Phone number of the merchant's store.
merchant_policy	String	Text that describes the merchant's policies, for example, a return policy.
verbiage	String	Additional text that the merchant can include on the receipt, for example, `Approved - Thank You`.

labelled_attributes object

Object	Description
amount	Total amount of the updated sale.
approval_code	Approval code for the updated sale from the processor.
authorization_response_code	Response code for an authorization.
avs_response_code	Response code that indicates the result of an AVS check.
batch_number	Unique identifier of the batch.
card_balance	Remaining balance of a prepaid card.
card_type	Type of card the customer used for the sale.
cardsecurity_response_code	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
clerk_id	Clerk ID that the merchant wants to display on the receipt. This is an alphanumeric value that the merchant assigns to a clerk, for example, `Al090-John Doe`.
entry_legend	Indicates how the payment terminal read the card details. The value is one of the following: • `CHIP READ` • `MAGSTRIPE` • `MANUAL`
entry_method	Indicates how the user entered the card details. The value is one of the following: • `Contact` • `Contactless` • `Manual` • `Swipe`
gratuity_amount	Amount that was included as a tip in the updated sale.
masked_card_number	Masked card number of the card that the customer used for the sale. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • For integrations in Australia or New Zealand, our gateway masks all digits except the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
merchant_id	Unique identifier for the merchant.
original_auth_code	The authorization code of the sale.
payment_type	Type of payment for the sale. For a list of possible values, see the payment type enumeration.

creditsale_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the creditsale_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the request. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL our gateway provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a sale id.`

reference_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the reference_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the request. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL our gateway provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a reference id.`

Successful response example

{
    "creditsale_id": "000000000081",
    "status": "approved",
    "approval_code": "055856",
    "card": {
        "masked_card_number": "476173XXXXXX0010",
        "expiry_month": "12",
        "expiry_year": "25",
        "type": "visa"
    },
    "payment": {
        "amount": "4.22",
        "type": "credit"
    },
    "transaction": {
        "batch_amount": "18.90",
        "batch_number": "000003"
    },
    "links": [
        {
            "creditsale_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/000000000081",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a sales transaction."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/000000000081",
                    "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/creditsales/000000000081/voids",
                    "relation": "void",
                    "method": "PUT",
                    "description": "Use this endpoint to void a previous sales transaction."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/000000000081/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/creditsales/reference_id/MER-b641e11b-5e74-419a-b190-c90ad6b1319c",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retreive a previous sales transaction using reference id."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/reference_id/MER-b641e11b-5e74-419a-b190-c90ad6b1319c",
                    "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/creditsales/reference_id/MER-b641e11b-5e74-419a-b190-c90ad6b1319c/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/creditsales/reference_id/MER-b641e11b-5e74-419a-b190-c90ad6b1319c/returns",
                    "relation": "return",
                    "method": "POST",
                    "description": "Use this endpoint to create a returns transaction associated with a previous sales using reference id."
                }
            ]
        }
    ],
    "reference_id": "MER-b641e11b-5e74-419a-b190-c90ad6b1319c"
}

Unsuccessful response schema

error object

Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see the Error response codes.
message	String	Text that describes the error.
detail	Object	Information that specifies the error’s location in the message body. Our gateway returns this object only when you receive an HTTP status code of 400. For a list of fields, see the detail object.
info	String	A link to our website for more information.

detail object

Field	Type	Description
description	String	Text that provides specific information about the error.
data_path	String	Location of the error, for example, transaction/country_code.

Unsuccessful response example

{
    "error": {
        "code": "invalid_input",
        "message": "Invalid input data",
        "detail": [
            {
                "description": "Invalid data: String is too short",
                "data_path": "/payment/amount"
            },
            {
                "description": "Amount should be greater than zero.",
                "data_path": "/payment/amount"
            }
        ],
        "info": "https://developers.api.pit.paygateway.com/errors"
    }
}

Running a return linked to a previous sale

To return an amount to a customer’s account with a reference_id or a creditsale_id, send a POST request to the relevant endpoint.

Note: To return an amount to a customer’s account without a reference_id or a creditsale_id for the sale, see Running a return not linked to a previous sale.

Important: You can’t run a return on a sale that is in an open batch. Instead, you must run a void. For more information about running a void, see Voiding a credit sale.

Endpoints

The endpoint you use depends on whether you identify the credit sale using either the creditsale_id (generated by the gateway) or the reference_id (generated by the merchant's POS).

Note: For integrations in Australia or New Zealand, you must use reference_id to identify a credit sale.

Using the creditsale_id

Environment	HTTP Method	URL
Test	POST	https://api.pit.paygateway.com/transactions/creditsales/{creditsale_id}/creditreturns
Production	POST	https://api.paygateway.com/transactions/creditsales/{creditsale_id}/creditreturns

Using the reference_id

Environment	HTTP Method	URL
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

Request

Important: Some objects have the same names, however, the parameters may be different. For more information, see Object naming.

Object	Parameter	Type	Size	Required?	Description
customer	id	String	N/A	Optional	Customer's ID from the customer experience (CX) application.
title	String	1-10	Optional	Customer’s title. Note: If the customer is a business, don’t send this parameter. Send the `business_name` parameter.
first_name	String	1-50	Optional	Customer’s first name. Note: If the customer is a business, don’t send this parameter. Send the `business_name` parameter.
middle_name	String	1-50	Optional	Customer’s middle name. Note: If the customer is a business, don’t send this parameter. Send the `business_name` parameter.
last_name	String	1-50	Optional	Customer’s last name. Note: If the customer is a business, don’t send this parameter. Send the `business_name` parameter.
business_name	String	1-50	Optional	Business name. Note: If the customer is not a business, send a value for each of the following parameters: • `title` • `first_name` • `middle_name` • `last_name`
email	String	1-50	Optional	Customer’s email address.
phone	String	2-50	Optional	Customer’s phone number.
note	String	1-40	Optional	Note that the merchant adds about the customer.
billing_address	Object	N/A	Optional	Object that includes the customer’s billing address. For a list of parameters, see the billing_address object.
payment	amount	String	1-9	Required	Total amount that you are returning to the customer. The value includes two decimal places, for example, `10.00.`
invoice_number	String	1-25	Optional	Alphanumeric invoice number or order number that the merchant creates and assigns to the return.: Send this parameter for integrations only in the US or Canada.

billing_address object

Parameter	Type	Size	Required?	Description
line1	String	1-50	Optional	First line of the customer’s address.
line2	String	1-50	Optional	Second line of the customer's address.
city	String	1-50	Optional	City of the customer’s address. For Australia and New Zealand, use the suburb of the customer's address for this parameter.
state	String	1-50	Optional	State or province of the customer’s address. You can send an alphanumeric value.
country	String	1-50	Optional	Country of the customer’s address.
postal_code	String	1-50	Optional	Postal code or zip code of the customer’s address. You can send an alphanumeric value.

processing_indicators object

Parameter	Type	Size	Required?	Description
allow_duplicate	Boolean	Explicit	Optional	If set to `true`, you can send duplicate transactions. The default time-frame to block duplicate transactions is 15 minutes.
generate_receipt	Boolean	Explicit	Optional	If set to `true`, the POS generates a customer receipt and a merchant receipt for the refund. Note: Send this parameter for integrations only in the US or Canada.

Request body example

{
    "payment": {
        "amount": "5.28"
    },
    "transaction": {
        "processing_indicators": {
            "generate_receipt": true
        }
    }
}

Response

Object	Field	Type	Description
N/A	creditreturn_id	String	Unique identifier that our gateway generated for the transaction. Note: This is the creditreturn_id that you can include in the endpoint URL to view the details of the return transaction.
status	String	Indicates the status of the return. For a list of possible values, see the status enumeration.
approval_code	String	Processor’s approval code for the return.
reference_id	String	Unique identifier that the merchant created for the return or that our gateway created for the return. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: This is the reference_id that you can include in the endpoint URL to view the details of the return transaction.
card	masked_card_number	String	Masked card number of the card that the customer used for the sale. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • For integrations in Australia or New Zealand, our gateway masks all digits except the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
expiry_month	String	Month that the card expires, in MM format. If our gateway cannot return an expiry month, it returns a value of `NA`.
expiry_year	String	Year that the card expires in YY format. If our gateway cannot return an expiry year, it returns a value of `NA`.
type	String	Name of the card brand that issued the card. For a list of possible values, see the card type enumeration.
payment	amount	String	Total amount the merchant returned to the customer.
invoice_number	String	Alphanumeric invoice number or order number that the merchant created and assigned to the return.

text object

Field	Type	Description
customer_receipt	String	Text for the customer's receipt that contains the details of the return.
merchant_receipt	String	Text for the merchant's receipt that contains the details of the return.

attributes object

Field	Type	Description
Authorization_agreement	String	Text that describes the merchant's authorization agreement, for example, `I agree to pay the total amount according to the card issuer agreement.`
call_issuer	String	Text that displays if the merchant needs to call the issuing bank, for example, `CALL ISSUER.`
copy_label_customer	String	Text that identifies the receipt as the customer's copy.
copy_label_merchant	String	Text that identifies the receipt as the merchant's copy.
merchant_address	String	Address of the merchant's store.
merchant_footer	String	Text that appears on the footer of the receipt.
merchant_header	String	Text that appears on the header of the receipt.
merchant_name	String	Name of the merchant's store.
merchant_phone	String	Phone number of the merchant's store.
merchant_policy	String	Text that describes the merchant's policies, for example, a return policy.
verbiage	String	Additional text that the merchant can include on the receipt, for example, `Approved - Thank You.`

labeled_attributes object

Our gateway returns a label field and a value field for each object. For example, our gateway returns the following for the amount object:

"Amount":
{
"label": "Total Amount",
"value": "99.45 USD"
}

Object	Description
amount	Total amount the merchant returned to the customer.
approval_code	Approval code for the return from the processor.
authorization_response_code	Response code for an authorization.
avs_response_code	Response code that indicates the result of an AVS check.
batch_number	Unique identifier of the batch.
card_balance	Remaining balance of a prepaid card.
card_type	Type of card the customer used for the sale the merchant returned.
cardsecurity_response_code	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
clerk_id	Clerk ID that the merchant wants to display on the receipt. This is an alphanumeric value that the merchant assigns to a clerk, for example, `Al090-John Doe.`
entry_legend	Indicates how the payment terminal read the card details. The value is one of the following: • `CHIP READ` • `MAGSTRIPE` • `MANUAL`
entry_method	Indicates how the customer or merchant entered the card details. The value is one of the following: • `Contact` • `Contactless` • `Manual` • `Swipe`
gratuity_amount	Amount that was included as a tip in the sale the merchant returned to the customer.
masked_card_number	Masked card number of the card that the customer used for the sale. Depending on the location of the POS, our gateway returns a different masked card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • For integrations in Australia or New Zealand, our gateway masks all digits except the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
merchant_id	Unique identifier for the merchant.
original_auth_code	The authorization code of the sale.
payment_type	Type of payment for the sale that the merchant returned to the customer. For a list of possible values, see the enumeration.

creditreturn_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the creditreturn_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the voids endpoint.
method	String	HTTP method for sending the transaction. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL we provided in the href field, for example, `Use this endpoint to retrieve a previous sales transaction using a sale id.`

reference_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the reference_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the voids endpoint.
method	String	HTTP method for sending the transaction. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL we provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a reference id.`

Successful response example

{
    "creditreturn_id": "000000000173",
    "status": "approved",
    "approval_code": "217499",
    "card": {
        "masked_card_number": "476173XXXXXX0010",
        "expiry_month": "12",
        "expiry_year": "25",
        "type": "visa"
    },
    "payment": {
        "amount": "5.28",
        "type": "credit"
    },
    "transaction": {
        "batch_amount": "5.00",
        "batch_number": "000007"
    },
    "receipt": {
        "text": {
            "customer_receipt": "\nBatch #             000007\nTrans ID            000000000173\nOrder ID            MER-7a5ea1e0-f582-42\n                    7c-b102-23135749e2ee\nTrans Type          Return\nDate/Time           2023-06-30 05:00:16\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Method        MANUAL\nApproval Code       217499\n\nTotal Amount        USD$5.28\n\n          Approved - Thank You\n\n X____________________________________\n               Signature\n\n         ****Customer Copy****",
            "merchant_receipt": "\nBatch #             000007\nTrans ID            000000000173\nOrder ID            MER-7a5ea1e0-f582-42\n                    7c-b102-23135749e2ee\nTrans Type          Return\nDate/Time           2023-06-30 05:00:16\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Method        MANUAL\nApproval Code       217499\n\nTotal Amount        USD$5.28\n\n          Approved - Thank You\n\n X____________________________________\n               Signature\n\n         ****Merchant Copy****"
        },
        "id": "173",
        "attributes": {
            "copy_label_customer": "****Customer Copy****",
            "copy_label_merchant": "****Merchant Copy****",
            "verbiage": "Approved - Thank You"
        },
        "labeled_attributes": {
            "amount": {
                "label": "Total Amount",
                "value": "USD$5.28"
            },
            "approval_code": {
                "label": "Approval Code",
                "value": "217499"
            },
            "batch_number": {
                "label": "Batch #",
                "value": "000007"
            },
            "card_type": {
                "label": "Card Type",
                "value": "Visa"
            },
            "entry_method": {
                "label": "Entry Method",
                "value": "MANUAL"
            },
            "masked_card_number": {
                "label": "Card Number",
                "value": "XXXXXXXXXXXX0010"
            },
            "reference_id": {
                "label": "Order ID",
                "value": "MER-7a5ea1e0-f582-427c-b102-23135749e2ee"
            },
            "total_amount": {
                "label": "Total Amount",
                "value": "USD$5.28"
            },
            "transaction_datetime": {
                "label": "Date/Time",
                "value": "2023-06-30 05:00:16"
            },
            "transaction_id": {
                "label": "Trans ID",
                "value": "000000000173"
            },
            "transaction_type": {
                "label": "Trans Type",
                "value": "Return"
            }
        }
    },
    "links": [
        {
            "creditreturn_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditreturns/000000000173",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a previously completed returns transaction."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditreturns/000000000173/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/creditreturns/reference_id/MER-7a5ea1e0-f582-427c-b102-23135749e2ee",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a previously completed returns transaction using reference id."
                }
            ]
        }
    ],
    "reference_id": "MER-7a5ea1e0-f582-427c-b102-23135749e2ee"
}

Unsuccessful Response schema

Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see Status and error codes.
message	String	Text that describes the error.
detail	Object	Information that specifies the error’s location in the message body. Our gateway returns this object only when you receive an HTTP status code of 400. For a list of fields, see the detail object.
info	String	A link to our website for more information.

detail object

Field	Type	Description
description	String	Text that provides specific information about the error.
data_path	String	Location of the error, for example, transaction/country_code.

Unsuccessful response example

{
  "error": {
    "code": "server_error",
    "message": "Server error. Please contact OpenEdge support",
    "detail": [
      {
        "description": "Invalid type: number (expected string)",
        "data_path": "/payment/currency_code"
      }
    ],
    "info": "https://developers.paygateway.com/errors"
  }
}

Running a return not linked to a previous sale

To return an amount to a customer’s account without a reference_id or a creditsale_id for the sale, send a POST request to the relevant endpoint.

Because the card is not present, the request must include either the customer's payment details or their corresponding token.

Note: If you have a reference_id or a creditsale_id for the sale, see Running a return linked to a previous sale.

Important: You can return an amount to only a credit card.

Endpoints

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

Request

Important: Some objects have the same names, however, the parameters may be different. For more information, see Object naming.

Object	Parameter	Type	Size	Required?	Description
N/A	reference_id	String	1-50	Required	Unique identifier that the merchant creates for the return. This is an alphanumeric value, for example, `XAZR863990`. Note: This is the reference_id that you can include in the endpoint URL to view the details of the return.
card	card_number	String	13-19	Conditional	Primary account number (PAN) on the payment card. If you send a value for the card_number parameter, you must send values for the following parameters: • `expiry_month` • `expiry_year` Note: For integrations in Australia or New Zealand, if you send a value for the card_number parameter, you must send a value for the cardholder_name parameter.
card_security_code	String	1-4	Optional	Three-digit code or four-digit code that is printed on the payment card. Also known as a card verification value (CVV) or a card verification code (CVC).
cardholder_name	String	2-26	Conditional	Cardholder's name on the payment card. If the merchant generates a receipt, this value is printed on the signature line. Note: For integrations in Australia or New Zealand, you must send a value for the cardholder_name parameter if you send a value for the card_number parameter.
expiry_month	String	2	Conditional	Month that the card expires, in MM format.
expiry_year	String	2	Conditional	Year that the card expires, in YY format.
token	String	1-40	Conditional	Unique alphanumeric value that identifies the payment card details in our vault. If you send a value for the token parameter, do not send values for the following parameters: • `card_number` • `expiry_month` • `expiry_year`
customer	id	String	1-255	Optional	Customer's ID from the Customer Experience (CX) application.
title	String	1-10	Optional	Customer’s title. You can send an alphanumeric value. Note: • If the customer is a business, do not send this parameter. Send the business_name parameter.• The combined length of the values for the following parameters must not exceed 50 characters:• • • •

billing_address object

Parameter	Type	Size	Required?	Description
line1	String	1-50	Optional	First line of the customer’s address.
line2	String	1-50	Optional	Second line of the customer’s address.
city	String	1-50	Optional	City of the customer’s address. Note: For Australia and New Zealand, use the suburb of the customer's address for this parameter.
state	String	1-50	Optional	State or province of the customer’s address. Note: Do not send this parameter for integrations in New Zealand.
country	String	1-50	Optional	Country of the customer’s address.
postal_code	String	1-20	Optional	Postal code or zip code of the customer’s address.

processing_indicators object

Parameter	Type	Size	Required?	Description
allow_duplicate	Boolean	Explicit	Optional	If set to `true`, you can send duplicate requests. The default time frame to block duplicate transactions is 15 minutes.
generate_receipt	Boolean	Explicit	Optional	If set to `true`, our gateway generates a receipt and returns it in the receipt object of the response.

Request body example

{
    "reference_id":"MER-80a03350-9817-4e54-acae-73c3fe3610e5",
    "card": {
        "card_number":"4761739001010010",
        "expiry_month":"12",
        "expiry_year":"25",
        "cardholder_name":"test name"
    },
    "payment": {
        "amount": "2.66",
        "currency_code":"840"
    },
    "transaction": {
        "country_code":"840",
        "processing_indicators": {
            "generate_receipt": true
        }
    }
}

Response

Object	Field	Type	Description
N/A	creditreturn_id	String	Unique identifier that our gateway generated for the return. Note: This is the creditreturn_id that you can include in the endpoint URL to view the details of the return.
status	String	Indicates the status of the return. For a list of possible values, see the status enumeration.
approval_code	String	Approval code for the return from the processor.
reference_id	String	Unique identifier that the merchant created for the return. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: This is the reference_id that you can include in the endpoint URL to view the details of the return.
card	masked_card_number	String	Masked card number of the card that the customer used for the return. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • For integrations in Australia or New Zealand, our gateway masks all digits except the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
cardholder_name	String	The cardholder's name on the payment card. If the merchant generates a receipt, this value is printed on the signature line.
expiry_month	String	Month that the card expires, in MM format. If our gateway cannot return an expiry month, it returns a value of `NA`.
expiry_year	String	Year that the card expires, in YY format. If our gateway cannot return an expiry year, it returns a value of `NA`.
type	String	Name of the card brand that issued the card. For a list of possible values, see the card type enumeration.
balance	String	Remaining balance of a prepaid card.
payment

text object

Field	Type	Description
customer_receipt	String	Text for the customer’s receipt, which contains the details of the return.
merchant_receipt	String	Text for the merchant’s receipt, which contains the details of the return.

attributes object

Field	Type	Description
authorization_agreement	String	Text that describes the merchant's authorization agreement, for example, `I agree to pay the total amount according to the card issuer agreement`.
call_issuer	String	Text that displays if the merchant needs to call the issuing bank, for example, `CALL ISSUER`.
copy_label_customer	String	Text that identifies the receipt as the customer's copy.
copy_label_merchant	String	Text that identifies the receipt as the merchant's copy.
merchant_address	String	Address of the merchant's store.
merchant_footer	String	Text that appears on the footer of the receipt.
merchant_header	String	Text that appears on the header of the receipt.
merchant_name	String	Name of the merchant's store.
merchant_phone	String	Phone number of the merchant's store.
merchant_policy	String	Text that describes the merchant's policies, for example, a return policy.
verbiage	String	Additional text that the merchant can include on the receipt, for example, `Approved - Thank You`.

labeled_attributes object

Our gateway returns a label field and a value field for each object. For example, for amount, our gateway returns the following for the amount object:

"amount":

{

"label": "Total Amount",

"value": "99.45 USD"

}

Object	Description
amount	Total dollar amount of the return.
approval_code	Approval code for the return from the processor.
authorization_response_code	Response code for an authorization.
avs_response_code	Response code that indicates the result of an AVS check.
batch_number	Unique identifier of the batch.
card_balance	Remaining balance of a prepaid card.
card_type	Type of card the customer used for the return.
cardsecurity_response_code	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
clerk_id	Clerk ID that the merchant wants to display on the receipt. This is an alphanumeric value that the merchant assigns to a clerk, for example, `Al090-John Doe`.
entry_legend	Indicates how the payment terminal read the card details. The value is one of the following: • `CHIP READ` • `MAGSTRIPE` • `MANUAL`
entry_method	Indicates how the customer or merchant entered the card details. The value is one of the following: • `contact` • `contactless` • `manual` • `swipe`
gratuity_amount	Amount that was included as a tip in the return.
masked_card_number	Masked card number of the card that the customer used for the return. Depending on the location of the POS, our gateway returns a different masked card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • For integrations in Australia or New Zealand, our gateway masks all digits except the last four digits. • If our gateway cannot return a masked card number, it returns a value of NA.
merchant_id	Unique identifier for the merchant.
original_auth_code	Authorization code of the return.
payment_type	Type of payment for the return. For a list of possible values, see the payment type enumeration.

creditreturn_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the creditreturn_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the request. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL our gateway provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a sale id.`

reference_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the reference_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the request. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL our gateway provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a reference id.`

Successful response example

{
    "creditreturn_id": "000000000174",
    "status": "approved",
    "approval_code": "278446",
    "card": {
        "masked_card_number": "476173XXXXXX0010",
        "cardholder_name": "test name",
        "expiry_month": "12",
        "expiry_year": "25",
        "type": "visa"
    },
    "payment": {
        "amount": "2.66",
        "currency_code": "840",
        "type": "credit"
    },
    "transaction": {
        "batch_amount": "2.34",
        "batch_number": "000007",
        "entry_type": "keyed",
        "language": "en-US"
    },
    "receipt": {
        "text": {
            "customer_receipt": "\nBatch #             000007\nTrans ID            000000000174\nOrder ID            MER-80a03350-9817-4e\n                    54-acae-73c3fe3610e5\nTrans Type          Return\nDate/Time           2023-06-30 05:17:57\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Method        MANUAL\nApproval Code       278446\n\nTotal Amount        USD$2.66\n\n          Approved - Thank You\n\n X____________________________________\n          Signature: test name\n\n         ****Customer Copy****",
            "merchant_receipt": "\nBatch #             000007\nTrans ID            000000000174\nOrder ID            MER-80a03350-9817-4e\n                    54-acae-73c3fe3610e5\nTrans Type          Return\nDate/Time           2023-06-30 05:17:57\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Method        MANUAL\nApproval Code       278446\n\nTotal Amount        USD$2.66\n\n          Approved - Thank You\n\n X____________________________________\n          Signature: test name\n\n         ****Merchant Copy****"
        },
        "id": "174",
        "attributes": {
            "copy_label_customer": "****Customer Copy****",
            "copy_label_merchant": "****Merchant Copy****",
            "verbiage": "Approved - Thank You"
        },
        "labeled_attributes": {
            "amount": {
                "label": "Total Amount",
                "value": "USD$2.66"
            },
            "approval_code": {
                "label": "Approval Code",
                "value": "278446"
            },
            "batch_number": {
                "label": "Batch #",
                "value": "000007"
            },
            "card_type": {
                "label": "Card Type",
                "value": "Visa"
            },
            "entry_method": {
                "label": "Entry Method",
                "value": "MANUAL"
            },
            "masked_card_number": {
                "label": "Card Number",
                "value": "XXXXXXXXXXXX0010"
            },
            "reference_id": {
                "label": "Order ID",
                "value": "MER-80a03350-9817-4e54-acae-73c3fe3610e5"
            },
            "total_amount": {
                "label": "Total Amount",
                "value": "USD$2.66"
            },
            "transaction_datetime": {
                "label": "Date/Time",
                "value": "2023-06-30 05:17:57"
            },
            "transaction_id": {
                "label": "Trans ID",
                "value": "000000000174"
            },
            "transaction_type": {
                "label": "Trans Type",
                "value": "Return"
            }
        }
    },
    "links": [
        {
            "creditreturn_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditreturns/000000000174",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a previously completed returns transaction."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditreturns/000000000174/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/creditreturns/reference_id/MER-80a03350-9817-4e54-acae-73c3fe3610e5",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a previously completed returns transaction using reference id."
                }
            ]
        }
    ],
    "reference_id": "MER-80a03350-9817-4e54-acae-73c3fe3610e5"
}

Unsuccessful response schema

Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see Status and error codes.
message	String	Text that describes the error.
detail	Object	Information that specifies the error’s location in the message body. Our gateway returns this object only when you receive an HTTP status code of 400. For a list of fields, see the detail object.
info	String	A link to our website for more information.

detail object

Field	Type	Description
description	String	Text that provides specific information about the error.
data_path	String	Location of the error, for example, transaction/country_code.

Unsuccessful response example

{
  "error": {
    "code": "server_error",
    "message": "Server error. Please contact OpenEdge support",
    "detail": [
      {
        "description": "Invalid type: number (expected string)",
        "data_path": "/payment/currency_code"
      }
    ],
    "info": "https://developers.paygateway.com/errors"
  }
}

Voiding a credit sale

To void a credit sale, send a PUT request to the relevant endpoint.

Endpoints

The endpoint you use depends on whether you identify the sale using the creditsale_id (which is generated by the gateway) or the reference_id (which is generated by the merchant's POS).

Using the creditsale_id

Environment	HTTP Method	URL
Test	PUT	https://api.pit.paygateway.com/transactions/creditsales/{creditsale_id}/voids
Production	PUT	https://api.paygateway.com/transactions/creditsales/{creditsale_id}/voids

Using the reference_id

Environment	HTTP Method	URL
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

Request

Important: Some objects have the same names, however, the parameters may be different. For more information, see Object naming.

Object	Parameter	Type	Size	Required?	Description
payment	amount	String	1-9	Optional	Total amount of the sale that the merchant wants to void. The value includes two decimal places, for example, `10.00`. Note: You can't partially void a sale. You must void the full amount of the sale.
transaction	processing_indicators	Object	-	Optional	Object that includes options for additional actions. For a list of parameters, see the processing_indicators object.

processing_indicators object

Parameter	Type	Size	Required?	Description
generate_receipt	Boolean	Explicit	Optional	If set to true, our gateway generates a receipt and returns it in the receipt object of the response. Note: Send this parameter for integrations in the US or Canada only.

Request body example

{
  "payment": {
    "amount": "3.22"
  },
  "transaction": {
    "processing_indicators": {
      "generate_receipt": true
    }
  }
}

Response

Object	Field	Type	Description
N/A	creditsale_id	String	Unique identifier that our gateway generated for the sale. Note: This is the creditsale_id that you can include in the endpoint URL to view the details of the voided sale.
N/A	reference_id	String	Unique identifier that the merchant created for the sale. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: This is the reference_id that you can include in the endpoint URL to view the details of the voided sale.
N/A	status	String	Indicates the status of the voided sale. For a list of possible values, see the Transaction status enumeration.
card	masked_card_number	String	Masked card number of the card that the customer used for the sale. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
expiry_month	String	Month that the card expires, in MM format. If our gateway cannot return an expiry month, it returns a value of `NA`.
expiry_year	String	Year that the card expires, in YY format. If our gateway cannot return an expiry year, it returns a value of `NA`.
type	String	Name of the card brand that issued the card. For a list of possible values, see the card type enumeration.
payment	amount	String	Total amount of the sale that the merchant voided.
type	String	Payment type of the sale that the merchant voided. For a list of possible values, see the payment type enumeration.
transaction (US and CA only)

text object

Field	Type	Description
customer_receipt	String	Text for the customer's receipt, which contains the details of the voided sale.
merchant_receipt	String	Text for the merchant's receipt, which contains the details of the voided sale.

attributes object

Field	Type	Description
authorization_agreement	String	Text that describes the merchant's authorization agreement, for example, `I agree to pay the total amount according to the card issuer agreement`.
call_issuer	String	Text that displays if the merchant needs to call the issuing bank, for example, `CALL ISSUER`.
copy_label_customer	String	Text that identifies the receipt as the customer's copy.
copy_label_merchant	String	Text that identifies the receipt as the merchant's copy.
merchant_address	String	Address of the merchant's store.
merchant_footer	String	Text that appears on the footer of the receipt.
merchant_header	String	Text that appears on the header of the receipt.
merchant_name	String	Name of the merchant's store.
merchant_phone	String	Phone number of the merchant's store.
merchant_policy	String	Text that describes the merchant's policies, for example, a return policy.
verbiage	String	Additional text that the merchant can include on the receipt, for example, `Approved - Thank You`.

labeled_attributes object

Our gateway returns a label field and a value field for each object. For example, our gateway returns the following for the amount object:

"amount":
{
"label": "Total Amount",
"value": "99.45 USD"
}

Object	Description
amount	Total amount of the sale that the merchant voided.
approval_code	Approval code for the void from the processor.
authorization_response_code	Response code for an authorization.
avs_response_code	Response code that indicates the result of an AVS check.
batch_number	Unique identifier of the batch.
card_balance	Remaining balance of a prepaid card.
card_type	Type of card the customer used for the sale that the merchant voided.
cardsecurity_response_code	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
clerk_id	Clerk ID that the merchant wants to display on the receipt. This is an alphanumeric value that the merchant assigns to a clerk, for example, A1090-John Doe.
entry_legend	Indicates how the payment terminal read the card details. The value is one of the following: • `CHIP READ` • `MAGSTRIPE` • `MANUAL`
entry_method	Indicates how the customer or merchant entered the card details. The value is one of the following: • `Contact` • `Contactless` • `Manual` • `Swipe`
gratuity_amount	Amount that was included as a tip in the sale that the merchant voided.
masked_card_number	Masked card number of the card that the customer used for the sale. Depending on the location of the POS, our gateway returns a different masked card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
merchant_id	Unique identifier for the merchant.
original_auth_code	Authorization code of the sale.
payment_type	Type of payment for the sale that the merchant voided. For a list of possible values, see the payment type enumeration.

creditsale_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the the creditsale_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the transaction. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL we provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a sale id`.

reference_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the the reference_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the transaction. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL we provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a reference id`.

Successful response example

{
    "creditsale_id": "000000000104",
    "status": "voided",
    "card": {
        "masked_card_number": "476173XXXXXX0010",
        "expiry_month": "12",
        "expiry_year": "25",
        "type": "visa"
    },
    "payment": {
        "amount": "3.22",
        "type": "credit"
    },
    "transaction": {
        "batch_amount": "0.00",
        "batch_number": "000005"
    },
    "receipt": {
        "text": {
            "customer_receipt": "\nBatch #             000005\nTrans ID            000000000104\nOrder ID            MER-d9c17668-b09d-49\n                    ab-a731-271d2518c49c\nTrans Type          Purchase Void\nDate/Time           2023-06-27 09:05:30\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Method        MANUAL\nOriginal Auth Code  724920\n\nTotal Amount        USD$3.22\n\n          Approved - Thank You\n\n X____________________________________\n          Signature: test name\n\n         ****Customer Copy****",
            "merchant_receipt": "\nBatch #             000005\nTrans ID            000000000104\nOrder ID            MER-d9c17668-b09d-49\n                    ab-a731-271d2518c49c\nTrans Type          Purchase Void\nDate/Time           2023-06-27 09:05:30\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Method        MANUAL\nOriginal Auth Code  724920\n\nTotal Amount        USD$3.22\n\n          Approved - Thank You\n\n X____________________________________\n          Signature: test name\n\n         ****Merchant Copy****"
        },
        "id": "105",
        "attributes": {
            "copy_label_customer": "****Customer Copy****",
            "copy_label_merchant": "****Merchant Copy****",
            "verbiage": "Approved - Thank You"
        },
        "labeled_attributes": {
            "amount": {
                "label": "Total Amount",
                "value": "USD$3.22"
            },
            "batch_number": {
                "label": "Batch #",
                "value": "000005"
            },
            "card_type": {
                "label": "Card Type",
                "value": "Visa"
            },
            "entry_method": {
                "label": "Entry Method",
                "value": "MANUAL"
            },
            "masked_card_number": {
                "label": "Card Number",
                "value": "XXXXXXXXXXXX0010"
            },
            "original_auth_code": {
                "label": "Original Auth Code",
                "value": "724920"
            },
            "reference_id": {
                "label": "Order ID",
                "value": "MER-d9c17668-b09d-49ab-a731-271d2518c49c"
            },
            "total_amount": {
                "label": "Total Amount",
                "value": "USD$3.22"
            },
            "transaction_datetime": {
                "label": "Date/Time",
                "value": "2023-06-27 09:05:30"
            },
            "transaction_id": {
                "label": "Trans ID",
                "value": "000000000104"
            },
            "transaction_type": {
                "label": "Trans Type",
                "value": "Purchase Void"
            }
        }
    },
    "links": [
        {
            "creditsale_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/000000000104",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a sales transaction."
                }
            ]
        },
        {
            "reference_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/reference_id/MER-d9c17668-b09d-49ab-a731-271d2518c49c",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retreive a previous sales transaction using reference id."
                }
            ]
        }
    ],
    "reference_id": "MER-d9c17668-b09d-49ab-a731-271d2518c49c"
}

Unsuccessful response schema

Column 1	Column 2	Column 3	Column 4
Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see Status and error codes.
message	String	Text that describes the error.
detail	Object	Information that specifies the error’s location in the message body. Our gateway returns this object only when you receive an HTTP status code of 400. For a list of fields, see the detail object.
info	String	A link to our website for more information.

detail object

Column 1	Column 2	Column 3
Field	Type	Description
description	String	Text that provides specific information about the error.
data_path	String	Location of the error, for example, transaction/country_code.

Unsuccessful response example

{
    "error": {
        "code": "invalid_transaction_referenced",
        "message": "Invalid transaction referenced; transaction does not exist.",
        "info": "https://developers.api.pit.paygateway.com/errors"
    }
}

Voiding a credit return

To void a credit return, send a PUT request to the relevant endpoint.

Endpoints

The endpoint you use depends on whether you identify the return using the creditreturn_id (which is generated by the gateway) or the reference_id (which is generated by the merchant's POS).

Using the creditreturn_id

Environment	HTTP Method	URL
Test	PUT	https://api.pit.paygateway.com/transactions/creditreturns/{creditreturn_id}/voids
Production	PUT	https://api.paygateway.com/transactions/creditreturns/{creditreturn_id}/voids

Using the reference_id

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

Request

Important: Some objects have the same names, however, the parameters may be different. For more information, see Object naming.

Object	Parameter	Type	String	Required?	Description
payment	amount	String	1-9	Optional	Total amount of the return that the merchant wants to void. The value includes two decimal places, for example, `10.00`. Note: You cannot partially void a return. You must void the full amount of the return.
transaction	processing_indicators	Object	-	Optional	Object that includes options for additional actions. For a list of parameters, see the processing_indicators object.

processing_indicators object

Parameter	Type	String	Required?	Description
generate_receipt	Boolean	Explicit	Optional	If set to `true`, our gateway generates a receipt and returns it in the receipt object of the response. Note: Send this parameter for integrations in the US or Canada only.

Request body example

{
  "payment": {
    "amount": "7.80"
  },
  "transaction": {
    "processing_indicators": {
      "generate_receipt": true
    }
  }
}

Response

Object	Field	Type	Description
N/A	creditreturn_id	String	Unique identifier that our gateway generated for the return. Note: This is the creditreturn_id that you can include in the endpoint URL to view the details of the voided return.
N/A	reference_id	String	Unique identifier that the merchant created for the return. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: This is the reference_id that you can include in the endpoint URL to view the details of the voided return.
N/A	status	String	Indicates the status of the voided return. For a list of possible values, see the request status enumeration.
card	masked_card_number	String	Masked card number of the card that the customer used for the return. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
expiry_month	String	Month that the card expires, in MM format. If our gateway cannot return an expiry month, it returns a value of `NA`.
expiry_year	String	Year that the card expires, in YY format. If our gateway cannot return an expiry year, it returns a value of `NA`.
type	String	Name of the card brand that issued the card. For a list of possible values, see the card type enumeration.
payment	amount	String	Total amount of the return that the merchant voided.
type	String	Type of payment for the return. For a list of possible values, see the payment type enumeration.
transaction (US and CA only)

text object

Field	Type	Description
customer_receipt	String	Text for the customer's receipt. Our gateway created this text using the details of the voided return.
merchant_receipt	String	Text for the merchant's receipt. Our gateway created this text using the details of the voided return.

attributes object

Field	Type	Description
authorization_agreement	String	Text that describes the merchant's authorization agreement, for example, `I agree to pay the total amount according to the card issuer agreement`.
call_issuer	String	Text that displays if the merchant needs to call the issuing bank, for example, `CALL ISSUER`.
copy_label_customer	String	Text that identifies the receipt as the customer's copy.
copy_label_merchant	String	Text that identifies the receipt as the merchant's copy.
merchant_address	String	Address of the merchant's store.
merchant_footer	String	Text that appears on the footer of the receipt.
merchant_header	String	Text that appears on the header of the receipt.
merchant_name	String	Name of the merchant's store.
merchant_phone	String	Phone number of the merchant's store.
merchant_policy	String	Text that describes the merchant's policies, for example, a return policy.
verbiage	String	Additional text that the merchant can include on the receipt, for example, `Approved - Thank You`.

labeled_attributes object

Our gateway returns a label field and a value field for each object. For example, our gateway returns the following for the amount object:

"amount":
{
"label": "Total Amount",
"value": "99.45 USD"
}

Object	Description
amount	Total amount of the return that the merchant voided.
approval_code	Approval code for the voided return from the processor.
authorization_response_code	Response code for an authorization.
avs_response_code	Response code that indicates the result of an AVS check.
batch_number	Unique identifier of the batch.
card_balance	Remaining balance of a prepaid card.
card_type	Type of card the customer used for the return that the merchant voided.
cardsecurity_response_code	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
clerk_id	Clerk ID that the merchant wants to display on the receipt. This is an alphanumeric value that the merchant assigns to a clerk, for example, `A1090-John Doe`.
entry_legend	Indicates how the payment terminal read the card details. The value is one of the following: • `CHIP READ` • `MAGSTRIPE` • `MANUAL`
entry_method	Indicates how the customer or merchant entered the card details. The value is one of the following: • `Contact` • `Contactless` • `Manual` • `Swipe`
gratuity_amount	Amount that was included as a tip in the return that the merchant voided.
masked_card_number	Masked card number of the card that the customer used for the return. Depending on the location of the POS, our gateway returns a different masked card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
merchant_id	Unique identifier for the merchant.
original_auth_code	Authorization code of the return.
payment_type	Type of payment for the return that the merchant voided. For a list of possible values, see the payment type enumeration.

creditreturn_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the the creditreturn_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the transaction. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL we provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a sale id`.

reference_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the the reference_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the transaction. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL we provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a reference id`.

Successful response example

{
    "creditreturn_id": "000000000114",
    "status": "voided",
    "card": {
        "masked_card_number": "476173XXXXXX0010",
        "expiry_month": "12",
        "expiry_year": "25",
        "type": "visa"
    },
    "payment": {
        "amount": "7.80",
        "type": "credit"
    },
    "transaction": {
        "batch_amount": "0.00",
        "batch_number": "000005"
    },
    "receipt": {
        "text": {
            "customer_receipt": "\nBatch #             000005\nTrans ID            000000000114\nOrder ID            MER-640ff59e-981f-46\n                    fc-abe8-b5af7d5a6d8f\nTrans Type          Purchase Void\nDate/Time           2023-06-28 05:27:37\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Method        MANUAL\nOriginal Auth Code  046276\n\nTotal Amount        USD$7.80\n\n          Approved - Thank You\n\n X____________________________________\n          Signature: test name\n\n         ****Customer Copy****",
            "merchant_receipt": "\nBatch #             000005\nTrans ID            000000000114\nOrder ID            MER-640ff59e-981f-46\n                    fc-abe8-b5af7d5a6d8f\nTrans Type          Purchase Void\nDate/Time           2023-06-28 05:27:37\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Method        MANUAL\nOriginal Auth Code  046276\n\nTotal Amount        USD$7.80\n\n          Approved - Thank You\n\n X____________________________________\n          Signature: test name\n\n         ****Merchant Copy****"
        },
        "id": "115",
        "attributes": {
            "copy_label_customer": "****Customer Copy****",
            "copy_label_merchant": "****Merchant Copy****",
            "verbiage": "Approved - Thank You"
        },
        "labeled_attributes": {
            "amount": {
                "label": "Total Amount",
                "value": "USD$7.80"
            },
            "batch_number": {
                "label": "Batch #",
                "value": "000005"
            },
            "card_type": {
                "label": "Card Type",
                "value": "Visa"
            },
            "entry_method": {
                "label": "Entry Method",
                "value": "MANUAL"
            },
            "masked_card_number": {
                "label": "Card Number",
                "value": "XXXXXXXXXXXX0010"
            },
            "original_auth_code": {
                "label": "Original Auth Code",
                "value": "046276"
            },
            "reference_id": {
                "label": "Order ID",
                "value": "MER-640ff59e-981f-46fc-abe8-b5af7d5a6d8f"
            },
            "total_amount": {
                "label": "Total Amount",
                "value": "USD$7.80"
            },
            "transaction_datetime": {
                "label": "Date/Time",
                "value": "2023-06-28 05:27:37"
            },
            "transaction_id": {
                "label": "Trans ID",
                "value": "000000000114"
            },
            "transaction_type": {
                "label": "Trans Type",
                "value": "Purchase Void"
            }
        }
    },
    "links": [
        {
            "creditreturn_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditreturns/000000000114",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a previously completed returns transaction."
                }
            ]
        },
        {
            "reference_id": [
                {
                    "href": "https://api.pit.paygateway.com/payments/creditreturns/reference_id/MER-640ff59e-981f-46fc-abe8-b5af7d5a6d8f",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a previously completed returns transaction using reference id."
                }
            ]
        }
    ],
    "reference_id": "MER-640ff59e-981f-46fc-abe8-b5af7d5a6d8f"
}

Unsuccessful response schema

Column 1	Column 2	Column 3	Column 4
Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see the Error response codes.
message	String	Text that describes the error.
info	String	A link to our website for more information.

Unsuccessful response example

{
    "error": {
        "code": "processing_forbidden",
        "message": "Transaction already voided",
        "info": "https://developers.api.pit.paygateway.com/errors"
    }
}

Viewing the details of an authorization

To view the details of an authorization, send a GET request including the reference_id to the relevant endpoint.

Important: The response does not include the following:

HATEOAS links
A receipt object

Endpoints

Environment	HTTP Method	URL
Test	GET	https://api.pit.paygateway.com/transactions/card/auths/reference\_id/{reference_id}
Production	GET	https://api.paygateway.com/transactions/card/auths/reference\_id/{reference_id}

Response

Object	Field	Type	Description
N/A	invoice_number	String	Invoice number for the authorization.
amount	String	Total amount of the authorization. The value includes two decimal places, for example, 10.00.
currency_code	String	The ISO currency code for the transaction. For a list of possible values, see the currency code enumeration.
gratuity_amount	String	Amount that was included as a tip in the authorization.
transactions	tender_type	String	Payment type that the customer used for the authorization. The value is one of the following: • `credit` • `debit` • `cash` • `check`
entry_type	String	Indicates how the user entered the card details. The value is one of the following: • `contact` • `contactless` • `manual` • `swipe`
id	String	Unique identifier that our gateway generated for the authorization. Note: This is the creditauth_id.
reference_id	String	Unique identifier for the authorization that the merchant created. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: You can include this reference_id in the endpoint URL for follow-on transactions.
status	String	Indicates the state of the authorization. For a list of possible values, see the transaction status enumeration.
status_code	String	Indicates the status of the request. For a list of possible values, see the status code enumeration.
processor_response	String	Response from the processor that describes the status of the transaction.
transaction_datetime

credit_attributes object

Object	Field	Type	Description
N/A	approval_code	String	Approval code for the authorization from the processor.
avs_response	String	Response code from an address verification service (AVS) lookup. For a list of possible values, see the AVS response enumeration.
avs_response_description	String	Text that describes the response code that the processor returned in the avs_response field.
cardsecurity_response	String	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
payment	amount	String	Total amount taken from the customer’s account for the authorization.
cashback_amount	String	Amount that was included as cashback in the authorization.
type	String	Type of payment for the authorization. For a list of possible values, see the payment type enumeration.
	fees	Object	Object that contains details of the fees that the customer paid. For a list of parameters, see the fees object below.
card	masked_card_number	String	Masked card number of the card that the customer used for the authorization. Our gateway masks all digits except the first six digits and the last four digits. If our gateway cannot return a masked card number, it returns a value of `NA`.
cardholder_name	String	Name that appears on the customer’s card.
expiry_month	String	Month that the card expires, in MM format. If our gateway cannot return an expiry month, it returns a value of `NA`.
expiry_year	String	Year that the card expires, in YY format. If our gateway cannot return an expiry year, it returns a value of .

fees object

Field	Type	Size	Description
surcharge_amount	Numeric	Variable	For US credit transactions, this is the surcharge amount applied to the amount submitted in the transaction request if surcharge fees have been configured for the merchant in the gateway. It is a dollar amount the merchant charged the cardholder as a surcharge for paying using a credit card

card_on_file_attributes object

Field	Type	Description
tokenization_error_code	String	Response code from our gateway.
tokenization_error_message	String	Text that describes why our gateway could not store the card details.

Successful response example

{
  "invoice_number": "239087",
  "amount": "23.09",
  "currency_code": "840",
  "gratuity_amount": "23.09",
  "transactions": [
    {
      "tender_type": "credit",
      "entry_type": "contactless",
      "id": "000008639902",
      "reference_id": "XAZR863990",
      "status": "approved",
      "status_code": "200",
      "processor_response": "APPROVAL ADB123",
      "transaction_datetime": "2019-12-15T13:00:00Z",
      "credit_attributes": {
        "approval_code": "ADB123",
        "avs_response": "full_match",
        "avs_response_description": "Match - Street Address",
        "cardsecurity_response": "match",
        "payment": {
          "amount": "23.09",
          "cashback_amount": "23.09",
          "type": "credit",
          "fees": {
            "surcharge_amount": "10.00"
          }
        },
        "card": {
          "masked_card_number": "XXXXXXXXXXX5538",
          "cardholder_name": "Joe Doe",
          "expiry_month": "03",
          "expiry_year": "23",
          "type": "visa",
          "balance": "12.09",
          "postal_code": "84042",
          "rfmiq": "ADB12",
          "token": "EnzMcSVlkP",
          "card_on_file_attributes": {
            "tokenization_error_code": "ADB12",
            "tokenization_error_message": "ADB12"
          }
        }
      }
    }
  ]
}

Unsuccessful response schema

error object

Column 1	Column 2	Column 3	Column 4
Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see the Error response codes.
message	String	Text that describes the error.
detail	Object	Information that specifies the error’s location in the message body. Our gateway returns this object only when you receive an HTTP status code of 400. For a list of fields, see the detail object.
info	String	A link to our website for more information.

detail object

Field	Type	Description
Description	String	Text that provides specific information about the error.
data_path	String	Location of the error, for example, transaction/country_code.

Unsuccessful response example

{
    "error": { 
        "code": "invalid_input",
        "message": "Invalid input data",
        "detail": [
            {
                "description": "invalid pararmter",
                "data_path": query:generate_receipt"
            },
            ],
        "info": "https://developers.api.pit.paygateway.com/errors"
    }
}

Viewing the details of any sale

To view the details of any sale, send a GET request including the reference_id to the relevant endpoint.

Important:

The response does not include the following:

HATEOAS links.
A receipt object. If you want to generate a receipt, see Viewing the details of a credit sale.

Endpoints

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

Response

Object	Field	Type	Description
N/A	invoice_number	String	Alphanumeric invoice number or order number that the merchant created and assigned to the sale. Note: The OpenEdge gateway saves only the first 25 digits of the invoice number.
amount	String	Total amount that was taken from the customer’s account for the sale.
currency_code	String	ISO currency code for the sale. For a list of possible values, see the currency code enumeration.
gratuity_amount	String	Amount that was included as a tip in the sale.
transactions	tender_type	String	Payment type that the customer used for the sale. The value is one of the following: • `credit` • `debit` • `cash` • `check`
entry_type	String	Indicates how the user entered the card details. The value is one of the following: • `contact` • `contactless` • `manual` • `swipe`
id	String	Unique identifier that our gateway generated for the sale. Note: This is the creditsale_id or debitsale_id that you can include in the endpoint URL for follow-on transactions.
reference_id	String	Unique identifier that the merchant created for the sale. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: This is the reference_id that you can include in the endpoint URL for follow-on transactions.
status	String	Indicates the status of the sale. For a list of possible values, see the status enumeration.
status_code	String	Indicates the status of your request. For a list of possible values, see the status code enumeration.
transaction_datetime

credit_attributes object

Object	Field	Type	Description
-	approval_code	String	Approval code for the sale from the processor.
avs_response	String	Response code from an address verification service (AVS) lookup. For a list of possible values, see the AVS response enumeration.
avs_response_description	String	Text that describes the response code that the processor returned in the avs_response field.
cardsecurity_response	String	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
payment	amount	String	Total amount taken from the customer’s account for the sale.
cashback_amount	String	Amount that was included as cashback in the sale.
type	String	Type of payment for the sale. For a list of possible values, see the payment type enumeration.
card	masked_card_number	String	Masked card number of the card that the customer used for the sale. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
cardholder_name	String	Name that appears on the customer’s card.
expiry_month	String	Month that the card expires, in MM format. If our gateway cannot return an expiry month, it returns a value of `NA`.
expiry_year	String	Year that the card expires, in YY format. If our gateway cannot return an expiry year, it returns a value of `NA`.
token

debit_attributes object

Object	Field	Type	Description
-	approval_code	String	Approval code for the sale from the processor.
avs_response	String	Response code from an address verification service (AVS) lookup. For a list of possible values, see the AVS response enumeration.
avs_response_description	String	Text that describes the response code that the processor returned in the avs_response field.
cardsecurity_response	String	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
payment	amount	String	Total amount taken from the customer’s account for the sale.
cashback_amount	String	Amount that was included as cashback in the sale.
type	String	Type of payment for the sale. For a list of possible values, see the payment type enumeration.
card	masked_card_number	String	Masked card number of the card that the customer used for the sale. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
cardholder_name	String	Name that appears on the customer’s card.
expiry_month	String	Month that the card expires, in MM format. If our gateway cannot return an expiry month, it returns a value of `NA`.
expiry_year	String	Year that the card expires, in YY format. If our gateway cannot return an expiry year, it returns a value of `NA`.
token

card_on_file_attributes object

Field	Type	Description
tokenization_error_code	String	Response code from our gateway.
tokenization_error_message	String	Text that describes why our gateway could not store the card details.

Successful response example

{
    "amount": "5.00",
    "transactions": [
        {
            "tender_type": "credit",
            "transaction_datetime": "20230630030730",
            "processor_response": "000AP",
            "reference_id": "MER-76a89d50-e58e-4e8e-b560-c935c12537d8",
            "id": "000000000170",
            "status": "approved",
            "status_code": "200",
            "credit_attributes": {
                "payment": {
                 "amount": "5.00",
                 "type": "credit"
        },
     "approval_code": "087836",
     "card": {
             "masked_card_number": "476173XXXXXX0010",
             "expiry_month": "12",
             "expiry_year": "25",
             "type": "visa"                }
           }
        }
    ]
}

Unsuccessful response schema

Column 1	Column 2	Column 3	Column 4
Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see the Error response codes.
message	String	Text that describes the error.
info	String	A link to our website for more information.

Unsuccessful response example

{
    "error": {
        "code": "invalid_input",
        "message": "Invalid reference_id provided",
        "info": "https://developers.api.pit.paygateway.com/errors"
    }
}

Viewing the details of a credit sale

To view the details of a credit sale, send a GET request including either the creditsale_id or the reference_id to the relevant endpoint.

Important: To generate a receipt, include the generate_receipt parameter in the URL and set the value to true. For example, https://api.paygateway.com/transactions/creditsales/000008639902?generate\_receipt=true.

Endpoints

The endpoint you use depends on whether you identify the sale using the creditsale_id (generated by the gateway) or the reference_id (generated by the merchant's POS).

Using the creditsale_id

Environment	HTTP Method	URL
Test	GET	https://api.pit.paygateway.com/transactions/creditsales/{creditsale_id}
Production	GET	https://api.paygateway.com/transactions/creditsales/{creditsale_id}

Using the reference_id

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

Response

Object	Field	Type	Description
N/A	creditsale_id	String	Unique identifier that our gateway generated for the sale. Note: This is the creditsale_id that you can include in the endpoint URL for follow-on transactions.
status	String	Indicates the status of the sale. For a list of possible values, see the transaction status enumeration.
approval_code	String	Approval code for the sale from the processor. Note: For integrations in Australia or New Zealand, our gateway returns a value of `NA`.
avs_response	String	Response code from an address verification service (AVS) lookup. For a list of possible values, see the AVS response enumeration.
avs_response_description	String	Text that describes the response code that the processor returned in the avs_response field.
cardsecurity_response	String	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
reference_id	String	Unique identifier that the merchant created for the sale. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: This is the reference_id that you can include in the endpoint URL for follow-on transactions.
card	masked_card_number	String	Masked card number of the card that the customer used for the sale. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • For integrations in Australia or New Zealand, our gateway masks all digits except the last four digits.• If our gateway cannot return a masked card number, it returns a value of .

fees object

Field	Type	Description
customer_fee_amount	String	For integrations in Australia or New Zealand, these are the total fees that the customer paid for the sale.

purchase_order object

Field	Type	Description
po_number	String	Purchase order number for the sale if the customer uses a corporate purchase card. Required for Level 2 transactions. This is an alphanumeric value that the merchant created, for example, `2343445`.
tax_amount	String	Total tax amount for the sale.

text object

Field	Type	Description
customer_receipt	String	Text for the customer’s receipt, which contains the details of the sale.
merchant_receipt	String	Text for the merchant’s receipt, which contains the details of the sale.

attributes object

Field	Type	Description
authorization_agreement	String	Text that describes the merchant's authorization agreement, for example, `I agree to pay the total amount according to the card issuer agreement`.
call_issuer	String	Text that displays if the merchant needs to call the issuing bank, for example, `CALL ISSUER`.
copy_label_customer	String	Text that identifies the receipt as the customer's copy.
copy_label_merchant	String	Text that identifies the receipt as the merchant's copy.
merchant_address	String	Address of the merchant's store.
merchant_footer	String	Text that appears on the footer of the receipt.
merchant_header	String	Text that appears on the header of the receipt.
merchant_name	String	Name of the merchant's store.
merchant_phone	String	Phone number of the merchant's store.
merchant_policy	String	Text that describes the merchant's policies, for example, a return policy.
verbiage	String	Additional text that the merchant can include on the receipt, for example, `Approved - Thank You`.

labeled_attributes object

Our gateway returns a label field and a value field for each object. For example, for amount, our gateway returns the following for the amount object:

"amount":
{
"label": "Total Amount",
"value": "99.45 USD"
}

Object	Description
amount	Total amount of the sale.
approval_code	Approval code for the sale from the processor.
authorization_response_code	Response code for an authorization.
avs_response_code	Response code that indicates the result of an AVS check.
batch_number	Unique identifier of the batch.
card_balance	Remaining balance of a prepaid card.
card_type	Type of card the customer used for the sale.
cardsecurity_response_code	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
clerk_id	Clerk ID that the merchant wants to display on the receipt. This is an alphanumeric value that the merchant assigns to a clerk, for example, `Al090-John Doe`.
entry_legend	Indicates how the payment terminal read the card details. The value is one of the following: • `CHIP READ` • `MAGSTRIPE` • `MANUAL`
entry_method	Indicates how the customer or merchant entered the card details. The value is one of the following: • `contact` • `contactless` • `manual` • `swipe`
gratuity_amount	Amount that was tip in the original transaction.
masked_card_number	Masked card number of the card that the customer used for the transaction. We mask all digits except the first six and the last four.
merchant_id	Unique identifier for the merchant.
original_auth_code	The authorization code of the sale.
payment_type	Type of payment for the sale. For a list of possible values, see the payment type enumeration.
number	Number of the receipt.
reference_id	Unique identifier that the merchant created for the sale. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead.: You can include the reference_id in the endpoint URL for follow-on transactions.

creditsale_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the creditsale_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the request. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL our gateway provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a sale id.`

reference_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the reference_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the request. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL our gateway provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a reference id.`

Successful response example

{
    "amount": "9.27",
    "transactions": [
        {
            "tender_type": "credit",
            "transaction_datetime": "20230705042852",
            "processor_response": "DEVELOPMENT APPROVAL",
            "reference_id": "MER-5f604e28-d7f5-4c3c-a635-20635e1252f4",
            "id": "000000000186",
            "status": "approved",
            "status_code": "200",
            "credit_attributes": {
                "payment": {
                    "amount": "9.27",
                    "type": "credit"
                },
                "approval_code": "333298",
                "card": {
                    "masked_card_number": "476173XXXXXX0010",
                    "expiry_month": "12",
                    "expiry_year": "25",
                    "type": "visa"
                }
            }
        }
    ]
}

Unsuccessful response schema

Column 1	Column 2	Column 3	Column 4
Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see the Error response codes.
message	String	Text that describes the error.
info	String	A link to our website for more information.

Unsuccessful response example

{
    "error": {
        "code": "invalid_input",
        "message": "Invalid reference_id provided",
        "info": "https://developers.api.pit.paygateway.com/errors"
    }
}

Viewing the details of any return

To view the details of any return, send a GET request including the reference_id to the relevant endpoint.

Endpoints

Environment	HTTP Method	URL
Test	GET	https://api.pit.paygateway.com/transactions/card/returns/reference\_id/{reference_id}
Production	GET	https://api.paygateway.com/transactions/card/returns/reference\_id/{reference_id}

Response

Object	Field	Type	Description
N/A	invoice_number	String	Invoice number for the return.
amount	String	Total amount of the return. The value includes two decimal places, for example, `10.00`. Note: • If the transaction was partially approved, the amount we return is less than the amount you sent in the request. • If the request included a tip, the amount we return is greater than the amount you send in the request.
currency_code	String	ISO currency code for the return. For a list of possible values, see the currency code enumeration.
transactions	tender_type	String	Payment type that the customer used for the return. The value is one of the following: • `credit` • `debit` • `cash` • `check`
entry_type	String	Indicates how the user entered the card details. The value is one of the following: • `contact` • `contactless` • `manual` • `swipe`
id	String	Unique identifier that our gateway generated for the return. Note: This is the creditreturn_id that you can include in the endpoint URL for follow-on transactions.
reference_id	String	Unique identifier for the return that the merchant created. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: This is the reference_id that you can include in the endpoint URL for follow-on transactions.
status	String	Indicates the status of the return. For a list of possible values, see the transaction status enumeration.
status_code	String	Indicates the status of the request. For a list of possible values, see the status code enumeration.
transaction_datetime

credit_attributes object

Object	Field	Type	Description
N/A	approval_code	String	Approval code for the return from the processor.
avs_response	String	Response code from an address verification service (AVS) lookup. For a list of possible values, see the AVS response enumeration.
avs_response description	String	Text that describes the response code that the processor returned in the avs_response field.
cardsecurity_response	String	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
payment	amount	String	Total amount for the return.
type	String	Type of payment for the return. For a list of possible values, see the payment type enumeration.
card	masked_card_number	String	Masked card number of the card that the customer used for the return. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
cardholder_name	String	The cardholder's name that is printed on the card.
expiry_month	String	Month that the card expires, in MM format. If our gateway cannot return an expiry month, it returns a value of `NA.`
expiry_year	String	Year that the card expires, in YY format. If our gateway cannot return an expiry year, it returns a value of `NA.`
type	String	Name of the card brand that issued the card. For a list of possible values, see the card type enumeration.

debit_attributes object

Object	Field	Type	Description
N/A	approval_code	String	Approval code for the return from the processor.
avs_response	String	Response code from an address verification service (AVS) lookup. For a list of possible values, see the AVS response enumeration.
avs_response description	String	Text that describes the response code that the processor returned in the avs_response field.
cardsecurity_response	String	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
payment	amount	String	Total amount for the return.
type	String	Type of payment for the return. For a list of possible values, see the payment type enumeration.
card	masked_card_number	String	Masked card number of the card that the customer used for the return. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
cardholder_name	String	The cardholder's name that is printed on the card.
expiry_month	String	Month that the card expires, MM format. If our gateway cannot return an expiry month, it returns a value of `NA.`
expiry_year	String	Year that the card expires, YY format. If our gateway cannot return an expiry year, it returns a value of `NA.`
type	String	Name of the card brand that issued the card. For a list of possible values, see the card type enumeration.

Successful response example

{
    "amount": "9.27",
    "transactions": [
        {
            "tender_type": "credit",
            "transaction_datetime": "20230705042852",
            "processor_response": "DEVELOPMENT APPROVAL",
            "reference_id": "MER-5f604e28-d7f5-4c3c-a635-20635e1252f4",
            "id": "000000000186",
            "status": "approved",
            "status_code": "200",
            "credit_attributes": {
                "payment": {
                    "amount": "9.27",
                    "type": "credit"
                },
                "approval_code": "333298",
                "card": {
                    "masked_card_number": "476173XXXXXX0010",
                    "expiry_month": "12",
                    "expiry_year": "25",
                    "type": "visa"
                }
            }
        }
    ]
}

Unsuccessful response schema

Column 1	Column 2	Column 3	Column 4
Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see the Error response codes.
message	String	Text that describes the error.
info	String	A link to our website for more information.

Unsuccessful response example

{
    "error": {
        "code": "invalid_transaction_referenced",
        "message": "Invalid transaction referenced; transaction does not exist.",
        "info": "https://developers.api.pit.paygateway.com/errors"
    }
}

Viewing the details of a credit return

To view the details of a credit return, send a GET request including either the creditreturn_id or the reference_id to the relevant endpoint.

Important: To generate a receipt, include the generate_receipt parameter in the URL and set the value to true. For example, https://api.paygateway.com/transactions/creditreturns/000008639902?generate\_receipt=true.

Endpoints

The endpoint you use depends on whether you identify the credit return using the creditreturn_id (generated by the gateway) or the reference_id (generated by the merchant's POS).

Using the creditreturn_id

Environment	HTTP Method	URL
Test	GET	https://api.pit.paygateway.com/transactions/creditreturns/{creditreturn_id}
Production	GET	https://api.paygateway.com/transactions/creditreturns/{creditreturn_id}

Using the reference_id

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

Response

Object	Field	Type	Description
N/A	creditreturn_id	String	Unique identifier that our gateway generated for the return. Note: This field is the creditreturn_id that you can include in the endpoint URL for follow-on transactions.
status	String	Status of the request. For a list of possible values, see the transaction status enumeration.
approval_code	String	Approval code for the return from the processor.
reference_id	String	Unique identifier that the merchant generated for the return. If the merchant does not send this in the request, our gateway automatically creates the reference_id instead. Note: This field is the reference_id that you can include in the endpoint URL for follow-on transactions.
card	masked_card_number	String	Masked card number of the card that the customer used for the transaction. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
expiry_month	String	Month that the card expires, in MM format. If our gateway cannot return an expiry month, it returns a value of `NA`.
expiry_year	String	Year that the card expires, in YY format. If our gateway cannot return an expiry month, it returns a value of `NA`.
type	String	Name of the card brand that issued the card. For a list of possible values, see the card type enumeration.
payment	amount	String	Total amount for the return.
invoice_number	String	Alphanumeric invoice number or order number that the merchant creates and assigns to the return.

text object

Field	Type	Description
customer_receipt	String	Text for the customer’s receipt. Our gateway creates this text using the details of the return.
merchant_receipt	String	Text for the merchant’s receipt. Our gateway creates this text using the details of the return.

attributes object

Field	Type	Description
authorization_agreement	String	Text that describes the merchant's authorization agreement, for example, `I agree to pay the total amount according to the card issuer agreement`.
call_issuer	String	Text that displays if the merchant needs to call the issuing bank, for example, `CALL ISSUER`.
copy_label_customer	String	Text that identifies the receipt as the customer's copy.
copy_label_merchant	String	Text that identifies the receipt as the merchant's copy.
duplicate_label	String	Text that identifies the receipt as a duplicate copy.
merchant_address	String	Address of the merchant's store.
merchant_footer	String	Text that appears on the footer of the receipt.
merchant_header	String	Text that appears on the header of the receipt.
merchant_name	String	Name of the merchant's store.
merchant_phone	String	Phone number of the merchant's store.
merchant_policy	String	Text that describes the merchant's policies, for example, a return policy.
verbiage	String	Additional text that the merchant can include on the receipt, for example, `Approved - Thank You`.

labeled_attributes object

Our gateway returns a label field and a value field for each object. For example, our gateway returns the following for the amount object:

"amount":
{
"label": "Total Amount",
"value": "99.45 USD"
}

Object	Description
amount	Total amount of the transaction.
approval_code	Approval code for the transaction from the processor.
authorization_response_code	Response code for an authorization.
avs_response_code	Response code that indicates the result of an AVS check.
batch_number	Unique identifier of the batch.
card_balance	Remaining balance of a prepaid card.
card_type	Type of card the customer used for the return.
cardsecurity_response_code	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
clerk_id	Clerk ID that the merchant wants to display on the receipt. This is an alphanumeric value that the merchant assigns to a clerk, for example, `Al090-John Doe`.
entry_legend	Indicates how the payment terminal read the card details. The value is one of the following: • `CHIP READ` • `MAGSTRIPE` • `MANUAL`
entry_method	Indicates how the customer or merchant entered the card details. The value is one of the following: • `contact` • `contactless` • `manual` • `swipe`
gratuity_amount	Amount that was included as a tip in the original transaction.
masked_card_number	Masked card number of the card that the customer used for the transaction. Depending on the location of the POS, our gateway masks different parts of the card number: • For integrations in the US or Canada, our gateway masks all digits except the first six digits and the last four digits. • If our gateway cannot return a masked card number, it returns a value of `NA`.
merchant_id	Unique identifier for the merchant.
original_auth_code	Authorization code of the original transaction.
payment_type	Type of payment for the transaction. For a list of possible values, see the payment type enumeration.

creditreturn_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the creditreturn_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the request. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL our gateway provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a sale id.`

reference_id object

Field	Type	Description
href	String	Endpoint URL for the follow-on transaction using the reference_id.
relation	String	Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • `return` - The transaction uses the returns endpoint. • `self` - The transaction uses the same type of endpoint as the original request. • `void` - The transaction uses the void endpoint.
method	String	HTTP method for sending the request. The value is one of the following: • `GET` • `PATCH` • `POST` • `PUT`
description	String	Text that describes how to use the endpoint URL our gateway provided in the href field. For example, `Use this endpoint to retrieve a previous sales transaction using a reference id.`

Successful response example

{
    "creditreturn_id": "000000086179",
    "status": "approved",
    "approval_code": "080303",
    "card": {
        "masked_card_number": "476173XXXXXX0010",
        "expiry_month": "12",
        "expiry_year": "25",
        "type": "visa"
    },
    "payment": {
        "amount": "0.60",
        "type": "credit"
    },
    "transaction": {
        "batch_number": "000395"
    },
    "links": [
        {
            "creditreturn_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditreturns/000000086179",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a previously completed returns transaction."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditreturns/000000086179/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/creditreturns/reference_id/MER-ab4380ca-1df2-4c68-ac9c-3b7871c83f3b",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a previously completed returns transaction using reference id."
                }
            ]
        }
    ],
    "reference_id": "MER-ab4380ca-1df2-4c68-ac9c-3b7871c83f3b"
}

Unsuccessful response schema

Column 1	Column 2	Column 3	Column 4
Object	Field	Type	Description
error	code	String	Text that indicates the reason our gateway couldn’t process the request. For a list of possible values, see the Error response codes.
message	String	Text that describes the error.
info	String	A link to our website for more information.

Unsuccessful response schema

{
    "error": {
        "code": "invalid_transaction_referenced",
        "message": "Invalid transaction referenced; transaction does not exist.",
        "info": "https://developers.api.pit.paygateway.com/errors"
    }
}

NA

title``first_name``middle_name``last_name

title

first_name

middle_name

last_name

NA