Skip to main content

Place orders with dynamic product information

Overview

Use this object to create new orders and collect payments from shoppers using products with dynamic information. 

Purchase types available are: PRODUCT, TAX, SHIPPING and COUPON. The surcharge defined in the pricing option is used for calculating the order renewal price, when applicable.

Supported payment methods

  1. Credit/Debit cards: Visa, Visaelectron, MasterCard, Maestro, Amex, Discover, Dankort, Cartebleue, JCB. Avangate supports local Brazilian cards.
  2. PayPal
  3. Free orders (no payment information required).
  4. 2Pay.js

How to test?

Place test orders with dynamic product information by following the instructions from this article.

Requirements

Product code must be sent as null. The order currency must match with the payment currency, otherwise, an error is thrown. The isDynamic parameter of the Items object must be true.

Limitations

Placing an order with both catalog and dynamic product information is not possible. Recurring options can be set only for purchase type PRODUCT and TAX.

For MoR business model, the purchase type can only be PRODUCT and COUPON

Attributes

Parameters Type/Description
Currency Optional (string)
  The currency ISO code for the payment - ISO 4217. Example: “usd.”
Country Optional (string)
  Shopper country. ISO 3166 two-letter code. Example: “us.”
Language Optional (string)
  ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”
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.
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.

CustomerReference Optional (Int)
  System-generated Avangate customer reference. Aggregate subscriptions under the same Customer account 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.
MachineId Optional (string)
  Unique, system generated code for each unique customer, identifying returning customers.
Items Required (array of objects)

 

 

  Details below. 

 

 

Code Optional (string)

 

 

  Should be send as NULL. Any other value will be ignored.

 

 

Quantity Required (integer)

 

 

  Number of units
  isDynamic Required (bool)
    Send true for creating orders with dynamic order information.
  Tangible Required (bool)
    Send false for product delivered electronically.
  PurchaseType Required (string)
    Purchase types available are: PRODUCT, TAX, SHIPPING and COUPON.
  PriceOptions Optional (array of objects)
    Array of price option groups.
    Name   Optional (string) 
        Name of the pricing option group. Mandatory for dynamic products.
    Options   Optional (array of objects)
        Array of pricing options.
    Name Optional (string)
      Pricing option name. Mandatory for dynamic products.
    Value Optional (string)
      Pricing option code. Mandatory for catalog products. 
    Surcharge Optional (double)
      Surcharge of the pricing option. For renewal orders, the renewal price includes the pricing option surcharge from the initial order. Mandatory for dynamic products.
  RecurringOptions Optional (Object)
      Contains recurring options.
    CycleLength Optional (int)
      The length of the recurring billing cycle.
    CycleUnit Optional (string)
      Unit of measuring billing cycles (years, months).
    CycleAmount Optional (int)
      The amount to be billed on each renewal.
    ContractLength Optional (int)
      The contact length for which the recurring option will apply.
    ContractUnit Optional
      Unit of measuring contact length (years, months).

 

 

Price Required (Object)
    Details below.
    Amount Required (Int)
      Amount of the product.
    Type Optional (string)
      Send "CUSTOM" for dynamic pricing.
    ProductTaxCategoryUUID Required (String)
     

The UUID of the tax category used for the product. Must be a category existent on your account.

Must be passed as NULL on PSP business model.

    PriceType Optional (String)
     

Possible values:

  • GROSS - with taxes included
  • NET - without taxes

If parameter is not sent, the default PriceType applied is GROSS.

    Trial Optional (Object) – Can be NULL
        Details below. 
      Period Optional (integer)
        The length of the trial subscription lifetime in days.
      Price Optional (double)
        Total trial price in the payment currency before Avangate deducts any taxes, discounts, etc.
    AdditionalFields Optional (array of objects) – Can be NULL
      AdditionalFieldSet Optional (Object) – Can be NULL
        Details below
        Code Optional (string)
          Identifier code for the additional field.
        Text Optional (string)
          Text displayed in the additional field.
        Value Optional (string)
          Additional field value.
    SubscriptionStartDate Optional (string)
     

