Place orders with catalog products

Use this object to create new orders and collect payments from shoppers using catalog products defined in Control Panel.

For orders that require physical delivery, if no shipping methods are provided, 2Checkout will add to the cart your account's default shipping configuration.

You can find a list of common errors that may arise when using the placeOrder call via API 6.0 here.

Supported payment methods/flows

• Credit / debit cards: Visa, Visa Electron, MasterCard, Maestro, Amex, Discover, Dankort, Carte Bleue, JCB. 2Checkout supports local Brazilian cards.

• PayPal and PayPal Express

• Apple Pay

• Boleto/Pix

• Google Pay

• WeChat Pay

• iDEAL

• Alipay

• Trustly

• WeChat Pay

• eChecks

• Stored credit

• Purchase order

• Wire

• Direct Debit

• Check

• Test orders

• 2Pay.js

• Order with installments

• Free orders (no payment information required)

• Previous order references

  In addition to the payment methods enumerated above, 2Checkout also supports 1-click purchase flows in which you use valid previous order references belonging to returning customers to pay for new orders with their previously used cards and PayPal accounts.

Requirements

For credit card orders placed using API 6.0, you need to pass through additional parameters that support the 3D Secure flow. 3D Secure works by redirecting customers to pages provided by their banks, where they need to enter additional security tokens or passwords to trigger the completion of the charge. By using 3D Secure, you get additional protection from liability for fraudulent card payments, with customers having to go through an extra layer of authentication.

Send the following parameters in the placeOrder call:

Parameter	Type / Description
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.
WSOrder	Optional (string) The WSOrder parameter is used to control the website URL displayed in the email messages shoppers receive after they place an order. By default, 2Checkout reports the URL set as Homepage in the Account information area. Adding WSOrder to the buy-links for your products will cause the optional website address set by using the parameter to override and replace the Homepage URL in the email notifications sent to customers. The behavior is similar to the WS_ORDER parameter supported on checkout/cart pages and described here.

Request parameters

