| Verifone Developer Portal

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	johnsmith@email.com
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;
}

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:

AUTHRECEIVED – Avangate blocks the amount corresponding to the transaction, but the process of collecting funds is incomplete.
PENDING - Avangate has yet to block the amount corresponding to the transaction or shoppers used an offline payment method like wire transfer.
COMPLETE – The shopper completed the transaction for the purchase and Avangate or you fulfilled the order (when required).
CANCELED – Avangate cancels orders for which shoppers fail to transfer funds in due time.
REVERSED – Avangate reverses order transactions that never reach the Complete/Finished stage. Shoppers never complete transactions for such purchases.
REFUND – Avangate refunds orders only after they reach the Complete/Finished stage and returns the funds collected to shoppers.

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:

WAITING: The Avangate anti-fraud system or a member of the anti-fraud department has yet to approve the order.
OK: The Avangate anti-fraud system or a member of the anti-fraud department approved the order.
INVALIDDATA: Shopper-supplied data is invalid – Avangate did not approve the order.
FRAUD: The order is fraudulent.

VendorApproveStatus

Optional (string)

Shows if you approved or not a partner order. Possible values:

OK
WAITING
REJECTED

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.

Email

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.

Email

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:

CC (credit/debit card - including local Brazilian cards).
PAYPAL
PAYPAL_EXPRESS
TEST (for test orders).
PREVIOUS_ORDER (place new orders using the reference of a previous order).
EXISTING_PAYMENT_DATA (use a card one of your customers already used to purchase from your account).
WIRE – the placeOrder response includes Wire payment details.
CHECK – the placeOrder response includes Check payment details.
PURCHASEORDER - use for orders with POs.
FREE – for 0 value orders for which you’re not requiring customers to provide payment details.

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.

Email

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.

Email

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:

Web – When customers use the desktop version of the Avangate shopping cart.
API - When customers use a custom, API-based ordering interface.
Mobile - When customers use the mobile version of the Avangate shopping cart.
Automatic Billing – For auto-renewals and trial conversions.

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.

Email

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:

PO status API	PO status cPanel
AWAITING_UPLOAD	Awaiting form submission - Waiting for the customer to submit the PO form
TIME_EXPIRED	Expired, form not received - The customer did not submit the PO form
AWAITING_MERCHANT	Awaiting your confirmation - PO approved by Avangate, awaiting vendor confirmation
MERCHANT_TIME_EXPIRED	Expired, PO not confirmed - You didn't confirm/reject the PO
AWAITING_MERCHANT	Rejected - You rejected the PO
AWAITING_PAYMENT	Awaiting payment - You approved the PO, waiting for payment
AWAITING_PAYMENT	Expired, not paid - The customer did not complete the PO payment. Avangate accepts payments up to 30 days after the PO payment interval expires
NOT_PAID	Canceled, not paid - The customer did not complete the PO payment
NOT_PAID	Canceled by Avangate - Avangate canceled the PO
NOT_PAID	Canceled via API - You canceled the PO (via API)
PAID	Complete - Customer paid the PO. The order is complete

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)

true for orders renewing subscriptions.
false for all other orders: new purchases, upgrades.

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)

true – For non-recurring, evergreen subscriptions.
false – For recurring subscriptions with a specific billing cycle from 7 days to 36 months.

Trial

Optional (boolean)

true – For trial subscriptions.
false – For non-trial, recurring subscriptions with a specific billing cycle from 7 days to 36 months.

Enabled

Optional (boolean)

true – For active and past due subscriptions.
false – For expired and cancelled subscriptions.

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)

true – you require shoppers to select the price option through the way in which you configured pricing.
false – you do not require shoppers to select the price option.

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:

UnitNetPrice: 99
UnitGrossPrice: 120.39
UnitVAT: 21.39
UnitDiscount: 9.9
UnitNetDiscountedPrice: 89.1
UnitGrossDiscountedPrice: 110.49
UnitAffiliateCommission: 22.28
Currency: "usd"
NetPrice: 198
GrossPrice: 240.77
NetDiscountedPrice: 178.2
GrossDiscountedPrice: 220.97
Discount: 19.8
VAT: 42.77
AffiliateCommission: 44.56

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)

REGULAR – product/cart line level discounts.
ORDER – quantity discounts.
GLOBAL – order-level discounts.
AFFILIATE – for discounts created by affiliates.

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)

REGULAR – product/cart line level discounts.
ORDER – quantity discounts.
GLOBAL – order-level discounts.
AFFILIATE – for discounts created by affiliates.

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:

Currency: "usd"
NetPrice: 396
GrossPrice: 486.29
NetDiscountedPrice: 376.2
GrossDiscountedPrice: 466.49
Discount: 19.8
VAT: 90.29
AffiliateCommission: 94.05

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.

Attach reseller information to an order

Overview

Use this method to add reseller details to a partner order.

Requirements

Parameters

Parameters	Type/Description
sessionID	Required (String)
	Session identifier, which is the output of the Login method. An exception is thrown if the values are incorrect.
refNo	Required (String)
	The unique, system-generated identifier of a partner order.
resellerCode	Required (String)
	Unique code identifying a specific reseller.

Response

Parameters	Type/Description
result	Boolean
	True or false

Request

<?php

require('PATH_TO_AUTH'); // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/02Authentication
require('PATH_TO_setPartner'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/Partner/00Set_partner

$refNo = 'YOUR_ORDER_REFERENCE_NUMBER';
$resellerCode = 'NEW_RESELLER_CODE';

try {
$AddedReseller= $client->setOrderReseller ($sessionID, $refNo, $resellerCode);
} catch (SoapFault $e) {
    Echo "orderReseller: " . $e->getMessage();
    exit;
}
var_dump ("orderReseller ", $AddedReseller);

Errors

Error	Description
NOT_FOUND_PARTNER	No partner set before invoking the method.
EMPTY_ORDER_REFERENCE	Order reference not provided.
INVALID_PARTNER_RESELLER_CODE	Invalid partner reseller provided.
INVALID_SUBSCRIPTION_REFERENCE	No reseller defined for this order reference.
INVALID_PARTNER_RESELLER_CODE	No partner reseller found for the specified code.

Orders with installments

Overview

2Checkout supports local Brazilian Visa, MasterCard and AMEX credit/debit cards limited to national purchases in the local currency BRL (Brazilian Real).

Requirements

Installments are available only for:
- Brazilian customers
- Local Visa, MasterCard and AMEX cards
- Non-recurring transactions
The minimum installment threshold is 5 BRL. The maximum number of installments is 6.
Mandatory information for payments also includes a shopper phone number and Fiscal Code (CPF/CNPJ).

Do local BR cards with/without installments require an addendum to my contract?

Yes. Contact 2Checkout for activation.

How does it work?

Create the Order object.
Validate the number of installments available based on total order value.
Place the order specifying the number of installments.

Funds collection for installment payments

2Checkout pays you in full, regardless of the number of installments (this is covered directly by the banks).

OrderInformation object structure

Member			Type/Description
RefNo			String
			Order reference number.
OrderNo			String
			The consecutive order number associated with orders available in the Order search.
ExternalRefNo			String
			The order reference code (max. 100 chars) provided by the seller. Empty string if missing.
ShopperRefNo			String
			External shopper identifier.
Status			String
			The status of the order: AUTHRECEIVED, PENDING, TEST (COMPLETE, CANCELED, REVERSED, REFUND statuses are only returned for the getOrder method).
ApproveStatus			String
			The status of the order approval as set either automatically by the Avangate system or manually by a member of our anti-fraud department. This status can vary for new purchases or for orders requiring customers to make manual payments. Possible values: WAITING: The order has yet to be approved. OK: The order has been approved. INVALIDDATA: The data supplied by the shopper is invalid. The order was not approved. FRAUD: The order is fraudulent.
Language			String
			Language used in the cart during the purchase process.
OrderDate			String
			The timestamp (in the API time zone defined in Control Panel) used when the order was placed. Format: Y-m-d H:i:s (2014-05-22 00:12:12).
FinishDate			String
			The timestamp (in the API time zone defined in Control Panel) when the order reached the Complete status. NULL if the order is not finalized. Format: Y-m-d H:i:s (2014-05-22 00:12:12).
Source			String
			The link source for the sales. The SRC parameter used to track every sale point generator.
AutoRenewalChecked			Boolean
			True or false, depending on whether the subscription auto-renewal checkbox was checked during the purchase process.
HasShipping			Boolean
			True or false, depending on whether the order required shipping.
BillingDetails			Object
			Details below.
	Address		String
			Shopper billing address.
	City		String
			Shopper city from the billing address.
	Country		String
			Shopper country from the billing address.
	Email		String
			Shopper billing email address.
	FirstName		String
			Shopper billing name.
	LastName		String
			Shopper billing surname.
	PostalCode		String
			Postal code from the billing address.
	State		String
			Shopper billing state. E.g.: "Alabama".
	Company		String
			Company name. Can be NULL for end users. When present, FiscalCode must also be provided.
	FiscalCode		String
			Can be null for end users. For companies, it needs to be the VAT ID, which is validated by Avangate. An error will be thrown if the VAT ID is invalid/incorrect when calling setPaymentDetails. When present, Company name must also be provided.
DeliveryDetails			Object
			Details below.
	Address		String
			Shopper delivery address.
	City		String
			Shopper delivery city.
	Country		String
			Shopper delivery country.
	Email		String
			Shopper email address.
	FirstName		String
			Shopper delivery first name.
	LastName		String
			Shopper delivery last name.
	PostalCode		String
			Shopper delivery postal code.
	State		String
			Shopper delivery state.
	Company		String
			Shopper delivery company. Can be NULL for end users.
PaymentInformation			Object
			Details below.
	Type		String
			The payment method: CC (credit/debit card) TEST (for test orders) PAYPAL WIRE OTHER (payment methods not listed above)
	Currency		String
			Payment currency ISO code – ISO 4217.
	PaymentMethod		Object
			Details below.
		FirstDigits	String
			First four credit card digits.
		LastDigits	String
			Last four credit card digits.
		CardType	String
			Card type: VISA VISAELECTRON MASTERCARD MAESTRO AMEX
Origin			String
			Order origin channel: Web API Mobile
Currency			String
			Order currency.
TotalGeneral			Double
			Total order value (the costs incurred by the shopper).
TotalWithoutTaxes			Double
			Total order value without VAT or sales tax.
Taxes			Double
			VAT or sales tax.
Shipping			Double
			Shipping costs. NULL if not applicable.
AvangateCommission			Double
			Avangate order commission.
AffiliateCommission			Double
			Avangate affiliate commission. NULL if not applicable.
Discount			Double
			Order discount value. NULL if not applicable.
Products			Array of objects
			Details below.
	Id		Int
			Unique, system-generated product ID from the Avangate platform.
	Code		String
			The code you can attach to products when configuring, editing or importing them in the Avangate platform.
	Name		String
			Product name.
	SKU		String
			Product SKU.
	ExtraInfo		String
			Additional information text entered when generating buy links or via the INFO[productid]= parameter.
	Quantity		Int
			Purchase number of products.
	PromotionName		String
			Promotion name.
	UnitPrice		Double
			Price per product unit.
	UnitTaxes		Double
			Taxes per product unit.
	UnitDiscount		Double
			Discount per product unit.
	UnitAffiliateCommision		Double
			Affiliate commission per product unit.
	Options		Array of objects
			Array of product pricing options with the structure detailed below.
		OptionText	String
			The name of the pricing option selected during the purchase process.
		OptionValue	String
			Unique option value code.
		OptionalValue	String
			Unique option value code.
		Operator	String
			ADD or SUBTRACT, depending on whether the option adds or subtracts a specific amount to or from the product price.
		Usage	String

		Price	String
			The amount added or subtracted by the pricing options.
		GroupName	String
			Product options group name.
	AdditionalFields		Array of objects
			Array of AdditionalFields information objects with the structure detailed below.
		FieldText	String
			Field text visible to shoppers in the cart.
		FieldValue	String
			The alpha-numeric characters, underscores and dashes set as the field identifier.
	Subscriptions		Array of objects
			Array of subscriptions objects with the structure detailed below.
		SubscriptionReference	String
			Unique, system-generated subscription identifier.
		PurchaseDate	String
			Purchase date.
		ExpirationDate	String
			Renewal/expiration date, not considering grace period settings.
		Lifetime	Boolean
			Subscription duration.
		Trial	Boolean
			TRUE or FALSE depending on whether the subscription is a trial.
		Disabled	Boolean
			TRUE or FALSE depending on whether the subscription is disabled.
		RecurringEnabled	Boolean
			TRUE or FALSE depending on whether the subscription renewal system is enabled.
AdditionalFields			Array of objects
			Array of AdditionalFields information objects with the structure detailed below.
	FieldText		String
			Field text visible to shoppers in the cart.
	FieldValue		String
			The alpha-numeric characters, underscores and dashes set as the field identifier.
PartnerCode			String
			Partner code defined in the Control Panel. NULL for eStore orders.
PartnerMargin			Double
			Partner margin offered for the order. NULL for eStore orders.
PartnerMarginPercent			Double
			Partner margin percentage from the net value of the products ordered, minus the value of any discounts. NULL for eStore orders.
ExtraMargin			Double
			Extra margin offered. NULL for eStore orders.
ExtraMarginPercent			Double
			Extra partner margin percentage from the net value of the products ordered, minus the partner margin and the value of any discounts. NULL for eStore orders.
ExtraDiscount			Double
			Extra discount offered. NULL for eStore orders.
ExtraDiscountPercent			Double
			Partner margin percentage from the net value of the products ordered, minus the value of any coupon discounts. NULL for eStore orders.

Use Test orders

Overview

Place a TEST order using catalog products defined in your Control Panel.

Requirements

Set the Payment details type to TEST in order to create an order in a test environment.

Parameters

Parameters	Type/Description
sessionID	Required (string)
	Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate throws an exception if the values are incorrect. The sessionID expires in 10 minutes.
Order	Required (Object)
	Object designed to collect all data necessary for an order, including billing, product/subscription plan and payment details.

Response

Parameters	Type/Description
Order information	Object
	Object containing order information.

Request

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'usd';
$Order->Country = 'US';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->Affiliate = new stdClass();
$Order->Affiliate->AffiliateCode = 'Partner123'
$Order->Affiliate->AffiliateSource = 'MobilePlatform'
$Order->CustomerReference = NULL;

$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = NULL;
$Order->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->Promotion = NULL;
$Order->Items[0]->SubscriptionStartDate = NULL; //If empty or null, subscriptions become active when purchase is made.

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'John';
$Order->BillingDetails->LastName = 'Doe';
$Order->BillingDetails->CountryCode = 'us';
$Order->BillingDetails->State = 'California';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '90210';
$Order->BillingDetails->Email = 'cosmin.deftu@avangate.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'TEST';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CCID = '123';

$Order->Promotions = NULL;
$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

try {
    $prevrefOrder = $client->placeOrder($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "prevrefOrder: " . $e->getMessage();
    exit;
}
var_dump("prevrefOrder", $prevrefOrder);

Extract invoices

Overview

Use the getInvoices method to extract shopper invoices from the 2Checkout system based on unique order references. The method returns the binary code for invoices in the PDF file format, Base64 encoded (Base64 is used to represent binary data in the ASCII string format).

getInvoices works for COMPLETE orders for which an invoice was already issued. For refunded orders, getInvoices provides two shopper invoices, one for the original order and the second for the refund, reflecting the repayment made.

In the case of cross-selling orders which contain products from different merchants, getInvoice enables you to re-send only the invoices for your own offerings.

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.
reference	Required (string)
	Unique, system generated reference for orders.

Response

Parameters		Type/Description
InvoicesData		Array of objects
		Details below.
	Sale	String
		Base64 encoded PDF file containing an invoice for a Complete order.
	Cancellation	String
		Base64 encoded PDF file containing a cancellation invoice.
	Refunds	Array of string
		Base64 encoded PDF files containing invoices for Refunds.

Request

<?php

require ('PATH_TO_AUTH');

$reference = 'ORDER_REFERENCE';

$jsonRpcRequest = array (
'method' => 'getInvoices',
'params' => array($sessionID, $Reference),
'id' => $i++,
'jsonrpc' => '2.0');

var_dump (callRPC((Object)$jsonRpcRequest, $host, true));

Configure renewal notifications

Overview

Renewal e-mail notifications are used extensively as one of the main mechanisms to notify users of upcoming or pending subscription charges, thus ensuring higher recurring revenue rates. You can set your own custom notification schedule for sending out renewal notification emails, within the boundaries of a 90 day limit around the renewal date.

Benefits

Custom renewal notifications increase recurring payments conversion – conversion for subscription renewals can benefit from a boost with extended custom schedules +/-90 days renewal date.
Closer matching between subscription renewal notifications and grace period - notify shoppers in a more relevant manner of upcoming recurring charges, during their grace periods (closer matching of grace period expiration timelines).
Added flexibility – set your own notifications schedule in a more personalized manner, run more extensive A/B tests on notifications campaigns and decide to apply optimal schedules which bring highest results for your target customers.

Workflow

Go to the Global renewal settings page.
Click the Add notification button in the renewal emails section.
Choose when to send renewal emails:
- on subscription expiration date
- before subscription expiration date
  - Enter the desired number of days before expiration when you want notifications to be sent. The value cannot be larger than 90 days.
- after subscription expiration date
  - Enter the desired number of days before after when you want notifications to be sent. The value cannot be larger than 90 days.
Choose the type of renewal you want the notifications to be sent for:
- Manual renewal
- Automatic renewal
Click Add notification.
Click Save.

Best practices for renewal notifications

You decide what is the best setup and how often you should engage your customers regarding their renewals. The success of each renewal notice schedule varies depending on: product type, sales process and customer location. While there isn’t sufficient data to offer a definitive optimal schedule, we do recommend:

Setting the products with grace period > 7 days, to enable shoppers to renew the subscriptions also after the expiration;
Defining different messages for the renewal notifications based on the moment when it is sent (for example - create a sense of urgency in the one sent very close to the expiration date)
Setting up an additional notification (45 or 60 days prior to expiration) for companies selling B2B (business-to-business) as B2B renewals can be a complex process, requiring approvals and budgeting decisions, so starting the renewal process earlier could improve your on-time renewal rates and customer satisfaction;
Adapting your notification schedule according to your customers’ preferences:
- Track your renewal data: Which renewal notification has the highest success? Do most of your customers renew right after the first notification? If so, we’d say the timing is working. Do you have many customers renewing during their grace period? If so, you might want to start the renewal notifications earlier;
- If customers have manual renewal enabled, try and win them over with discounts for early renewals or incentive them to opt for automatic renewal.

Here's two examples of setup that we recommend, depending on the renewal configuration of your product: 6 months and 12 months billing cycles.

No.	Setup for subscriptions with 6 months billing cycles	Setup for subscription with 12 months billing cycles
a)	Two notifications before expiration date: 15 and 7 days	Three notifications before expiration date: 30, 15 and 7 days
b)	One notification on the expiration date	One notification on the expiration date
c)	One notification after expiration date: 5 days	One notification after expiration date: 5 days

Retrieve a pricing configuration by name

Overview

Use the getPricingConfigurationByName method to extract information on a specific pricing configuration you set for a subscription plan/product.

Parameters

sessionID	Required (string)
	Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate throws an exception if the values are incorrect. The sessionID expires in 10 minutes.
ProductCode	Required (string)
	The unique product code you control and not the system-generated product ID.
PricingConfigurationName	Required (string)
	The name of the pricing configuration.
SchemaType	Required (string)
	FLAT (without Base Price) DYNAMIC (with Base Price)
PriceType	Optional (string)
	Possible values: NET or GROSS

Response

PricingConfiguration

Object

Request

<?php

$host   = "https://api.avangate.com";
$client = new SoapClient($host . "/soap/4.0/?wsdl", array(
    'location' => $host . "/soap/4.0/",
    "stream_context" => stream_context_create(array(
        'ssl' => array(
            'verify_peer' => false,
            'verify_peer_name' => false
        )
    ))
));


function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}

$merchantCode = "YOURCODE123"; //your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key          = "SECRET_KEY"; //your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')

$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);

try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}

catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}

$ProductCode = '4643116';
$PricingConfigurationName = 'No base';
$SchemaType               = 'FLAT';
$PriceType                = 'NET';

try {
    $ProductPricingConfiguration = $client-> getPricingConfigurationByName ($sessionID, $ProductCode, $PricingConfigurationName, $SchemaType, $PriceType);
}

catch (SoapFault $e) {
    echo "Pricing Configuration: " . $e->getMessage();
    exit;
}

var_dump("Pricing Configuration", $ProductPricingConfiguration);


?>

Overview

Overview

Availability

Build the IPN HASH signature

Example

PHP Hash Example

PHP Hash Response Example

Validation

Node.JS (ES6) sample

Python sample (Flask)

Verifone IPN send request sample

Overview

Attributes

Overview

Requirements

Parameters

Response

Request

Errors

Overview

Requirements

Do local BR cards with/without installments require an addendum to my contract?

How does it work?

Funds collection for installment payments

Overview

Requirements

Parameters

Response

Request

Overview

Parameters

Response

Request

Overview

Benefits

Workflow

Best practices for renewal notifications

Overview

Parameters

Response

Request

Need help?

Not yet a Verifone customer?