Specify the date time stamp when the subscription becomes active. Format 2016-07-02 22:22:22 (YYYY-MM-DD HH:mm:ss). Available for JSON-RPC and REST.

Send empty or NULL to activate subscriptions on the same date when customers purchase them.

You can exclude HH:mm:ss when sending the date and include only YYYY-MM-DD. In this case, Avangate uses 00:00:01. Default time zone GMT+02:00.

BillingDetails Required (Object)
    Details below. 
  Person Object
    Details below. 
    FirstName Required (string)
      Shopper name.
    LastName Required (string)
      Shopper surname.
    CountryCode Optional (string)
      Shopper country. ISO 3166 two-letter code.
    State String/Optional – Required for US, Canada, Brazil, Turkey, India and Romania
      The state in the shopper's country. Mandatory when you set the Billing Country to US, Canada, Brazil, Turkey, 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.
    TaxExemptionId  Optional (string)
      Tax Exempt Certification id used to deduct taxes for US orders
Example: 1b80eecc349v
  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 you set Brazil as the Billing Country. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).

Mandatory when you set India as the Billing Country, and purchase is made by a Company.

• Can be NULL for end users.

DeliveryDetails Required (Object)
                    Details below. 
  Person Object
                    Details below. 
    FirstName Required (string)
                    Shopper name from the delivery details.
    LastName Required (string)
                    Shopper surname from the delivery details.
    CountryCode Optional (string)
                    Shopper country. ISO 3166 two-letter code from the delivery details.
    State String/Optional – Required for US, Canada, Brazil, Turkey, India and Romania
                    The state in the shopper's country. Mandatory when you set the Billing Country to US, Canada, Brazil, Turkey, India 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 Required (Object)
  Adapt this object to the desired payment method.
  Type Required (string)
   

The payment method:

  • CC (credit/debit card - including local Brazilian cards).
  • ENCRYPTED_PAYMENT_DATA (client-side encryption)
  • PAYPAL
  • PAYPAL_EXPRESS
  • CCNOPCI(credit/debit card for non-PCI certified merchants).
  • 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.
  • WE_CHAT_PAY (for WeChat payments).
  • IDEAL (for iDEAL payments).
  • PURCHASEORDER - use for orders with POs.
  • FREE – for 0 value orders for which you’re not requiring customers to provide payment details.
  • EES_TOKEN_PAYMENT (2Pay.js)

 

  Currency Required (string)
    The currency ISO code for the payment - ISO 4217. Example: “usd.”
  RecurringEnabled Optional (boolean)
   

true – shopper checks the auto renewal checkbox and Avangate charges subscription renewals using a recurring billing process.

false – shopper doesn’t check the auto renewal checkbox.

  PaymentMethod Optional (object)
   

Object structure and parameters differ according to payment method selected and API method (placing orders (POST) vs. retrieving order data (GET)).

 

NULL for 0 value orders for which you’re not requiring customers to enter payment details.

      CardPayment Optional (object)
          Details below. 
        CardNumber Required (string)
          The credit/debit card number.
        CardType Required (string)
          visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
        ExpirationYear Required (string)
          The year in which the card expires.
        ExpirationMonth Required (string)
          The month in which the card expires.
        HolderName Required (string)
          Card holder name.
        Vendor3DSReturnURL Required (string)
          URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.
        Vendor3DSCancelURL Required (string)
          URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.
        CCID Optional (string)
          Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.
        HolderNameTime Optional (float)
         

The interval of time in seconds in which shoppers enter their name in the HolderName field. An abnormally short interval is usually a red flag for fraud attempts.

Can be NULL, but not a negative number.

        CardNumberTime Optional (float)
         

The interval of time in seconds in which shopper enter their card number in the CardNumber field. An abnormally short interval is usually a red flag for fraud attempts.

