Transaction API Documentation

Lime Light API will accept various method calls using https POST or https GET.   Each API call must have at a minimum, an API username, API password and an API method name.  The API username and password are different than those used for your Lime Light CRM system. The username and password for your API will be assigned to you by Lime Light CRM support, you can find these credentials under API Accounts from Admin Settings.  The API method names are listed below followed by the required request parameters and response parameters.

The following conventions are used in the parameter tables below:

FORMAT VALUES:  A = Alphanumeric, N = numeric

There are currently three methods that can be used to post new orders into the system which include:

  • NewOrder (requiring all fields re-entered each time and re-passed to the API each time)
  • NewOrderCardOnFile (passing in an existing order's information, but new product, campaign and shipping parameters to make a sale of a card on file)
  • NewOrderWithProspect (first using the NewProspect method to create a new prospect record.  Then passing that main prospectId returned back as prospectId to use that existing information you captured earlier to complete the sale and clean up the prospect record if sale is completed without decline)

The following methods can be used in conjunction with the aforementioned methods:

  • NewProspect (creates a new prospect record which can then be converted into a customer via the NewOrderWithProspect)
  • authorize_payment (takes basic billing and card data fields used in NewOrder and simply authorizes against the gateway for the amount supplied. No order is created. Transaction data is returned)
  • three_d_redirect (takes an order id from the crm and does the final phase of the 3DS process and redirects the user to their bank url to fill out final pieces of information to verify the customer and complete the order.)

 

NewOrder, NewOrderCardOnFile, NewOrderWithProspect, authorize_payment request fields:


Field Name


Format/Value


Comments


  Method Used

method

NewOrder,NewOrderCardOnFile, NewOrderWithProspect

Required - Creates a new order.

NewOrder, NewOrderCardOnFile, NewOrderWithProspect, authorize_payment

username

String

Required - API username

NewOrder, NewOrderCardOnFile, NewOrderWithProspect, authorize_payment

password

String

Required - API password

NewOrder, NewOrderCardOnFile, NewOrderWithProspect, authorize_payment

firstName

A - Max 64 Characters

Required - Customer's first name

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

lastName

A - Max 64 Characters

Required - Customer's last name

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

shippingAddress1

A - Max 64 Characters

Required - Customer's shipping address1

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

shippingAddress2

A - Max 64 Characters

Optional- Customer's Shipping address 2  NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

shippingCity

A - Max 32 Characters

Required - Customer's shipping city

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

shippingState

A- Max 32 Characters

Required-Customer's shipping state. For US states use the 2 character abbreviation; for other countries use the full state name or state code (if applicable, see state codes* look-up below)

New Order, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

shippingZip

N - Max 10 digits

Required - Customer's shipping zipcode

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

shippingCountry

2 character country value*

Required - Customer's shipping country

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

billingFirstName

A - Max 64 Characters

Optional-Customer's Billing First Name

NewOrder, information copied from prospective shipping fields (if using NewOrderWithProspect and passing billingSameAsShipping=YES) or previousOrderId record (if using NewOrderCardOnFile),authorize_payment

billingLastName

A - Max 64 Characters

Optional-Customer's Billing Last Name

NewOrder, information copied from prospective shipping fields (if using NewOrderWithProspect and passing billingSameAsShipping=YES) or previousOrderId record (if using NewOrderCardOnFile),authorize_payment

billingAddress1

A - Max 64 Characters

Required - Customer's billing address1

NewOrder, information copied from prospective shipping fields (if using NewOrderWithProspect and passing billingSameAsShipping=YES) or previousOrderId record (if using NewOrderCardOnFile),authorize_payment

billingAddress2

A - Max 64 Characters

Optional- Customer's billing address2  NewOrder, information copied from prospective shipping fields (if using NewOrderWithProspect and passing billingSameAsShipping=YES) or previousOrderId record (if using NewOrderCardOnFile),authorize_payment

billingCity

A - Max 32 Characters

Required - Customer's billing city

NewOrder, information copied from prospective shipping fields (if using NewOrderWithProspect and passing billingSameAsShipping=YES) or previousOrderId record (if using NewOrderCardOnFile),authorize_payment

billingState

A - Max 32 Characters

Required - Customer's shipping state. For US states use the 2 character abbreviation; for other countries use the full state name or state code (if applicable see state code look-up below

NewOrder, information copied from prospective shipping fields (if using NewOrderWithProspect and passing billingSameAsShipping=YES) or previousOrderId record (if using NewOrderCardOnFile),authorize_payment

billingZip

N - Max 10 digits

Required - Customer's billing zip

NewOrder, information copied from prospective shipping fields (if using NewOrderWithProspect and passing billingSameAsShipping=YES) or previousOrderId record (if using NewOrderCardOnFile),authorize_payment

billingCountry

2 character country value*

Required - Customer's billing country

NewOrder, information copied from prospective shipping fields (if using NewOrderWithProspect and passing billingSameAsShipping=YES) or previousOrderId record (if using NewOrderCardOnFile),authorize_payment

phone

N - Max 18 Characters

Required - Customer's phone number

*If using Kount, and NOT collecting a phone number, please use 0123456789.

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile),authorize_payment

