Language

2Checkout Documentation

Create a Sale

Once you have passed the token to your server, you can use it along with your private key to charge the credit card and create a new sale using the authorization API call. The authorization will capture and deposit automatically within 48 hours of being placed.

Each of our community supported libraries provides a method to perform an authorization and create a new sale.


Attributes

The authorization API call must be passed a JSON string with the customers billing information, an order identifier through the `merchantOrderId` parameter, your seller ID, private key, and either lineItem(s) data or just a sale total on all requests. The API will always return a JSON response body that includes a `response` sub object on successful authorizations and a `exception` sub object on failed authorizations that provide the result and transaction details.

API URL: https://www.2checkout.com/checkout/api/1/(seller_id)/rs/authService

When testing in our sandbox, you will need to use our sandbox authorization URL:

https://sandbox.2checkout.com/checkout/api/1/(seller_id)/rs/authService

Replace (seller_id) with your 2Checkout seller ID.

Content-Type: application/json

Returns: JSON response

HTTP Method: POST


Authorization Request Object

Base Attributes

Attribute Description
sellerId Your 2Checkout account number. Required
privateKey Your 2Checkout Private Key.  Required
merchantOrderId Your custom order identifier. Required.
token The credit card token. Required.
currency ARS, AUD, BRL, GBP, CAD, DKK, EUR, HKD, INR, ILS, JPY, MYR, MXN, NZD, NOK, PHP, RON, RUB, SGD, ZAR, SEK, CHF, TRY, AED, USD. Use to specify the currency for the sale. Required.
total The Sale Total. Format: 0.00-99999999.99, defaults to 0 if a value isn’t passed in or if value is incorrectly formatted, no negatives (Only Use if you are not passing in lineItems.)

Lineitem Attributes

