Guides
Start typing to search…

Transaction Types

The following transaction types are supported:

  • Sale (S): Standard purchase transaction.
  • Void (V): Cancels a previously authorized transaction.
  • Refund (R): Return/refund a previously completed transaction.
  • Refund Void (M): Cancel a previously authorized refund.
  • Auth Only (A): Authorizes funds without completing the transaction immediately.
  • Force Post (F): Used to finalize an auth-only approved transaction.
  • Pre-Authorization (P) / Completion (C): Flow for handling pre-auth and final capture.
  • Tokenize (K): Used to replace a One-Time Token - OTT with a secure, reusable 'permanent' token for future use.
  • Settlement (D): Mark the batch for deposit.

📘

Using CustomerPay

Utilize the Check UserFee call to determine the UserFee amount to be added to the transaction. Transactions will be declined if the UserFee is less than the processing cost based on the merchant's specific pricing model.

Refer to Sequence of Passing USERFEE for more information

Sale

Type:S

A Sale transaction is when you authorize and request a Draft Capture. If the transaction is successful then at settlement it will be marked for deposit into the merchant's account.

Requests

The Sale API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID ( TERMID) and Password (PASS), the type of transaction (S for Sale), the One-Time Token - OTT or Tokenized Card Data (TOKEN), the Amount (AMT ) of the transaction, and a unique Reference Number (REF).

To add additional details to the Sale, you may include additional parameters such as CUSTNAME, CUSTEMAIL, INV, and DESC.

You may also utilize our optional functionalities such as USERFEE, PLATFEE, and PLATCHRG.

Refer to Sale API Reference

# Example Sale request using Token
curl --request POST \
  --url https://svra.interpaypos.com:1443/ \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "TYPE": "S",
    "TERMID": "TEST0058",
    "PASS": "zX3Ht5va",
    "AMT": "150.00",
    "USERFEE": "3.00",
    "TOKEN": "token123456789012",
    "REF": "Ref-123456",
    "CUSTNAME": "John Doe",
    "CUSTEMAIL": "[email protected]",
    "INV": "INV00123",
    "DESC": "Summer Registration"
  }'

Response

All requests will be responded to with TEXT field and CODE field.

  • TEXT : The authorization number and amount are displayed here on an approval-type transaction. For errors and decline responses this field contains the error message or decline message. i.e. "R02564 $8.99"
  • CODE: This is the 4-digit response code from the transaction. "0000" constitutes a successful transaction, and any other 4-digit code constitutes a failure. This code should be used to check for authorization successes (0000), decline conditions (0001 - 1299), and error conditions (8000 - 9999). Refer to Errors & Troubleshooting.

All approved Sale transactions will include Tokenized Card Data (TOKEN) in the response. Additional fields returned include AUTH, HASH, GATEREF, DATE, TIME, and DUR.

//Example APPROVED response
{
  "TEXT": "R02564 $8.99",
  "CODE": "0000",
  "AUTH": "A12345",
  "TOKEN": "41100HWKWPAY00002",
  "HASH": "A4A41E8BFE8359FFC8F316EF526BD454",
  "GATEREF": "h0li4kshlsmi96", 
  "DATE": "2024-10-15",
  "TIME": "12:41:22",
  "DUR": "0.109"
}

Void

Type:V

A Void is when you remove a previously authorized transaction from the current Batch . Voided transactions do not appear on the cardholder's statement.

Voids can be used to remove Sale (S), Force Post (F), or Completion (C) transactions. It is not necessary to Void "Auth Only" (A) or "Pre-Authorization" (P) transactions since they are not marked for Draft Capture.

It is not possible to Void a transaction which has already been settled. in that case, a Refund (R) would need to be completed.

Requests

The Void API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID ( TERMID) and Password (PASS), the type of transaction (V for Void), and the Reference Number (REF) of the original transaction you are voiding.

Refer to Void API Reference

# Example Void request (JSON)
# REF = Reference number of the original transaction being voided
curl --request POST \
  --url https://svra.interpaypos.com:1443/ \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "TYPE": "V",
    "TERMID": "TEST0058",
    "PASS": "zX3Ht5va",
    "REF": "Ref-123456"
  }'

Response

