Capture/Adjust

Overview

The capture command moves an authorized transaction into the current batch for settlement. It is possible to capture an amount other than the one originally authorized, however, you must follow the guidelines established by the merchant service bank. Capturing a higher or lower dollar amount could result in additional penalties and fees.

Most banks typically allow no more than 10 days to pass between the authorization/capture and settlement of a transaction.

If you do not wish to capture a previously authorized transaction, you may void the original authorization rather than capturing a 0 dollar amount, or simply allow the captured transaction to time out.

The adjust command allows you to make changes to an existing (unsettled) sale. The authorization amount can be increased (incremental authorization) or decreased (partial reversal) or not changed. Additional data elements such as tax amount and po number can be added. The tolerances for the settle amount vary depending on the type of Merchant Account and the merchant service provider. The adjust and capture commands function identically except that the adjust command does not place the transaction in the batch.

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:capture",
    "refnum": "21725966"
}'

This cURL request is an example of how to perform a capture.

Response

{  
   "type":"transaction",
   "key":"2nfmpckztbq6pw5",
   "refnum":"21725966",
   "is_duplicate":"N",
   "result_code":"A",
   "result":"Approved",
   "authcode":"001745",
   "batch":{  
      "type":"batch",
      "key":"0t1hkmb63g4h968",
      "sequence":"2"
   },
   "auth_amount":"14.00"
}

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.
refnum number This is the 8-digit transaction id of the sale you wish to capture/adjust
amount string/double This is an optional quantity, which can alter the transaction amount.

Response Variables

Variable Type Description
type string The type of sale performed. Successful sales return a value of 'transaction'.
key integer Unique key for the transaction record
refnum integer Transaction reference number
is_duplicate char(Y/N) If Y, a duplicate transaction was detected. The system is showing the response from the original transaction, rather than running a duplicate.
result_code char 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 integer Authorization code
batch object Object which contains the information associated with the batch that the transaction belongs to.
auth_amount double The amount authorized

Sample Code

List of available capture/adjust commands

Capture Capture Error Capture Reauth Capture Override Adjust Refund Adjust
cc:capture cc:capture:error cc:capture:reauth cc:capture:override cc:adjust refund:adjust

Capture

To capture a transaction:

curl -X POST https://sandbox.newtekgateway.com/api/v2/transactions
    -H "Content-Type: application/json"
    -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
    -d
    '{
    "command": "cc:capture",
    "refnum": "21726773"
}'

This cURL request is an example of a merchant who is trying to capture a transaction.

{
   "type": "transaction",
   "key": "3nftd99sr41zgq3",
   "refnum": "21726773",
   "is_duplicate": "N",
   "result_code": "A",
   "result": "Approved",
   "authcode": "001282",
   "batch": {
      "type": "batch",
      "key": "0t1jyndn769q1vb",
      "sequence": "1"
   },
   "auth_amount": "100.00"
}

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

Capture Error

Captures a transaction. If the authorization has expired, the command will throw an error.

curl -X POST https://sandbox.newtekgateway.com/api/v2/transactions
  -H "Content-Type: application/json"
  -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
  -d 
    '{ 
    "command": "cc:capture:error",
    "refnum": "21726795" 
}''

This cURL request is an example of a merchant who is trying to capture a transaction.

{
   "type": "transaction",
   "key": "pnfkgynn1244pvs",
   "refnum": "21726795",
   "is_duplicate": "N",
   "result_code": "A",
   "result": "Approved",
   "authcode": "001287",
   "batch": {
      "type": "batch",
      "key": "0t1jyndn769q1vb",
      "sequence": "1"
   },
   "auth_amount": "100.00"
}

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

Capture Reauth

Developers can capture transactions using the cc:capture:reauth command. If the authorization has not expired, it will place the transaction in the batch for settlement. If the authorization has expired, it will attempt to reauthorize the same card. The developer does not need to know the state of the transaction ahead of time.