Attribute Description
lineItems Array of lineitem objects using the attributes specified below.
Will be returned in the order that they are passed in.
(Passed as a sub object to the Authorization Object.)
(Only Use if you are not passing in total.)
type The type of line item that is being passed in. (Always Lower Case, ‘product’, ‘shipping’, ‘tax’ or ‘coupon’, defaults to ‘product’) Required
name Name of the item passed in. (128 characters max, cannot use ‘<' or '>’, defaults to capitalized version of ‘type’.) Required
quantity Quantity of the item passed in. (0-999, defaults to 1 if not passed in or incorrectly formatted.) Optional
price Price of the line item. Format: 0.00-99999999.99, defaults to 0 if a value isn’t passed in or if value is incorrectly formatted, no negatives (use positive values for coupons). Required
tangible Y or N. Will default to Y if the type is shipping. Optional
productId Your custom product identifier. Optional
recurrence Sets billing frequency. Ex. ‘1 Week’ to bill order once a week. (Can use # Week, # Month or # Year) Required for recurring lineitems.
duration Sets how long to continue billing. Ex. ‘1 Year’. (Forever or # Week, # Month, # Year) Required for recurring lineitems.
startupFee Any start up fees for the product or service. Can be negative to provide discounted first installment pricing, but cannot equal or surpass the product price. Optional

Lineitem Option Attributes

Attribute Description
options Array of option objects using the attributes specified below. Optional
Will be returned in the order that they are passed in.
(Passed as a sub object of a lineItem object.)
optName Name of product option. Ex. Size (64 characters max – cannot include ‘<' or '>’) Required
optValue Option selected. Ex. Small (64 characters max, cannot include ‘<' or '>’) Required
optSurcharge Option price in seller currency. (0.00 for no cost options) Required

Billing Address Attributes

Attribute Description
billingAddr Object that defines the billing address using the attributes specified below. Required
(Passed as a sub object to the Authorization Object.)
name Card holder’s name. (128 characters max) Required
addrLine1 Card holder’s street address. (64 characters max) Required
addrLine2 Card holder’s street address line 2. (64 characters max) Required if “country” value is: CHN, JPN, RUS - Optional for all other “country” values.
city Card holder’s city. (64 characters max) Required
state Card holder’s state. (64 characters max) Required if “country” value is ARG, AUS, BGR, CAN, CHN, CYP, EGY, FRA, IND, IDN, ITA, JPN, MYS, MEX, NLD, PAN, PHL, POL, ROU, RUS, SRB, SGP, ZAF, ESP, SWE, THA, TUR, GBR, USA - Optional for all other “country” values.
zipCode Card holder’s zip. (16 characters max) Required if “country” value is ARG, AUS, BGR, CAN, CHN, CYP, EGY, FRA, IND, IDN, ITA, JPN, MYS, MEX, NLD, PAN, PHL, POL, ROU, RUS, SRB, SGP, ZAF, ESP, SWE, THA, TUR, GBR, USA - Optional for all other “country” values.
country Card holder’s country. (64 characters max) Required
email Card holder’s email. (64 characters max) Required
phoneNumber Card holder’s phone. (16 characters max) Optional
phoneExt Card holder’s phone extension. (9 characters max) Optional

Shipping Address Attributes

Attribute Description
shippingAddr Object that defines the shipping address using the attributes specified below. Optional
Only required if a shipping lineitem is passed.
(Passed as a sub object to the Authorization Object.)
name Card holder’s name. (128 characters max) Required
addrLine1 Card holder’s street address. (64 characters max) Required
addrLine2 Card holder’s street address line 2. (64 characters max) Required if “country” value is: CHN, JPN, RUS - Optional for all other “country” values.
city Card holder’s city. (64 characters max) Required
state Card holder’s state. (64 characters max) Required if “country” value is ARG, AUS, BGR, CAN, CHN, CYP, EGY, FRA, IND, IDN, ITA, JPN, MYS, MEX, NLD, PAN, PHL, POL, ROU, RUS, SRB, SGP, ZAF, ESP, SWE, THA, TUR, GBR, USA - Optional for all other “country” values.
zipCode Card holder’s zip. (16 characters max) Required if “country” value is ARG, AUS, BGR, CAN, CHN, CYP, EGY, FRA, IND, IDN, ITA, JPN, MYS, MEX, NLD, PAN, PHL, POL, ROU, RUS, SRB, SGP, ZAF, ESP, SWE, THA, TUR, GBR, USA - Optional for all other “country” values.
country Card holder’s country. (64 characters max) Optional


Example Authorization Request

Twocheckout::privateKey('BE632CB0-BB29-11E3-AFB6-D99C28100996');
Twocheckout::sellerId('901248204');
// Twocheckout::sandbox(true);  #Uncomment to use Sandbox

try {
    $charge = Twocheckout_Charge::auth(array(
        "merchantOrderId" => "123",
        "token" => 'Y2U2OTdlZjMtOGQzMi00MDdkLWJjNGQtMGJhN2IyOTdlN2Ni',
        "currency" => 'USD',
        "total" => '10.00',
        "billingAddr" => array(
            "name" => 'Testing Tester',
            "addrLine1" => '123 Test St',
            "city" => 'Columbus',
            "state" => 'OH',
            "zipCode" => '43123',
            "country" => 'USA',
            "email" => 'testingtester@2co.com',
            "phoneNumber" => '555-555-5555'
        ),
        "shippingAddr" => array(
            "name" => 'Testing Tester',
            "addrLine1" => '123 Test St',
            "city" => 'Columbus',
            "state" => 'OH',
            "zipCode" => '43123',
            "country" => 'USA',
            "email" => 'testingtester@2co.com',
            "phoneNumber" => '555-555-5555'
        )
    ), 'array');
    if ($charge['response']['responseCode'] == 'APPROVED') {
        echo "Thanks for your Order!";
    }
} catch (Twocheckout_Error $e) {
    $e->getMessage();
}
Twocheckout::API.credentials = {
    :seller_id => '1817037',
    :private_key => '8CE03B2D-FE41-4C53-9156-52A8ED5A0FA3',
#   :sandbox => 1   #Uncomment to use Sandbox
}

params = {
    :merchantOrderId     => '123',
    :token          => 'ZmYyMzMyZGMtZTY2NS00NDAxLTlhYTQtMTgwZWIyZTgwMzQx',
    :currency       => 'USD',
    :total          => '1.00',
    :billingAddr    => {
        :name => 'Testing Tester',
        :addrLine1 => '123 Test St',
        :city => 'Columbus',
        :state => 'OH',
        :zipCode => '43123',
        :country => 'USA',
        :email => 'example@2co.com',
        :phoneNumber => '555-555-5555'
    }
}

begin
  result = Twocheckout::Checkout.authorize(params)
rescue Twocheckout::TwocheckoutError => e
  puts e.message
end
var tco = new Twocheckout({
    sellerId: "901248156",
    privateKey: "3508079E-5383-44D4-BF69-DC619C0D9811",
//  sandbox: true   #Uncomment to use Sandbox
});

var params = {
    "merchantOrderId": "123",
    "token": "MWQyYTI0ZmUtNjhiOS00NTIxLTgwY2MtODc3MWRlNmZjY2Jh",
    "currency": "USD",
    "total": "10.00",
    "billingAddr": {
        "name": "Testing Tester",
        "addrLine1": "123 Test St",
        "city": "Columbus",
        "state": "Ohio",
        "zipCode": "43123",
        "country": "USA",
        "email": "example@2co.com",
        "phoneNumber": "5555555555"
    }
};

tco.checkout.authorize(params, function (error, data) {
    if (error) {
        console.log(error.message);
    } else {
        console.log(JSON.stringify(data));
    }
});
twocheckout.Api.auth_credentials({
    'private_key': '8CE03B2D-FE41-4C53-9156-52A8ED5A0FA3',
    'seller_id': '1817037',
#   'mode': 'sandbox'  #Uncomment to use Sandbox
})

params = {
    'merchantOrderId': '123',
    'token': 'ODAxZjUzMDEtOWU0MC00NzA3LWFmMDctYmY1NTQ3MDhmZDFh',
    'currency': 'USD',
    'total': '1.00',
    'billingAddr': {
        'name': 'Testing Tester',
        'addrLine1': '123 Test St',
        'city': 'Columbus',
        'state': 'OH',
        'zipCode': '43123',
        'country': 'USA',
        'email': 'example@2co.com',
        'phoneNumber': '555-555-5555'
    }
}

try:
    result = twocheckout.Charge.authorize(params)
    print result.responseCode
except TwocheckoutError as error:
    print error.msg
TwoCheckoutConfig.SellerID = "901248156";
TwoCheckoutConfig.PrivateKey = "8CE03B2D-FE41-4C53-9156-52A8ED5A0FA3";
// TwoCheckoutConfig.Sandbox = true;    #Uncomment to use Sandbox

try
{
    var Billing = new AuthBillingAddress();
    Billing.addrLine1 = "123 test st";
    Billing.city = "Columbus";
    Billing.zipCode = "43123";
    Billing.state = "OH";
    Billing.country = "USA";
    Billing.name = "Testing Tester";
    Billing.email = "example@2co.com";
    Billing.phoneNumber = "5555555555";

    var Customer = new ChargeAuthorizeServiceOptions();
    Customer.total = (decimal)1.00;
    Customer.currency = "USD";
    Customer.merchantOrderId = "123";
    Customer.billingAddr = Billing;
    Customer.token = "MzIwNzI3ZWQtMjdiNy00NTVhLWFhZTEtZGUyZGQ3MTk1ZDMw";

    var Charge = new ChargeService();
    
    var result = Charge.Authorize(Customer);
    Console.Write(result);
}
catch (TwoCheckoutException e)
{
    Console.Write(e);
}
Twocheckout.privatekey = "3508079E-5383-44D4-BF69-DC619C0D9811";
// Twocheckout.mode = "sandbox";    #Uncomment to use Sandbox

try {
    HashMap billing = new HashMap();
    billing.put("name", "Testing Tester");
    billing.put("addrLine1", "xvxcvxcvxcvcx");
    billing.put("city", "Columbus");
    billing.put("state", "Ohio");
    billing.put("country", "USA");
    billing.put("zipCode", "43230");
    billing.put("email", "tester@2co.com");
    billing.put("phoneNumber", "555-555-5555");

    HashMap request = new HashMap();
    request.put("sellerId", "1817037");
    request.put("merchantOrderId", "test123");
    request.put("token", "MGI4OTU0OTQtMDIxNi00YThlLTliOTctZjg1YmJiMzg0MjA3");
    request.put("currency", "USD");
    request.put("total", "1.00");
    request.put("billingAddr", billing);

    Authorization response = TwocheckoutCharge.authorize(request);
    String message = response.getResponseMsg();
} catch (Exception e) {
    String message = e.toString();
}
curl -X POST https://sandbox.2checkout.com/checkout/api/1/901248156/rs/authService \
    -d '{"sellerId": "901248156", "privateKey": "8CE03B2D-FE41-4C53-9156-52A8ED5A0FA3", "merchantOrderId": "123", "token": "ODAxZjUzMDEtOWU0MC00NzA3LWFmMDctYmY1NTQ3MDhmZDFh", "currency": "USD", "lineItems": [{"name": "Demo Item", "price": "4.99", "type": "product", "quantity": "1", "recurrence": "4 Year", "startupFee": "9.99"}  ], "billingAddr": {"name": "testing tester", "addrLine1": "123 test blvd", "city": "columbus", "state": "Ohio", "zipCode": "43123", "country": "USA", "email": "example@2co.com", "phoneNumber": "123456789"} }' \
    -H 'Accept: application/json' -H 'Content-Type: application/json'

Authorization Response Object

The ‘response’ sub object is returned on successful authorizations to provide the result and transaction details.

Base Attributes

Attribute Description
type Response Object Type “AuthResponse”
merchantOrderId Your custom order identifier registered to the sale.
orderNumber 2Checkout Order Number
transactionId 2Checkout Invoice ID
responseMsg Message indicating the result of the authorization attempt.
responseCode Code indicating the result of the authorization attempt.
total The Sale Total. Format: 0.00-99999999.99.
currencyCode The sale currency code.

Lineitem Attributes

Attribute Description
lineitems Array of lineitem objects associated with the sale returned in the order that they are passed in.
(Returned as a sub object to the Response Object.)
type The type of line item that is being passed in.
name Name of the item passed in.
quantity Quantity of the item passed in.
price Price of the line item.
productId Your custom product identifier.
tangible Y or N.
recurrence Sets billing frequency.
duration Sets how long to continue billing.
startupFee Any start up fees for the product or service.

Lineitem Option Attributes

Attribute Description
options Array of option objects returned in the order that they are passed in.
(Returned as a sub object of a lineItem object.)
optName Name of product option.
optValue Option selected.
optSurcharge Option price in seller currency.

Billing Address Attributes

Attribute Description
billingAddr Object that defines the billing address.
(Returned as a sub object to the Response Object.)
name Card holder’s name.
addrLine1 Card holder’s street address.
addrLine2 Card holder’s street address line 2.
city Card holder’s city.
state Card holder’s state.
zipCode Card holder’s zip.
country Card holder’s country.
email Card holder’s email.
phone Card holder’s phone.
phoneExt Card holder’s phone extension.

Shipping Address Attributes

Attribute Description
shippingAddr Object that defines the shipping address.
(Returned as a sub object to the Response Object.)
name Recipient name.
addrLine1 Recipient’s street address.
addrLine2 Recipient’s street address line 2.
city Recipient’s city.
state Recipient’s state.
zipCode Recipient’s zip.
country Recipient’s country.


Example Response JSON Object

{
    "validationErrors": null,
    "exception": null,
    "response": {
        "type": "AuthResponse",
        "lineItems": [
            {
                "options": [],
                "price": "6.99",
                "quantity": "2",
                "recurrence": "1 Month",
                "startupFee": null,
                "productId": "123",
                "tangible": "N",
                "name": "Demo Item 1",
                "type": "product",
                "description": "",
                "duration": "1 Year"
            },
            {
                "options": [
                    {
                        "optName": "Size",
                        "optValue": "Large",
                        "optSurcharge": "1.00"
                    }
                ],
                "price": "1.99",
                "quantity": "1",
                "recurrence": null,
                "startupFee": null,
                "productId": "",
                "tangible": "N",
                "name": "Demo Item 2",
                "type": "product",
                "description": "",
                "duration": null
            },
            {
                "options": [],
                "price": "3.00",
                "quantity": "1",
                "recurrence": null,
                "startupFee": null,
                "productId": "",
                "tangible": "Y",
                "name": "Shipping Fee",
                "type": "shipping",
                "description": "",
                "duration": null
            }
        ],
        "transactionId": "205182114564",
        "billingAddr": {
            "addrLine1": "123 Test St",
            "addrLine2": null,
            "city": "Columbus",
            "zipCode": "43123",
            "phoneNumber": "5555555555",
            "phoneExtension": null,
            "email": "example@2co.com",
            "name": "Testing Tester",
            "state": "Ohio",
            "country": "USA"
        },
        "shippingAddr": {
            "addrLine1": "123 Test St",
            "addrLine2": "",
            "city": "Columbus",
            "zipCode": "43123",
            "phoneNumber": null,
            "phoneExtension": null,
            "email": null,
            "name": "Testing Tester",
            "state": "OH",
            "country": "USA"
        },
        "merchantOrderId": "123",
        "orderNumber": "205182114555",
        "recurrentInstallmentId": null,
        "responseMsg": "Successfully authorized the provided credit card",
        "responseCode": "APPROVED",
        "total": "19.97",
        "currencyCode": "USD",
        "errors": null
    }
}


Errors

If an error occurs when attempting to authorize the sale, such as a processing error or an error in the JSON request, the errorCode and errorMsg will be returned in the exception sub object in the response body.

Base Attributes

Error Code Error Message Cause
300 Unauthorized Seller unauthorized to use the API or incorrect private key.
Invalid Token
200 Unable to process the request Incorrect attributes or malformed JSON object.
400 Bad request - parameter error Missing required attributes or invalid token.
600 Authorization Failed Credit Card failed to authorize.
601 Payment Authorization Failed:  Please update your cards expiration date and try again, or try another payment method. Invalid Expiration Date.
602 Payment Authorization Failed:  Please verify your Credit Card details are entered correctly and try again, or try another payment method. Credit Card failed to authorize.
603 Your credit card has been declined because of the currency you are attempting to pay in.  Please change the currency of the transaction or use a different card and try again. Invalid Currency for card type.
604 Payment Authorization Failed: Credit is not enabled on this type of card, please contact your bank for more information or try another payment method. Credit Card failed to authorize.
605 Payment Authorization Failed: Invalid transaction type for this credit card, please use a different card and try submitting the payment again, or contact your bank for more information. Invalid transaction type for credit card.
606 Payment Authorization Failed: Please use a different credit card or payment method and try again, or contact your bank for more information. Credit Card failed to authorize.
607 Payment Authorization Failed: Please verify your information and try again, or try another payment method. Credit Card failed to authorize.


Example Exception JSON Object


{
    "validationErrors": null,
    "exception": {
        "errorMsg": "Payment Authorization Failed:  Please verify your Credit Card details are entered correctly and try again, or try another payment method.",
        "httpStatus": "400",
        "exception": false,
        "errorCode": "602"
    },
    "response": null
}