> 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/700-start-credit-card-charge-3ds-enabled.md).

# 700 – Start Credit Card charge (3DS Enabled)

Allows the merchant to submit a charge to the cardholder’s Credit Card and includes 3DS capability when 3DS is specified in the Merchant Agreement. (See Appendix for “3DS Explanation”).

## 700 Request Data description:

<table data-full-width="false"><thead><tr><th width="161">NODE</th><th width="108">INCLUDE IN CHECKSUM (IN THIS ORDER)</th><th width="118">REQUIRED</th><th width="102">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>700</td><td>3 digit numeric transaction code must be 700</td></tr><tr><td>transaction->merchanttransid</td><td>YES (4)</td><td>YES</td><td>Character max 50.</td><td>Merchant transaction id must be included in the request. Merchant transaction id must be unique for each transaction.</td></tr><tr><td>transaction->amount</td><td>YES (5)</td><td>YES</td><td>Number with point decimal</td><td>Full amount to charge in currency specified. The amount must be specified as a number with decimal point and 2 digits to the right of the decimal point. Decimal separator must be point (.). example: 3500.25 = Three thousand five hundred units of currency and twenty five hundredths of a single unit of currency.</td></tr><tr><td>transaction->curcode</td><td>YES (6)</td><td>YES</td><td>Character 3.</td><td>May only use currencies specified in the Merchant Agreement.</td></tr><tr><td>transaction</td><td></td><td>YES</td><td>Xml Node</td><td>Section containing Transaction Information</td></tr><tr><td>transaction->description</td><td></td><td>YES</td><td>Character max 100.</td><td>Description of the charge. When available, that description may be used in the billing statement of the card holder.</td></tr><tr><td>transaction->merchantspecific1</td><td></td><td>OPT</td><td>Character max 200.</td><td>Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.</td></tr><tr><td>transaction->merchantspecific2</td><td></td><td>OPT</td><td>Character max 200.</td><td>Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.</td></tr><tr><td>transaction->merchantspecific3</td><td></td><td>OPT</td><td>Character max 200.</td><td>Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.</td></tr><tr><td>transaction->merchantspecific4</td><td></td><td>OPT</td><td>Character max 200.</td><td>Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.</td></tr><tr><td>transaction->merchantspecific5</td><td></td><td>OPT</td><td>Character max 200.</td><td>Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.</td></tr><tr><td>customer</td><td></td><td>YES</td><td>Xml Node</td><td>Section containing Customer Information</td></tr><tr><td>customer->firstname</td><td></td><td>YES</td><td>Character max 50.</td><td>First name of the Customer.</td></tr><tr><td>customer->lastname</td><td></td><td>YES</td><td>Character max 50.</td><td>Last name of the Customer.</td></tr><tr><td>customer->birthday</td><td></td><td>YES*</td><td>Number 1-2 digits</td><td>Day of birth of the Customer (1-31) Important Note: If Merchant cannot provide such data, he/she should contact GPN’s Sales Account Manager. <br>*Tag will be set as “Optional” only with Sales Account Manager approval.</td></tr><tr><td>customer->birthmonth</td><td></td><td>YES*</td><td>Number 1-2 digits</td><td>Month of birth of the customer (1-12) Important Note: If Merchant cannot provide such data, he/she should contact GPN’s Sales Account Manager. <br>*Tag will be set as “Optional” only with Sales Account Manager approval.</td></tr><tr><td>customer->birthyear</td><td></td><td>YES*</td><td>Number 4 digits</td><td>Year of birth of the customer (1900-2100) Important Note: If Merchant cannot provide such data, he/she should contact GPN’s Sales Account Manager. <br>*Tag will be set as “Optional” only with Sales Account Manager approval.</td></tr><tr><td>customer->email</td><td></td><td>YES</td><td>Character max 100.</td><td>Email of the Customer.</td></tr><tr><td>customer->countryiso</td><td></td><td>YES</td><td>Character exactly 3.</td><td>3 letter ISO country code of the Customer. Full list of codes can be obtained from the website inside your merchant account.</td></tr><tr><td>customer->stateregioniso</td><td></td><td>YES*</td><td>Character max 3.</td><td>1-3 character ISO 3166 state/region/province code of the Customer. *Mandatory for US and Canada.</td></tr><tr><td>customer->zippostal</td><td></td><td>YES</td><td>Character max 15.</td><td>Customer’s Zipcode or postal code.</td></tr><tr><td>customer->city</td><td></td><td>YES</td><td>Character max 50.</td><td>Customer’s City</td></tr><tr><td>customer->address1</td><td></td><td>YES</td><td>Character max 75.</td><td>Customer’s address line 1</td></tr><tr><td>customer->address2</td><td></td><td>OPT</td><td>Character max 75.</td><td>Customer’s address line 2</td></tr><tr><td>customer->phone1phone</td><td></td><td>YES</td><td>Character max 20.</td><td>Customer’s phone number, including country code and area code. Digits only, without (+) character</td></tr><tr><td>customer->phone2phone</td><td></td><td>OPT</td><td>Character max 20.</td><td>Customer’s phone number, including country code and area code. Digits only, without (+) character</td></tr><tr><td>customer->accountid</td><td></td><td>YES</td><td>Character max 50.</td><td>Customer unique account id used inside the merchant organization.</td></tr><tr><td>customer->ipaddress</td><td></td><td>YES</td><td>Character max 15.</td><td>Full IP address of the customer used for this transaction</td></tr><tr><td>creditcard</td><td></td><td>COND</td><td>Xml Node</td><td>Section containing sepa bank account Information. Required for sepa transactions, forbidden for credit card transactions.</td></tr><tr><td>creditcard->ccnumber</td><td>YES (7)</td><td>YES</td><td>Character max 16.</td><td>Full credit card number without dashes or separators. Only numbers.</td></tr><tr><td>creditcard->cccvv</td><td>YES (8)</td><td>YES</td><td>Character max 4.</td><td>Verification Code of the Credit Card</td></tr><tr><td>creditcard->expmonth</td><td></td><td>YES</td><td>Numeric 1-2</td><td>Expiration month of the credit card.</td></tr><tr><td>creditcard->expyear</td><td></td><td>YES</td><td>Numeric 4</td><td>Expiration year of the credit card.</td></tr><tr><td>creditcard->nameoncard</td><td>YES (9)</td><td>YES</td><td>Character max 50.</td><td>Full name as it appears on card.</td></tr><tr><td>creditcard->billingcountryiso</td><td></td><td>YES</td><td>Character exactly 3.</td><td>3-digits ISO country code of the Customer. Full list of codes can be obtained from the website inside your merchant account.</td></tr><tr><td>creditcard->billingstateregioniso</td><td></td><td>YES</td><td>Character max 5.</td><td>ISO 3166 state/region/province code of the Customer. Full list of codes can be obtained from the website inside your merchant account.</td></tr><tr><td>creditcard->billingzippostal</td><td></td><td>YES</td><td>Character max 15.</td><td>Customer’s Zip code or postal code.</td></tr><tr><td>creditcard->billingcity</td><td></td><td>YES</td><td>Character max 50.</td><td>Customer’s City</td></tr><tr><td>creditcard->billingaddress1</td><td></td><td>YES</td><td>Character max 75.</td><td>Customer’s address line 1</td></tr><tr><td>creditcard->billingaddress2</td><td></td><td>OPT</td><td>Character max 75.</td><td>Customer’s address line 2</td></tr><tr><td>creditcard->billingphone1phone</td><td></td><td>YES</td><td>Character max 20.</td><td>Customer’s phone number, including country code and area code. Digits only, without (+) character</td></tr><tr><td>creditcard->issuemonth</td><td></td><td>OPT</td><td>Numeric 1-2</td><td>Issuing month of the credit card.</td></tr><tr><td>creditcard->issueyear</td><td></td><td>OPT</td><td>Numeric 4</td><td>Issuing year of the credit card.</td></tr><tr><td>creditcard->returnurl</td><td></td><td>COND</td><td>Character string max 2000</td><td>The URL on the merchant website the customer will be returned to after the transaction has been processed.</td></tr><tr><td>checksum</td><td></td><td>YES</td><td>Character 36</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><tr><td>auth</td><td></td><td>YES</td><td>Xml Node</td><td>Section containing authorization type</td></tr><tr><td>auth->type</td><td></td><td>YES</td><td>Character max. 7</td><td>This tag Must be present. Valid values are Direct = non- 3DS Charge (Auth/Capture) Auth = non-3DS Auth Only 3DS = 3DS Charge (Auth/Capture) Auth3DS = 3DS Auth Only Note: only those choices available as indicated in the Merchant Profile are accepted.</td></tr><tr><td>auth->sid</td><td></td><td>COND</td><td>Character no limit*</td><td>This tag is used only during 3D Secure transactions. It is intended to use as a session identification string and it is forwarded to you as a part of your Return URL. (See Appendix for “3D Secure Integration”) Note: Keep in mind that URL length (your Return URL + SID) must be under 2 000 characters</td></tr><tr><td>auth->xid</td><td></td><td>COND</td><td>28 byte-long</td><td>base-64 encoded XID : Unique Internet transaction ID To be taken from ACS Response.</td></tr><tr><td>auth->eci</td><td></td><td>COND</td><td>Numeric 2</td><td>Valid values are 01,02,05,06,07 MasterCard: 01 / 02 Visa: 05 / 06 / 07 empty for non-3D transactions To be taken from ACS Response.</td></tr><tr><td>auth->cavv</td><td></td><td>COND</td><td>Character 28</td><td>contains a 20-byte value that has been Base64 encoded, giving a 28 byte result. To be taken from ACS Response.</td></tr><tr><td>auth->cavvAlgorithm</td><td></td><td>COND</td><td>Numeric 1</td><td>Digit from [0-9] depending on ACS response. To be taken from ACS Response.</td></tr></tbody></table>

