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.
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/authServiceReplace (seller_id) with your 2Checkout seller ID.
Content-Type: application/json
Returns: JSON response
HTTP Method: POST
| 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.) |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
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'
The ‘response’ sub object is returned on successful authorizations to provide the result and transaction details.
| 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. |
| 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. |
| 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. |
| 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. |
| Card holder’s email. | |
| phone | Card holder’s phone. |
| phoneExt | Card holder’s phone extension. |
| 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. |
{
"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
}
}
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.
| 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. |
{
"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
}