All requests will be responded to with TEXT field and CODE field.

  • TEXT : "VOID OK" is displayed here when successfully voided. For errors and decline responses this field contains the error message or decline message.
  • CODE: This is the 4-digit response code from the transaction. "0000" constitutes a successful transaction, and any other 4-digit code constitutes a failure. This code should be used to check for authorization successes (0000), decline conditions (0001 - 1299), and error conditions (8000 - 9999). Refer to Errors & Troubleshooting.

Additional fields returned include AUTH, HASH, GATEREF, DATE, TIME, and DUR.

//Example APPROVED response
{
  "TEXT": "VOID OK",
  "CODE": "0000",
  "AUTH": "A12345",
  "TOKEN": "41100HWKWPAY00002",
  "HASH": "A4A41E8BFE8359FFC8F316EF526BD454",
  "GATEREF": "h0li4kshlsmi96", 
  "DATE": "2024-10-15",
  "TIME": "12:41:22",
  "DUR": "0.109"
}

Refund

Type:R

Return money to the customer's card. The card is not affected at all until deposit, at which time the card will be credited for the returned amount.

Note: The effect on the card is not immediate - it can take 7-10 business days in some cases for the card's open-to-buy limit to be updated. This is largely dependent on the credit card Issuer. The merchant account will be debited before the cardholder receives their refund.

Requests

The Refund API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID ( TERMID) and Password (PASS), the type of transaction (R for Sale), the One-Time Token - OTT or Tokenized Card Data (TOKEN), the Amount (AMT ) that should be refunded, and a unique Reference Number (REF).

To add additional details to the Refund, you may include additional parameters such as CUSTNAME, CUSTEMAIL, INV, and DESC.

Refer to Refund API Reference

# Example Refund with Token request 
curl --request POST \
  --url https://svra.interpaypos.com:1443/ \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "TYPE": "R",
    "TERMID": "TEST0058",
    "PASS": "zX3Ht5va",
    "AMT": "150.00",
    "TOKEN": "4000HWKWPAY00002",
    "REF": "Ref-123456"
  }'

Response

All requests will be responded to with TEXT field and CODE field.

  • TEXT : The authorization number and the word "RETURN" is displayed here when successfully refunded. For errors and decline responses this field contains the error message or decline message. i.e. "RETURN A12345"
  • CODE: This is the 4-digit response code from the transaction. "0000" constitutes a successful transaction, and any other 4-digit code constitutes a failure. This code should be used to check for authorization successes (0000), decline conditions (0001 - 1299), and error conditions (8000 - 9999). Refer to Errors & Troubleshooting.

All approved Refund with Card transactions will include Tokenized Card Data (TOKEN) in the response. Additional fields returned include AUTH, HASH, GATEREF, DATE, TIME, and DUR.

//Example APPROVED response
{
  "TEXT": "RETURN A12345",
  "CODE": "0000",
  "AUTH": "A12345",
  "TOKEN": "41100HWKWPAY00002",
  "HASH": "A4A41E8BFE8359FFC8F316EF526BD454",
  "GATEREF": "h0li4kshlsmi96", 
  "DATE": "2024-10-15",
  "TIME": "12:41:22",
  "DUR": "0.109"
}

Refund Void

Type:M

Remove a previously sent Refund (R) from the batch. This has the effect of cancelling a Refund. This can only be done if the batch has not been settled, and therefore, the customer's card is not affected, and neither transaction will appear on their statement.

Requests

The Refund Void API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID ( TERMID) and Password (PASS), the type of transaction (M for Refund Void), and the Reference Number (REF) of the original transaction you are voiding.

Refer to Refund Void API Reference

# Example Refund Void request
# REF = Reference number of the original Refund you are voiding
curl --request POST \
  --url https://svra.interpaypos.com:1443/ \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "TYPE": "M",
    "TERMID": "TEST0058",
    "PASS": "zX3Ht5va",
    "REF": "Ref-123456"
  }'

Response

All requests will be responded to with TEXT field and CODE field.

  • TEXT : " VOID OK" is displayed here when successfully voided. For errors and decline responses this field contains the error message or decline message.
  • CODE: This is the 4-digit response code from the transaction. "0000" constitutes a successful transaction, and any other 4-digit code constitutes a failure. This code should be used to check for authorization successes (0000), decline conditions (0001 - 1299), and error conditions (8000 - 9999). Refer to Errors & Troubleshooting.

