Overview

Use the getCustomerInformation method to retrieve the details of a customer entity from the Avangate system.

Parameters

Request

<?php

require ('PATH_TO_AUTH');

$customerReference = CUSTOMER_REFERENCE;
$externalCustomerReference = 'EXT_CUSTOMER_REFERENCE'; //Optional, but if you include it it needs to belong to the same customer as the internal Avangate customer reference

$jsonRpcRequest = array (
'method' => 'getCustomerInformation',
'params' => array($sessionID, $customerReference, $externalCustomerReference),
'id' => $i++,
'jsonrpc' => '2.0');

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

Response

Overview

Place an order with on the fly pricing using catalog products defined in your Control Panel. Set the Items->Price->Type parameter to CUSTOM, while adding the dynamic price to the Items->Price->Amount parameter.

Payment methods

You can place orders with dynamic pricing using the following payment methods:

• Credit cards
• PayPal
• WeChat Pay
• iDEAL
• Purchase Order

Parameters

Response

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]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->SubscriptionStartDate = NULL; //If empty or null, subscriptions become active when purchase is made.


$Order->Items[0]->Price = new stdClass();
$Order->Items[0]->Price->Amount = 11; // set the price of the order
$Order->Items[0]->Price->Type = 'CUSTOM'; // must be sent as CUSTOM in order to use dynamic pricing

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'FirstName';
$Order->BillingDetails->LastName = 'LastName';
$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 = 'email@2checkout.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC'; // you can also use TEST, PAYPAL, PURCHASEORDER, WE_CHAT_PAY, IDEAL, CHECK. The flow and requirements are different for each payment method.
$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->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

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

var_dump("newOrder", $newOrder);

Overview

To start, you need to have the buy-link with the return-URL and return-type parameters defined and signed. Read here how to create such a link and sign its parameters.

After opening the buy-link in the browser, the shopper will be redirected to the 2Checkout page. During the booting of the cart, the signature is checked against the buy-link query parameters.

In case of an invalid signature, the buy-link parameter is disregarded and the shopper will see the 'Thank You' page instead of a redirect.

In case of a valid signature for the buy-link parameters and successful order placing, the shopper is redirected to the page you have defined in the return parameters. The return-URL is appended with all buy-link parameters and with some extra parameters, all of them are signed and their signature should be present in the query parameters. 

In the backend, you need to gather all these parameters and validate the parameter's hash you generate with the new signature appended to the return-URL.

To generate the hash and validate the return URL, follow the steps below. 

Build the ConvertPlus Signature

To sign a ConvertPlus buy-link, you need to follow these steps:

1. Sort the parameters that require a signature alphabetically.
2. Serialize the parameters and append to them the length of their values.
3. Concatenate the resulting values.
4. The serialized value is then encrypted with your Buy-Link Secret Word using the HMAC method (algorithm sha256).
5. The resulting value is added to the buy-link under the signature parameter.

In order to generate a valid ConvertPlus signature, you should include all the parameters from the return URL, except the signature.

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.

1. Let's consider the following parameters:

• return-url = 'https://www.yourbackend.com'
• return-type = 'redirect'
• merchant = 'YOUR_VENDOR_CODE' (this is the merchant code)
• prod = 'TEST_PROD'  (this is the product code)
• qty = 1
• price = 29
• tpl = default
• refno = 11606896
• total = 29
• total-currency = USD
• currency = USD

The regular return link will have the following structure:

https://www.yourbackend.com/?merchant=YOUR_VENDOR_CODE&currency=USD&return-url=https%3A%2F%yourbackend.com%2F&return-type=redirect&tpl=default&prod=TEST_PROD&price=29&qty=1&refno=11606896&total=29&total-currency=USD&signature=95052ee0c558b53040e97d7d81add2e0f1400ca0936a558910c68ddc8301fc63

2. Sort the parameters alphabetically: currency, merchant, price, prod, qty, refno, return-type, return-url, total, total-currency, tpl.

3. 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 return-type parameter has the 'redirect' value that will be serialized as '8redirect'', where 8 is the number of characters that make up the value. 

• currency - 3USD
• merchant - 16YOUR_VENDOR_CODE
• price - 229
• prod - 9TEST_PROD
• qty - 11
• refno - 811606896
• return-type - 8redirect
• return-url - 24https://yourbackend.com/
• total - 229
• total-currency - 3USD
• tpl - 7default

