international post api - payscout · creationdate:11/05/2011 documentname international post api...

International Post API

2 Page | Copyrighted 2011 — International Post API

Creation Date: 11/05/2011

Document Name International Post API

Document Owner Payscout, Inc.

Intended Audience DevelopersReview RequirementsSecurity EnvironmentSupporting Documents

Change Logs:﹡ Added response back information - 2011.12.28

﹡ Added transaction log information - 2011.12.28

﹡ Added adding products, pricing schedules, and offers - 2012-01-13

﹡ Added ip_address to documentation - 2012-02-24

﹡ Added override_processor_account_id, and override_processing_state - 2012-02-26

﹡ Added FAQ section, and changed use to required, and added ‘M/O’ - 2013-02-04

﹡ Changed phone number to a mandatory field - 2013-02-15

﹡ Added pass_through to documentation - 2013-02-12

﹡ Added raw_message to the response - 2013-08-02

﹡ Added social security number - 2013-09-02

﹡ Added more standardized messages to the list - 2013-09-03



Merchant Account Requirements

All merchants need to set up a merchant account with a Payscout sales representative. For security reasons you also must register all IP addresses of any servers you may use to connect to the gateway.

All transactions will be posted to this URL secure.andazsolutions.com.

To verify what our servers identify your system as, you could use this url:

https://secure.andazsolutions.com/util/ip

The Different APIs we support

SOAP: https://secure.andazsolutions.com/soap-web-service?wsdl

POST: https://secure.andazsolutions.com/post-web-service/process

Since WSDL is already descriptive in itself, this documentation is only to explain how to interact with the POST API. The naming conventions used are pretty consistent between the two methods, however, if you need assistance with either of these APIs please do not hesitate to contact us at [email protected].

There are three modes to Payscout’s API:﹡ Defined - Every product, every price schedule, every offer has to be defined in

Payscout's system before it can be used.﹡ Dynamic - This mode creates everything on the fly.

﹡ Undefined - Is a subset of Dynamic. This mode will create a undefinedproduct, an undefined offer, the only thing that is required for you to

define is the price schedule.

I will display each mode under the DEBIT processing_type (note: M - Mandatory, O -

Optional, X - Define, or use another Field).

mailto:[email protected]?subject=Assistance with Altobilling API



DEFINED MODE

Normally used for third party pages, and shopping carts. All products, offers, and

price schedules are required to be entered before hand. This also allows the ability

to make a offer, buy one get one free for example.

A real example:

https://secure.andazsolutions.com/cart/index/offer-id/1/site-id/4

Mode type: DEFINED

Field Description M/O

client_id Client id given to you by Andaz M

client_username Client username given to you by Andaz M

client_password Client password given to you by Andaz M

client_token Client token given to you by Andaz M

username Customer’s username O

password Customer’s password O

billing_date_of_birth Customer’s birth date (YYYYMMDD) M

billing_first_name Customer’s first name M

billing_last_name Customer’s last name M

billing_social_security_number Customer’s social security number O

billing_email_address Customer’s email address M

billing_cell_phone_number Customer’s cell phone number - only numbers O

billing_phone_number Customer’s phone number - only numbers M

billing_address_line_1 Customer’s address line 1 M

billing_address_line_2 Customer’s address line 2 O

billing_city Customer’s city M

billing_state Customer’s state O

billing_postal_code Customer’s postal code M

billing_country Customer’s country iso2 standard M

billing_drivers_license Customer’s driver’s license O

shipping_first_name Ship to first name O

shipping_last_name Ship to last name O

shipping_email_address Ship to email address O

shipping_cell_phone_number Ship to cell phone number - only numbers O

shipping_phone_number Ship to phone number - only numbers O

shipping_address_line_1 Ship to address line 1 O


shipping_city Ship to city O

shipping_state Ship to state O

shipping_postal_code Ship to postal code O

shipping_country Ship to country O



ip_address Customer’s IP M

mode defined M

routing_number Routing number to your checking (required for

check)

O

expiration_month The month the card expires (required for cc) M/O

expiration_year The year the card expires YYYY (required for

cc)

M/O

account_number The account number to your credit or checking M

