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.usaepay.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.usaepay.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.usaepay.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.usaepay.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.usaepay.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.usaepay.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.usaepay.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.