## 700 – Response

You initiate a transaction with an authentication type of either 3DS or Auth3DS.

Auth3DS involves a two-step process of authorization and capture. Some merchants opt for Auth3DS, where they authorize the payment and keep it in an AUTHORIZED status for a few days (usually less than 7) before capturing the funds. This waiting period serves as a buffer, allowing customers to cancel the deposit without requiring a refund. This practice helps prevent Chargebacks (CHB) because a transaction can be marked as CHB if it is not fully captured.

Transaction results:

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

```
<?xml version="1.0" encoding="utf-8"?>
<transaction>
  <result>SUCCESS</result>
  <merchanttransid></merchanttransid>
  <transref>343387</transref>
  <gatetransid></gatetransid>
  <errorcode></errorcode>
  <errormessage/>
  <description>Test approved</description>
  <descriptor></descriptor>
</transaction>
```

{% endtab %}

{% tab title="Pending" %}

```
 Gateway Response:
	<?xml version="1.0" encoding="utf-8"?>
	<transaction>
	  <result>PENDING</result>
	  <merchanttransid></merchanttransid>
	  <transref></transref>
	  <gatetransid></gatetransid>
	  <errorcode></errorcode>
	  <errormessage/>
	  <description></description>
  	<redirect></redirect>
	</transaction>
```