cvv2 Card verification code (required for cc

-initial)

M/O

domain The domain of the purchase M

offer_id You can define the offer id M

processing_type This is used for all posts calls, however for

this specific example this is for debit

M

override_processor_account_id Allows you to have some control over which

merchant to send the transaction to

O

override_processing_state Allows you to define where in the processing

schedule you want to begin this transaction in

O

currency The currency the purchase is made in, default

is USD.

O

pass_through Variables you would like to store on our side.

Format: name1:value1,name2:value2

Example: OrderID:AEF10E,invoice_id:12121

O

DEFINING PRODUCTS, PRICING SCHEDULES, AND OFFERS

To set up products, pricing schedules, and offers, you will have to log into the web

interface, and click on the tab marked “Products & Pricing.” The order in which you

create each depends on you, however, the last stage is always Offers. An offer can

contain one product, or many. Lets start with the Product screen, after you click on

new:



Title, is the product name. The type is if it is a subscription base, or tangible. If you have different types that need to be added, please don’t hesitate to email [email protected]. Clients can be connected to a master account, so one can easily move between accounts via a drop down located at the upper right hand corner. There is one more thing that is needed to send a transaction, and that is site id.

Pricing Schedule Screen:

mailto:[email protected]



This is where you set the prices of your item.



Offers screen:

The title, is what you call the offer, you select the products you want to include in

the offer at the price you want to offer it.

Pricing Schedule has the detailed of the pricing schedule in a format like this:

Init. (00:$01.25), Inter. (00:$00.00), Recur. (25:$34.00:30)

This basically means that you charge the customer a 1.25 to start, 25 days later you

charge them $34.00, and every 30 days later. Depending on your permissions, it could

just be initial amount.

DYNAMIC MODE

For our clients who would like to have the fastest path to getting up and processing.

Your offers, your products, and pricing schedules are all done on the fly.

Mode Type: DYNAMIC










billing_date_of_birth Customer’s birthday (YYYYMMDD) M


























mode dynamic M


ach)

O




cc)

M/O


-initial)

M/O

domain The domain where the purchase is being made M

offer_name The offer name M

product_name The name of the product M

initial_amount The amount you want to charge M


10 Page| Copyrighted 2011 — International Post API



M



O

override_processing_state_id Allows you to define where in the processing


O


is USD.

O




O

UNDEFINED MODE

This is very much like the Dynamic mode. If you like having the data recorded by offer

name, and product names then Dynamic mode is for you, however, if you just want to

record the transaction; where your own system keeps the details, then undefined mode

is a good fit for what you might be looking for. What is required for undefined mode

is the domain and pricing schedule.

Mode Type: UNDEFINED








billing_date_of_birth Customer’s birthday (YYYYMMDD) M




























mode undefined M


ach)

O




cc)

M/O


-initial)

M/O

domain The domain where the purchase is being made M

initial_interval How long do you want to wait before you charge

this customer

M

initial_amount The amount you want to charge M



M



O

override_processing_state Allows you to define where in the processing


O


is USD.

O




O

REFUND

Credit, is how you can issue a credit.

Processing Type: CREDIT








processing_type Credit M

transaction_id Transaction given from the Authorized process M

amount Amount you desire to refund O

RESPONSES YOU WILL SEE

The responses sent back to you will be in json format, so you could have a parser

translate it into an array, like so (For approved transactions):

{

status: "approved",

customer_id: 232,

customer_account_id: 121,

transaction_id: 324234,

message: ‘’,

raw_message: ‘’,

results: null,

pass_through: [{’field’:’OrderId’,’value’:’23423423’},{’field’:’anything’,’

value’:’whatever you want’}]

}

For declined transactions:

{

status: "declined",

customer_id: 232,


transaction_id: 324234,

message: ‘’,


results: null,

pass_through: null

}

As for possible errors, please look in the FAQs.

If you have offers with multiple products, it would look like this:

{



status: "approved",

customer_id: 232,


transaction_id: 324234, // if there are multiple products, this is the primary.

message: ‘’,

results: [

{

status: “approved”,

product_id: 2,

message: ‘’,


transaction_id: 324234

},

{


product_id: 3,

message: ‘’,



},

{


product_id: 4,

message: ‘’,



}

]

}

