Sale

Overview

This page will show you how to initiate a sale transaction, whether it be via credit/debit card, check, or cash. The API endpoint below encapsulates all of these use cases related to sales. One specifies what type of sale is being performed via the command parameter. Note that while this allows for great flexibility on the user-facing API, this one endpoint may accept/reject certain parameters based on the type of sale being performed. Please refer to the typical use cases at the bottom for specific implementation details.

The API endpoint is as follows:

POST /api/v2/transactions

Quick Start

Request

curl -X POST https://sandbox.newtekgateway.com/api/v2/transactions
    -H "Content-Type: application/json"
    -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
    -d
    '{
    "command": "cc:sale",
    "amount": "5.00",
    "amount_detail": {
        "tax": "1.00",
        "tip": "0.50"
    },
    "creditcard": {
        "cardholder": "John Doe",
        "number": "4000100011112224",
        "expiration": "0919",
        "cvc": "123",
        "avs_street": "1234 Main",
        "avs_zip": "12345"
    },
    "invoice": "12356"
    }'

This cURL request is an example of a merchant who is trying to charge a customer via a credit card sale.

Response

{
  "type": "transaction",
  "key": "bnf17whjvqqpj2s",
  "refnum": "124444201",
  "is_duplicate": "N",
  "result_code": "A",
  "result": "Approved",
  "authcode": "147598",
  "creditcard": {
    "number": "4000xxxxxxxx2224",
    "category_code": "A"
  },
  "invoice": "12356",
  "avs": {
    "result_code": "YYY",
    "result": "Address: Match & 5 Digit Zip: Match"
  },
  "cvc": {
    "result_code": "M",
    "result": "Match"
  },
  "batch": {
    "type": "batch",
    "key": "0t1k3yx5xs37cvb",
    "sequence": "1"
  },
  "auth_amount": "5"
}

This is the sample response object sent back from the server.

Request Parameters

This is a complete overview of the request parameters that are sent. Note that each command type may only accept a subset of the parameters.

Parameter Name	Type	Description
Command	string	This specified the type of transaction to run. Look here for the list of supported commands.
Amount	double	Total transaction amount (Including tax, tip, shipping, etc.)
creditcard*	object	Object which holds all credit card information
check**	object	Object which holds all check information
payment_key	string	One time token created when using the Client JS Library.
save_card	bool	Set to true to tokenize card.
currency	string	Currency numerical code. Full list of supported numerical currency codes can be found here. Defaults to 840 (USD).
customerid	string	Merchant assigned customer ID
invoice	string	Custom Invoice Number to easily retrieve sale details. (11 chars max)
ponum	string	Customer's purchase order number (required for level 3 processing)
orderid	string	Merchant assigned order ID
description	string	Public description of the transaction.
comments	string	Private comment details only visible to the merchant.
terminal	string	Terminal identifier (i.e. multilane)
table	integer	Restaurant table number
clerk	string	Clerk/Cashier/Server name
email	string	Customer's email address
send_receipt	bool	If set, this parameter will send an email to the email passed in the request.3
terminal_detail	object	Details on the type of terminal
amount_detail	object	Object containing a more detailed breakdown of the amount. Not required if Amount is previously set.
billing_address	object	Object which holds the billing address information.
shipping_address	object	Object which holds the shipping address information.
traits	object	Object which holds transaction characteristics.
clientip	string	IP address of client. Used in conjunction with the Block By Host or IP fraud module.
geolocation	string	Latitude and longitude of transaction location.
software	string	Software name and version (useful for troubleshooting)
ignore_duplicate	bool	Set to true to Bypass duplicate detection/folding.

* Required field for credit card transactions

** Required field for check transactions

Response Variables

Variable	Type	Description
type	string	The type of sale performed. Successful sales return a value of 'transaction'.
key	string	Unique key for the transaction record
refnum	string	Transaction reference number
is_duplicate	bool	If Y, a duplicate transaction was detected. The system is showing the response from the original transaction, rather than running a duplicate.
result_code	string	Result code ('A' = Approved, 'P' = Partial Approval, 'D' = Declined, 'E' = Error, or 'V' = Verification Required)
result	string	Long version of above result_code ('Approved', etc)
authcode	string	Authorization code
auth_amount	double	Amount authorized
avs	object	Object which contains the verification status of the AVS response system
cvc	object	Object which contains the status of the Card Security Code (the 3-4 check digit on a credit card)

Sample Code

List of available sale commands

Credit Card	Check	Cash
cc:sale	check:sale	cash:sale

Credit Card Sale

To make a credit card sale:

curl -X POST https://sandbox.newtekgateway.com/api/v2/transactions
    -H "Content-Type: application/json"
    -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
    -d
    '{
    "command": "cc:sale",
    "amount": "5.00",
    "amount_detail": {
        "tax": "1.00",
        "tip": "0.50"
    },
    "creditcard": {
        "cardholder": "John Doe",
        "number": "4000100011112224",
        "expiration": "0919",
        "cvc": "123",
        "avs_street": "1234 Main",
        "avs_zip": "12345"
    },
    "invoice": "12356"
    }'

This cURL request is an example of a merchant who is trying to charge a customer via a credit card sale.

{
  "type": "transaction",
  "key": "bnf17whjvqqpj2s",
  "refnum": "124444201",
  "is_duplicate": "N",
  "result_code": "A",
  "result": "Approved",
  "authcode": "147598",
  "creditcard": {
    "number": "4000xxxxxxxx2224",
    "category_code": "A"
  },
  "invoice": "12356",
  "avs": {
    "result_code": "YYY",
    "result": "Address: Match & 5 Digit Zip: Match"
  },
  "cvc": {
    "result_code": "M",
    "result": "Match"
  },
  "batch": {
    "type": "batch",
    "key": "0t1k3yx5xs37cvb",
    "sequence": "1"
  },
  "auth_amount": "5"
}

This is the sample response object sent back from the server.

Check Sale

To make a check sale:

curl -X POST https://sandbox.newtekgateway.com/api/v2/transactions
    -H "Content-Type: application/json"
    -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
    -d
    '{
    "command": "check:sale",
    "amount": "5.00",
    "amount_detail": {
        "tax": "1.00",
        "tip": "0.50"
    },
    "check": {
        "accountholder": "John Doe",
        "account": "324523524",
        "routing": "123456789"
    },
    "invoice": "12356"
}'

This cURL request is an example of a merchant who is trying to charge a customer via a check sale.

{
  "type": "transaction",
  "key": "3nf18vbrqpp32ts",
  "refnum": "124444297",
  "is_duplicate": "N",
  "result_code": "A",
  "result": "Approved",
  "authcode": "TM4054",
  "invoice": "12356",
  "proc_refnum": "17062698499437"
}

This is the sample response object sent back from the server.

Payment Key Sale

If processing using the Client JS Library, you can also process a sale with a payment_key in place of a card number. The payment_key is a one time use token. To create a reusable token, set the save_card flag to true.

curl -X POST https://sandbox.newtekgateway.com/api/v2/transactions
    -H "Content-Type: application/json"
    -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
    -d
    '{
    "command": "cc:sale",
        "payment_key": "02zxfg87ty824",
    "amount": "1124.25",
    "amount_detail": {
        "tax": "0.00",
        "subtotal": "1124.25"
    },
    "billing_address": {
        "firstname": "John",
        "lastname": "Jones",
        "street": "1234 Main",
        "street2": "Apt 123",
        "city": "Spring",
                "state": "TX",
                "postalcode": "77379",
                "country": "USA",
                "phone": "5558675309",
        "email": "12345"
    },
    "custemailaddr": "john@tmcode.com"
    }'

This cURL request is an example of a merchant who is trying to charge a customer via a payment key.

{
  "type": "transaction",
  "key": "bnf17whjvqqpj2s",
  "refnum": "124444201",
  "is_duplicate": "N",
  "result_code": "A",
  "result": "Approved",
  "authcode": "147598",
  "creditcard": {
    "number": "4000xxxxxxxx2224",
    "category_code": "A"
  },
  "avs": {
    "result_code": "YYY",
    "result": "Address: Match & 5 Digit Zip: Match"
  },
  "cvc": {
    "result_code": "M",
    "result": "Match"
  },
  "batch": {
    "type": "batch",
    "key": "0t1k3yx5xs37cvb",
    "sequence": "1"
  },
  "auth_amount": "1124.25"
}

This is the sample response object sent back from the server.

Cash Sale

To make a cash sale:

curl -X POST https://sandbox.newtekgateway.com/api/v2/transactions
    -H "Content-Type: application/json"
    -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
    -d
    '{
    "command": "cash:sale",
    "amount": "5.00",
    "amount_detail": {
        "tax": "1.00",
        "tip": "0.50"
    }
}'

This cURL request is an example of a merchant who is trying to charge a customer via a cash sale.

{
  "type": "transaction",
  "key": "nnf4ktszxfk0f2y",
  "refnum": "124444369",
  "is_duplicate": "N",
  "result_code": "A",
  "result": "Approved",
  "authcode": ""
}

This is the sample response object sent back from the server.

Change Log

Date	Change
2017-08-01	Added page.
2017-11-29	Added is_final parameter.

Click here for the full REST API change log.