{% endtab %}

{% tab title="Decline" %}

```
<?xml version="1.0" encoding="utf-8"?>
<transaction>
  <result>DECLINED</result>
  <merchanttransid></merchanttransid>
  <transref></transref>
  <errorcode>000</errorcode>
  <errormessage/>
  <description></description>
</transaction>
```

{% endtab %}

{% tab title="Error" %}

```
=<?xml version="1.0" encoding="utf-8"?>
<transaction>
  <result>ERROR</result>
  <merchanttransid/>
  <transref/>
  <errorcode></errorcode>
  <errormessage></errormessage>
  <description/>
</transaction>
```

{% endtab %}
{% endtabs %}

The gateway response includes XML data with the PENDING status. In this case, direct the user to the specified URL where they will complete the redirection process and proceed to the URL.

## Response Data description:

| NODE            | REQUIRED | DATA TYPE                 | DESCRIPTION                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| --------------- | -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| result          | YES      | Character                 | Indicates the result of the transaction. SUCCESS: Customer’s Credit Card account has been charged (or AUTHORIZED) with the amount of the transaction. DECLINED: transaction was declined. ERROR: An error has been detected in the request. PENDING: If the Issuing bank has been determined to participate in the 3DS program, this is the normal response and it will include the redirect URL. The merchant must present a redirect screen to the cardholder, using the URL. |
| merchanttransid | YES      | Character max 50.         | Unique merchant transaction id received in the request.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| transref        | COND     | Integer                   | Gateway’s transaction reference number. Will be sent in the response only if the result is not ERROR. Merchant should save this reference number for support and troubleshooting.                                                                                                                                                                                                                                                                                               |
| gatetransid     | COND     | Character 36              | Gateway transaction ID. Will be sent in the response only if the result is not ERROR. Merchant should save this reference number for refunds and other transaction activity performed through API.                                                                                                                                                                                                                                                                              |
| errorcode       | YES      | Character 3               | Error Code of the transaction or 000 if no error condition found.                                                                                                                                                                                                                                                                                                                                                                                                               |
| errormessage    | OPT      | 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.                                                                                                                                                                                                                                                                                                                                                            |
| redirect        | COND     | Character string max 2000 | Direct the user to this URL, where he will complete the process and be redirected to the return URL                                                                                                                                                                                                                                                                                                                                                                             |

{% tabs %}
{% tab title="CURL" %}
The 700 request is plain XML that contains the following data:

```
<?xml version="1.0" encoding="UTF-8"?>
<transaction>
  <transaction>
    <merchanttransid></merchanttransid>
    <amount></amount>
    <curcode></curcode>
    <description></description>
  </transaction>
  <customer>
    <id></id>
    <ipaddress></ipaddress>
  </customer>
  <auth>
    <type></type>
  </auth>
  <creditcard>
    <token></token>
    <cccvv></cccvv>
    <returnurl></returnurl>
  </creditcard>
  <apiUser></apiUser>
  <apiPassword></apiPassword>
  <apiCmd></apiCmd>
  <checksum></checksum>
</transaction>
							  
```

The 700 response is plain XML that contains the following data:

```

	<?xml version="1.0" encoding="utf-8"?>
	<transaction>
	  <result></result>
	  <merchanttransid></merchanttransid>
	  <transref></transref>
	  <gatetransid></gatetransid>
	  <errorcode></errorcode>
	  <errormessage/>
	  <description></description>
	  <descriptor></descriptor>
	  <redirect></redirect>
	</transaction>
```

{% endtab %}

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

```
require_once 'autoload.php';

use Omnipay\Common\CreditCard;
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://testapi.txpmnts.com/v1/transactions/');

$card = new CreditCard([
	'firstname'        => '',
	'lastname'         => '',
	'billingAddress1'  => '',
	'billingAddress2'  => '',
	'billingCity'      => '',
	'billingPostcode'  => '',
	'billingState'     => '',
	'billingCountry'   => '',
	'shippingAddress1' => '',
	'shippingAddress2' => '',
	'shippingCity'     => '',
	'shippingPostcode' => '',
	'shippingState'    => '',
	'shippingCountry'  => '',
	'phone'            => '',
	'number'           => '4127209999999581',
	'expiryMonth'      => 04,
	'expiryYear'       => 2018,
	'cvv'              => 345,
]);

$params = [
	'amount'        => '',
	'firstName'     => '',
	'lastName'      => '',
	'card'          => $card,
	'currency'      => '',
	'transactionId' => '',
	'statement'     => '',
	'description'   => '',
	'birthDay'      => 16,
	'birthMonth'    => 7,
	'birthYear'     => 1985,
	'email'         => '',
	'clientIp'      => '',
	'accountId'     => 12345,
	'rebillAmount'  => 10,
	'rebillCount'   => 3,
	'rebillDescription' => '',
	'rebillFollowupAmount' => '',
	'rebillFollowupTime' => '',
	'rebillFrequency' => '1d',
	'rebillStart' => '',
	'rebill' => true,
	'authType' => 'Auth3DS',
];

try {
	// Auth3DS
	$response = $gpnGateway->purchase($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());
if($response->getData()->getSecure()->getAcs()){
echo 'ACS : '; print_r($response->getData()->getSecure()->getAcs());
echo 'MD : '; print_r($response->getData()->getSecure()->getMD());
echo 'PaReq : '; print_r($response->getData()->getSecure()->getPaReq());
echo 'Term URL : '; print_r($response->getData()->getSecure()->getTermUrl());
}
if($response->getData()->getRebill()->getWindow()){
echo 'Rebill Windows : '; print_r($response->getData()->getRebill()->getWindow());
}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Good to know:** This API method was created using the API Method block, it's how you can build out an API method documentation from scratch. Have a play with the block and you'll see you can do some nifty things like add and reorder parameters, document responses, and give your methods detailed descriptions.
{% endhint %}


---

# 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/700-start-credit-card-charge-3ds-enabled.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.