> For the complete documentation index, see [llms.txt](https://developer.convergegate.com/legacy/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.convergegate.com/legacy/card-server-to-server/api-commands/701-request-capture-authorization.md).

# 701 – Request Capture Authorization

## 701 Request Data description:

<table data-full-width="false"><thead><tr><th>NODE</th><th>INCLUDE IN CHECKSUM (IN THIS ORDER)</th><th>REQUIRED</th><th>DATA TYPE</th><th>DESCRIPTION</th></tr></thead><tbody><tr><td>apiUser</td><td>YES (1)</td><td>YES</td><td>Character max 50.</td><td>The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.</td></tr><tr><td>apiPassword</td><td>YES (2)</td><td>YES</td><td>Character max 50.</td><td>The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.</td></tr><tr><td>apiCmd</td><td>YES (3)</td><td>YES</td><td>701</td><td>3 digit numeric transaction code must be 701</td></tr><tr><td>gatetransid</td><td>YES (4)</td><td>YES</td><td>Character max 50.</td><td>Unique gateway internal transaction id, received by the merchant in the 850 Notification of the originating transaction.</td></tr><tr><td>amount</td><td></td><td>Opt</td><td>Number with point decimal</td><td>Optionally may be Required, depending on setting in Merchant Profile. Will be in currency of the original authorization transaction. The amount for capture may not exceed the amount in the authorized transaction. Decimal separator must be point (.). example: 125.45 = One hundred and twenty-five Major Currency Units with forty-five Minor Currency Units.</td></tr><tr><td>carrier</td><td></td><td>Opt</td><td>Character max 50.</td><td>Optionally may be Required, depending on setting in Merchant Profile. Must be one of the following: USPS, FedEx, UPS, DHL, Canada, TNT</td></tr><tr><td>trackingnumber</td><td></td><td>Opt</td><td>Character max 100.</td><td>Optionally may be Required, depending on setting in Merchant Profile. This is the tracking number provided by the carrier</td></tr><tr><td>checksum</td><td></td><td>YES</td><td>Character no limit</td><td>SHA-1 calculated using the fields specified by the transaction plus the API key assigned by gateway to the merchant. This field must be calculated using the fields marked as “Include in checksum” (in the order indicated) plus the API key at the end.</td></tr></tbody></table>

## 701 Response Data description

| NODE         | REQUIRED | DATA TYPE          | DESCRIPTION                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | -------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| result       | YES      | Character          | Result indicates the result of the transaction. SUCCESS: Transaction has been Captured PENDING: Request for Capture has been accepted but yet processed. (Can happen in case of transactions which need to be confirmed by staff or when tracking number provided). After the Capture has been processed, the results will be sent in the 850 Transaction State Notification that will be sent from the system server to the merchant server. Do NOT ASSUME the pending request as APPROVED or DECLINED. ERROR: means error detected in the request, no processing takes place, and transaction was not accepted by the system. |
| gatetransid  | YES      | Character max 50.  | Unique gateway internal transaction id refers to Authorized transaction for which the Capture has been requested.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| errorcode    | YES      | Character 3        | Error Code of the transaction or 000 if no error condition found.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| errormessage | YES      | Character max 100  | Full description of the error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| description  | OPT      | Character no limit | Optional details of the transaction except in the case of DECLINED and then the reason for the decline. May be null.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

## Creating users

{% tabs %}
{% tab title="CURL" %}

The 701 request is plain XML that contains the following data:

```
  <?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<apiUser> </apiUser>
		<apiPassword> </apiPassword>
		<apiCmd> </apiCmd>
		<gatetransid> </gatetransid>
		<amount> </amount>
		<carrier> </carrier>
		<trackingnumber> </trackingnumber>
		<checksum> </checksum>		
	</transaction> 
							  
```

The response to a 701 - Request Capture Authorization is plain xml un-encoded that contains the following data:

```

	<?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<result> </result>
		<merchanttransid> </merchanttransid>
		<gatetransid> </gatetransid>
		<errorcode> </errorcode>
		<errormessage> </errormessage>
		<description> </description>
	</transaction> 
```

{% endtab %}

{% tab title="PHP" %}
The 701 request is PHP that contains the following data:

```
  require_once 'autoload.php';

use Omnipay\GPNDataEurope\GPNGateway;
set_time_limit(0);

$gpnGateway = new GPNGateway();
$gpnGateway->setApiKey('APIKEY');
$gpnGateway->setApiPassword('APIPASS');
$gpnGateway->setApiUser('APIUSER');
$gpnGateway->setMode(GPNGateway::PROD_MODE);
$gpnGateway->setPROD('https://txtest.txpmnts.com/api/transaction/');


$params = [
	'gateTransId' => 'F1CD74B9-E94B-1877-DB9F-4A44B82D04EC',
	'amount' => '10.00',
	'carrier' => '',
    'trackingNumber' => '',	
];

try {
	// Capture 701
	$response = $gpnGateway->capture($params)->send();
	printf("%s-%s\n", $response->getCode(), $response->getMessage());
	
echo 'GPN Ref. No : '; print_r($response->getData()->getrefer());
echo 'Description : '; print_r($response->getData()->getmessage());
echo 'Merchant Transaction ID : '; print_r($response->getData()->getmerchantTransId());
echo 'Status : '; print_r($response->getData()->getstatus());
echo 'Status Code : '; print_r($response->getData()->getstatusCode());
echo 'Gateway Transaction ID : '; print_r($response->getData()->gettransId());


} catch (Exception $exc) {
	print_r($exc->getCode(), $exc->getMessage());
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.convergegate.com/legacy/card-server-to-server/api-commands/701-request-capture-authorization.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.