email

A - Max 96 Characters

Required - Customer's email address

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile),authorize_payment

creditCardType

amex, visa, master, discover, checking, offline, solo, maestro, switch, boleto, paypal, diners, hipercard, aura, eft_germany, giro, amazon, icepay, bitcoin_pg, eurodebit, sepa, boleto_bradesco, boleto_caixa_eco_fed, boleto_hsbc, boleto_banco_do_bras, boleto_itau, cielo_visa, cielo_mastercard, cielo_amex, cielo_diners, cielo_elo, redecard_webs_visa, redecard_webs_master

Required - Credit card type. 

NewOrder,NewOrderWithProspect (not needed for NewOrderCardOnFile),authorize_payment

creditCardNumber

N - Max 20 digits

Required - Credit card or CNPJ or CPF ID if using Boleto

NewOrder,NewOrderWithProspect (not needed for NewOrderCardOnFile),authorize_payment

expirationDate

N - MMYY

Required, Must be in MMYY format, 4 digits only.

NewOrder,NewOrderWithProspect (not needed for NewOrderCardOnFile),authorize_payment

CVV

N - Max 4 digits

Required if creditCardType not checking or offline. Used as issue id if creditCardType is switch,solo, or maestro. Use CVV=OVERRIDE to exclude the CVV from the gateway post.

NewOrder,NewOrderWithProspect (not needed for NewOrderCardOnFile),authorize_payment

checkAccountNumber N - Max 50 digits Required if creditCardType is checking or eft_germany NewOrder,NewOrderWithProspect (not needed for NewOrderCardOnFile)
checkRoutingNumber N - Max 50 digits Required if creditCardType is checking or eft_germany (relates to bank number) NewOrder,NewOrderWithProspect (not needed for NewOrderCardOnFile)
sepa_iban A - Max 50 digits Required if creditCardType is sepa NewOrder,NewOrderWithProspect (not needed for NewOrderCardOnFile)
sepa_bic A - Max 50 digits Required if creditCardType is sepa NewOrder,NewOrderWithProspect (not needed for NewOrderCardOnFile)
eurodebit_acct_num  A - Max 50 digits Required if creditCardType is eurodebit  NewOrder,NewOrderWithProspect (not needed for NewOrderCardOnFile)
eurodebit_route_num  A - Max 50 digits Required if creditCardType is eurodebit  NewOrder,NewOrderWithProspect (not needed for NewOrderCardOnFile)

tranType

Sale


Required, cannot be blank.  Tells what kind of credit card sale to run.

NewOrder, NewOrderCardOnFile, NewOrderWithProspect

ipAddress

A - 15 Characters Max

Required - Customer's IP Address

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile),authorize_payment

AFID

A - 255 Characters Max

Optional - Affiliate Id

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

SID

A - 255 Characters Max

Optional - Sub-Affiliate Id

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

AFFID

A - 255 Characters Max

Optional - Affiliate Id

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

C1

A - 255 Characters Max

Optional - Sub-Affiliate Id

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

C2

A - 255 Characters Max

Optional - Sub-Affiliate Id

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

C3

A - 255 Characters Max

Optional - Sub-Affiliate Id

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

AID

A - 255 Characters Max