curl -X POST https://sandbox.newtekgateway.com/api/v2/transactions
    -H "Content-Type: application/json"
    -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
   -d 
    '{ 
    "command": "cc:capture:reauth",
    "refnum": "21726791" 
}''

This cURL request is an example of a merchant who is trying to capture a transaction, potentially reauthorizing the card.

{
   "type": "transaction",
   "key": "lnfy6b2x1v3kzg0",
   "refnum": "21726791",
   "is_duplicate": "N",
   "result_code": "A",
   "result": "Approved",
   "authcode": "001285",
   "batch": {
      "type": "batch",
      "key": "0t1jyndn769q1vb",
      "sequence": "1"
   },
   "auth_amount": "100.00"
}

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

Capture Override

We do not allow setting the expiration time to longer that 30 days. We do however, have a “cc:capture:override” command that will force a capture, even if the authorization has exceeded the maximum 30 days. We would not recommend capturing transactions over 60 days due to the charge back risk.

curl -X POST https://sandbox.newtekgateway.com/api/v2/transactions
  -H "User-Agent: uelib v6.8"
  -H "Content-Type: application/json"
  -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
  -d 
    '{ 
    "command": "cc:capture:override",
    "refnum": "21726794" 
}'

This cURL request is an example of a merchant who is trying to capture a transaction, potentially overriding authorization.

{
   "type": "transaction",
   "key": "onfkpzd7ssg8cy0",
   "refnum": "21726794",
   "is_duplicate": "N",
   "result_code": "A",
   "result": "Approved",
   "authcode": "002045",
   "batch": {
      "type": "batch",
      "key": "0t1jyndn769q1vb",
      "sequence": "1"
   },
   "auth_amount": "100.00"
}

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

Adjust

To adjust a transaction:

curl -X POST https://sandbox.newtekgateway.com/api/v2/transactions
    -H "Content-Type: application/json"
    -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
    -d
    '{ 
    "command": "cc:adjust",
    "refnum": "21726798", 
    "amount" : "3.00" 
}'

This cURL request is an example of a merchant who is trying to adjust a transaction.

{
   "type": "transaction",
   "key": "2nfmnj4fxj13b3q",
   "refnum": "21726798",
   "is_duplicate": "N",
   "result_code": "A",
   "result": "Approved",
   "authcode": "002048",
   "batch": {
      "type": "batch",
      "key": "0t1jyndn769q1vb",
      "sequence": "1"
   },
   "auth_amount": "3.00"
}

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

Refund Adjust

Interchangable with the command cc:refund:adjust. If the authorization has not settled yet, it will adjust the authorization amount down by the inputted amount (releasing funds back to the card holder in realtime). If the authorization has settled, a credit transaction will be submitted.

curl -X POST https://sandbox.newtekgateway.com/api/v2/transactions
  -H "Content-Type: application/json"
  -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
  -d
  '{
    "command": "refund:adjust",
    "refnum": "21726766", \
    "amount" : "3.00"
}'

This cURL request is an example of a merchant who is trying to adjust or refund a transaction.

{
   "type": "transaction",
   "key": "mnfky8s1mz0gmbd",
   "refnum": "21726766",
   "is_duplicate": "N",
   "result_code": "A",
   "result": "Approved",
   "authcode": "002035",
   "batch": {
      "type": "batch",
      "key": "0t1jyndn769q1vb",
      "sequence": "1"
   },
   "auth_amount": "97.00"
}

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

Common Errors

Transaction has already been settled.

If you attempt to capture a transaction that has been settled, you will get the following response.

{
   "type": "transaction",
   "key": "",
   "refnum": "",
   "is_duplicate": "N",
   "result_code": "E",
   "result": "Error",
   "error": "Transactions has already been settled.",
   "error_code": "10126"
}

Change Log

Date Change
2017-08-01 Added page.
2018-03-14 Corrected transid to refnum.

Click here for the full REST API change log.