Parameter	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 in 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 in Buy Links. Use the SRC parameter to track sale sources. Maximum length 255 characters.
CustomerReference	Optional (integer) Set an external customer ID, attached to the customer.
Affiliate	Optional (object)
Affiliate.AffiliateCode	Required (string) The affiliate unique code (as returned by the affiliates API methods).
Affiliate.AffiliateSource	Optional (string) The affiliate source.
Items	Required (array of object) Details below.
Items.OrderItem	Object Details below.
Items.OrderItem.Code	Mandatory (string) Unique product identifier your control. Max length 256 characters. Only for catalog products.
Items.OrderItem.Quantity	Optional (integer) Number of units
Items.OrderItem.PriceOptions	Optional (array of strings) Array of price option codes.
Items.OrderItem.SKU	Optional (string) SKU identifier.
Items.OrderItem.Price	Object Can be NULL. If Price Type is set to 'CUSTOM', dynamic pricing can be added to the order via the Amount parameter.
Items.OrderItem.CrossSell	Object Can be NULL Details below.
Items.OrderItem.CrossSell.ParentCode	String The product code of the master product you set to trigger the campaign.
Items.OrderItem.CrossSell.CampaignCode	String Unique, system-generated identifier for cross-sell campaigns.
Items.OrderItem.Trial	Object Can be NULL Details below.
Items.OrderItem.Trial.Period	Integer The length of the trial subscription lifetime in days.
Items.OrderItem.Trial.Price	Optional (double) Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.
Items.OrderItem.AdditionalFields	Array of objects Can be NULL
Items.OrderItem.AdditionalFields.AdditionalFieldSet	Object Can be NULL
Items.OrderItem.AdditionalFields.AdditionalFieldSet.Code	String The alpha-numeric characters, underscores and dashes that are set as the field identifier.
Items.OrderItem.AdditionalFields.AdditionalFieldSet.Value	String Selected field value.
Items.OrderItem.SubscriptionStartDate	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, 2Checkout uses 00:00:01. Default time zone GMT+02:00.
Items.OrderItem.SubscriptionCustomSettings	Optional (object) To use this, the ExtraInformation object with AssistedSale property set to "true" is required.
Items.OrderItem.CycleAmountType	Required (string) Billing cycle unit NET/GROSS.
Items.OrderItem.CycleUnit	Required (string) DAY/MONTH. Can be NULL.
Items.OrderItem.CycleAmount	Required (float) Billing cycle (renewal) price.
Items.OrderItem.CycleLenght	Required (integer) Billing cycle length. Can be NULL.
Items.OrderItem.ContractLenght	Optional (integer) Contract period length (expressed in the specified CycleUnit; must be multiple of CycleLength). Can be NULL.
Items.OrderItem.MerchantDealAutoRenewal	Optional (boolean) Merchant deal auto-renewal flag.
Items.OrderItem.ClientDealAutoRenewal	Optional (boolean) Client deal auto-renewal flag.
BillingDetails	Required (object) Details below.
BillingDetails.FirstName	Required (string) Shopper name.
BillingDetails.LastName	Required (string) Shopper surname.
BillingDetails.CountryCode	Required (string) Shopper country. ISO 3166 two-letter code.
BillingDetails.State	Optional (string) – 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.
BillingDetails.City	Required (string) Shopper city.
BillingDetails.Address1	Required (string) Shopper address.
BillingDetails.Address2	Optional (string) Shopper address.
BillingDetails.Zip	Required (string) ZIP/ Postal code.
BillingDetails.Email	Required (string) Shopper email address.
BillingDetails.Phone	Optional (string) Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.
BillingDetails.Company	Optional (string) Company name. Can be null for end users. When present, you also need to provide the FiscalCode.
BillingDetails.FiscalCode	Optional (string) – Required for Brazil • For companies, it needs to be the VAT ID. 2Checkout 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.
BillingDetails.TaxExemptionId	Optional (string) Tax Exempt Certification id used to deduct taxes for US orders. Example: 1b80eecc349v
DeliveryDetails	Required (object) Details below.
DeliveryDetails.FirstName	Required (string) Shopper name from the delivery details.
DeliveryDetails.LastName	Required (string) Shopper surname from the delivery details.
DeliveryDetails.CountryCode	Required (string) Shopper country. ISO 3166 two-letter code from the delivery details.
DeliveryDetails.State	Optional (string) – 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.
DeliveryDetails.City	Optional (string) Shopper city from the delivery details.
DeliveryDetails.Address1	Optional (string) Shopper address from the delivery details.
DeliveryDetails.Address2	Optional (string) Shopper address from the delivery details.
DeliveryDetails.Zip	Optional (string) ZIP/ Postal code from the delivery details.
DeliveryDetails.Email	Optional (string) Shopper email address from the delivery details.
DeliveryDetails.Phone	Optional (string) Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.
DeliveryDetails.Company	Optional (string) Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.
DeliveryInformation	Optional (object) For products that require physical delivery, use this object to send the shipping method.
DeliveryInformation.ShippingMethod	Object Details below
DeliveryInformation.ShippingMethod.Code	String System-generated identified for your shipping method configuration
PaymentDetails	Required (object) Adapt this object to the desired payment method.
PaymentDetails.Type	Required (string) The payment method: CC (credit/debit card - including local Brazilian cards). ENCRYPTED_PAYMENT_DATA (client-side encryption) PAYPAL PAYPAL_EXPRESS DIRECT_EBANKING 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. DIRECTDEBIT– the placeOrder response includes Direct Debit 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. ALIPAY UNIONPAY TRUSTLY (for Trustly payments) EES_TOKEN_PAYMENT (2Pay.js) APPLE PAY BOLETO GOOGLE PAY Echeck/ACH Stored Credit
PaymentDetails.Country	Required (string) The currency ISO code for the payment - ISO 4217. Example: “usd.”
PaymentDetails.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.
PaymentDetails.PaymentMethod.RecurringEnabled	Optional (boolean) true – shopper checks the auto-renewal checkbox and 2Checkout charges subscription renewals using a recurring billing process. false – shopper doesn’t check the auto-renewal checkbox.
PaymentDetails.PaymentMethod.CardPayment	Optional (object) Details below.
PaymentDetails.PaymentMethod.CardPayment.CardNumber	Required (string) The credit/debit card number.
PaymentDetails.PaymentMethod.CardPayment.CardType	Required (string) visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
PaymentDetails.PaymentMethod.CardPayment.ExpirationYear	Required (string) The year in which the card expires.
PaymentDetails.PaymentMethod.CardPayment.ExpirationMonth	Required (string) The month in which the card expires.
PaymentDetails.PaymentMethod.CardPayment.HolderName	Required (string) Card holder name.
PaymentDetails.PaymentMethod.CardPayment.CCID	Required (string) Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.
PaymentDetails.PaymentMethod.CardPayment.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.
PaymentDetails.PaymentMethod.CardPayment.Vendor3DSCancelURL	Required (string) URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.
PaymentDetails.PaymentMethod.CardPayment.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.
PaymentDetails.PaymentMethod.CardPayment.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.
PaymentDetails.PaymentMethod.CardPayment.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.
PaymentDetails.PaymentMethod.PayPalExpress	Optional (object) Details below.
PaymentDetails.PaymentMethod.PayPalExpress.Email	Optional (string) Email address customers use for their PayPal account.
PaymentDetails.PaymentMethod.PayPalExpress.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.
PaymentDetails.PaymentMethod.PayPalExpress.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.
PaymentDetails.PaymentMethod.PayPalExpress.FundingSource	Optional (string) The funding source is the buyer's source for the payment. Values can be "Standard", where the buyer's funding source is the regular one in their PayPal account, or "Credit", where the buyer's funding source is a credit line in their PayPal account.
PaymentDetails.PaymentMethod.DirectDebit	Optional (object) Details below.
PaymentDetails.PaymentMethod.DirectDebit.FirstName	Required (string) First name of the account holder.
PaymentDetails.PaymentMethod.DirectDebit.LastName	Required (string) Last name of the account holder.
PaymentDetails.PaymentMethod.DirectDebit.Iban	Required (string) IBAN code for the Direct Debit account.
PaymentDetails.PaymentMethod.DirectDebit.Swift	Optional (string) Bank swift code.
PaymentDetails.PaymentMethod.PreviousOrder	Optional (Object) Details below.
PaymentDetails.PaymentMethod.PreviousOrder.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 2Checkout system blocks you from using references for fraudulent or potentially fraudulent orders.
PaymentDetails.PaymentMethod.PurchaseOrderPaymentDetails	Optional (object) Details below.
PaymentDetails.PaymentMethod.PurchaseOrderPaymentDetails.InternalPONumber	Optional (string) Identifier that business customers use internally in their organization to track and manage Purchase Orders (PO). Can be NULL.
PaymentDetails.PaymentMethod.PurchaseOrderPaymentDetails.AutoApprove	Optional (boolean) TRUE - requires activation of the PO AutoApprove package (If the package is inactive 2Checkout returns an error). Please contact 2Checkout. When AutoApprove is TRUE, 2Checkout no longer requires that business customers upload a PO document. As such, PO orders are automatically approved for your account, without a PO doc. 2Checkout 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. 2Checkout 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 2Checkout and that you need to approve. 2Checkout sets the AVAITING_UPLOAD status for POs and Unfinished for their orders. Can be NULL.
PaymentDetails.PaymentMethod.WE_CHAT_PAY	Optional (string) Details below
PaymentDetails.PaymentMethod.WE_CHAT_PAY.ReturnURL	Optional (string) The return URL is the page to which your customers are redirected after their successful payment.
PaymentDetails.PaymentMethod.WE_CHAT_PAY.CancelURL	Optional (string) The cancel URL is the page to which your customers are redirected after their failed payment attempt.
PaymentDetails.PaymentMethod.IDEAL	Optional (string) Details below
PaymentDetails.PaymentMethod.IDEAL.ReturnURL	Optional (string) The return URL is the page to which your customers are redirected after their successful payment.
PaymentDetails.PaymentMethod.IDEAL.CancelURL	Optional (string) The cancel URL is the page to which your customers are redirected after their failed payment attempt.
PaymentDetails.PaymentMethod.IDEAL.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".
PaymentDetails.PaymentMethod.EXISTING_PAYMENT_DATA	Optional (Object) By using EXISTING_PAYMENT_DAT you no longer require shoppers to enter any payment details.
PaymentDetails.PaymentMethod.EXISTING_PAYMENT_DATA.TransientToken	Optional (string) Returned as a part of the process of retrieving customer information by SSOToken.
PaymentDetails.PaymentMethod.TRUSTLY	Optional (string) Details below.
PaymentDetails.PaymentMethod.TRUSTLY.ReturnURL	Optional (string) The return URL is the page to which your customers are redirected after their successful payment.
PaymentDetails.PaymentMethod.DIRECT_DEBIT_ACH	Optional (object) Details below.
PaymentDetails.PaymentMethod.DIRECT_DEBIT_ACH.AccountHolderName	Optional (string) Full name of the account holder.
PaymentDetails.PaymentMethod.DIRECT_DEBIT_ACH.BankRoutingNumber	Optional (string) Bank Routing number consisting of up to 17 digits.
PaymentDetails.PaymentMethod.DIRECT_DEBIT_ACH.AccountNumber	Optional (string) Account number with fixed 9 digit length.
PaymentDetails.PaymentMethod.DIRECT_DEBIT_ACH.AccountType	Optional (string) Possible values are "S" for SAVINGS accounts or "C" for CHECKING accounts.
PaymentDetails.CustomerIP	Optional (string) Shopper IP.
Promotions	Optional (array of strings) Array of promotion codes.
AdditionalFields	Optional (object) Details below.
AdditionalFields.Code	Optional (string) The alpha-numeric characters, underscores, and dashes are set as the field identifier.
AdditionalFields.Text	Optional (string) Field text visible to shoppers in the cart.
AdditionalFields.Value	Optional (string) Selected field value.
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.
GiftDetails	Optional (object) Contains contact details for the recipient of gift purchase.
GiftDetails.FirstName	Optional (string) First name of the gift recipient.
GiftDetails.LastName	Optional (string) Last name of the gift recipient.
GiftDetails.Email	Optional (string) Email of the gift recipient. 2Checkout uses this email for the delivery/fulfillment process.
GiftDetails.GiftNote	Optional (string) Custom text shoppers provide a message to the gift recipient.
BillingCycleReset	Optional (boolean) Only used when the request type is "Place an order with manual renewal". The licence renewal will start as soon as the new order is processed, resetting the billing cycle.