Can be NULL, but not a negative number.

        InstallmentsNumber  Optional (Int)
          Number of installments. Available only when customers un Brazil pay with Visa or MasterCard using Brazilian Real as the order currency. Use 1 or exclude the parameter for full payments. 
      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 yourbuyer'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.
      PreviousOrder Optional (Object)
          Details below. 
        RefNo Optional (string)
         

Order reference a previous purchase which reached the Approved/Complete status. You can use order for which customers paid with credit/debit cards or with PayPal. The status of order should be AUTHRECEIVED or COMPLETE.

 

Check the validity of references with the isValidOrderReference method.

 

The Avangate system blocks you from using references for fraudulent or potentially fraudulent orders.

      PurchaseOrderPaymentDetails Optional (Object)
          Details below. 
        InternalPONumber Optional (string)
          Identifier that business customers use internally in their organization to track and manage Purchase Orders (PO). Can be NULL.
        AutoApprove Optional (boolean)
         

TRUE - requires activation of the PO AutoApprove package (If the package is inactive Avangate returns an error). Please contact Avangate. When AutoApprove is TRUE, Avangate no longer requires that business customers upload a PO document. As such, PO orders are automatically approved for your account, without a PO doc. Avangate sets the PURCHASE_PENDING status for auto-approved PO orders.

FALSE - Default. Send this if the PO AUtoApprove package is not available for your account. Avangate uses the same flow as cart purchases with Purchase Orders for business customers placing orders with POs via API. This means that customers receive the same emails as if they made the purchase using the cart and need to update the PO document, which is reviewed by Avangate and that you need to approve. Avangate sets the AVAITING_UPLOAD status for POs andUnfinished for their orders.

 

Can be NULL.

      WE_CHAT_PAY Optional (string)
        Details below
        ReturnURL Optional (string)
          The return URL is the page to which your customers are redirected after their successful payment.
        CancelURL Optional (string)
          The cancel URL is the page to which your customers are redirected after their failed payment attempt.
      IDEAL Optional (string)
        Details below
        ReturnURL Optional (string)
          The return URL is the page to which your customers are redirected after their successful payment.
        CancelURL Optional (string)
          The cancel URL is the page to which your customers are redirected after their failed payment attempt.
        BankCode Required (string)
          String contains the SWIFT code of the bank, the plus sign "+", and the first 3 characters from the bank name. E.q.: in the case of Rabobank, code parameter is "RABONL2U+RAB".
      EXISTING_PAYMENT_DATA Optional (Object)
        By using EXISTING_PAYMENT_DATA you no longer require shoppers to enter any payment details.
        TransientToken Optional (string)
          Returned as a part of the process of retrieving customer information by SSOToken.
  CustomerIP Optional (string)
    Shopper IP.
Promotions Optional (Array of strings)
  Array of promotion codes.
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.

 

 

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.

RefNo

Required (string)

 

Unique, system generated reference for orders.

Response

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
$host   = "https://api.2checkout.com";
$client = new SoapClient($host . "/soap/3.0/?wsdl", array(
    'location' => $host . "/soap/3.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 = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.2checkout.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;
}
$Reference = '43997639';
try {
    $invoices = $client->getInvoices($sessionID, $Reference);
}
catch (SoapFault $e) {
    echo "invoices: " . $e->getMessage();
    exit;
}
var_dump("invoices", $invoices);

 

Add comments to an order

Overview

Use this method to attach a comment when placing a partner order.

Requirements

Parameters

Parameter Type/Description
sessionID Required (String)
  Session identifier, which is the output of the Login method. An exception is thrown if the values are incorrect.
comment Required (String)
  A comment visible to both you and the partner.

Response

Parameter Type/Description
Response 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
require('PATH_TO_addProduct'); // addProduct example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/08Place_an_order/00Add_product_to_cart

$comment = 'YOUR_COMMENT';

try {
    $CommentSet= $client->setComment ($sessionID, $comment);
} catch (SoapFault $e) {
    echo " Comment: " . $e->getMessage();
    exit;
}
var_dump ("Comment", $CommentSet);

Errors

Error Description

INVALID_COMMENT

The provided comment is empty.

 

Remove product from cart

Overview

Use this method to remove a product that was added to the shopping cart, during the current session.

Requirements

Parameters

Parameter Type/Description
sessionID Required (String)
  Session identifier, which is the output of the Login method. An exception is thrown if the values are incorrect.
productId Required (Integer)
  Unique product identifier from the Avangate system.
priceOptions Optional (StringArray)
 

Array of price options codes. These identifiers mark the individual options inside pricing options configuration groups.

This parameter must match exactly the pricing option combination of the product added to the cart in order for the product to be removed.

 

Partner orders can involve the same product, bot ordered in multiple instances, each with different pricing options.

 

Can be NULL.

quantity Optional (Integer)
  Defines the number of product units added to cart that should be removed. If no quantity info is provided, the product is completely removed from cart. Can be NULL.

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
require('PATH_TO_addProduct'); // addProduct example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/08Place_an_order/00Add_product_to_cart

$productId = 'YOUR_PRODUCT_ID';
$priceOptions = array(
'Pricing_options_group_code1',
'Pricing_options_group_code2'
);
$quantity = YOUR_QUANTITY;

try {
$RemoveProduct= $client->deleteProduct ($sessionID, $productId, $priceOptions, $quantity);
} catch (SoapFault $e) {
echo "ProductDeleted: " . $e->getMessage();
exit;
}
var_dump ("ProductDeleted ", $RemoveProduct);

Errors

Error Description

EMPTY_CART

The shopping cart is empty.

PRODUCT_ERROR

There is no product with the specified settings in cart.

 

Use PayPal

Overview

Place an order using catalog products defined in your Control Panel, and collect the payment using PayPal.

Currency support

Check with Avangate support for a list of currencies available for PayPal. 

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.

To place an order with PayPal rather than PayPal Express, use PAYPAL as the type of the PaymentDetails object and send the shopper email and a return URL as part of the PaymentMethod object. See code sample. 

Workflow

  1. Create the order object. Use PAYPAL as the type of the PaymentDetails object and send the shopper email and a return URL as part of the PaymentMethod object. Place the order.
  2. Once you place the order, Avangate logs it into the system. At this point in time, the status of the order is PENDING. Avangate responds with the Order information object.
  3. Redirect shoppers to the RedirectURL from the Order information object you receive as response from Avangate.
  4. Once shoppers log into their PayPal account and complete the transaction, they're redirected to the ReturnURL you set in the order object. Avangate also authorizes the order and updates the status to AUTHRECEIVED. 

Response

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

 

<?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]->SubscriptionStartDate = NULL;

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

$Order->PaymentDetails = new stdClass();
$Order->PaymentDetails->Type = 'PAYPAL';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->CustomerIP = '91.220.121.21';
$Order->PaymentDetails->FundingSource = 'Credit';
$Order->PaymentDetails->PaymentMethod = new stdClass();
$Order->PaymentDetails->PaymentMethod->ReturnURL = 'http://yoururl.com';
$Order->PaymentDetails->PaymentMethod->Email = 'email@avangate.com';

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

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

$order = callRPC($jsonRpcRequest, $host);

Retrieve assigned price option groups

Overview

Use the getAssignedPriceOptionGroups method to extract information about the price option groups you assigned to one of your products.

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.

ProductCode

Required (string)

 

The editable code that you control at product-level, not the unique, system-generated product ID.

Response

Parameters Type/Description

PriceOptionGroup

Array of objects

Request

<?php

require ('PATH_TO_AUTH');
 
$productCode = 'YOUR_PRODUCT_CODE';
 
$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'getAssignedPriceOptionGroups',
'params' => array($sessionID, $productCode)
);

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

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

try {
    $invoices = $client->getInvoices($sessionID, $reference);
}
catch (SoapFault $e) {
    echo "invoices: " . $e->getMessage();
    exit;
}
var_dump("invoices", $invoices);

 

Use Checks

Overview 

Place an order using catalog products, and collect the payment using Check.

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.

Order

Required (Object)

 

Object designed to collect all data necessary for an order, including billing, product/subscription plan and payment details.

 

Workflow 

  1. Customer places the order using Check as payment option.
  2. After order is confirmed, customer receives the payment instructions via e-mail, including the address to which the check should be sent.
  3. Order is finalized as soon as the payment is confirmed into 2Checkout's bank account.

Response 

Parameters Type/Description

Order information

Object

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]->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 = 'customer@2checkout.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = 'ABC Company';
$Order->DeliveryDetails = NULL;


$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CHECK';
$Order->PaymentDetails->Currency = 'USD';
$Order->PaymentDetails->PaymentMethod = new stdClass ();

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

Domestic Brazilian credit/debit cards

Overview

2Checkout supports local Brazilian Visa, MasterCard, American Express, Elo, and HiperCard credit/debit cards limited to national purchases in Brazilian Real. Local cards in Brazil account for approximately 50% of all domestic online transactions.

   Payments made with Brazilian cards require shoppers to input a valid phone number and the CPF (Cadastrado de Pessoas Físicas) fiscal code.

Free orders/trials

2Checkout charges customers' cards using local Brazilian Visa and MasterCard credit/debit cards a minimum amount for authorization purposes and will refund the entire value immediately.

Installments

Brazilian customers are able to use installments for online transactions when using Visa, MasterCard, Elo, Hipercard, and American Express. Installments are only available for initial purchases and manual renewals, but not for automatic renewals. 2Checkout offers up to six (6) installments for all Brazilian cards and the minimum amount for an installment is 5 BRL. 2Checkout will split the total costs of an order ensuring that shoppers pay at least 5 BRL for each installment.

Card authorization rates in Brazil

You can push the authorization rate for card purchases in Brazil up to 90% by going 'local'. Brazilian shoppers use credit or debit cards for over 70% of online purchases with 80% of those cards issued by local banks and offering support only for Brazilian Real (R$). The vast majority of transactions involve locally-issued Visa and MasterCard, but Brazilians also use EloHipercard, and American Express for some 15% of card payments.

If you want master card authorization rates in Brazil just look at the graph below.

To summarize, almost 9 out of every 10 transactions with local Brazilian cards authorize successfully, compared to only 3 out of every 10 transactions with international cards. Installments are a key characteristic of the Brazilian payments culture and are also critical in pushing authorization rates to 90%.

Check out the self-service area of your Merchant Control Panel to start collecting revenue from Brazil by enabling your shoppers to use locally-issued cards.

F.A.Q.

  1. What are the supported currencies for domestic BR cards?
    • BRL (Brazilian Real)
  2. Do domestic Brazilian cards support recurring charges?
    • Yes, for one-off transactions.
    • No transactions using installments, but shoppers can manually renew their subscriptions.
  3. How do shoppers choose installments?
    • In the ordering interface, after shoppers select one of the supported domestic cards available for their account, they can choose to pay in full or use installments (from 2 to 6).
  4. What's the minimum amount of an installment?
    • Each installment must be a minimum of 5 BRL.
  5. How am I paid for transactions using installments?
    • 2Checkout pays you the full value of the transaction, minus the commissions you agreed to for your account, regardless of the number of installments (this is covered directly by the banks). 
  6. Why is this important?
    • Authorization rates are much higher on locally issued cards (given the fact that numerous Brazilian credit cards are closed for cross-border transactions) and access to installments is done through a local acquirer.
  7. What is the 2Checkout commission for domestic Brazilian cards?
    • Please contact 2Checkout directly for this information.
  8. Do local BR cards with/without installments require an addendum to my contract?
  9. Do I have to offer installments?
    • No, 2Checkout can set only local cards supporting one-off payments. 
  10. Does lead management work for unfinished payments via local BR cards?
    • 2Checkout sends follow-up emails for failed one-off transactions with local Brazilian cards, but not for installments.
  11. Are refunds supported for local Brazilian cards?
    • Yes. However, only a single either total or partial refund can be issued for each order.