TRANSACTION LOGS

https://secure.andazsolutions.com/post-web-service/transaction-log/from_time/2011-10-25

%2000:00:00/to_time/2011-10-28%2023:59:59/client_id/15/client_username/myusername/client_

password/mypassword/client_token/mytoken

The response from the server should look like this:

[

{

"original_transaction_id":"1850",

"transaction_id":"3764",

"type":"cancel",

"status":"approved",



"billing_first_name":"carl",

"billing_last_name":"sammartino",

"amount":"0.00",

"created":"2011-10-25 09:24:47",

"pass_through":{"avariable":"55707420130301120757249136"}}

},

{



"type":"credit",

"status":"request",

"billing_first_name":"Johny",

"billing_last_name":"FellowDeer",

"amount":"44.86",

"created":"2011-10-25 10:04:30",


},

{



"type":"debit",

"status":"approved",

"billing_first_name":"mathew",

"billing_last_name":"moulton",

"amount":"42.26",

"created":"2011-10-25 00:08:03",


}

]

However, if there is no information found, it should response with:

[]

FAQ

﹡ The expiration_month, and expiration_year in the documentation says it is optional,

but I am getting denied, what might be the problem?

ｏ For creditcard transactions, expiration_month, and expiration_year is

mandatory.

﹡ I am getting this response back what does it mean:

ｏ Response:

﹠ [status] => declined

﹠ [customer_id] => 155434



﹠ [customer_account_id] => 155050

﹠ [transaction_id] => 872313

﹠ [message] => Rule-set is invalid - rule set[authorize-creditcard]

﹠ [results] =>

ｏ This means that there was not a rule set defined for this type of

transaction.

﹡ I set my sequence to only process for this domain: nbc.com, but it is denying every

transaction when I send domain as: http://www.nbc.com what am I doing wrong?

ｏ It has to be an exact match, so www.nbc.com, nbc.com/, will not match, only

nbc.com will match, so if you restrict a merchant account to a domain, make

sure you have all the forms you will be sending in our system.

﹡ I am getting an INV_ACTION_IS_NOT_SUPPORTED what does this mean?

ｏ Normally this has to do with the bank and what they support, most banks

provide the basics, authorize, settle, debit, credit, recurring. However,

there are some that do not allow authorize, some that do not allow

recurring, so in those rare cases, you will get this response back.

﹡ Where is the response from the bank?

ｏ The response from the bank is located in the raw_message.

ｏ The message field just returns our standardized message.

﹡ What are some of the standard responses I might see?

ｏ These are a few standard messages you might see:

﹠ bank-negative-database

﹠ bank-specific-decline

﹠ bank-system-error

﹠ communication-failure

﹠ declined-by-processor

﹠ declined-retry-later

﹠ declined-transaction

﹠ duplicate-transaction

﹠ expired-card

﹠ invalid-account-number

﹠ invalid-credentials

﹠ invalid-data

﹠ invalid-merchant-account-credential

﹠ invalid-transaction

﹠ lost-card

﹠ merchant-disabled

﹠ over-the-limit

﹠ remote-system-error

﹠ remote-timeout

﹠ do-not-honor

﹠ expired-card

http://www.nbc.com

http://www.nbc.com



﹠ insufficient-funds

﹠ invalid-account-number

﹠ pick-up-card

﹠ lost-card

﹠ fraudulant-card

﹠ stolen-card

﹠ invalid-expiration

﹠ declined-retry-later

﹠ invalid-cvv2

﹠ over-the-limit

﹠ Rule-set is invalid - rule set [*]

﹠ payment information invalid.

﹠ INV_ACTION_IS_NOT_SUPPORTED

﹠ error:unsupported protocol:1

﹠ error:initialization failed:2

﹠ error:url was not properly formatted:3

﹠ error:protocol or option was not built in:4

﹠ error:could not resolve proxy:5

﹠ error:could not resolve host:6

﹠ error:could not connect:7

﹠ error:ftp weird server reply:8

﹠ error:remote access denied:9

﹠ error:ftp weird PASS reply:11

﹠ error:ftp weird PASV reply:13