PaymentDetails.PaymentMethod.DirectDebit.Swift

PaymentDetails.PaymentMethod.DirectDebit.Swift

PaymentDetails.PaymentMethod.DirectDebit

Request sample (with Credit Card)

<?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
{
    "Currency": "USD",
    "Country": "US",
    "CustomerIP": "91.220.121.21",
    "Source": "testAPI.com",
    "WSOrder": "http://www.myurlfortest.com",
    "ExternalReference": null,
    "BillingDetails": {
        "Address1": "Test Address",
        "City": "London",
        "CountryCode": "US",
        "Email": "[email protected]",
        "FirstName": "Customer",
        "LastName": "2Checkout",
        "Phone": "556133127400",
        "State": "DF",
        "Zip": "70403-900"
    },
    "PaymentDetails": {
        "Type": "CC",
        "Currency": "USD",
        "CustomerIP": "91.220.121.21",
        "PaymentMethod": {
            "CCID": "123",
            "CardNumber": "4111111111111111",
            "CardNumberTime": "12",
            "CardType": "Visa",
            "ExpirationMonth": "12",
            "ExpirationYear": "2023",
            "HolderName": "John Doe",
            "HolderNameTime": "12",
            "RecurringEnabled": true,
            "Vendor3DSReturnURL": "www.test.com",
            "Vendor3DSCancelURL": "www.test.com"
        }
    },
    "Items": [
        {
            "Code": "testprod",
            "Quantity": "1"
        }
    ]
}
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);
}