4. Concatenate the values:

3USD16YOUR_VENDOR_CODE2299TEST_PROD118116068968redirect24https://yourbackend.com/2293USD7default'

5. Encrypt using your Buy-Link Secret Word that can be found in your Merchant Control Panel, under Integrations → Webhooks & API → Secret word section.

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 'vendor-secret-key')

This outputs a 64 character string: 

3598511a17b038b9a0f5579f26bb51a17a8e78ac99a2f6b833714a88a6bbb0c4

 Also, you can use HashValidationTool:

<?php

class HashValidationTool
{

    const SHA_256 = 'sha256';
    private $params;
    private $signature;
    private $key;

    /**
     * HashValidationTool constructor.
     *
     * @param string $key
     */
    public function __construct(string $key)
    {
        $this->key = $key;
    }

    /**
     * @return string
     */
    private function encrypt(): string
    {
        $serialized = $this->serializeParameters($this->params);

        if (strlen($serialized) > 0) {
            echo 'Success: serialized params - ' . $serialized . PHP_EOL;

            return bin2hex(hash_hmac(self::SHA_256, $serialized, $this->key, true));
        } else {
            echo 'Error: serialization parameters are empty' . PHP_EOL;

            return '';
        }
    }

    /**
     * @param string $url
     *
     * @return bool
     */
    public function validate(string $url): bool
    {
        $this->setUrl($url);

        return $this->encrypt() === $this->signature;
    }

    /**
     * @param array $array
     *
     * @return string
     */
    private function serializeParameters(array $array): string
    {
        ksort($array);

        $serializedString = '';

        foreach ($array as $value) {
            if (is_array($value)) {
                $serializedString .= $this->serializeParameters($value);
            } else {
                $serializedString .= strlen($value) . $value;
            }
        }

        return $serializedString;
    }

    /**
     * @param string $url
     */
    private function setUrl(string $url): void
    {
        $urlParts = parse_url($url);
        parse_str($urlParts['query'], $this->params);
        $this->signature = $this->params['signature'];
        unset($this->params['signature']);
    }
}

$hashValidationTool = new HashValidationTool('vendor-secret-key');
if ($hashValidationTool->validate('https://www.yourbackend.com/?merchant=YOUR_VENDOR_CODE&currency=USD&return-url=https://yourbackend.com/&return-type=redirect&tpl=default&prod=TEST_PROD&price=29&qty=1&refno=11606896&total=29&total-currency=USD&signature=95052ee0c558b53040e97d7d81add2e0f1400ca0936a558910c68ddc8301fc63')) {
    echo 'valid';
} else {
    echo 'invalid';
}

The successful order with a valid signature for the default theme is described in the following diagram.

The successful order with an invalid signature for the default theme is described in the following diagram. 

Overview

Use the getPayPalExpressCheckoutRedirectURL method to retrieve the RedirectURL by sending an Order object with PAYPAL_EXPRESS payment method.

Parameters

Response

Retrieve PayPal redirect URL

<?

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->Language = 'fr';
//$Order->LocalTime = date('Y-m-d G:i:s');
$Order->CustomerReference = 'APITEST';//uniqid('TESTCUSTOMER:');
$Product = new stdClass();
$Product->Code = 'my_subscription_1';
$Product->Quantity = 1;
$Order->Items[] = $Product;
$Order->Currency = 'EUR';
$Payment = new stdClass();
$Payment->Type = 'PAYPAL_EXPRESS';
$Payment->Currency = 'EUR';
$Payment->CustomerIP = '91.220.121.21';

$PayPalExpress = new stdClass();
$PayPalExpress->Email='customer@email.com';
$PayPalExpress->ReturnURL = 'http://' . $_SERVER['HTTP_HOST'] . '/api/place_order_api_soap_paypal_express_response.php';
$PayPalExpress->CancelURL = 'http://' . $_SERVER['HTTP_HOST'] . '/api/place_order_api_soap_paypal_express_response.php' . '?cancel=true';
$Payment->PaymentMethod = $PayPalExpress;    
$Order->PaymentDetails = $Payment;
// Call the method for retrieving Express Checkout redirect URL
$redirectUrl = $client->getPayPalExpressCheckoutRedirectURL($sessionID,$Order);
header('Location:' . $redirectUrl);

