Saving Card Details to the Vault

Column 1	Column 2	Column 3
Environment	HTTP Method	URL
Test	POST	https://api.pit.paygateway.com/transactions/cardpresent/auths
Production	POST	https://api.paygateway.com/transactions/cardpresent/auths

Column 1

Column 2

Column 3

Environment

HTTP Method

URL

Test

POST

https://api.pit.paygateway.com/transactions/cardpresent/auths

Production

POST

https://api.paygateway.com/transactions/cardpresent/auths

Column 1	Column 2	Column 3	Column 4	Column 5	Column 6
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
payment	amount	String	1-10	Required	Set to 0.00 to process a zero dollar authorization.
currency_code	String	Explicit	Required	ISO currency code for the sale. For a list of possible values, see the currency code enumeration.
invoice_number	String	1-8	Required	Alphanumeric invoice number or order number that the merchant creates and assigns to the sale.
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.
transaction	keyed_entry_mode	String	Explicit	Optional	Indicates if the device allows the user to enter the card details using the keypad. Send one of the following values: • default - The device uses only keyed entry. • allowed - The device can accept keyed entry and displays it as an option on the payment selection screen. Note: If you don’t send a value, the device doesn’t display keyed entry as an option on the payment selection screen.
country_code	String	Explicit	Required	ISO code for the country where the sale 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.
create_token_reason	String	Explicit	Conditional	When the value for create_token is true, you must indicate who requested the transaction. Send one of the following values: • unscheduled_merchant_initiated_transaction - The merchant requested the transaction. • unscheduled_customer_initiated_transaction - The customer requested the transaction.

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

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

payment

amount

String

1-10

Required

Set to 0.00 to process a zero dollar authorization.

currency_code

String

Explicit

Required

ISO currency code for the sale. For a list of possible values, see the currency code enumeration.

invoice_number

String

1-8

Required

Alphanumeric invoice number or order number that the merchant creates and assigns to the sale.

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.

transaction

keyed_entry_mode

String

Explicit

Optional

Indicates if the device allows the user to enter the card details using the keypad. Send one of the following values:
• default - The device uses only keyed entry.
• allowed - The device can accept keyed entry and displays it as an option on the payment selection screen. Note: If you don’t send a value, the device doesn’t display keyed entry as an option on the payment selection screen.

country_code

String

Explicit

Required

ISO code for the country where the sale 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.

create_token_reason

String

Explicit

Conditional

When the value for create_token is true, you must indicate who requested the transaction. Send one of the following values:
• unscheduled_merchant_initiated_transaction - The merchant requested the transaction.
• unscheduled_customer_initiated_transaction - The customer requested the transaction.

Column 1	Column 2	Column 3	Column 4	Column 5
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.
create_token	Boolean	Explicit	Optional	Set to true to save the card details to our vault. Our gateway creates a token and returns it in the response.

Column 1

Column 2

Column 3

Column 4

Column 5

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.

create_token

Boolean

Explicit

Optional

Set to true to save the card details to our vault. Our gateway creates a token and returns it in the response.

{ "reference_id":"12478789089fd", "payment":{ "amount":"0.00", "currency_code":"840", "invoice_number":"INV-1234" }, "receipt":{ "clerk_id":"Test Name" }, "transaction":{ "keyed_entry_mode":"allowed", "country_code":"840", "create_token_reason": "unscheduled_merchant_initiated_transaction", "processing_indicators":{ "create_token":true, "allow_duplicate":true } } }

Column 1	Column 2	Column 3	Column 4
Object	Field	Type	Description
	amount	String	Total dollar amount of the sale. Note: • If the transaction was partially approved, the amount we return is less than the dollar 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.
	status	String	Indicates the status of the request. For a list of possible values, see the request status enumeration.
	currency_code	String	ISO currency code for the sale. For a list of possible values, see the currency code enumeration.
	gratuity_amount	String	Dollar amount that was tip in the original sale.
transactions	tender_type	String	The payment type that the customer used for the sale. The value is one of the following: • credit • debit
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 for the sale that the merchant created. 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 transaction status enumeration.
status_code	String	Indicates the status of the request. For a list of status codes, see Handling responses.
transaction_datetime	String	Date and time of the sale that the processor returns in YYYY-MM-DDThh:mm:ssZ format, for example, 2019-12-15T13:00:00Z.
credit_attributes	Object	Object that contains details of the amount. See the credit_attributes object.
amount	Object	Object that contains details of credit card transactions. See the credit_attributes object.