Optional - Affiliate Id

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

OPT

A - 255 Characters Max

Optional - Sub-Affiliate Id

NewOrder, information pulled from prospectId record (if using NewOrderWithProspect) or previousOrderId record (if using NewOrderCardOnFile)

click_id

A - 255 Characters Max

Optional - Click ID used by your affiliate tracking system to identify unique clicks/requests

NewOrder, NewOrderCardOnFile, information pulled from prospectId record (if using NewOrderWithProspect)

productId

N - Integer


Required - Valid Lime Light product id to use for the order

NewOrder, NewOrderCardOnFile, NewOrderWithProspect, authorize_payment

campaignId

N - Integer


Required - Valid Lime Light campaign id to use for the order

NewOrder, NewOrderCardOnFile, NewOrderWithProspect, authorize_payment

shippingId

N - Integer


Required - Valid Lime Light shipping id to use for the order

NewOrder, NewOrderCardOnFile, NewOrderWithProspect

upsellCount

N - Integer

 

Required – Flag to indicate that the order has upsells.

1 = has upsells

0 = no upsells

NewOrder, NewOrderCardOnFile, NewOrderWithProspect

upsellProductIds

Comma delimited string of Lime Light product ids.   Example: 1,2,4,11

Optional - Used only if upsellCount is = 1

NewOrder, NewOrderCardOnFile, NewOrderWithProspect

dynamic_product_price_XX

You can dynamically set the price of the product by sending over a price for product XX (where XX is the product ID)

Example would be dynamic_product_price_5=99.99

Would purchase product ID 5 at 99 dollars and 99 cents

Optional

NewOrder, NewOrderCardOnFile, NewOrderWithProspect

prospectId N - Integer

Required on NewOrderWithProspect

Please pass the prospect you wish to place the order against.
NewOrderWithProspect

billingSameAsShipping

A - YES or NO (case insensitive)

Optional on NewOrder, and NewOrderWithProspect.

If left blank, will default to yes and will copy all the shipping columns into the billing columns.

NewOrder, NewOrderWithProspect

initializeNewSubscription Either include this or don't.  If you include this it will restart the subscription.  If you don't include it and the transaction is on the same campaign Id as the original order on file, it will relate the new order as a child order Optional - If there is a case where you use NewOrderCardOnFile where you wish to create a new initial transaction instead of a new child order NewOrderCardOnFile

previousOrderId

N - Integer

Required On NewOrderCardOnFile.

Pass previous orderId for the card on file and all previous sale information will be used for the new order on file.

NewOrderCardOnFile

 

notes

 

 

A - 512 Characters Max

Optional - Notes to be appended to the orders history on the orders detail.

NewOrder, NewOrderCardOnFile, NewOrderWithProspect

product_qty_x

product_qty_4=10

Where x is the product id and the value is the quantity

NewOrder, NewOrderCardOnFile, NewOrderWithProspect

forceGatewayId

N -Integer

Optional-Lime Light gateway to force the transaction into

NewOrder, NewOrderCardOnFile, NewOrderWithProspect

preserve_force_gateway

N -Integer

Optional – Flag to preserve the forceGatewayId (if provided). 1 or 0. Defaults to 0 if not provided.

NewOrder, NewOrderCardOnFile, NewOrderWithProspect

createdBy

A -100 Characters Max

Optional-Username of employee to assign as creator of order

NewOrder, NewOrderCardOnFile, NewOrderWithProspect

thm_session _id

A -255 Characters Max

Optional-Threat Matrix Session Id

NewOrder, NewOrderWithProspect

total_installments

N - Integer

Optional-Total installments for Cobre Bem Gateway

NewOrder, NewOrderWithProspect

alt_pay_token

A - 20 Characters Max

Conditional -Alternative payment token retrieved. Required if creditCardType is Paypal, Amazon, or IcePay

NewOrder, NewOrderWithProspect

alt_pay_payer_id A - 20 Characters Max Conditional - Alternative payment PayerId retrieved. Required if creditCardType is Paypal, Amazon NewOrder, NewOrderWithProspect
secretSSN N – Integer 4 Characters Max Conditional – Required If using Actum Processing as the check provider,
Passes “ for any other provider
NewOrder,
NewOrderCardOnFile
force_subscription_cycle Integer (0 – 1)