﹠ error:ftp weird 227 format:14

﹠ error:ftp cant get host:15

﹠ error:ftp could not set type:17

﹠ error:partial file:18

﹠ error:ftp could not RETR file:19

﹠ error:quote error:21

﹠ error:http returned error:22

﹠ error:write error:23

﹠ error:upload failed:25

﹠ error:read error:26

﹠ error:out of memory:27

﹠ error:operation timeout:28

﹠ error:ftp port failed:30

﹠ error:ftp could not use REST:31

﹠ error:range error:33

﹠ error:http post error:34

﹠ error:ssl connection error:35

﹠ error:bad download resume:36



﹠ error:could not read file:37

﹠ error:ldap can not bind:38

﹠ error:ldap search failed:39

﹠ error:function not found:41

﹠ error:abouted by callback:42

﹠ error:bad function argument:43

﹠ error:interface failed:45

﹠ error:too many redirects:47

﹠ error:unknown telnet option:48

﹠ error:telnet option syntax:49

﹠ error:peer failed verification:51

﹠ error:nothing was received from server:52

﹠ error:the specified crypto engine was not found:53

﹠ error:failed setting the selected SSL crypto engine as default:54

﹠ error:failed sending network data:55

﹠ error:failed receiving network data:56

﹠ error:problem with the local client certificate:58

﹠ error:Could not use specified cipher:59

﹠ error:peer certificate can not be authenticated with known CA

certificates:60

﹠ error:unrecognized transfer encoding:61

﹠ error:invalid ldap url:62

﹠ error:filesize was exceeded:63

﹠ error:requested ftp ssl level failed:64

﹠ error:rewind operation failed:65

﹠ error:initializing the ssl engine failed:66

﹠ error:remote server denied login:67

﹠ error:file not found on tftp server:68

﹠ error:permission problem on tftp server:69

﹠ error:remote disk full:70

﹠ error:illegal tftp operation:71

﹠ error:unknown tftp transfer id:72

﹠ error:remote file exists:73

﹠ error:no such user on tftp server:74

﹠ error:character conversion failed:75

﹠ error:caller must register conversion callbacks:76

﹠ error:problem with reading the ssl CA cert:77

﹠ error:remote file not found:78

﹠ error:an unspecified error occured during the ssh session:79

﹠ error:failed to shutdown ssh connection:80

﹠ error:socket is not ready for send/recv wait till it is ready and try

again:81



﹠ error:failed to load CRL file:82

﹠ error:issuer check failed:83

﹠ error:the ftp server does not under stand PRET command:84

﹠ error:mismatch of RTSP CSeq numbers:85

﹠ error:mismatch of RTSP Session Identifiers:86

﹠ error:unable to parse FTP file list:87

﹠ error:chunk callback reported error:88

﹠ Exception

ｏ If we do not have a standard message for an banks error, we normally pass

the banks response.

﹡ I don't see my transaction being sent to the bank, but I am seeing this in your system.

ｏ {"status":"declined","customer_id":0,"customer_account_id":0,"transaction_i

d":0,"message":"{"CountryVerifier":["passed

country"],"IP2CountryVerifier":["passed country"],"EmailVerifier":["passed

email verification"],"PaymentAccountVerifier":[]}","results":null}

ｏ This response can only happen if you have fraud defense turned on. This is

because there was an error in the PaymentAccountVerifier object. This is

normally either from expiration information, or it did not pass the mod10

check for the creditcard.

﹡ I am getting back an empty response, how do I fix this issue?

ｏ Empty response looks something like this: {"status":"declined",

"customer_id":0, "customer_account_id”:0, "transaction_id":0, "message":””,

"results":null}

ｏ This could mean that something wasn’t configured right with your account,

either the sequence isn't defined, or merchant accounts are set up in the

sequence, but not set to include. Or, you are sending a type of payment

that you did not say your merchants could accept (this is normally defined

when your merchant set up in our system, this is where you defined which

cards are acceptable for your merchant, if they also accept checks,

international cards, etc.

If there is anything that you will need integrating with Andaz, please don’t hesitate to email [email protected], for code examples, testing.

mailto:[email protected]