Additional fields returned include AUTH, HASH, GATEREF, DATE, TIME, and DUR.

//Example APPROVED response
{
  "TEXT": "VOID OK",
  "CODE": "0000",
  "AUTH": "A12345",
  "TOKEN": "41100HWKWPAY00002",
  "HASH": "A4A41E8BFE8359FFC8F316EF526BD454",
  "GATEREF": "h0li4kshlsmi96", 
  "DATE": "2024-10-15",
  "TIME": "12:41:22",
  "DUR": "0.109"
}

Authorize Only

Type:A

Authorize but do not request Draft Capture. If this transaction is successful, the card's "open to buy" will be reduced, but the transaction will not be marked for deposit at settlement.

If you use this transaction type, you can Force Post (F) the transaction to cause Draft Capture.

Requests

The Auth Only API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID ( TERMID) and Password (PASS), the type of transaction (A for Auth Only), the One-Time Token - OTT or Tokenized Card Data (TOKEN), the Amount (AMT ) of the transaction, and a unique Reference Number (REF).

To add additional details to the transaction, you may include additional parameters such as CUSTNAME, CUSTEMAIL, INV, and DESC.

You may also utilize our optional functionalities such as USERFEE, PLATFEE, and PLATCHRG.

Refer to Authorize Only API Reference

# Example Auth Only request using Token
curl --request POST \
  --url https://testgate.interpaypos.com/api/ \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "TYPE": "A",
    "TERMID": "TEST0058",
    "PASS": "zX3Ht5va",
    "AMT": "150.00",
    "TOKEN": "token123456789012",
    "REF": "Ref-123456",
    "CUSTNAME": "John Doe",
    "CUSTEMAIL": "[email protected]",
    "INV": "INV00123",
    "DESC": "Summer Registration",
    "USERFEE": "3.00"
  }'

Response

All requests will be responded to with TEXT field and CODE field.

  • TEXT : The authorization number and amount are displayed here on an approval-type transaction. For errors and decline responses this field contains the error message or decline message. i.e. "R02564 $8.99"
  • CODE: This is the 4-digit response code from the transaction. "0000" constitutes a successful transaction, and any other 4-digit code constitutes a failure. This code should be used to check for authorization successes (0000), decline conditions (0001 - 1299), and error conditions (8000 - 9999). Refer to Errors & Troubleshooting..

All approved Auth with Card transactions will include Tokenized Card Data (TOKEN) in the response. Additional fields returned include AUTH, HASH, GATEREF, DATE, TIME, and DUR.

//Example APPROVED response
{
  "TEXT": "R02564 $8.99",
  "CODE": "0000",
  "AUTH": "A12345",
  "TOKEN": "41100HWKWPAY00002",
  "HASH": "A4A41E8BFE8359FFC8F316EF526BD454",
  "GATEREF": "h0li4kshlsmi96", 
  "DATE": "2024-10-15",
  "TIME": "12:41:22",
  "DUR": "0.109"
}

Force Post

Type:F

Submit a transaction for Draft Capture for which you have previously obtained an authorization.
Using this transaction you can collect the funds for a previous Auth Only (A) or Pre-Authorization (P), however, for Pre-Auths (P) it is better to use the Completion (C) transaction.

Requests

The Force Post API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID ( TERMID) and Password (PASS), the type of transaction (F for Force Post), the One-Time Token - OTT or Tokenized Card Data (TOKEN), the Amount (AMT ) of the transaction, the Authorization Number (AUTH) of the transaction you are Force Posting, and a unique Reference Number (REF).

Refer to Force Post API Reference

# Example Force Post request using Token
# AUTH = Authorization number from the original Auth Only transaction
curl --request POST \
  --url https://svra.interpaypos.com:1443/ \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "TYPE": "F",
    "TERMID": "TEST0058",
    "PASS": "zX3Ht5va",
    "AMT": "150.00",
    "AUTH": "A12345",
    "TOKEN": "token123456789012",
    "REF": "Ref-123456"
  }'