Conditional – This field must be provided to use any of the 3 fields below:

recurring_days, subscription_week, subscription_day
NewOrder, NewOrderCardOnFile, NewOrderWithProspect
recurring_days Integer Conditional – This value is used when the products subscription type is Bill By Cycle or Bill By Date(Bill By Date the value can only be from (1 -31) NewOrder, NewOrderCardOnFile, NewOrderWithProspect
subscription_week

Integer(1-5)

1 = First                                    

2 = Second                                

3 = Third                                   

4 = Fourth

5 = Last                                

Conditional – This is meant for subscription type Bill By Day. (If this one is used then subscription_day also needs to be populated) NewOrder, NewOrderCardOnFile, NewOrderWithProspect
subscription_day

Integer(1-7)

1 = Sunday                                

2 = Monday                              

3 = Tuesday                              

4 = Wednesday                          

5 = Thursday                            

6 = Friday                                 

7 = Saturday

 Conditional – This is meant for subscription type Bill By Day. (If this one is used then subscription_week also needs to be populated)  NewOrder, NewOrderCardOnFile, NewOrderWithProspect
product_attribute

URL array of product attribute => options to be used. Must be of format:

product_attribute[product_id]
[attribute] = option.

See examples** below

Conditional. If the product being purchased has variants assigned, attributes must be provided to match a valid variant. Must not be provided for products that do not have variants. NewOrder, NewOrderCardOnFile, NewOrderWithProspect
auth_amount

Float

Amount to authorize for. Defaults to 1.00 if not supplied or invalid authorize_payment
master_order_id

integer

Lime Light order id to which the new order will be linked, if approved. NewOrder, NewOrderCardOnFile, NewOrderWithProspect
promoCode

A – 100 Characters Max

Lime Light promo code in coupon profile that is attached to campaign NewOrder, NewOrderCardOnFile, NewOrderWithProspect
temp_customer_id

A – 32 characters max

Optional, value returned from authorize_payment when save_customer is on. If used, omit creditCardType, creditCardNumber, expirationDate, and CVV NewOrder,NewOrderCardOnFile, NewOrderWithProspect

cascade_enabled

Integer – 0 or 1

Optional, if enabled, allows the authorization to follow a cascade profile. authorize_payment
save_customer

Integer – 0 or 1

Optional, if enabled, saves temporary customer data authorize_payment
three_d_redirect_url

Success URL for 3D Secure redirect

Conditional, if gateway has 3D Secure enabled NewOrder, NewOrderWithProspect
sessionId

A-32 characters max

Conditional, if using Kount NewOrder, NewOrderCardOnFile, NewOrderWithProspect
cascade_override

Integer -0 or 1

Optional, if passed as '1', the cascade profile will be overridden. NewOrder, NewOrderCardOnFile
validate_only_flag

Integer - 0 or 1

Optional, if passed as '1', the card will be validated.  If passed as '0' , the card will be authorized at the auth_amount. authorize_payment
void_flag

Integer - 0 or 1

Optional, if passed as '1', the authorization will be immediately voided.  If passed as '0', the authorization will remain. authorize_payment

 

**Product attributes can be built several ways. HTML bracket syntax for arrays is sampled below as a <select> field. cURL requests can also be simulated to provide the data to LimeLight. IDs can be obtained by calling the product_attribute_index method of the membership API.

 

Option 1: Text values
<select name=”product_attribute[1][Color]”>
  <option value=”Red”>Red</option>
  <option value=”Blue”>Blue</option>
</select>

 

Option 2: Numeric ids
<select name=”product_attribute[1][123]”>
  <option value=”124”>Red</option>
  <option value=”125”>Blue</option>
</select>

Option 3: cURL request (in PHP)
// Multiple products with attributes. Showing both text and numeric attribute/option representations
$attr = array(
            ‘1’ = array(
                        ‘Color’ => ‘Red’
            ),
            ‘2’ = array(
                        ‘123’ => ‘124’
            )
);

// Assign to ‘product_attribute’ key
$data[‘product_attribute’] = $attr;

// Important; http_build_query is required for cURL to properly parse the data as an array
curl_setopt($cs, CURLOPT_POSTFIELDS, http_build_query($data));

 

 

NewOrder, NewOrderCardOnFile, NewOrderWithProspect, and authorize_payment Responses:


Field Name


Format/Value


Comments

errorFound

N - 1 digit

0 or 1.  If 1, then errorMessage will be posted.

errorMessage

A - 255 Characters Max

Optional, only posted if errorFound is 1; not provided with authorized_payment.

responseCode

N - 5 Digits Max

Tells response of transaction. See appendix A for complete list

transactionID

A - 100 Characters Max

Optional, only posted if responseCode is 100

authId

A - 100 Characters Max

Optional, only posted if responseCode is 100

orderId

N - Integer

Lime Light order Id for the order that was just created.

orderTotal

A - 25 Characters Max

Optional, only posted if responseCode is 100

customerId

N - Integer

Optional, only posted if responseCode is 100

orderSalesTaxPercent

N - Float Sales Tax Percent

orderSalesTaxAmount

N - Float Sales Tax Amount

declineReason

A - 255 Characters Max


Optional, only posted if responseCode is 800.  Text string stating decline reason, comes from the gateway.

product1DigitalURL

A - 255 Characters Max

Optional, only posted if product is a digitally delivered good. "1" will be replaced with an incremented number for each applicable product.

product1DigitalUsername

A - 25 Characters Max

Optional, only posted if product is a digitally delivered good and username is generated.

product1DigitalPassword

A - 25 Characters Max

Optional, only posted if product is a digitally delivered good and a password is generated.

product1DigitalCustomFields

A – 255 Characters Max

Optional, only posted if product is a digitally delivered good and additional fields have been requested for the provider. Each field/value pair will be colon “:” separated, each set will be pipe “|” separated (eg: product1DigitalCustomFields=field1:value1|field2:value2)

gatewayId

N - Integer

The Lime Light gatewayId that the order was charged against. If load balanced, this can be several different gateways on the same campaign.

gatewayDescriptor A - 255 Characters Max For the gatewayId charged, this is the value of any non-empty value that is stored as the descriptor in the gateway popup
gatewayCustomerService A - 255 Characters Max For the gatewayId charged, this is the value of any non-empty value that is stored as the customer service number in the gateway popup

test

N - Integer

Test order flag. 1=test order. 0=not a test. This response is shown only on approved orders.

prepaid_match

Yes or NO

Identifies whether or not a credit card matched a prepaid BIN, if applicable

prepaid

1 or 0

Identifies whether or not a credit card matched a prepaid BIN, if applicable

orderDocuments

JSON

JSON Encoded array of documents pertaining to gateways such as boleto

 

giro_account_name

A

Giro account name associated with the Pacnet profile assigned to the campaign. Only provided if creditCardType is giro

 

 

giro_bank_name

 

A

Giro account name associated with the Pacnet profile assigned to the campaign. Only provided if creditCardType is giro

 

 

giro_bank_address

 

A

Giro bank address associated with the Pacnet profile assigned to the campaign. Only provided if creditCardType is giro

giro_sort_code 

A

Giro sort code associated with the Pacnet profile assigned to the campaign. Only provided if creditCardType is giro

 

 

giro_account_number

 

A

Giro account number associated with the Pacnet profile assigned to the campaign. Only provided if creditCardType is giro

giro_iban

A

Giro IBAN associated with the Pacnet profile assigned to the campaign. Only provided if creditCardType is giro

 

giro_swift

A

Giro Swift code associated with the Pacnet profile assigned to the campaign. Only provided if creditCardType is giro

subscription_id[1]
subscription_id[n]

A

Subscription ID associated with each product purchased, where n represents the product ID.

temp_customer_id

A

Optional, provided when passing the save_customer parameter with the authorized_payment method

alt_pay_url

Encoded URL

Returned when using alternative payment providers (i.e. Bitcoin Paygate). This is the redirect URL for Bitcoin transactions.

processor_id

A

Returned when using a gateway integration that passes back the processor ID for the sale. ‘Post Processor ID’ must be enabled in the gateway profile.

 

 

 

 

NewOrderCardOnFile

NewOrderCardOnFile method supports all the existing parameters of the NewOrder method, but simplifies the process so you can pass an existing order_id under the previousOrderId parameter, so you don’t have to pass existing information under the customer associated with that order.

NewOrderCardOnFile typical post using https GET or POST:

https://yourdomain.com/admin/transact.php? username=xxxUserNamexxx&password=xxxPassWordxxx&method=NewOrderCardOnFile&previousOrderId=10000&productId=1&campaignId=3&shippingId=1&product_qty_1=10

or

 

Array

(

    [username] => xxxUserNamexxx

    [password] => xxxPassWordxxx

    [method] => NewOrderCardOnFile

    [previousOrderId] => 10000

    [productId] => 1

    [campaignId] => 3

    [shippingId] => 1

    [product_qty_1] => 10

)

 

authorize_payment

authorize_payment utilizes the billing and card data fields used by NewOrder, as well as some basic CRM identifiers for campaign and product, and sends an authorization request to the gateway. No order is created. Upon successful authorization, the transaction information will be returned, otherwise the decline reason is provided. If no auth_amount is provided, it will default to a 1.00 authorization.

An optional parameter ‘save_customer’ will temporarily save the encrypted card data. Upon successfully saving the information, you will receive a temp_customer_id in the response in which this Id will be available for use with the NewOrder, NewOrderCardOnFile, or NewOrderWithProspect method for up to 24 hours after the call is made. 
 

 

 

NewOrderWithProspect

NewOrderWithProspect must be used in conjunction with the NewProspect call.  NewProspect will return a prospectId of which you must pass as "prospectId" on this call as well.  The logic flow is similar to that of a two-step campaign.

Please note that it is recommended to send a complete record with all available fields to pass upon initially sending the prospect through the NewProspect call to reduce confusion of what fields are required during the sale.  An example would be if you don’t pass IPAddress through the prospect record and don’t prompt or require IPAddress during the NewOrderWithProspect.  Our systems will reject that because there is a blank value on the IPAddress.

NewOrderWithProspect typical post using https GET or POST:

https://yourdomain.com/admin/transact.php? username=xxxUserNamexxx &password=xxxPassWordxxx&method=NewOrderWithProspect&prospectId=22&upsellCount=0&upsellProductIds=4&productId=1&campaignId=1&shippingId=1&creditCardType=master&creditCardNumber=1444444444444440&expirationDate=1015&CVV=252&tranType=Sale&billingSameAsShipping=yes&product_qty_1=10

or

 

Array

(

    [username] => xxxUserNamexxx

    [password] => xxxPassWordxxx

    [method] => NewOrderWithProspect

    [prospectId] => 22

    [upsellCount] => 0

    [upsellProductIds] => 4

    [productId] => 1

    [campaignId] => 1

    [shippingId] => 1

    [creditCardType] => master

    [creditCardNumber] => 1444444444444440

    [expirationDate] => 1015

    [CVV] => 252

    [tranType] => Sale

    [billingSameAsShipping] => yes

    [product_qty_1] => 10

)

 

 

 

 

NewProspect

The NewProspect API call is meant to allow you to do a two-step order where you capture initial prospect information and our API will return to you the prospect ID in the system.  If you capture all elements initially required for sale, then it is easy to submit the final order like the above NewOrderWithProspect post.

We allow our API calls to be flexible, where we only require email, campaignId and ipAddress when you create it in situations where that information isn’t available.  If you use it like this, please ensure to pass the other missing elements when you place the NewOrderWithProspect.

Please note that it is recommended to send a complete record with all available fields to pass upon initially sending the prospect through the NewProspect call to reduce confusion of what fields are required during the sale.  An example would be if you don’t pass IPAddress through the prospect record and don’t prompt or require IPAddress during the NewOrderWithProspect.  Our systems will reject that because there is a blank value on the IPAddress.

NewProspect request fields:


Field Name


Format/Value


Comments

method

NewProspect

Required - Creates a new order.

username

String

Required - API username

password

String

Required - API password

firstName

A - Max 64 Characters

Optional - But Must be completed before sale - Prospect's first name

lastName

A - Max 64 Characters

Optional - But Must be completed before sale - Prospect's last name

address1

A - Max 64 Characters

Optional - But Must be completed before sale - Prospect's shipping address1

address2

A - Max 64 Characters

Optional -Prospect's shipping address2

city

A - Max 32 Characters

Optional - But Must be completed before sale - Prospect's shipping city

state

A - Max 32 Characters

Optional - But Must be completed before sale - Prospect's shipping state. For US states, use the 2 character abbreviation; for other countries use the full state name or state code (if applicable, see state codes*)

zip

N - Max 10 digits

Optional - But Must be completed before sale - Prospect's shipping zipcode

country

2 character country value*

Optional - But Must be completed before sale - Prospect's shipping country

phone

N - Max 18 Characters

Optional - But Must be completed before sale - Customer's phone number

email

A - Max 96 Characters

Required - Prospect's email address

ipAddress

A - 15 Characters Max

Required - Prospect's IP Address

AFID

A - 100 Characters Max

Optional - Affiliate Id

SID

A - 100 Characters Max

Optional - Sub-Affiliate Id

AFFID

A - 100 Characters Max

Optional - Affiliate Id

C1

A - 100 Characters Max

Optional - Sub-Affiliate Id

C2

A - 100 Characters Max

Optional - Sub-Affiliate Id

C3

A - 100 Characters Max

Optional - Sub-Affiliate Id

AID

A - 100 Characters Max

Optional - Affiliate Id

OPT

A - 100 Characters Max

Optional - Sub-Affiliate Id

click_id

A - 255 Characters Max

Optional - Click ID used by your affiliate tracking system to identify unique clicks/requests

campaignId

N - Integer


Required  - Valid Lime Light campaign id to use for the prospect record

notes

A - 255 Characters Max

Optional - Any notes about the prospect to append to the prospect record

 

NewProspect response fields:


Field Name


Format/Value


Comments

errorFound

Numeric - 1 digit

0 or 1.  If 1, then errorMessage will be posted.

responseCode

Numeric - 5 Digits Max

Tells response of transaction. See appendix A for complete list

prospectId

Numeric

Internal LimeLight CRM Prospect ID Created

(If same email and campaign sent up matching prospect, existing ID will be passed and no new record added)

 

 

 

NewProspect typical post using https GET or POST:

https://yourdomain.com/admin/transact.php? username=xxxUserNamexxx&password=xxxPassWordxxx&method=NewProspect&campaignId=1&firstName=FirstName&lastName=LastName&address1=123+Main+St.&city=Tampa&state=FL&zip=90210&country=US&phone=8135551212&email=no-reply%40mydomain.com&AFID=AFID&SID=SID&AFFID=AFFID&C1=C1111&C2=C222&C3=C333&AID=AID&OPT=OPT&notes=Prospect+Notes&ipAddress=71.40.154.126

 

or

 

Array

(

    [username] => xxxUserNamexxx

    [password] => xxxPassWordxxx

    [method] => NewProspect

    [campaignId] => 1

    [firstName] => FirstName

    [lastName] => LastName

    [address1] => 123 Main St.

    [city] => Tampa

    [state] => FL

    [zip] => 90210

    [country] => US

    [phone] => 8135551212

    [email] => no-reply@mydomain.com

    [AFID] => AFID

    [SID] => SID

    [AFFID] => AFFID

    [C1] => C1111

    [C2] => C222

    [C3] => C333

    [AID] => AID

    [OPT] => OPT

    [notes] => Prospect Notes

    [ipAddress] => 71.40.154.126

)

 

 

three_d_redirect

This method is use for orders that return response code 101 from the NewOrder method. This method redirects the customer to their personal bank URL for 3D Secure payments.

three_d_redirect request fields:


Field Name


Format/Value


Comments

method

three_d_redirect

Required – Starts 3DS redirect process.

username

String

Required - API username

password

String

Required - API password

order_id

integer

Required – order_id that is in 3DS wait order status

 

 

three_d_redirect response fields:


Field Name


Format/Value


Comments

errorFound

Numeric - 1 digit

0 or 1.  If 1, then errorMessage will be posted.

responseCode

Numeric - 5 Digits Max

Tells response of transaction. See appendix A for complete list

declineReason

A - 255 Characters Max

Optional, only posted if responseCode is 800.  Text string stating decline reason, comes from the gateway.

orderId

N - Integer

Lime Light order Id for the order that was just created.

 

 

three_d_redirect typical post using https GET or POST:

https://yourdomain.com/admin/transact.php?username=xxxUserNamexxx &password=xxxPassWordxxx&method=three_d_redirect&order_id=1

or

 

Array

(

    [username] => xxxUserNamexxx

    [password] => xxxPassWordxxx

    [method] => three_d_redirect

    [order_id] => 1

)

 

 

Posting Details

Posts should be made to https://yourlimelightcrmdomain/admin/transact.php  Substitute the yourlimelightcrmdomain for whatever URL has been assigned to your installation.  The transact.php file expects an HTTPS POST using name value pairs that are URL encoded.

 

Testing transactions

To test NewOrder requests, just pass in valid data for the required fields and use the test credit card number, 1444444444444440.  This will allow you to create an order without it being processed by any gateway. 

 

Method Specific Message Legend

NewOrderCardOnFile

 

NewOrderWithProspect

 

 

 

 

 

Appendix A – Response Codes and Meanings

100 – Success    

101 – Order is 3DS and needs to go to bank url (use 3DS redirect method)                                                                                     

123 - Prepaid Credit Cards Are Not Accepted                                                                                                                                                                                       
200 – Invalid login credentials

201 - three_d_redirect_url is required

303 – Invalid upsell product Id of (XXX) found
304 – Invalid first name of (XXX) found
305 – Invalid last name of (XXX) found
306 – Invalid shipping address1 of (XXX) found
307 – Invalid shipping city of (XXX) found
308 – Invalid shipping state of (XXX) found
309 – Invalid shipping zip of (XXX) found
310 – Invalid shipping country of (XXX) found
311 – Invalid billing address1 of (XXX) found
312 – Invalid billing city of (XXX) found
313 – Invalid billing state of (XXX) found
314 – Invalid billing zip of (XXX) found
315 – Invalid billing country of (XXX) found
316 – Invalid phone number of (XXX) found
317 – Invalid email address of (XXX) found
318 – Invalid credit card type of (XXX) found
319 – Invalid credit card number of (XXX) found
320 – Invalid expiration date of (XXX) found
321 – Invalid IP address of (XXX) found
322 – Invalid shipping id of (XXX) found
323 – CVV is required for tranType 'Sale'
324 – Supplied CVV of (XXX) has an invalid length
325 – Shipping state must be 2 characters for a shipping country of US
326 – Billing state must be 2 characters for a billing country of US

327 – Invalid payment type of XXX

328 – Expiration month of (XXX) must be between 01 and 12

329 – Expiration date of (XXX) must be 4 digits long

330 – Could not find prospect record

331 – Missing previous OrderId

332 – Could not find original order Id

333 – Order has been black listed

334 – The credit card number or email address has already purchased this product(s)

335 – Invalid Dynamic Price Format

336 – checkRoutingNumber must be passed when checking is the payment type is checking or eft_germany

337 – checkAccountNumber must be passed when checking is the payment type is checking or eft_germany

338 – Invalid campaign to perform sale on.  No checking account on this campaign.

339 – tranType missing or invalid

340 - Invalid employee username of (XXX) found

341-  Campaign Id (XXX) restricted to user (XXX)

342 - The credit card has expired

400 – Invalid campaign Id of (XXX) found

411 – Invalid subscription field

412 – Missing subscription field

413 – Product is not subscription based

414 – The product that is being purchased has a different subscription type than the next recurring product

415 – Invalid subscription value

600 – Invalid product Id of (XXX) found

666- User does not have permission to use this method

667- This user account is currently disabled

668 - Unauthorized IP Address

669- Unauthorized to access campaign

700 – Invalid method supplied

705 – Order is not 3DS related

800 – Transaction was declined

900 – SSL is required to run a transaction

901 – Alternative payment payer id is required for this payment type

902 – Alternative payment token is required for this payment type

1000 – Could not add record

1001- Invalid login credentials supplied

1002- Invalid method supplied

 

In the above response codes, the value of XXX will be replaced with the bad value sent to the API. 

 

*Country and State Codes can be found here:

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.