Use Alipay

Overview

Alipay is a third-party online payment solution, allowing customers to make and receive payments on the Internet. Alipay's market share of online payments exceeds 54% in China.

Supported currencies

Alipay supports USD and CNY transactions.

Workflow

  1. Shoppers select Alipay as a payment option in the checkout interface you provide to them.
  2. Create the order object. Use “ALIPAY” as the type of the PaymentDetails object.
  3. Use the placeOrder method to send the data to 2Checkout.
  4. Once you place the order, 2Checkout logs it into the system. At this point, the status of the order is PENDING.
  5. 2Checkout returns an Order object as the output of the placeOrder method. 
  6. Use the Redirect Object in the PaymentMethod object of the response to create a redirect URL for your shoppers. Using the provided URL, make a request using the provided method (usually a GET request) and add the parameters (located in the Params object) as key-value pairs to URL of the request. 

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.

Order

Required (Object)

 

Object designed to collect all data necessary for an order, including billing, product/subscription plan and payment details.

See code sample for more details. 

Request Example 

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = "CNY" ;
$Order->Country = "TW";
$Order->Language = 'EN';
$Order->CustomerIP = '10.5.22.197';
$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 = '67B4EDC822';
$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]->SubscriptionStartDate = NULL;
$Order->BillingDetails = new stdClass();
$Order->BillingDetails->IsCompany = false;
$Order->BillingDetails->Address1 = 'Xian Jing Blvd 77';
$Order->BillingDetails->Address2 = 'floor 1';
$Order->BillingDetails->City = 'Shanghai';
$Order->BillingDetails->State = '';
$Order->BillingDetails->CountryCode = 'CN';
$Order->BillingDetails->Phone = '010-6552-9988';
$Order->BillingDetails->Email = 'hujianbing@336699.cn';
$Order->BillingDetails->FirstName = 'Hu';
$Order->BillingDetails->LastName = 'Jianbing';
$Order->BillingDetails->Zip = '334321';


$Order->DeliveryDetails = new stdClass();
$Order->DeliveryDetails->Address1 = 'Xian Jing Blvd 77';
$Order->DeliveryDetails->Address2 = 'floor 1';
$Order->DeliveryDetails->City = 'Shanghai';
$Order->DeliveryDetails->State = $state;
$Order->DeliveryDetails->CountryCode = 'CN';
$Order->DeliveryDetails->Phone = '010-6552-9988';
$Order->DeliveryDetails->Email = 'hujianbing@336699.cn';
$Order->DeliveryDetails->FirstName = 'Hu';
$Order->DeliveryDetails->LastName = 'Jianbing';
$Order->DeliveryDetails->Zip = '334321';

$Order->PaymentDetails->Type = 'ALIPAY';
$Order->PaymentDetails->Currency = "CNY" ;
$Order->PaymentDetails->HadPayPalToken = false;
$Order->PaymentDetails->CustomerIP = '10.5.22.197';

$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->PaymentMethod->ReturnURL = 'https://yourreturnurl.com';
$Order->PaymentDetails->PaymentMethod->CancelURL= 'https://yourcancelurl.com ';


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

var_dump($Order);

Response Parameters

Parameter Type/Description

Order information

Object

  Object containing order information.

Response Example

{
    "RefNo": "189698901",
    "OrderNo": 0,
    "ExternalReference": null,
    "ShopperRefNo": null,
    "Status": "PENDING",
    "ApproveStatus": "WAITING",
    "VendorApproveStatus": "OK",
    "MerchantCode": "251772850506",
    "Language": "en",
    "OrderDate": "2022-08-23 14:32:21",
    "FinishDate": null,
    "Source": "testAPI.com",
    "WSOrder": null,
    "Affiliate": {
        "AffiliateCode": null,
        "AffiliateSource": null,
        "AffiliateName": null,
        "AffiliateUrl": null
    },
    "HasShipping": true,
    "BillingDetails": {
        "FiscalCode": null,
        "TaxOffice": null,
        "Phone": "010-6552-9988",
        "FirstName": "John",
        "LastName": "Doe",
        "Company": null,
        "Email": "test@verifone.com",
        "Address1": "Test Address",
        "Address2": null,
        "City": "Shanghai",
        "Zip": "35005",
        "CountryCode": "cn",
        "State": null
    },
    "DeliveryDetails": {
        "Phone": "010-6552-9988",
        "FirstName": "John",
        "LastName": "Doe",
        "Company": null,
        "Email": "test@verifone.com",
        "Address1": "Test Address",
        "Address2": null,
        "City": "Shanghai",
        "Zip": "35005",
        "CountryCode": "cn",
        "State": null
    },
    "PaymentDetails": {
        "Type": "ALIPAY",
        "Currency": "cny",
        "PaymentMethod": {
            "Amount": "243",
            "Currency": "cny",
            "Redirect": {
                "Url": "https://intlmapi.alipay.com/gateway.do?_input_charset=utf-8&currency=USD&notify_url=https%3A%2F%2Fsecure.2checkout.com%2Falipay%2Fipn.php&out_trade_no=189698901&partner=2088201540985859&refer_url=1.TEST.MOR.com&return_url=https%3A%2F%2Fsecure.2checkout.com%2Forder%2Fgateway_return.php&rmb_fee=243&service=create_forex_trade&subject=2Checkout%E7%92%81%E3%88%A0%E5%B4%9F+%E9%8D%97%E6%9B%9E%E5%BD%BF%3A+%23189698901&trade_information%5Bbusiness_type%5D=4&trade_information%5Bgoods_info%5D=LPUJL13OZ6%5E1&trade_information%5Btotal_quantity%5D=1&sign=1c6c63019202662f10a96b528f8ee1a4&sign_type=MD5",
                "Method": "GET",
                "Params": {
                    "_input_charset": "utf-8",
                    "currency": "USD",
                    "notify_url": "https://secure.2checkout.com/alipay/ipn.php",
                    "out_trade_no": "189698901",
                    "partner": "2088201540985859",
                    "refer_url": "1.TEST.MOR.com",
                    "return_url": "https://secure.2checkout.com/order/gateway_return.php",
                    "rmb_fee": "243",
                    "service": "create_forex_trade",
                    "subject": "2Checkout璁㈠崟 鍗曞彿: #189698901",
                    "trade_information": {
                        "business_type": "4",
                        "goods_info": "LPUJL13OZ6^1",
                        "total_quantity": "1"
                    },
                    "sign": "1c6c63019202662f10a96b528f8ee1a4",
                    "sign_type": "MD5"
                },
                "FullHtml": "<!DOCTYPE html>\n<html lang=\"EN\"><body><script type=\"text/javascript\">window.location.replace(\"https://intlmapi.alipay.com/gateway.do?_input_charset=utf-8&currency=USD&notify_url=https%3A%2F%2Fsecure.2checkout.com%2Falipay%2Fipn.php&out_trade_no=189698901&partner=2088201540985859&refer_url=1.TEST.MOR.com&return_url=https%3A%2F%2Fsecure.2checkout.com%2Forder%2Fgateway_return.php&rmb_fee=243&service=create_forex_trade&subject=2Checkout%E7%92%81%E3%88%A0%E5%B4%9F+%E9%8D%97%E6%9B%9E%E5%BD%BF%3A+%23189698901&trade_information%5Bbusiness_type%5D=4&trade_information%5Bgoods_info%5D=LPUJL13OZ6%5E1&trade_information%5Btotal_quantity%5D=1&sign=1c6c63019202662f10a96b528f8ee1a4&sign_type=MD5\");</script></body></html>"
            },
            "ReturnURL": https://yourreturnurl.com,
            "CancelURL": https://yourcancelurl.com,
            "RecurringEnabled": false,
            "Vendor3DSReturnURL": null,
            "Vendor3DSCancelURL": null,
            "InstallmentsNumber": null
        },
        "CustomerIP": "91.220.121.21"
    },
    "DeliveryInformation": {
        "ShippingMethod": {
            "Code": null,
            "TrackingUrl": null,
            "TrackingNumber": null,
            "Comment": null
        }
    },
    "CustomerDetails": null,
    "Origin": "API",
    "AvangateCommission": 18,
    "OrderFlow": "REGULAR",
    "GiftDetails": null,
    "PODetails": null,
    "ExtraInformation": null,
    "PartnerCode": null,
    "PartnerMargin": null,
    "PartnerMarginPercent": null,
    "ExtraMargin": null,
    "ExtraMarginPercent": null,
    "ExtraDiscount": null,
    "ExtraDiscountPercent": null,
    "LocalTime": null,
    "TestOrder": false,
    "FxRate": 0.14024803891494,
    "FxMarkup": 4,
    "PayoutCurrency": "USD",
    "DeliveryFinalized": false,
    "Errors": null,
    "Items": [
        {
            "ProductDetails": {
                "Name": "Test Product",
                "ShortDescription": "<p>Join all your clouds in a big one</p>",
                "Tangible": false,
                "IsDynamic": false,
                "ExtraInfo": null,
                "RenewalStatus": false,
                "Subscriptions": null,
                "DeliveryInformation": {
                    "Delivery": "BY_AVANGATE",
                    "DownloadFile": null,
                    "DeliveryDescription": "",
                    "CodesDescription": "",
                    "Codes": []
                }
            },
            "PriceOptions": [],
            "Price": {
                "UnitNetPrice": 243,
                "UnitGrossPrice": 243,
                "UnitVAT": 0,
                "UnitDiscount": 0,
                "UnitNetDiscountedPrice": 243,
                "UnitGrossDiscountedPrice": 243,
                "UnitAffiliateCommission": 0,
                "ItemUnitNetPrice": null,
                "ItemUnitGrossPrice": null,
                "ItemNetPrice": null,
                "ItemGrossPrice": null,
                "VATPercent": 0,
                "HandlingFeeNetPrice": 0,
                "HandlingFeeGrossPrice": 0,
                "Currency": "cny",
                "NetPrice": 243,
                "GrossPrice": 243,
                "NetDiscountedPrice": 243,
                "GrossDiscountedPrice": 243,
                "Discount": 0,
                "VAT": 0,
                "AffiliateCommission": 0
            },
            "LineItemReference": "281d818c9b23daf15405807916e95dac5423d043",
            "PurchaseType": "PRODUCT",
            "Code": "LPUJL13OZ6",
            "ExternalReference": "",
            "Quantity": 1,
            "SKU": null,
            "CrossSell": null,
            "Trial": null,
            "AdditionalFields": null,
            "Promotion": null,
            "RecurringOptions": null,
            "SubscriptionStartDate": null,
            "SubscriptionCustomSettings": null,
            "UpSell": null
        }
    ],
    "Promotions": [],
    "AdditionalFields": null,
    "Currency": "cny",
    "NetPrice": 243,
    "GrossPrice": 243,
    "NetDiscountedPrice": 243,
    "GrossDiscountedPrice": 243,
    "Discount": 0,
    "VAT": 0,
    "AffiliateCommission": 0,
    "CustomParameters": null,
    "Refunds": null
}
Parameter Type/Description

Order information

Object

  Object containing order information.

For more on how to redirect shoppers to the payment method’ page  to finalize the payment, read here.

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Verifone logo