Place order with PayPal Express 

<?php
declare(strict_types=1);

class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/soap/6.0';
    public const ACTION = 'placeOrder';
    public const ADDITIONAL_OPTIONS = null;
    //array or JSON
    public const PAYLOAD = <<<JSON
{
  "Country": "us",
  "Currency": "USD",
  "CustomerIP": "91.220.121.21",
  "ExternalReference": "SOAP_API_AVANGTE",
  "Language": "en",
  "Source": "testAPI.com",
  "BillingDetails": {
    "Address1": "Test Address",
    "City": "LA",
    "State": "California",
    "CountryCode": "US",
    "Email": "testcustomer@2Checkout.com",
    "FirstName": "Customer",
    "LastName": "2Checkout",
    "Zip": "12345"
  },
  "Items": [
    {
      "Code": "A90B3D8FDE",
      "Quantity": 1
    }
  ],
  "PaymentDetails": {
    "Currency": "USD",
    "CustomerIP": "91.220.121.21",
    "PaymentMethod": {
      "RecurringEnabled": false,
      "ReturnURL": "http://secure.avangate.local/test/index.php",
      "CancelURL": "http://secure.avangate.local/test/create_order.php"
    },
    "Type": "PAYPAL"
  }
}
JSON;
}

class Client
{
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?object {
        if (is_array($payload)) {
            $payload = json_encode($payload);
        }
        if (!empty($payload)) {
            // SoapClient works with objects(StdClass)
            $payload = json_decode($payload);
        }
        $soapClient = $this->getClient($url);
        $sessionId = $this->getSession($soapClient);
        $args = array_filter([$sessionId, $payload]);

        return $soapClient->$action(...$args);
    }

    public function getClient(string $url): SoapClient
    {
        return new SoapClient(
            $url.'?wsdl',
            [
                'location' => $url,
                'cache_wsdl' => WSDL_CACHE_NONE,
            ]
        );
    }

    public function getSession(SoapClient $client)
    {
        $date = gmdate('Y-m-d H:i:s');
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $string = strlen($merchantCode).$merchantCode.strlen($date).$date;
        $hash = hash_hmac('md5', $string, $key);
        $client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');

        return $client->login($merchantCode, $date, $hash);
    }
}

try {
    $client = new Client();
    var_dump($client->call());
} catch (Exception $ex) {
    var_dump($ex);
}

Workflow 

1. Authentication via login API method.
2. Retrieve PayPal redirect URL. When you retrieve the PayPal redirect URL, apart from the token you will also receive 2 parameters that are encoded: billingDetails and deliveryDetails. These have to be base64_decoded and the information should be used in the placeOrder API call (email, billing address etc.). 
3. Place the order with PayPal Express using the token sent by PayPal.

Overview

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

Requirements

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

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

Yes. Please contact 2Checkout for activation.

How does it work?

1. Create the Order object.
2. Validate the number of installments available based on total order value. 
3. 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). 

Overview

Redirect and login shoppers automatically from your user portal into their 2Checkout myAccount based on subscription or customer information.

Requirements

You need a custom domain to use Single Sign-On. Contact 2Checkout directly for guidance on how to set up a custom domain.

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

Generate custom links

ConvertPlus parameters that require a signature:

ConvertPlus parameters to be included in the signature

1. 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.
2. 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.
3. Parameters to be included in the signature for manual renewal buy-links: prod, qty, opt.
4. Parameters to be included for on-the-fly pricing for catalog products: prod, price, qty, opt, coupon, currency.
5. 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:

1. Sort the parameters that require a signature alphabetically.
2. Serialize the parameters and append to them the length of their values.
3. Concatenate the resulting values.
4. The serialized value is then encrypted with your Buy-Link Secret Word using the HMAC method (algorithm sha256).
5. 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

520ba411696e37f1839145bfa793f7199d8d0295a228ea42dc20a3f39196e358

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

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

Response

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));

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

1. Add an HTML link or button in your page like the one below.
2. Create a JavaScript click handler to execute the Inline Client desired methods.
3. Use theTwoCoInlineCart.products.add({code, quantity, options})method to prepare your catalog product.
4. In order to set currency use TwoCoInlineCart.cart.setCurrency(currency-code).
5. In order to set order external reference useTwoCoInlineCart.cart.setOrderExternalRef(your-external-reference)method.
6. 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: