ConvertPlus Buy-Link Signature for Catalog Products
Overview
You can generate links for catalog products outside the Merchant Control Panel, using the ConvertPlus parameters explained in this article. Some of the ConvertPlus buy-link parameters require a signature for the redirect.
Recommended resources
ConvertPlus is a full-stack solution that enables you to increase conversion rates with faster loading time and optimized flows. Download this solution brief to learn more!
Generate custom links
ConvertPlus parameters that require a signature:
Parameter | Description |
---|---|
return-url | URL to which customers are redirected after their finalized purchase. Learn more about Redirect URL in this article. |
return-type |
The return method used for redirecting your customers after a successful sale. Possible values:
|
expiration |
Buy link expiry date. The link becomes invalid after the date of this parameter. Send as a UTC timestamp. Example: 1537549421 |
order-ext-ref | Use this parameter to set an external reference to the order. |
item-ext-ref | Set product identifier for your catalog products. When included, the parameter needs to be signed. |
customer-ref | The 2Checkout system generates default customer numerical (integer) IDs automatically for all orders of products that feature subscriptions. It can be used for new acquisitions aggregating new subscriptions under an existing Customer account. |
customer-ext-ref | The external customer reference. |
ConvertPlus parameters to be included in the signature
- General parameters included in the signature, regardless of the type of checkout (catalog products, dynamic products, renewal, unfinished payment): return-url, return-type, expiration, order-ext-ref,customer-ref, customer-ext-ref, lock.
- Parameters to be included in the signature for dynamic products buy-links: currency, prod, price, qty, tangible, type, opt, description, recurrence, duration, renewal-price, item-ext-ref.
- Parameters to be included in the signature for manual renewal buy-links: prod, qty, opt.
- Parameters to be included for on-the-fly pricing for catalog products: prod, price, qty, opt, coupon, currency.
- Parameters to be included when an approved URL is set: in this case, all parameters will be included in the signature, when redirected after successful completion of a sale.
Build the ConvertPlus Signature
To sign a ConvertPlus buy-link, you need to follow these steps:
- Sort the parameters that require a signature alphabetically.
- Serialize the parameters and append to them the length of their values.
- Concatenate the resulting values.
- The serialized value is then encrypted with your Buy-Link Secret Word using the HMAC method (algorithm sha256).
- The resulting value is added to the buy-link under the signature parameter.
In order to generate a valid ConvertPlus signature, you can include the below parameters as well. The merchant parameter does not require to be signed.
- merchant = '2COLRNC' (this is the merchant code)
- prod = 'E2932D0DE2' (this is the product code)
- qty = 1
EXAMPLE
When encrypting the values to generate the signature, for the return-url parameter, use an URL with the following structure: https://..... Do not use an encoded URL.
Let's consider the following parameters:
- return-url = 'https://www.2checkout.com'
- return-type = 'redirect'
- expiration = '1665835200'
- order-ext-ref = '123456'
The regular buy-link will have the following structure:
https://secure.2checkout.com/checkout/buy?merchant=2COLRNC&prod=E2932D0DE2&qty=1&return-url=https%3A%2F%2Fwww.2checkout.com&return-type=redirect&expiration=1665835200&order-ext-ref=123456
Sort the parameters alphabetically
- expiration = '1665835200'
- order-ext-ref = '123456'
- return-type = 'redirect'
- return-url = 'https://www.2checkout.com'
Serialize the values
To serialize a value, you need to append before it the number of letters or digits a value has. For example, the expiration parameter has the '1665835200' value that will be serialized as '101665835200', where 10 is the number of digits that make up the value. The value of the return-type parameter is 'redirect', so the serialized value will be '8redirect', where 8 is the number of letters that make up the value.
- expiration = '101665835200'
- order-ext-ref = '6123456'
- return-type = '8redirect'
- return-url = '25https://www.2checkout.com'
Concatenate the values
'10166583520061234568redirect25https://www.2checkout.com'
Encrypt using your Secret Word
The serialized value is then encrypted using the HMAC method.
- the algorithm used is sha256
- the key used when encrypting is the merchant secret word (in this example, the secret word is 'secret_word')
This outputs a 64 character string:
520ba411696e37f1839145bfa793f7199d8d0295a228ea42dc20a3f39196e358
Add the string in the buy-link
https://secure.2checkout.com/checkout/buy?merchant=2COLRNC&prod=E2932D0DE2&qty=1&test=1&return-url=https%3A%2F%2Fwww.2checkout.com&return-type=redirect&expiration=1665835200&order-ext-ref=123456&signature=520ba411696e37f1839145bfa793f7199d8d0295a228ea42dc20a3f39196e358
Are affiliates cannibalizing online sales?
Did you ever wonder how valuable your affiliates are to your purchase funnel? If that's true, then you're going to want to watch this webinar. Jessica Griffin, Sr. Sales and Marketing Specialist at Schaaf-PartnerCentric and Cristian Miculi, Sr. Alliances Manager at 2Checkout will lend their considerable experience and expertise to answering the critical question of how to get the most value from your affiliate relationships. With their help, you'll come away with a clear understanding of the different types of affiliates in the marketplace, their key motivations and drivers, and how best to work with them. Plus, they'll also provide you with some hands-on advice and tips for optimizing affiliate program conversion rates. |
SSO in cart
Overview
Use the getSingleSignOnInCart method. 2Checkout attaches a unique token to links, designed to identify the returning shoppers and support the automatic extraction of payment data and billing information from the 2Checkout system. For example, you can generate single sign on in cart links for existing customers logged into your website based on their external or 2Checkout customer IDs.
How does this work?
When accessing the shopping cart using tokenized payment links:
- 2Checkout prefills automatically customer billing and delivery details associated with their 2Checkout customer accounts (linked based on their unique customer IDs).
- 2Checkout presents shoppers with an optimized payment area featuring the credit / debit cards used to make previous purchases / transactions in the 2Checkout system. Customers have the option of selecting one of the payment methods depending on available card-on-file data.
Parameters
Parameters | Type/Description |
---|---|
sessionID |
Required (string) |
|
Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes. |
Customer |
Required (string) |
Unique customer identifiers. Can be either the ExternalCustomerReference you control or the system-generated AvangateCustomerReference. |
|
customerType |
Required (string) |
|
Possible values:
|
url |
Required (string) |
|
The shopping cart URL. 2Checkout redirects shoppers to this URL.
Possible values:
Any buy link you generate from the cPanel or using the API. Note: For the time being, payment tokenization does not support Express Payments Checkout or the 2Checkout mobile shopping cart. |
validityTime |
Optional (int) |
|
The time, in seconds, before the single sign-on URL expires. By default, the URL expires after 10 seconds. (optional) |
validationIp |
Optional (string) |
|
The IP address of the shopper, necessary for security purposes. Can be an empty string or a valid IP, or null. |
Response
Parameters | Type/Description |
---|---|
Single sign-on URL |
String |
The generated string is the tokenized time-limited single sign-on URL pointing to 2Checkout shopping cart.
Note: Each SSO link cleans any previous cart sessions. Shoppers using multiple SSO links would purchase only a single product at a time.
If shoppers add multiple products to cart via SSO buy links and then use a non-SSO link, they’ll purchase all items using the same order. When you use single sign on in cart for customers without card on files in the 2Checkout system, the generated tokenized link prefills the billing information but the purchase process requires that shoppers provide payment information, such as a credit or debit card.
Important! You can use the value of the logintoken to retrieve customer information by SSO token.
|
Request
<?php
require ('PATH_TO_AUTH');
$idCustomer = '352365983';
$customerType = 'AvangateCustomerReference';
$url = 'https://store.avancart.com/order/checkout.php?PRODS=4639321&QTY=1&CART=1&CARD=2';
$validityTime = 50;
$validationIp = null;
$jsonRpcRequest = array (
'method' => 'getSingleSignOnInCart',
'params' => array($sessionID, $idCustomer, $customerType, $url, $validityTime, $validationIp),
'id' => $i++,
'jsonrpc' => '2.0');
var_dump (callRPC((Object)$jsonRpcRequest, $host, true));
Set the order external reference in the InLine Cart
Overview
Use the Cart object to set order external reference of the InLine Cart by calling theTwoCoInlineCart.cart.setOrderExternalRef(your-external-reference)
method.
Use case
- Add an HTML link or button in your page like the one below.
- Create a JavaScript click handler to execute the Inline Client desired methods.
- Use the
TwoCoInlineCart.products.add({code, quantity, options})
method to prepare your catalog product. - In order to set currency use TwoCoInlineCart.cart.setCurrency(currency-code).
- In order to set order external reference use
TwoCoInlineCart.cart.setOrderExternalRef(your-external-reference)
method. - You can see below a signature token request payload for this example. A success response contains a JSON with the property “signature“ which needs to be used at the next step to set the signature using the TwoCoInlineCart method.
{
"merchant": "AVLRNG",
"currency": "USD",
"products": [
{
"code": "74B8E17CC0"
}
],
"reference": {
"external": {
"order": "test-order-external-ref"
}
}
}
The above payload will generate the signature f40503a3feeb2c5fc0ca002ded20c59ad0f0b439e3911cfb03538906635d0ae4.
7. Use the TwoCoInlineCart.cart.setSignature('f40503a3feeb2c5fc0ca002ded20c59ad0f0b439e3911cfb03538906635d0ae4') method to set the signature.
8. Use theTwoCoInlineCart.cart.checkout()
method to show the cart on your page.
Sample request
HTML
<a href="#" class="btn btn-success" id="buy-button">Buy now!</a>
Javascript
window.document.getElementById('buy-button').addEventListener('click', function() {
TwoCoInlineCart.cart.setCurrency('USD');
TwoCoInlineCart.products.add({
code: "74B8E17CC0"
});
TwoCoInlineCart.cart.setSignature('f40503a3feeb2c5fc0ca002ded20c59ad0f0b439e3911cfb03538906635d0ae4');
TwoCoInlineCart.cart.setOrderExternalRef('test-order-external-ref');
TwoCoInlineCart.cart.checkout();
});
Demo
After setting the order external reference in the InLine cart using the above method, your cart should look like this:
LCN POST failure recovery process
Overview
In case of an invalid inline response, 2Checkout resends the LCN notification until successfully confirmed. Also, we will display an error notification in the Control Panel Dashboard area.
LCN POST Failure recovery |
No of attempts |
|
---|---|---|
Stage 1: |
The first License Change Notification (LCN) is sent instantaneously for subscription/license modification events per the vendor's LCN Settings. |
1 |
Stage 2: |
If the initial notification fails, the subsequent two (2) LCN messages are sent after the next five (5) minutes. |
2 |
Stage 3: |
If the issue persists, and requests continue to result in failures, another four (4) tries are made, at 15-minute intervals. |
4 |
Stage 4: |
Following the four tries made in Stage 3, the 2Checkout system will perform one-hour interval continuous requests for a maximum of two (2) days since the notification was initially triggered until a valid response is received. |
1/h |
Add a digital dynamic product with a dynamic coupon
Overview
Use the order promotions object to add a digital dynamic product with a dynamic coupon (for the PSP business model).
Use case
- Add an HTML link or button to your page like the one below.
- Create a JavaScript click handler to execute the InLine Client desired methods.
- Use the TwoCoInlineCart.setup.setMode('DYNAMIC') method to let the cart know you are using dynamic instead of catalog products.
- Use the TwoCoInlineCart.cart.setCurrency(currency-code) method to set the currency.
- Add your product to the cart by calling the TwoCoInlineCart.products.add({name, quantity, price, options}) method.
- You can see below a signature token request payload for this example. A success response contains a JSON with the property “signature“ which needs to be used at the next step to set the signature using the TwoCoInlineCart method.
{
"merchant": "250535979326",
"dynamic": "1",
"currency": "USD",
"products": [
{
"name" : "A test digital product",
"quantity": 1,
"price" : 20,
"type" : 'digital'
},
{
"name" : "A test promotion",
"quantity": 1,
"price" : 5,
"type" : 'coupon'
}
]
}
7. Use the TwoCoInlineCart.cart.setSignature('718e810fee34be2bf4b9d4582323aa37580c4011ef694116cca5b0bb7badd2f1') method to set the signature. It is important that you employ TwoCoInlineCart.cart.removeAll() just before TwoCoInlineCart.products.addMany(products) or TwoCoInlineCart.products.add(product) methods to remove previous products as the signature is based on the products' definition.
8. Use the TwoCoInlineCart.cart.checkout() method to show the cart on your page.
Sample request
HTML
<a href="#" class="btn btn-success" id="buy-button">Buy now!</a>
JavaScript
window.document.getElementById('buy-button').addEventListener('click', function() {
TwoCoInlineCart.setup.setMode('DYNAMIC');
TwoCoInlineCart.cart.setCurrency('USD');
TwoCoInlineCart.products.removeAll();
TwoCoInlineCart.products.add({
name: 'A test digital product',
quantity: 1,
price: 20,
type: 'digital'
});
TwoCoInlineCart.products.add({
name: 'A test promotion',
quantity: 1,
price: 5,
type: 'coupon'
});
TwoCoInlineCart.cart.setSignature('5c07abeddff1f1e9521d7c726b7746a09049fcf24e6d1299577b1703d275089c');
TwoCoInlineCart.cart.checkout();
});
Demo
After adding a digital dynamic product with a dynamic coupon using the above method, your cart should look like this:
Professional Services customizations
Overview
Our Professional Services team is always ready to do all the heavy lifting when it comes to customizing ordering interfaces (shopping carts). Contact 2Checkout directly to ask how the PS team can help you:
- Align the look-and-feel of your cart with the rest of your web properties
- Include tried and tested conversion optimization best practices into the design
- Create shopper experiences such as cross-sell and upsell to drive Average Order Value (AOV) up
- Build custom events that cut your abandonment rate
Calculate the IPN HASH signature
Overview
Using the IPN HASH signature is optional and it's only meant for source validation.
Availability
Available for all 2Checkout accounts.
Build the IPN HASH signature
- To build the HMAC_SHA source string, sent in IPN payload, you need to pre-pend each value (Sample value column in the Example table below) with its own length (Field length column in the Example table below) in bytes. You should use the same order for parameters as the one received in the payload. If you will change the order, the HMAC_SHA string will be different.
- Use 0 for null or empty values without prepending their length. However, when the value is 0 (zero), you do need to prepend its length (1).
- Note that for UTF-8 characters the length in bytes can be longer than the string length. When calculating the hash signature, you must use multibyte methods that return the number of bytes in a string, instead of methods that return the number of characters. Example: if using PHP, use the strlen method instead of length.
Each value from the body of the IPN call needs be included in the string in the exact same sequence as you received in the IPN payload. Also, this should match the HASH property of the IPN call body for the request to be considered valid, so you can verify that the request comes from our system.
Example
Field name | Field length | Sample value |
---|---|---|
SALEDATE |
19 |
2016-06-01 12:22:09 |
REFNO |
7 |
1000037 |
REFNOEXT |
0 |
|
ORDERNO |
2 |
13 |
ORDERSTATUS |
8 |
COMPLETE |
PAYMETHOD |
13 |
Wire transfer |
FIRSTNAME |
4 |
John |
LASTNAME |
5 |
Smith |
COMPANY |
0 |
|
REGISTRATIONNUMBER |
0 |
|
FISCALCODE |
0 |
|
CBANKNAME |
0 |
|
CBANKACCOUNT |
0 |
|
ADDRESS1 |
15 |
101 Main Street |
ADDRESS2 |
0 |
|
CITY |
8 |
New York |
STATE |
8 |
New York |
ZIPCODE |
6 |
500365 |
COUNTRY |
24 |
United States of America |
PHONE |
12 |
951-121-2121 |
FAX |
0 |
|
CUSTOMEREMAIL |
19 |
|
FIRSTNAME_D |
4 |
John |
LASTNAME_D |
5 |
Smith |
COMPANY_D |
0 |
|
ADDRESS1_D |
15 |
101 Main Street |
ADDRESS2_D |
0 |
|
CITY_D |
8 |
New York |
STATE_D |
8 |
New York |
ZIPCODE_D |
6 |
500365 |
COUNTRY_D |
24 |
United States of America |
PHONE_D |
12 |
951-121-2121 |
IPADDRESS |
14 |
213.233.121.50 |
CURRENCY |
3 |
USD |
IPN_PID[0] |
1 |
1 |
IPN_PNAME[0] |
16 |
Software program |
IPN_PCODE[0] |
5 |
PM_11 |
IPN_INFO[0] |
0 |
|
IPN_QTY[0] |
1 |
1 |
IPN_PRICE[0] |
5 |
29.00 |
IPN_VAT[0] |
4 |
0.00 |
IPN_VER[0] |
0 |
|
IPN_DISCOUNT[0] |
4 |
0.00 |
IPN_PROMONAME[0] |
0 |
|
IPN_DELIVEREDCODES[0] |
0 |
|
IPN_TOTAL[0] |
5 |
29.00 |
IPN_TOTALGENERAL |
5 |
34.00 |
IPN_SHIPPING |
4 |
5.00 |
IPN_COMMISSION |
4 |
3.38 |
IPN_DATE |
14 |
20050303123434 |
TEST_ORDER | 1 | 1 |
2. Using the data in the example table you can calculate the following HMAC source string by prepending each length to each value, without adding any space that is not part of the value between them:
192016-06-01 12:22:097100003702138COMPLETE13Wire transfer4John5Smith9BV-66778800000015101 Main Street08New York8New York650036524United States of America12951-121-2121019johnsmith@email.com4John5Smith015101 Main Street08New York8New York650036524United States of America12951-121-212114213.233.121.503USD1116Software program5PM_11011529.0040.00040.0000529.00534.0045.0043.38142005030312343411
3. The Secret Key in this example is: AABBCCDDEEFF
To find your own Secret Key, log in to the Merchant Control Panel and navigate to Integrations → Webhooks & API. You can find the Secret Key in the API section, as shown in this image:
4. For this source string, the SHA-2 HASH value is:
d80f8520e989904df0d2b3caa710ba9907456ac6545eb75e357b10728234e495
For this source string, the SHA-3 HASH value is:
d0464d5712e893efc292be66ac6538bc4493706bd9deb43eae409142e848400e
Use the example below to test creating the IPN HASH and the response for the data supplied in this article.
PHP Hash Example
/* 2Checkout IPN HASH example */
/*
* possible values: sha256, sha3-256
* sha3-256 only for php version > 7.1
*/
$used_hash_algorithm = 'sha256';
/* pass to compute HASH. Retrieve your secret key by accessing https://secure.2checkout.com/cpanel/webhooks_api.php */
$secret_key = 'AABBCCDDEEFF';
date_default_timezone_set('UTC');
echo '<pre>';
//*********FUNCTIONS FOR HMAC*********
function serializeArray($array) {
$retval = "";
foreach ($array as $i => $value) {
if (is_array($value)) {
$retval .= serializeArray($value);
}
else {
$size = strlen($value);
$retval .= $size . $value;
}
}
return $retval;
}
//PARAMETERS
$IPN_parameters = array();
$IPN_parameters['SALEDATE'] = '2016-06-01 12:22:09';
$IPN_parameters['REFNO'] = '1000037';
$IPN_parameters['REFNOEXT'] = '';
$IPN_parameters['ORDERNO'] = '13';
$IPN_parameters['ORDERSTATUS'] = 'COMPLETE';
$IPN_parameters['PAYMETHOD'] = 'Wire transfer';
$IPN_parameters['FIRSTNAME'] = 'John';
$IPN_parameters['LASTNAME'] = 'Smith';
$IPN_parameters['COMPANY'] = '';
$IPN_parameters['REGISTRATIONNUMBER'] = '';
$IPN_parameters['FISCALCODE'] = '';
$IPN_parameters['CBANKNAME'] = '';
$IPN_parameters['CBANKACCOUNT'] = '';
$IPN_parameters['ADDRESS1'] = '101 Main Street';
$IPN_parameters['ADDRESS2'] = '';
$IPN_parameters['CITY'] = 'New York';
$IPN_parameters['STATE'] = 'New York';
$IPN_parameters['ZIPCODE'] = '500365';
$IPN_parameters['COUNTRY'] = 'United States of America';
$IPN_parameters['PHONE'] = '951-121-2121';
$IPN_parameters['FAX'] = '';
$IPN_parameters['CUSTOMEREMAIL'] = 'johnsmith@email.com';
$IPN_parameters['FIRSTNAME_D'] = 'John';
$IPN_parameters['LASTNAME_D'] = 'Smith';
$IPN_parameters['COMPANY_D'] = '';
$IPN_parameters['ADDRESS1_D'] = '101 Main Street';
$IPN_parameters['ADDRESS2_D'] = '';
$IPN_parameters['CITY_D'] = 'New York';
$IPN_parameters['STATE_D'] = 'New York';
$IPN_parameters['ZIPCODE_D'] = '500365';
$IPN_parameters['COUNTRY_D'] = 'United States of America';
$IPN_parameters['PHONE_D'] = '951-121-2121';
$IPN_parameters['IPADDRESS'] = '213.233.121.50';
$IPN_parameters['CURRENCY'] = 'USD';
$IPN_parameters['IPN_PID'][0] = '1';
$IPN_parameters['IPN_PNAME'][0] = 'Software program';
$IPN_parameters['IPN_PCODE'][0] = 'PM_11';
$IPN_parameters['IPN_INFO'][0] = '';
$IPN_parameters['IPN_QTY'][0] = '1';
$IPN_parameters['IPN_PRICE'][0] = '29.00';
$IPN_parameters['IPN_VAT'][0] = '0.00';
$IPN_parameters['IPN_VER'][0] = '';
$IPN_parameters['IPN_DISCOUNT'][0] = '0.00';
$IPN_parameters['IPN_PROMONAME'][0] = '';
$IPN_parameters['IPN_DELIVEREDCODES'][0] = '';
$IPN_parameters['IPN_TOTAL'][0] = '29.00';
$IPN_parameters['IPN_TOTALGENERAL'] = '34.00';
$IPN_parameters['IPN_SHIPPING'] = '5.00';
$IPN_parameters['IPN_COMMISSION'] = '3.38';
$IPN_parameters['IPN_DATE'] = '20050303123434';
$IPN_parameters['TEST_ORDER'] = '1';
//*********Base string for SHA2-256/SHA3-256 calculation:*********
echo "This is the base string for SHA2-256/SHA3-256 calculation: ";
$result = '';
foreach ($IPN_parameters as $key => $val){
$result .= serializeArray((array)$val);
}
var_dump($result);
//*********Calculated SHA2-256/SHA3-256 signature:*********
switch ($used_hash_algorithm) {
case 'sha256':
echo "This is the SHA2-256 signature: ";
$hash = hash_hmac('sha256', $result, $secret_key);
$IPN_parameters['SIGNATURE_SHA2_256'] = $hash;
var_dump($hash);
break;
case 'sha3-256':
echo "This is the SHA3-256 signature: ";
$hash = hash_hmac('sha3-256', $result, $secret_key);
$IPN_parameters['SIGNATURE_SHA3_256'] = $hash;
var_dump($hash);
break;
}
Read receipt response from 2Checkout
The read receipt response is required in the IPN response body, unlike the previous hash string which is optional, with the EPAYMENT tag. We use this hash as a method of security.
To validate the success of the notification process, insert an inline response in the script output of your IPN listener. 2Checkout expects the following format:
<sig algo="sha256" date="DATE">HASH</sig>
Once 2Checkout validates that the above format is part of the response it considers the IPN successful. Otherwise, 2Checkout continues to send notifications per the failure recovery process until you provide a valid response.
DATE |
Datetime stamp. YmdHis. (20081117145935) |
---|---|
HASH |
Calculate the HMAC_SHA signature using:
HASH fields values are case insensitive. |
The fields used in the HMAC_SHA signature are captured from the IPN payload just received, in the same order:
Field name | Description |
---|---|
IPN_PID[0] |
First product ID from the IPN_PID[] array. |
IPN_PNAME[0] |
First product name from the IPN_PNAME[] array. |
IPN_DATE |
IPN date in the YmdHis format (ex: 20081117145935) |
DATE |
Response issuing date (server time) in the YmdHis format (ex: 20081117145935) |
For the example parameters included in this article, build the response using shorter data formats for date values. Use only the following values, in the same order, for the HMAC source string:
Field name |
Length |
Field value |
---|---|---|
IPN_PID[0] |
1 |
1 |
IPN_PNAME[0] |
16 |
Software program |
IPN_DATE |
14 |
20050303123434 |
DATE |
14 |
20050303123434 |
Therefore, the HMAC source string is:
1116Software program14200503031234341420050303123434
while the HMAC SHA-2 string is:
ea6f44c39b3d204b59500998fcb9221c92744d9721a94b45fc6d5cda99980176
and the HMAC SHA-3 string is:
85180497aaaa4844a278b52b1ce257d2820dbf5857470a5f678fef2266d0d4a8
Configure the response to output anywhere on the page defined as the IPN URL for:
- SHA-2:
<sig algo="sha256" date="20050303123434">ea6f44c39b3d204b59500998fcb9221c92744d9721a94b45fc6d5cda99980176</sig>
- SHA-3:
<sig algo="sha3-256" date="20050303123434">85180497aaaa4844a278b52b1ce257d2820dbf5857470a5f678fef2266d0d4a8</sig>
2Checkout checks the string’s validity and marks notifications as "successfully sent" in the 2Checkout system. Otherwise, 2Checkout resends the IPN notifications at specific time intervals described in the failure recovery process section, until successfully confirmed. Also, 2Checkout displays an error notification in the Dashboard area of your Merchant Control Panel.
PHP Hash Response Example
$IPN_parameters_response = array();
$IPN_parameters_response['IPN_PID'][0] = '1';
$IPN_parameters_response['IPN_PNAME'][0] = 'Software program';
$IPN_parameters_response['IPN_DATE'] = '20050303123434';
$IPN_parameters_response['DATE'] = '20050303123434';
//*********Response base string for SHA2-256/SHA3-256 calculation:*********
echo "This is the response base string for SHA2-256/SHA3-256 calculation: ";
$result_response = '';
foreach ($IPN_parameters_response as $key => $val){
$result_response .= serializeArray((array)$val);
}
var_dump($result_response);
//*********Calculated response SHA2-256/SHA3-256 signature:*********
$responseString = '';
switch ($used_hash_algorithm) {
case 'sha256':
echo "This is the response SHA2-256 signature: ";
$hash = hash_hmac('sha256', $result_response, $secret_key);
var_dump($hash);
$responseString = '<sig algo="sha256" date="' . $IPN_parameters_response['DATE'] . '">' . $hash . '</sig>' . PHP_EOL;
break;
case 'sha3-256':
echo "This is the response SHA3-256 signature: ";
$hash = hash_hmac('sha3-256', $result_response, $secret_key);
var_dump($hash);
$responseString = '<sig algo="sha3-256" date="' . $IPN_parameters_response['DATE'] . '">' . $hash . '</sig>' . PHP_EOL;
break;
}
//Expected response
echo 'Expected response:' . PHP_EOL . $responseString;
Validation
To validate the request and create the HMAC hash string you can use the below sample:
Node.JS (ES6) sample
let hashString = '';
let valueLengthInBytes;
function byteLength(str) {
let s = str.length;
for (let i = str.length-1; i>=0; i--) {
var code = str.charCodeAt(i);
if (code > 0x7f && code <= 0x7ff) s++;
else if (code > 0x7ff && code <= 0xffff) s+=2;
if (code >= 0xDC00 && code <= 0xDFFF) i--;
}
return s;
}
Object.keys(request.params).forEach(function(key) {
valueLengthInBytes = byteLength(request.params[key].toString());
if (valueLengthInBytes > 0) {
hashString += valueLengthInBytes + request.params[key].toString();
}
});
Python sample (Flask)
from urllib import request
from flask import Flask, jsonify, request, Request
from urllib.parse import urlencode, urldefrag
from werkzeug.datastructures import ImmutableOrderedMultiDict
class MyRequest(Request):
parameter_storage_class = ImmutableOrderedMultiDict
class MyFlask(Flask):
request_class = MyRequest
app = MyFlask(__name__)
def bytes_length(string):
return len(string.encode('utf-8'))
def calculate_hash_string(payload_tuple_list):
hash_string = ''
for payload_key in payload_tuple_list:
payload_value = payload_tuple_list[payload_key]
bytes = bytes_length(payload_value)
if bytes > 0:
hash_string = hash_string + str(bytes) + payload_value
return hash_string
@app.route('/ipn', methods=['POST'])
def ipn():
ipn_payload_received = request.form
return calculate_hash_string(ipn_payload_received)
if __name__ == '__main__':
app.run()
Verifone IPN send request sample
For the parameters listed in the table below we will have the following request sample:
POST /vg8NfWXNBmaW8Lrsarfu HTTP/1.1
Host: putsreq.com
Content-Type: application/x-www-form-urlencoded
Cookie: __cfduid=d9526a7dbe99fe081deef1ae1940420891612782045;
owner_token=9631c27fbfa38e7da850137e6c23f7cceba0450debcd834a
Content-Length: 218
GIFT_ORDER=0&SALEDATE=2021-02-04 09:11:30&PAYMENTDATE=2021-02-04
09:14:53&REFNO=11758694&REFNOEXT=&SHOPPER_REFERENCE_NUMBER
=&IPCOUNTRY=&CURRENCY=USD&IPN_PID[]=30969748&IPN_PNAME[]=Antivi
rus 2021&IPN_DATE=20210208063206
IPN Parameter | Value |
---|---|
GIFT_ORDER | 0 |
SALEDATE | 2021-02-04 09:11:30 |
PAYMENTDATE | 2021-02-04 09:14:53 |
REFNO | 11758694 |
REFNOEXT | |
SHOPPER_REFERENCE_NUMBER | |
IPCOUNTRY | |
CURRENCY | |
IPN_PID[] | 30969748 |
IPN_PNAME[] | Product name |
IPN_DATE | 20210208063206 |
Order information object
Overview
Use this object to retrieve information about orders.
Attributes
Order Information |
Type/Description |
|||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
RefNo |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Avangate generates unique reference numbers for all orders (purchases). You can use this parameter to retry authorizations for orders with failed transactions by changing the payment method.
NULL when you place new orders. |
||||||||||||||||||||||||||||||||||||
OrderNo |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The consecutive order number Avangate associates with orders and displays in the Order search area of your account. |
||||||||||||||||||||||||||||||||||||
ExternalReference |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Set external reference identifiers for orders. Enables you to replicate the functionality of the REF parameter included into Buy Links. Maximum 100 characters. If there is a need for longer references, you can apply an md5 hash for any string value, resulting in a 32 characters string. You can verify the hash after the order notification, on the client side. |
||||||||||||||||||||||||||||||||||||
ShopperRefNo |
Optional (string) |
|||||||||||||||||||||||||||||||||||
External shopper identifier. |
||||||||||||||||||||||||||||||||||||
Status |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The status of the order:
|
||||||||||||||||||||||||||||||||||||
ApproveStatus |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The status of the order resulted from the evaluation by the Avangate anti-fraud system or by a member of the anti-fraud department. This status varies for new purchases and for orders requiring customers to make manual payments. Possible values:
|
||||||||||||||||||||||||||||||||||||
VendorApproveStatus |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shows if you approved or not a partner order. Possible values:
|
||||||||||||||||||||||||||||||||||||
Language |
Optional (string) |
|||||||||||||||||||||||||||||||||||
ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.” |
||||||||||||||||||||||||||||||||||||
OrderDate |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Y-m-d H:i:s (2014-05-22 00:12:12) The datetime stamp (in the API time zone defined in cPanel) when customers place their orders. |
||||||||||||||||||||||||||||||||||||
FinishDate |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Y-m-d H:i:s (2014-05-22 00:12:12) The datetime stamp (in the API time zone defined in cPanel) when the order reach the Complete status.
NULL for order that did not reach the Complete/Finished stage. |
||||||||||||||||||||||||||||||||||||
Source |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The link source for the sales. Enables you to replicate the functionality of the SRC (separate link identifier) parameter when included into Buy Links. Use the SRC parameter to track sale sources. Maximum length 255 characters. Cannot be null. |
||||||||||||||||||||||||||||||||||||
AffiliateSource |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The link source for affiliate referred sales. Similar to the functionality of the SRC (separate link identifier) parameter included into Buy Links, but controlled by the AFFSRC parameter. Affiliates use the AFFSRC parameter to track sale sources for their referrals. Maximum length 255 characters. |
||||||||||||||||||||||||||||||||||||
AffiliateId |
Optional (int) |
|||||||||||||||||||||||||||||||||||
Identifier belonging to affiliates who refer orders. |
||||||||||||||||||||||||||||||||||||
AffiliateName |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Affiliate name. |
||||||||||||||||||||||||||||||||||||
AffiliateUrl |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Affiliate website URL from the Affiliate Details. |
||||||||||||||||||||||||||||||||||||
RecurringEnabled |
Optional (boolean) |
|||||||||||||||||||||||||||||||||||
true or false, depending on whether the shoppers checked the subscription auto-renewal checkbox or not, during the purchase process. |
||||||||||||||||||||||||||||||||||||
HasShipping |
Optional (boolean) |
|||||||||||||||||||||||||||||||||||
true or false, depending on whether the order requires shipping. |
||||||||||||||||||||||||||||||||||||
BillingDetails |
Optional (Object) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
Person |
Object |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
FirstName |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper name. |
||||||||||||||||||||||||||||||||||||
LastName |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper surname. |
||||||||||||||||||||||||||||||||||||
CountryCode |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper country. ISO 3166 two-letter code. |
||||||||||||||||||||||||||||||||||||
State |
Optional (string) – Required for US, Brazil, India and Romania |
|||||||||||||||||||||||||||||||||||
The state in the shopper's country. Mandatory when you set the Billing Country to US, Brazil, India and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code. |
||||||||||||||||||||||||||||||||||||
City |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper city. |
||||||||||||||||||||||||||||||||||||
Address1 |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper address. |
||||||||||||||||||||||||||||||||||||
Address2 |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper address. |
||||||||||||||||||||||||||||||||||||
Zip |
Optional (string) |
|||||||||||||||||||||||||||||||||||
ZIP/ Postal code. |
||||||||||||||||||||||||||||||||||||
|
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper email address. |
||||||||||||||||||||||||||||||||||||
Phone |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL. |
||||||||||||||||||||||||||||||||||||
Company |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Company name. Can be null for end users. When present, you also need to provide the FiscalCode. |
||||||||||||||||||||||||||||||||||||
FiscalCode |
Optional (string) – Required for Brazil |
|||||||||||||||||||||||||||||||||||
• For companies, it needs to be the VAT ID. Avangate will validate the value provided and throw an error if the VAT ID is invalid/incorrect when calling setPaymentDetails. When present, you also need to provide the Company name. • Mandatory when the Billing Country is set to Brazil. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ). • Mandatory when the Billing Country is set to India and purchase is made by a Company. • Can be null for end users. |
||||||||||||||||||||||||||||||||||||
DeliveryDetails |
Optional (Object) Optional. When missing, Avangate uses the same details as for the BillingDetails object. |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
Person |
Object |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
FirstName |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper name from the delivery details. |
||||||||||||||||||||||||||||||||||||
LastName |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper surname from the delivery details. |
||||||||||||||||||||||||||||||||||||
CountryCode |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper country. ISO 3166 two-letter code from the delivery details. |
||||||||||||||||||||||||||||||||||||
State |
Optional (string) – Required for US, Brazil and Romania |
|||||||||||||||||||||||||||||||||||
The state in the shopper's country from the delivery details. Mandatory when you set the Billing Country to US, Brazil and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code. |
||||||||||||||||||||||||||||||||||||
City |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper city from the delivery details. |
||||||||||||||||||||||||||||||||||||
Address1 |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper address from the delivery details. |
||||||||||||||||||||||||||||||||||||
Address2 |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper address from the delivery details. |
||||||||||||||||||||||||||||||||||||
Zip |
Optional (string) |
|||||||||||||||||||||||||||||||||||
ZIP/ Postal code from the delivery details. |
||||||||||||||||||||||||||||||||||||
|
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper email address from the delivery details. |
||||||||||||||||||||||||||||||||||||
Phone |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL. |
||||||||||||||||||||||||||||||||||||
Company |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode. |
||||||||||||||||||||||||||||||||||||
PaymentDetails |
Optional (Object) |
|||||||||||||||||||||||||||||||||||
Adapt this object to the desired payment method. |
||||||||||||||||||||||||||||||||||||
Type |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The payment method:
|
||||||||||||||||||||||||||||||||||||
Currency |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The currency ISO code for the payment - ISO 4217. Example: “usd.” |
||||||||||||||||||||||||||||||||||||
PaymentMethod |
Optional (object) |
|||||||||||||||||||||||||||||||||||
Object structure and parameters differ according to payment method selected and API method (placing orders (POST) vs. retrieving order data (GET)). For payments with credit cards, PalPay Express, previous order reference and purchase order use the objects below.
For payments with check and wire, send only the ‘CHECH’ and ‘WIRE’ strings.
null for 0 value orders for which you’re not requiring customers to enter payment details. |
||||||||||||||||||||||||||||||||||||
PaymentDetailsCard |
Optional (object) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
CardType |
Optional (string) |
|||||||||||||||||||||||||||||||||||
visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo |
||||||||||||||||||||||||||||||||||||
FirstDigits |
Optional (string) |
|||||||||||||||||||||||||||||||||||
First four digits of the credit card. |
||||||||||||||||||||||||||||||||||||
LastDigits |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Last four digits of the credit card. |
||||||||||||||||||||||||||||||||||||
CheckPaymentDetails |
Optional (Object) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
Beneficiary |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The beneficiary of the payment. Can be NULL. |
||||||||||||||||||||||||||||||||||||
CheckPostalAddress |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The address of the beneficiary. Can be NULL. |
||||||||||||||||||||||||||||||||||||
Amount |
Optional (double) |
|||||||||||||||||||||||||||||||||||
The total costs incurred by the customer for an order. Can be NULL. |
||||||||||||||||||||||||||||||||||||
Currency |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The currency ISO code of the order/payment - ISO 4217. Can be NULL. |
||||||||||||||||||||||||||||||||||||
PayPalExpress |
Optional (Object) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
|
Optional (string) |
|||||||||||||||||||||||||||||||||||
Email address customers use for their PayPal account. |
||||||||||||||||||||||||||||||||||||
ReturnURL |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The PayPal Express Checkout redirect URL returned by calling the getPayPalExpressCheckoutRedirectURL method. The return URL is the page on your website to which PayPal redirects your buyer's browser after the buyer logs into PayPal and approves the payment. Typically, this is a secure page (https://...) on your site. |
||||||||||||||||||||||||||||||||||||
CancelURL |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The cancel URL is the page on your website to which PayPal redirects your buyer's browser if the buyer does not approve the payment. Typically, this is the secure page (https://...) on your site from which you redirected the buyer to PayPal. |
||||||||||||||||||||||||||||||||||||
WirePaymentDetails |
Optional (Object) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
Amount |
Optional (double) |
|||||||||||||||||||||||||||||||||||
The total costs customers incur. Can be NULL. |
||||||||||||||||||||||||||||||||||||
Currency |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The currency ISO code of the order - ISO 4217. Can be NULL. |
||||||||||||||||||||||||||||||||||||
PaymentReference |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Transaction identifier. Can be NULL. |
||||||||||||||||||||||||||||||||||||
RoutingNumber |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Identification number assigned to financial institutions. Can be NULL. |
||||||||||||||||||||||||||||||||||||
BankAccounts |
Optional (Array of objects) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
Beneficiary |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The beneficiary of the payment. Can be NULL. |
||||||||||||||||||||||||||||||||||||
BankName |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The name of the beneficiary's bank. Can be NULL. |
||||||||||||||||||||||||||||||||||||
BankCountry |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The country of the beneficiary's bank. Can be NULL. |
||||||||||||||||||||||||||||||||||||
BankCity |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The city of the beneficiary's bank. Can be NULL. |
||||||||||||||||||||||||||||||||||||
BankAddress |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The address of the beneficiary's bank. Can be NULL. |
||||||||||||||||||||||||||||||||||||
BankAccount |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The number for the account in which customers transfer the funds. Can be NULL. |
||||||||||||||||||||||||||||||||||||
BankAccountIban |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The IBAN of the beneficiary's bank. Can be NULL. |
||||||||||||||||||||||||||||||||||||
BankAccountSwiftCode |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The Swift Code of the beneficiary's bank. Can be NULL. |
||||||||||||||||||||||||||||||||||||
Currency |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The currency ISO code for the bank account - ISO 4217. Can be NULL. |
||||||||||||||||||||||||||||||||||||
CustomerIP |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Shopper IP. |
||||||||||||||||||||||||||||||||||||
CustomerDetails |
Object Avangate populates the parameters of the customer entity with information from the customer whose AvangateCustomerReference or ExternalCustomerReference you send during the purchase. |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
AvangateCustomerReference |
Optional (Int) |
|||||||||||||||||||||||||||||||||||
System-generated Avangate customer reference. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by adding the AV_CUSTOMERID (case sensitive) parameter to buy links. The Avangate system generates default customer numerical (integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions. |
||||||||||||||||||||||||||||||||||||
ExternalCustomerReference |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The external customer reference you control. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by adding the CUSTOMERID (case sensitive) parameter to buy links. |
||||||||||||||||||||||||||||||||||||
FirstName |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Customer's first name. |
||||||||||||||||||||||||||||||||||||
LastName |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Customer's last name. |
||||||||||||||||||||||||||||||||||||
CountryCode |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Customer's country code (ISO 3166 two-letter code). |
||||||||||||||||||||||||||||||||||||
State |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Customer's state. For example, "Alabama","Alaska","Arizona". |
||||||||||||||||||||||||||||||||||||
City |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Customer's city. |
||||||||||||||||||||||||||||||||||||
Address1 |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Customer's address. |
||||||||||||||||||||||||||||||||||||
Address2 |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Customer's address. |
||||||||||||||||||||||||||||||||||||
Zip |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Zip code. |
||||||||||||||||||||||||||||||||||||
|
Optional (string) |
|||||||||||||||||||||||||||||||||||
Customer's email. |
||||||||||||||||||||||||||||||||||||
Phone |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Customer's phone number. |
||||||||||||||||||||||||||||||||||||
Company |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Company name. |
||||||||||||||||||||||||||||||||||||
FiscalCode |
Optional (string) |
|||||||||||||||||||||||||||||||||||
For companies, it needs to be the VAT ID. Avangate validates this values and throws an error if the VAT ID is invalid/incorrect. When present, you need to also provide Company name.
Can be null for end users. |
||||||||||||||||||||||||||||||||||||
Fax |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Customer's fax number. |
||||||||||||||||||||||||||||||||||||
Enabled |
Optional (boolean) |
|||||||||||||||||||||||||||||||||||
true or false, depending on whether the customer account is active or inactive. An active customer account features at least one Active or Past due subscription. |
||||||||||||||||||||||||||||||||||||
Trial |
Optional (boolean) |
|||||||||||||||||||||||||||||||||||
true or false, depending on whether the customer account features only trials or also paid subscriptions. |
||||||||||||||||||||||||||||||||||||
Language |
Optional (string) |
|||||||||||||||||||||||||||||||||||
ISO 639-1 two-letter code. Example: “en.” |
||||||||||||||||||||||||||||||||||||
ExistingCards |
Optional (Array of objects) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
TransientToken |
Optional (Object) |
|||||||||||||||||||||||||||||||||||
Populated only when you retrieve customer information by SSOToken. |
||||||||||||||||||||||||||||||||||||
Token |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Token for the EXISTING_PAYMENT_DATA flow. Use it to charge customers using cards they used in the past for purchases from your Avangate account. |
||||||||||||||||||||||||||||||||||||
CardType |
Optional (string) |
|||||||||||||||||||||||||||||||||||
visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo |
||||||||||||||||||||||||||||||||||||
LastDigits |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Last four digits of the credit card. |
||||||||||||||||||||||||||||||||||||
ExpirationMonth |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Card expiration month. |
||||||||||||||||||||||||||||||||||||
ExpirationYear |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Card expiration year. |
||||||||||||||||||||||||||||||||||||
NameOnCard |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Card holder name. |
||||||||||||||||||||||||||||||||||||
Origin |
Optional (String) |
|||||||||||||||||||||||||||||||||||
Avangate automatically tracks the source of purchases:
|
||||||||||||||||||||||||||||||||||||
AvangateCommission |
Optional (Int) |
|||||||||||||||||||||||||||||||||||
Avangate's commission for the order. |
||||||||||||||||||||||||||||||||||||
OrderFlow |
Optional (string) |
|||||||||||||||||||||||||||||||||||
PURCHASE_ORDER - Sent only when shoppers used Purchase Orders. REGULAR - Sent in all other cases. |
||||||||||||||||||||||||||||||||||||
GiftDetails |
Optional (object) |
|||||||||||||||||||||||||||||||||||
Contains contact details for the recipient of a gift purchase. |
||||||||||||||||||||||||||||||||||||
FirstName |
Optional (string) |
|||||||||||||||||||||||||||||||||||
First name of gift recipient. |
||||||||||||||||||||||||||||||||||||
LastName |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Last name of gift recipient. |
||||||||||||||||||||||||||||||||||||
|
Optional (string) |
|||||||||||||||||||||||||||||||||||
Email of gift recipient. Avangate uses this email for the delivery/fulfillment process. |
||||||||||||||||||||||||||||||||||||
GiftNote |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Custom text shoppers provide as a message to the gift recipient. |
||||||||||||||||||||||||||||||||||||
PODetails |
Object (optional) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
Status |
Optional (string) |
|||||||||||||||||||||||||||||||||||
PO status. Possible values:
|
||||||||||||||||||||||||||||||||||||
AutoApprove |
Optional (Boolean) |
|||||||||||||||||||||||||||||||||||
TRUE or FALSE, depending on whether you set POs to auto-approve or not. |
||||||||||||||||||||||||||||||||||||
ExtraInformation |
Optional (Object) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
|
PaymentLink |
Optional (String) |
||||||||||||||||||||||||||||||||||
|
|
Can be: 1. The PO doc upload link - If you set AutoApprove as FALSE on the original order and before shoppers upload the PO. 2. Payment link for orders with POs. Business customers can use the PaymentLink to finalize payment for orders with POs. If you set AutoApprove as TRUE on the original order and if Avangate and you approve the PO. |
||||||||||||||||||||||||||||||||||
PaymentLink |
Optional (string) |
|||||||||||||||||||||||||||||||||||
In scenarios in which an issue blocks the transaction from finalizing, Avangate provides a retry link where shopper can complete their purchase by providing new payment details. |
||||||||||||||||||||||||||||||||||||
PartnerCode |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Partner code you configured for your partner. NULL for eStore orders. |
||||||||||||||||||||||||||||||||||||
PartnerMargin |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Partner margin you set for the order. NULL for eStore orders. |
||||||||||||||||||||||||||||||||||||
PartnerMarginPercent |
Optional (double) |
|||||||||||||||||||||||||||||||||||
The percentage of the partner margin from the net value of the products ordered, minus the value of any discounts. NULL for eStore orders. |
||||||||||||||||||||||||||||||||||||
ExtraMargin |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Extra margin you offer by editing partner orders. NULL for eStore orders. |
||||||||||||||||||||||||||||||||||||
ExtraMarginPercent |
Optional (double) |
|||||||||||||||||||||||||||||||||||
The percentage of the extra partner margin from the net value of the products ordered, minus the partner margin and the value of any discounts. NULL for eStore orders. |
||||||||||||||||||||||||||||||||||||
ExtraDiscount |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Extra discount you offer by editing partner orders. NULL for eStore orders. |
||||||||||||||||||||||||||||||||||||
ExtraDiscountPercent |
Optional (double) |
|||||||||||||||||||||||||||||||||||
The percentage of the partner margin from the net value of the products ordered, minus the value of any coupon discounts. NULL for eStore orders. |
||||||||||||||||||||||||||||||||||||
LocalTime |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Local shopper time in the following format: Y-m-d H:i:s. This parameter can impact the fraud score of an order when it's missing, NULL or incorrectly formatted. |
||||||||||||||||||||||||||||||||||||
TestOrder |
Optional (Boolean) |
|||||||||||||||||||||||||||||||||||
True for test orders. False of regular orders. |
||||||||||||||||||||||||||||||||||||
Errors |
Optional (StringArray) |
|||||||||||||||||||||||||||||||||||
Payment gateway processing errors. |
||||||||||||||||||||||||||||||||||||
Items |
Array of objects |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
ProductDetails |
Object |
|||||||||||||||||||||||||||||||||||
Name |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Product name. |
||||||||||||||||||||||||||||||||||||
ExtraInfo |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The text entered in the Additional information field when generating Buy links, or via the INFO[PRODUCT_ID] parameter used in Buy links. |
||||||||||||||||||||||||||||||||||||
RenewalStatus |
Optional (boolean) |
|||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||
Subscriptions |
Object |
|||||||||||||||||||||||||||||||||||
SubscriptionReference |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Unique, system-generated subscription identifier. |
||||||||||||||||||||||||||||||||||||
PurchaseDate |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The date time stamp when shoppers acquired their subscriptions corresponding to the moment when the Avangate system marks the purchase as finished. Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.
e.g. 2015-08-11 15:18:52 |
||||||||||||||||||||||||||||||||||||
SubscriptionStartDate |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Example: 2015-09-29 17:57:59 |
||||||||||||||||||||||||||||||||||||
ExpirationDate |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The date time stamp of upcoming renewal/expiration for subscriptions not taking into account grace period settings.
Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.
e.g. 2015-09-11 15:18:52 |
||||||||||||||||||||||||||||||||||||
Lifetime |
Optional (boolean) |
|||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||
Trial |
Optional (boolean) |
|||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||
Enabled |
Optional (boolean) |
|||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||
RecurringEnabled |
Optional (boolean) |
|||||||||||||||||||||||||||||||||||
|
PriceOptions |
Optional (array of strings) |
||||||||||||||||||||||||||||||||||
Array of price option codes. |
||||||||||||||||||||||||||||||||||||
Code |
Optional (strings) |
|||||||||||||||||||||||||||||||||||
Unique code that the Avangate system generates or that you set for each pricing options group. |
||||||||||||||||||||||||||||||||||||
Required |
Optional (boolean) |
|||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||
Options |
Optional (array of strings) |
|||||||||||||||||||||||||||||||||||
The code you set or that the Avangate system generates for each price option child inside a pricing options group parent. |
||||||||||||||||||||||||||||||||||||
Price |
Object |
|||||||||||||||||||||||||||||||||||
This object returns the price per unit at order line level.
In the case of trials, the object returns the costs for the trial to full subscription conversion. |
||||||||||||||||||||||||||||||||||||
UnitNetPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
The value per product unit, excluding sales tax/VAT expressed in the payment currency. |
||||||||||||||||||||||||||||||||||||
UnitGrossPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Total value per product unit, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts. |
||||||||||||||||||||||||||||||||||||
UnitVAT |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Sales tax/VAT per product unit expressed in the payment currency. |
||||||||||||||||||||||||||||||||||||
UnitDiscount |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Value of the discount per product unit expressed in the payment currency. |
||||||||||||||||||||||||||||||||||||
UnitNetDiscountedPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
The value per product unit, expressed in the payment currency, excluding sales tax/VAT, from which Avangate deducts the unit discount. |
||||||||||||||||||||||||||||||||||||
UnitGrossDiscountedPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Total costs shoppers incur per product unit, expressed in the payment currency. This value includes sales tax/VAT, Avangate and affiliate commissions, but Avangate deducts the value of any discounts. |
||||||||||||||||||||||||||||||||||||
UnitAffiliateCommission |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Value of the affiliate commission per product unit calculated expressed in the payment currency.
Avangate deducts discounts from the costs incurred by shoppers before calculating affiliate commissions.
Avangate does not take into account shipping costs when calculating affiliate commissions.
NULL when Avangate does not apply an affiliate commission. |
||||||||||||||||||||||||||||||||||||
Currency |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The currency ISO code for the payment - ISO 4217. Example: usd. |
||||||||||||||||||||||||||||||||||||
NetPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
The value per order line, excluding sales tax/VAT expressed in the payment currency. |
||||||||||||||||||||||||||||||||||||
GrossPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Total value per order line, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts. |
||||||||||||||||||||||||||||||||||||
NetDiscountedPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
The NetPrice value per order line (in the payment currency), excluding sales tax/VAT, from which Avangate deducts discounts. |
||||||||||||||||||||||||||||||||||||
GrossDiscountedPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Total costs shoppers incur per order line, expressed in the payment currency. This value includes sales tax/VAT, Avangate and affiliate commissions, but Avangate deducts the value of any discounts.
Example:
|
||||||||||||||||||||||||||||||||||||
Discount |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Value of the discounts per order line expressed in the payment currency. |
||||||||||||||||||||||||||||||||||||
VAT |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Value of sales tax/VAT per order line expressed in the payment currency. |
||||||||||||||||||||||||||||||||||||
AffiliateCommission |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Value of the affiliate commission per order line, calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. Avangate does not take into account shipping costs when calculating affiliate commissions. |
||||||||||||||||||||||||||||||||||||
Code |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Unique product identifier your control. Max length 256 characters. |
||||||||||||||||||||||||||||||||||||
Quantity |
Optional (integer) |
|||||||||||||||||||||||||||||||||||
Number of units |
||||||||||||||||||||||||||||||||||||
SKU |
Optional (string) |
|||||||||||||||||||||||||||||||||||
SKU identifier. |
||||||||||||||||||||||||||||||||||||
CrossSell |
Optional (Object) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
ParentCode |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The product code of the master product you set to trigger the campaign. |
||||||||||||||||||||||||||||||||||||
CampaignCode |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Unique, system-generated identifier for cross-sell campaigns. |
||||||||||||||||||||||||||||||||||||
Trial |
Optional (Object) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
Period |
Optional (integer) |
|||||||||||||||||||||||||||||||||||
The length of the trial subscription lifetime in days. |
||||||||||||||||||||||||||||||||||||
GrossPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Total trial price in the payment currency before Avangate deducts any taxes, discounts, etc. |
||||||||||||||||||||||||||||||||||||
VAT |
Optional (double) |
|||||||||||||||||||||||||||||||||||
The total value of taxes for the trial in the payment currency, before Avangate deducts any discounts. |
||||||||||||||||||||||||||||||||||||
NetPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Total trial price in the payment currency, not including taxes, before Avangate deducts any discounts. |
||||||||||||||||||||||||||||||||||||
AdditionalFields |
Optional (array of objects) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
Code |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The alpha-numeric characters, underscores and dashes that are set as the field identifier. |
||||||||||||||||||||||||||||||||||||
Text |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Field text visible to shoppers in the cart. |
||||||||||||||||||||||||||||||||||||
Value |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Selected field value. |
||||||||||||||||||||||||||||||||||||
Promotion |
Optional (object) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
Name |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Promotion name. |
||||||||||||||||||||||||||||||||||||
Description |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Promotion description. |
||||||||||||||||||||||||||||||||||||
StartDate |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The date when you set the promotion to start. NULL for promotions that start immediately after you create them. |
||||||||||||||||||||||||||||||||||||
EndDate |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The date when you set the promotion to end. NULL for promotions you want active indefinitely. |
||||||||||||||||||||||||||||||||||||
MaximumOrdersNumber |
Optional (integer) |
|||||||||||||||||||||||||||||||||||
Avangate only applies the promotion to a maximum number of orders you define.
Can be NULL if you want the promotion to apply to an unlimited number of orders. |
||||||||||||||||||||||||||||||||||||
MaximumQuantity |
Optional (integer) |
|||||||||||||||||||||||||||||||||||
Discount only applies to a maximum number of units purchased through a single order, smaller than the quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units. |
||||||||||||||||||||||||||||||||||||
InstantDiscount |
Optional (boolean) |
|||||||||||||||||||||||||||||||||||
The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon. |
||||||||||||||||||||||||||||||||||||
Coupon |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Promotion coupon/voucher. |
||||||||||||||||||||||||||||||||||||
DiscountLabel |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency. |
||||||||||||||||||||||||||||||||||||
Enabled |
Optional (string) |
|||||||||||||||||||||||||||||||||||
true or false, depending on whether a promotion is active or disabled. |
||||||||||||||||||||||||||||||||||||
Type |
Optional (string) |
|||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||
Promotions |
Optional (Array of objects) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
Name |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Promotion name. |
||||||||||||||||||||||||||||||||||||
Description |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Promotion description. |
||||||||||||||||||||||||||||||||||||
StartDate |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The date when you set the promotion to start. NULL for promotions that start immediately after you create them. |
||||||||||||||||||||||||||||||||||||
EndDate |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The date when you set the promotion to end. NULL for promotions you want active indefinitely. |
||||||||||||||||||||||||||||||||||||
MaximumOrdersNumber |
Optional (integer) |
|||||||||||||||||||||||||||||||||||
Avangate only applies the promotion to a maximum number of orders you define.
Can be NULL if you want the promotion to apply to an unlimited number of orders. |
||||||||||||||||||||||||||||||||||||
MaximumQuantity |
Optional (integer) |
|||||||||||||||||||||||||||||||||||
Discount only applies to a specific number of units purchased at once, smaller than the maximum quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units. |
||||||||||||||||||||||||||||||||||||
InstantDiscount |
Optional (boolean) |
|||||||||||||||||||||||||||||||||||
The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon. |
||||||||||||||||||||||||||||||||||||
Coupon |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Promotion coupon/voucher. |
||||||||||||||||||||||||||||||||||||
DiscountLabel |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Discounts can be set as a percentage from the product price or as a fixed amount in the payment currency. |
||||||||||||||||||||||||||||||||||||
Enabled |
Optional (string) |
|||||||||||||||||||||||||||||||||||
true or false, depending on whether a promotion is active or disabled. |
||||||||||||||||||||||||||||||||||||
Type |
Optional (string) |
|||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||
AdditionalFields |
Optional (array of objects) |
|||||||||||||||||||||||||||||||||||
Details below. |
||||||||||||||||||||||||||||||||||||
Code |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The alpha-numeric characters, underscores and dashes that are set as the field identifier. |
||||||||||||||||||||||||||||||||||||
Text |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Field text visible to shoppers in the cart. |
||||||||||||||||||||||||||||||||||||
Value |
Optional (string) |
|||||||||||||||||||||||||||||||||||
Selected field value. |
||||||||||||||||||||||||||||||||||||
Currency |
Optional (string) |
|||||||||||||||||||||||||||||||||||
The currency ISO code for the payment - ISO 4217. Example: usd. |
||||||||||||||||||||||||||||||||||||
NetPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Order value excluding sales tax/VAT expressed in the payment currency. |
||||||||||||||||||||||||||||||||||||
GrossPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Total order value, including sales tax/VAT expressed in the payment currency. GrossPrice does not reflect any discounts. |
||||||||||||||||||||||||||||||||||||
NetDiscountedPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
The NetPrice order value excluding sales tax/VAT, from which Avangate deducts discounts. NetDiscountedPrice is expressed in the payment currency. |
||||||||||||||||||||||||||||||||||||
GrossDiscountedPrice |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Total costs shoppers incur, expressed in the payment currency. This value includes sales tax/VAT, Avangate and affiliate commissions, but Avangate deducts the value of any discounts.
For example:
|
||||||||||||||||||||||||||||||||||||
Discount |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Value of the discounts for an order expressed in the payment currency. |
||||||||||||||||||||||||||||||||||||
VAT |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Value of sales tax/VAT expressed in the payment currency. |
||||||||||||||||||||||||||||||||||||
AffiliateCommission |
Optional (double) |
|||||||||||||||||||||||||||||||||||
Value of the affiliate commission for the order calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. Avangate does not take into account shipping costs when calculating affiliate commissions. |