Response

All requests will be responded to with TEXT field and CODE field.

  • TEXT : The authorization number and amount are displayed here on an approval-type transaction. For errors and decline responses this field contains the error message or decline message. i.e. "R02564 $8.99"
  • CODE: This is the 4-digit response code from the transaction. "0000" constitutes a successful transaction, and any other 4-digit code constitutes a failure. This code should be used to check for authorization successes (0000), decline conditions (0001 - 1299), and error conditions (8000 - 9999). Refer to Errors & Troubleshooting.

Additional fields returned include AUTH, HASH, GATEREF, DATE, TIME, and DUR.

{
  "TEXT": "FORCE POST OK",
  "CODE": "0000",
  "TOKEN": "4000HWKWPAY00002",
  "HASH": "A4A41E8BFE8359FFC8F316EF526BD454",
  "GATEREF": "h0li4kshlsmi96", 
  "DATE": "2024-10-21",
  "TIME": "10:32:02",
  "DUR": "0.129"
}

Pre-Authorization

Type:P

Authorize but do not request Draft Capture. If this transaction is successful, the card's "open to buy" will be reduced, but the transaction will not be marked for draft capture.

If you use this transaction type, you can use a Completion (C) transaction in order to cause draft capture.

Requests

The Pre-Authorization API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID ( TERMID) and Password (PASS), the type of transaction (P for Pre-Authorization), the One-Time Token - OTT or Tokenized Card Data (TOKEN), the Amount (AMT ) of the transaction, and a unique Reference Number (REF).

To add additional details to the transaction, you may include additional parameters such as CUSTNAME, CUSTEMAIL, INV, and DESC.

You may also utilize our optional functionalities such as USERFEE, PLATFEE, and PLATCHRG.

Refer to Pre-Authorization API Reference

# Example Pre-Authorization with Token request
curl --request POST \
  --url https://svra.interpaypos.com:1443/ \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "TYPE": "P",
    "TERMID": "TEST0058",
    "PASS": "zX3Ht5va",
    "AMT": "150.00",
    "TOKEN": "TOKEN1234567",
    "REF": "Ref-123456"
  }'

Response

All requests will be responded to with TEXT field and CODE field.

  • TEXT : The authorization number and amount are displayed here on an approval-type transaction. For errors and decline responses this field contains the error message or decline message. i.e. "R02564 $8.99"
  • CODE: This is the 4-digit response code from the transaction. "0000" constitutes a successful transaction, and any other 4-digit code constitutes a failure. This code should be used to check for authorization successes (0000), decline conditions (0001 - 1299), and error conditions (8000 - 9999). Refer to Errors & Troubleshooting.

All approved Pre-Auth with Card transactions will include Tokenized Card Data (TOKEN) in the response. Additional fields returned include AUTH, HASH, DATE, TIME, and DUR.

//Example APPROVED response
{
  "TEXT": "VOID OK",
  "CODE": "0000",
  "AUTH": "A12345",
  "TOKEN": "41100HWKWPAY00002",
  "HASH": "A4A41E8BFE8359FFC8F316EF526BD454",
  "DATE": "2024-10-15",
  "TIME": "12:41:22",
  "DUR": "0.109"
}

Completion

Type:C

Submit a previously Pre-Authorized (P) transaction for Draft Capture. There must be a corresponding Pre-Authorization transaction in the past 7 days in order to use this transaction type.

Another useful feature is the ability to perform partial Completions. If you send a lesser amount in the Completion than you sent in the Pre-Authorization (P), the system will deduct that amount from the amount outstanding on the Pre-Authorization (P).

Requests

The Completion API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID ( TERMID) and Password (PASS), the type of transaction (C for Completion), the Amount (AMT ) of the transaction, and the Reference Number (REF) of the original Pre-Authorization that you are completing.

Refer to Completion API Reference

# Example Completion request
# REF = Reference number from the Pre-Authorized transaction you are completing
curl --request POST \
  --url https://svra.interpaypos.com:1443/ \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "TYPE": "C",
    "TERMID": "TEST0058",
    "PASS": "zX3Ht5va",
    "AMT": "150.00",
    "REF": "Ref-123456"
  }'

Response