Column 1

Column 2

Column 3

Column 4

Object

Field

Type

Description

amount

String

Total dollar amount of the sale.
Note:
• If the transaction was partially approved, the amount we return is less than the dollar 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.

status

String

Indicates the status of the request. For a list of possible values, see the request status enumeration.

currency_code

String

ISO currency code for the sale. For a list of possible values, see the currency code enumeration.

gratuity_amount

String

Dollar amount that was tip in the original sale.

transactions

tender_type

String

The payment type that the customer used for the sale. The value is one of the following:
• credit
• debit

entry_type

String

Indicates how the user entered the card details. The value is one of the following:
• Contact
• Contactless
• Manual
• Swipe

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 for the sale that the merchant created.
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 transaction status enumeration.

status_code

String

Indicates the status of the request. For a list of status codes, see Handling responses.

transaction_datetime

String

Date and time of the sale that the processor returns in YYYY-MM-DDThh:mm:ssZ format, for example, 2019-12-15T13:00:00Z.

credit_attributes

Object

Object that contains details of the amount. See the credit_attributes object.

amount

Object

Object that contains details of credit card transactions. See the credit_attributes object.

Column 1	Column 2	Column 3	Column 4
Object	Field	Type	Description
N/A	approval_code	String	Approval code for the sale from the processor.
N/A	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 dollar amount for the sale.
cashback_amount		Dollar amount of cashback for 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. We mask all digits except the first six and the last four.
cardholder_name	String	Name that appears on the customer’s card.
expiry_month	String	Month that the card expires in MM format.
expiry_year	String	Year that the card expires in YY format.
token	String	Unique reference for the customer's payment details that they stored on our vault.
type	String	Name of the card brand that issued the card. For a list of possible values, see the card type enumeration.
balance	String	Dollar amount that remains on the card.
postal_code	String	Postal code that the card is registered to.
rfmiq	String	Unique token that tracks the customer’s spending habits.
card_on_file_attributes	String	If our gateway was unable to create a token, this object contains error details. See the card_on_file_attributes object.
emv	amount	Object	Object that contains details about the dollar amount of the sale. See the amount object.
icc	Object	Object that contains details about the integrated circuit card (ICC). See the icc object.

Column 1

Column 2

Column 3

Column 4

Object

Field

Type

Description

N/A

approval_code

String

Approval code for the sale from the processor.

N/A

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 dollar amount for the sale.

cashback_amount

Dollar amount of cashback for 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. We mask all digits except the first six and the last four.

cardholder_name

String

Name that appears on the customer’s card.

expiry_month

String

Month that the card expires in MM format.

expiry_year

String

Year that the card expires in YY format.

token

String

Unique reference for the customer's payment details that they stored on our vault.

type

String

Name of the card brand that issued the card. For a list of possible values, see the card type enumeration.

balance

String

Dollar amount that remains on the card.

postal_code

String

Postal code that the card is registered to.

rfmiq

String

Unique token that tracks the customer’s spending habits.

card_on_file_attributes

String

If our gateway was unable to create a token, this object contains error details. See the card_on_file_attributes object.

emv

amount

Object

Object that contains details about the dollar amount of the sale. See the amount object.

icc

Object

Object that contains details about the integrated circuit card (ICC). See the icc object.

Column 1	Column 2	Column 3
Field	Type	Description
amount_authorized	String	Dollar amount that was approved for the sale.
amount_other	String	Dollar amount that was cashback.

Column 1

Column 2

Column 3

Field

Type

Description

amount_authorized

String

Dollar amount that was approved for the sale.

amount_other

String

Dollar amount that was cashback.

Column 1	Column 2	Column 3
Field	Type	Description
dedicated_file_name	String	Name of the EMV Dedicated File for receipts. For more information, refer to the EMVCo website.
application_label	String	Application label for an EMV transaction.
application_expiry_date	String	Date the application expires.
application_effective_date	String	Date the application was released.
application_interchange_profile	String	Indicates the card’s functions.
application_version_number	String	Version number of the application.
application_transaction_counter	String	Application transaction counter (ATC) for an EMV transaction.
application_usage_control	String	Indicates the geographic and service restrictions that the issuer has placed on the card.
application_preferred_name	String	Name of the application in the cardholder’s local language.
application_display_name	String	Name of the application to display.
application_pan_sequence_number	String	Sequence number to identify cards with the same PAN in a transaction.
application_cryptogram	String	Application cryptogram (AC) for an EMV transaction.
application_cryptogram_type	String	Type of cryptogram that the application uses. The value is one of the following: • TC - Transaction Certificate • AAC - Application Authorization Cryptogram • ARQC - Authorization Request Cryptogram
cardholder_verification_method_results	String	Result of the last card verification.
issuer_application_data	String	Information for sending the transaction request to the issuer.
terminal_verification_results	String	Terminal verification results (TVR) for an EMV transaction.
unpredictable_number	String	Value that the terminal uses to generate a cryptogram.
pos_entry_mode	String	Indicates how the device read the card details.
terminal_type	String	Details of the terminal that sent the transaction.

Column 1

Column 2

Column 3

Field

Type

Description

dedicated_file_name

String

Name of the EMV Dedicated File for receipts. For more information, refer to the EMVCo website.

application_label

String

Application label for an EMV transaction.

application_expiry_date

String

Date the application expires.

application_effective_date

String

Date the application was released.

application_interchange_profile

String

Indicates the card’s functions.

application_version_number

String

Version number of the application.

application_transaction_counter

String

Application transaction counter (ATC) for an EMV transaction.

application_usage_control

String

Indicates the geographic and service restrictions that the issuer has placed on the card.

application_preferred_name

String

Name of the application in the cardholder’s local language.

application_display_name

String

Name of the application to display.

application_pan_sequence_number

String

Sequence number to identify cards with the same PAN in a transaction.

application_cryptogram

String

Application cryptogram (AC) for an EMV transaction.

application_cryptogram_type

String

Type of cryptogram that the application uses. The value is one of the following:
• TC - Transaction Certificate
• AAC - Application Authorization Cryptogram
• ARQC - Authorization Request Cryptogram

cardholder_verification_method_results

String

Result of the last card verification.

issuer_application_data

String

Information for sending the transaction request to the issuer.

terminal_verification_results

String

Terminal verification results (TVR) for an EMV transaction.

unpredictable_number

String

Value that the terminal uses to generate a cryptogram.

pos_entry_mode

String

Indicates how the device read the card details.

terminal_type

String

Details of the terminal that sent the transaction.

{ "amount": "0.00", "currency_code": "840", "status": "completed", "gratuity_amount": "0.00", "transactions": [ { "id": "000000001923", "entry_type": "contactless", "tender_type": "credit", "status": "approved", "status_code": "201", "processor_response": "", "reference_id": "MER-db69012b-b3e6-48fc-8510-ab55ddd6d6cf", "transaction_datetime": "2025-02-27T21:26:14.000Z", "credit_attributes": { "card": { "masked_card_number": "************4111", "type": "mastercard", "token": "KAQC1RcvdF" }, "payment": { "amount": "0.00", "type": "credit", "cashback_amount": "0.00" }, "approval_code": "MC2616", "emv": { "icc": { "cardholder_verification_method_results": "1F0302", "issuer_application_data": "0110A00003220400000000000000000000FF", "terminal_verification_results": "0400000001", "unpredictable_number": "60D01EC8", "pos_entry_mode": "07", "cryptogram_information_data": "80", "cvm_method": "none", "iac_default": "B470840000", "iac_denial": "0000000000", "iac_online": "B470848000", "authorization_response_code": "00", "dedicated_file_name": "A0000000041010", "application_label": "MasterCard", "application_interchange_profile": "1980", "application_version_number": "0002", "application_transaction_counter": "0146", "application_usage_control": "FF00", "application_preferred_name": "MasterCardCredit", "application_display_name": "MasterCardCredit", "application_cryptogram_type": "ARQC", "application_cryptogram": "FA9C3785A6BF301E", "terminal_type": "22", "terminal_country_code": "840", "tac_default": "FC509C8800", "tac_denial": "0000000000", "tac_online": "FC509C8800", "transaction_type": "00", "transaction_currency_code": "840", "transaction_status_information": "6800" }, "amount": { "amount_authorized": "0.00", "amount_other": "0.00" } } } } ] }

Policies

Connect

Additional Resources

Saving Card Details to the Vault

Endpoints

Request

processing_indicators object

Request example

Response

credit_attributes object

amount object

icc object

Response example