All requests will be responded to with TEXT field and CODE field.

  • TEXT : 'COMPL OK' is displayed here when successfully voided. For errors and decline responses this field contains the error message or decline message.
  • CODE: This is the 4-digit response code from the transaction. "0000" constitutes a successful transaction, and any other 4-digit code constitutes a failure. This code should be used to check for authorization successes (0000), decline conditions (0001 - 1299), and error conditions (8000 - 9999). Refer to Errors & Troubleshooting.

All approved Completion transactions will include Tokenized Card Data (TOKEN) in the response. Additional fields returned include AUTH, HASH, GATEREF, DATE, TIME, and DUR.

//Example APPROVED response
{
  "TEXT": "COMPL OK",
  "CODE": "0000",
  "AUTH": "A12345",
  "TOKEN": "41100HWKWPAY00002",
  "HASH": "A4A41E8BFE8359FFC8F316EF526BD454",
  "GATEREF": "h0li4kshlsmi96", 
  "DATE": "2024-10-15",
  "TIME": "12:41:22",
  "DUR": "0.109"
}

Tokenize

Type:K

Tokenize the card data and verify the account.

The Tokenization API Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID ( TERMID) and Password (PASS), the type of transaction (K for Tokenize), the One-Time Token - OTT (OTT ), and a unique Reference Number (REF).

Refer to Tokenization API Reference

# Example Tokenize request
curl --request POST \
  --url https://svra.interpaypos.com:1443/ \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "TYPE": "K",
    "TERMID": "TEST0058",
    "PASS": "zX3Ht5va",
    "OTT": "4200HDETSHGT0042",
    "REF": "Ref-123456"
  }'

Response

All requests will be responded to with TEXT field and CODE field.

  • TEXT : "TOKEN OK" is displayed here when successfully voided. For errors and decline responses this field contains the error message or decline message.
  • CODE: This is the 4-digit response code from the transaction. "0000" constitutes a successful transaction, and any other 4-digit code constitutes a failure. This code should be used to check for authorization successes (0000), decline conditions (0001 - 1299), and error conditions (8000 - 9999). Refer to Errors & Troubleshooting.

All approved Tokenize transactions will include Tokenized Card Data (TOKEN). Additional fields returned include HASH, GATEREF, DATE, TIME, and DUR.

//Example APPROVED response
{
  "TEXT": "TOKEN OK",
  "CODE": "0000",
  "TOKEN": "41100HWKWPAY00002",
  "HASH": "A4A41E8BFE8359FFC8F316EF526BD454",
  "GATEREF": "h0li4kshlsmi96", 
  "DATE": "2024-10-15",
  "TIME": "12:41:22",
  "DUR": "0.109"
}

Settlement

Type:D

Marks the batch for deposit and clears the totals. Auto-settled customers should never use this transaction type since it will cause incorrect reporting and difficulty in reconciliation.

By default, all merchants are setup as auto-settle.

Requests

The Settlement Reference outlines the required and optional parameters needed for your request. The minimum required information in your request includes the merchants Terminal ID( TERMID) and Password (PASS) , and the type of transaction (D for Settlement).

Refer to Settlement API Reference

# Example Settlement request
curl --request POST \
  --url https://svra.interpaypos.com:1443/ \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "TYPE": "D",
    "TERMID": "TEST0058",
    "PASS": "zX3Ht5va"
  }'

Response

All requests will be responded to with TEXT field and CODE field.

  • TEXT : Will display "SETTLED" followed by the total amount that was settled. i.e. "SETTLED $115.00"
  • CODE: This is the 4-digit response code from the transaction. "0000" constitutes a successful transaction, and any other 4-digit code constitutes a failure. This code should be used to check for authorization successes (0000), decline conditions (0001 - 1299), and error conditions (8000 - 9999). Refer to Errors & Troubleshooting.

Additional fields returned include HASH, GATEREF, DATE, TIME, and DUR.

//Example APPROVED response
{
  "TEXT": "SETTLED $115.00",
  "CODE": "0000",
  "GATEREF": "h0li4kshlsmi96", 
  "DATE": "2024-10-15",
  "TIME": "12:41:22",
  "DUR": "0.109"
}

Updated 4 months ago