ShaiDham

PayTechnique API Integration Manual (v. 1.3.5 SOAP)

1

Online Credit Card Processing Service

Description of work with API

version 1.3.5 SOAP


2

CONTENTS

GENERAL INFORMATION ...................................................................... 3

REGISTRATION IN THE SYSTEM ….......................................................... 4

PROTOCOL OF THE INTERACTION.......................................................... 5

Types of transactions in the system.................................................. 5

Synchronous operations ................................................................. 7

Operations auth, sale - sales .................................................... 7

External verification 3DSecure............................................... 9

Operations authRebill, rebill – recurring payments .................... 10

Operations schedule, deschedule for recurring payments ........... 12

Operation capture — sale/payment completion .......................... 15

Operation cancel — sale/payment cancellation ........................... 16

Operation status — getting the actual state of the purchase.......... 17

Asynchronous operations (callbacks)................................................ 18

Rules for calculating the checksum .................................................. 19

Appendixes ....................................................................................... 20

Testing cards................................................................................ 20

Examples..................................................................................... 21


3

General information

The interaction between the client and the system PayTechnique carried out in

two modes: synchronous and asynchronous. In synchronous mode, the client and server systems exchange XML messages via protocol SOAP

(http://www.w3.org/TR/soap/). In asynchronous mode, the client receives notification from the system by POST method using HTTP protocol.

Thus the interaction involves:

URL web-service system: systemURL

URL client for receiving notifications: callbackURL

To ensure secure data communication, is used protocol SSL v3. Note, that protocol version SSL v2 is not supported by servers.

http://www.w3.org/TR/soap/


4

Registration in the system

Identification of client accounts of the system is based on the entities referred

to as the merchants (merchant).

The merchant ID and password to work with, can be obtained by sending a request to the e-mail address:

The letter should specify your domain name and IP address from which you will be selling, and URL, on which transaction results notifications will be sent (callbackURL).


5

Protocol of the interaction

Types of transactions in the system

The system include the following types of transactions:

Transaction type Description

AUTH Authorization of sale

SALE Sale

AUTH_REBILL Authorization of recurring payment

REBILL Recurring payment

SCHEDULE Set recurring payments schedule

DESCHEDULE Cancellation of recurring payments schedule

CAPTURE Completion of sale/payment after authorization

CANCEL Cancellation of the sale/payment on the initiative of the seller or the system

CHARGEBACK Cancellation of the sale/payment on the initiative of the bank-issuer

Every transaction can include one of the multiple statuses:

Transaction type

Transaction status

Description

AUTH, SALE ACCEPT The transaction is accepted for processing

AUTH, SALE VERIFY The transaction requires additional external verification (3DS)

AUTH, SALE ONHOLD Successful completion of the transaction is expected

SALE SUCCESS Transaction completed successfully

AUTH, SALE FAIL The transaction is rejected

AUTH_REBILL, REBILL

ACCEPT The transaction is accepted for processing

AUTH_REBILL, REBILL

ONHOLD Successful completion of the transaction is expected


6

REBILL SUCCESS Transaction completed successfully

AUTH_REBILL, REBILL

FAIL The transaction is rejected

SCHEDULE SUCCESS The recurring schedule is created successfully

SCHEDULE CANCEL The recurring schedule was canceled

CAPTURE SUCCESS Transaction completed successfully

CAPTURE FAIL Transaction completion failed.

CANCEL ONHOLD1 Successful completion of the transaction is expected

CANCEL REVERSAL Cancellation of the sale is successful, performed on the stage of completion of the transaction SALE/REBILL

CANCEL REFUND Cancellation of the sale is successful, performed after the completion of the transaction SALE/REBILL

CHARGEBACK SUCCESS Cancellation of the sale on the initiative of the bank-issuer

1 Note, that the status FAIL for the transaction type CANCEL does not exist, since it is assumed that the cancellation

of the sale should always be available at the initiative of the merchant. If you can not cancel the sale (for example, at the expiration of the statute of limitations), the system will send standard error message like SoapFault.


7

Synchronous operations

Operations auth and sale – sales.

The operations are performed by the corresponding functions (auth(), sale()) of the web service.

Auth and sale operations are virtually identical to the merchant system. The differences between them are the following:

- sale operation results in an immediate transfer of funds from the customer's card account on the seller's account (actual payment).

- auth operation results in blocking sum (orderAmount) on the customer's card account. To complete the payment (transfer of the blocked amount on the

seller's account) merchant must send capture command (see below).

Auth and sale transactions have the same request and response parameters.

Request parameters

Parameter Obligat. Format2 Description

merchantID + char(16) Merchant ID

channelID - char(16) Internal payment channel identifier. Required for

distribution of the order between merchant's sub-accounts if it's applicable. Please contact the Administration to check the availability of this feature for your account.

orderReference + char(16) Unique identifier of the order

orderAmount + decimal(6, 2) Order amount

orderCurrency + char(3) Currency order in compliance with ISO-4217 (USD, EUR, GBP etc.)

orderDescription + text(1024) Order description

customerName + char(32) Name/ID, located on the card or name of the

customer in case of the absence of necessary information on the card


8

customerEmail + char(256) Customer E-mail

customerPhoneNumber + char(32) Customer phone number

customerIP + ip(15) Customer IP-аddress

customerCountry + char(3) Customer's country code in accordance with ISO 3166-1 alpha-3

customerState -/+ char(3) Customer's country region code (state, province, territory, etc...) in accordance with ISO 3166-2

Note: Mandatory for US, CA and AU countries.

customerCity + char(64) Customer's city

customerAddress + char(256) Customer's address

customerZipCode + char(32) Customer's zip code

cardType + enum Type of credit card payment system.

Valid values: VISA, MASTERCARD, AMEX, DISCOVER

cardNumber + num(20) Customer's credit card number

cardExpiration + num(4) Credit card expiry date in format: MMYY, were MM — month number, YY —two last year numbers

cardVerificationCode - num(4) CVV/CVC2 credit card verification code

returnUrl2 - char(256) URL, on which customer will be returned after the external verification 3DSecure

initRecurring - enum Initialization of the recurring payments mode

Valid values are: YES, NO

Default is NO (empty or not specified value)

signature + alphanum(32) Checksum.

See "Rules for calculating checksums"

Response parameters

Parameter Obligat. Format Description


orderReference + char(16) Unique order ID

2 It is recommended to send returnUrl for all types of cards, including those that do not support an external

verification of the 3DSecure type


9

statusCode + num(3) Status of transaction processing:

200 - the transaction is processed in the standard mode

204 – has found an attempt of duplicate sale; in response will be sent details of the original transaction

transactionType + enum Transaction type: AUTH, SALE

transactionStatus + enum Transaction status: ACCEPT, VERIFY, ONHOLD, SUCCESS, FAIL

recurringToken - alphanum(32) Identifier for recurring payments by the call of the functions authRebill/rebill

transactionError - char(256) Description of the error in case of an unsuccessful sale

verificationUrl - char(1024) URL, on which customer should be redirected for the external verification of 3DSecure

verificationParams - text(65536) Url-encoded parameters for POST request to an external verification 3DSecure.

If this field is not presented in the answer,

customer must be redirected to verificationUrl by GET method.

External 3DSecure verification

In the case of getting in response parameters like verificationUrl and verificationParams merchant should redirect the customer (by creating HTML

forms or automatically) to the verificationUrl to go through 3DSecure verification.

In case, if the function indicates verificationParams, redirection should be carried out by the POST method, differently — the GET method.

After the customer passes the verification process on 3DSecure server, he will be redirected to the URL, that is indicated in returnURL sale request

parameter; at the same time, the sale function will be accepted for processing by the system. Since at the time that the customer applies on returnURL

address, the current state of the sale will be still unknown, the merchant

should wait for the asynchronous response type sale by the system.


10

Operations authRebill and rebill — recurring payments.

The operations of recurring payments run by the call of the functions authRebill() and rebill() of the web service.

In order to initialize the mode of recurring payments for a particular sale, you

need to specify optional parameter initRecurring for function auth()/sale(). Received in response parameter recurringToken is used in further calls of the

authRebill()/rebill() functions.

The difference between functions authRebill() and rebill() is the same as for functions auth() and sale() described above.

AuthRebill and rebill transactions have the same request and response parameters.

Request parameters



orderAmount3 + decimal(6,2) Order amount

orderDescription + text(1024) Payment description

orderReference + char(16) Unique identifier of the purchase, generated by the merchants system

originalOrderReference + char(16) Identifier of the first purchase in series of

recurring payments (Parameter orderReference of the corresponding operation sale)

recurringToken + alphanum(32) Identifier for recurring payments, received in response to operation sale



3 Parameter orderCurrency not specified. System will use currency corresponding to the currency of original

purchase.


11

Response parameters



orderReference + char(16) Unique identifier of the purchase, in the merchants system

statusCode + num(3) Transaction processing status:

200 — transaction is processed in the standard mode

204 — has found an attempt of duplicate sale; in response will be sent details of the original transaction

transactionType + enum Transaction type: AUTH_REBILL, REBILL

transactionStatus + enum Transaction status: ACCEPT, ONHOLD, SUCCESS, FAIL

transactionError - char(256) Description of the error or the decline reason. Present for FAIL status only.


12

Operations schedule, deschedule for recurring payments.

The schedule operations are for managing automatic recurring payments. The

payments will be performed by the PayTechnique system on behalf of the merchant.

Operation schedule sets up the recurring schedule.

Request parameters



orderAmount4 + decimal(6,2) Order amount

orderDescription - text(1024) Payment description. If not provided, the description of the original purchase will be used.

originalOrderReference5 + char(16) Identifier of the first purchase in series of

recurring payments (Parameter orderReference of the corresponding operation auth/sale)

recurringToken + alphanum(32) Identifier for recurring payments, received in

response to operation auth/sale

scheduleCount - num(8) The number of times the payments will be done.

Not provided or zero value means unlimited number of payments until the corresponding command deschedule will be sent or PayTechnique system will cancel the schedule by itself.

scheduleDelay - num(8) Delay in days before performing the first payment.

If not provided, the first payment will be done as soon as possible.

schedulePeriod + num(8) Period in days to perform the payments



4 Parameter orderCurrency not specified. System will use currency corresponding to the currency of original

purchase.

5 Parameter orderReference not specified - system will generate it itself based on originalOrderReference.


13

Response parameters



orderReference + char(16) Echo of input parameter originalOrderReference



transactionType + enum Transaction type: SCHEDULE

transactionStatus + enum Transaction status: SUCCESS

Operation deschedule cancels corresponding recurring schedule.

Request parameters



originalOrderReference + char(16) Identifier of the first purchase in series of

recurring payments (Parameter orderReference of the corresponding operation auth/sale)

recurringToken + alphanum(32) Identifier for recurring payments, received in response to operation auth/sale



Response parameters



orderReference + char(16) Echo of input parameter originalOrderReference



transactionType + enum Transaction type: SCHEDULE

transactionStatus + enum Transaction status: CANCEL


14

Scheduled payment callbacks and the rules of naming the orders

The PayTechnique system will send callback to merchant system after performing each scheduled payment.

The callback will contain parameters transactionType = REBILL with

corresponding transactionStatus and parameter orderReference generated

by the PayTechnique system based on the parameter

originalOrderReference – it will be concatenated with string ―-X‖, where X is

the payment serial number (without leading zeros).

Because of the limitation of 16 symbols to the length of parameter

orderReference it is the responsibility of the merchant to ensure that the

order reference of the original transaction (for which he plans to set up the recurring schedule) is short enough to be suffixed with at least two symbols.


15

Operation capture — completion of the auth and

authRebill

Completion of the sale or recurring payment is performed by the function

capture() of the web service.

Command capture completes both sale and recurring payment and requires providing reference to the original transaction made with auth/authRebill.

Request parameters




amount - decimal(6, 2) Amount to capture in currency of the leading

authorization. Should not be greater than authorized amount. If omitted – the full authorized amount will be captured.

Availability of partial amount capture is the Acquirer-dependent feature.



Response parameters






transactionType + enum Transaction type: CAPTURE

transactionStatus + enum Transaction status: SUCCESS, FAIL

transactionError - char(256) Description of the error or the decline reason. Present for FAIL status only.


16

Operation cancel — cancellation of the sale

Cancellation of the sale is performed by the function cancel() of the web service.

Request parameters




amount - decimal(6, 2) Amount to refund in currency of the leading

purchase. Should not be greater than amount of the purchase. If omitted – the full refund will be processed.

Availability of partial amount refund is the Acquirer-dependent feature.



Response parameters






204 — has attempted to re-cancel, in reply will be sent the current transactionStatus

transactionType + enum Transaction type: CANCEL

transactionStatus + enum Transaction status: ONHOLD, REVERSAL, REFUND


17

Operation status — getting the actual state of the

purchase

Getting the actual state of the of the sale/purchase is performed by the

function status() of the web service.

Request parameters






Response parameters




orderStatus + enum Order status: VERIFY, FAIL, ONHOLD, SUCCESS, REVERSAL, REFUND, CHARGEBACK

orderError - char(256) Description of the error or the decline reason. Present for FAIL status only.


18

Asynchronous operations

In some cases, the system is required to pass to the customer data, about the

changes that have occurred with his transactions, just which the system has done without his direct involvement. Such cases include:

• notice about the sale after the customers verification in the system 3DSecure

• cancellation notice about the sale initiated by the merchant/system (cancel)

• cancellation notice about sale initiated by the cardholder/issuer bank (chargeback)

In these cases, the system initiates an asynchronous dispatch of data by the

POST method to the merchants system to the specified during the registration handler callbackURL. The merchant's callback should reply with HTTP 200 code

response. In case of any other responses the system will try to send an asynchronous message again – up to 5 times.

Format of the asynchronous messages



orderReference + char(16) Unique identifier of the purchase

transactionType + enum Transaction type: AUTH, SALE, AUTH_REBILL, REBILL, CANCEL, CHARGEBACK

transactionStatus + enum Transaction status: ONHOLD, SUCCESS, FAIL, REVERSAL, REFUND

transactionError - char(256) Description of the error in case of the transaction

fail (for AUTH, SALE, AUTH_REBILL, REBILL transactions)




19

Rules for calculating checksums

Checksum (signature) will be added by the sending party in the message in

order to verify transferred data by the receiving party.

The checksum is the MD5 hash in hexadecimal, received from the line, specially-formed from the original data of merchant’s message and password,

resulting in the registration process.

The algorithm for generating a checksum

1. To generate an array of input parameters of the message;

2. Sort the resulting array in ascending order of parameter names;

3. Get the check line, by the concatenation of the values of the array;

4. Add to the control line merchants password;

5. Get the MD5 hash of the check line;

6. If necessary, convert the resulting hash of the binary representation to a

hexadecimal line.

See ―Examples‖


20

Appendixes

Testing cards

Card number cardExpiration Result

4111111111111111 0120 Successful sale with successful following payments

(AUTH/SUCCESS; SALE/SUCCESS; AUTH_REBILL/SUCCESS; REBILL/SUCCESS)

4111111111111111 0121 Successful sale with unsuccessful following payments

(AUTH/SUCCESS; SALE/SUCCESS; AUTH_REBILL/FAIL; REBILL/FAIL)

4111111111111111 0220 Unsuccessful sale/recurring payment

(AUTH/FAIL; SALE/FAIL; AUTH_REBILL/FAIL; REBILL/FAIL)

4111111111111111 0320 Successful auth/authRebill with unsuccessful following captures

(AUTH/SUCCESS; SALE/SUCCESS;

AUTH_REBILL/SUCCESS; REBILL/SUCCESS; CAPTURE/FAIL)

4111111111111111 0520 Successful sale after 3DS verification

(SALE/VERIFY; SALE/SUCCESS)

4111111111111111 0620 Unsuccessful sale after 3DS verification

(SALE/VERIFY; SALE/FAIL)


21

Examples

Calculating the checksums

Merchant ID: MERCHANT-1

Password: Pa$$W0rD

Data of the sale request:

cardExpiration: 0120

cardNumber: 4111111111111111

cardType: VISA

cardVerificationCode: 112

customerAddress: 123, Main Street

customerCity: Anytown

customerCountry: USA

customerEmail: [email protected]

customerIP: 123.123.123.123

customerName: John Doe

customerPhoneNumber: 1234567890

customerState: XX

customerZipCode: 99999

initRecurring: YES

merchantID: MERCHANT-1

orderAmount: 19.90

orderCurrency: USD

orderDescription: Some Product

orderReference: ORDER-123456

returnUrl: http://example.com/return_url.php

Check line:

01204111111111111111VISA112123, Main

[email protected]

Doe1234567890XX99999YESMERCHANT-119.90USDSome ProductORDER-

123456http://example.com/return_url.phpPa$$W0rD

Checksum:

signature: 2c708af6666ebed6b7329ee2c9fdd363


22

Data of the cancel request:

merchantID: MERCHANT-1

orderReference: ORDER-123456

Check line:

MERCHANT-1ORDER-123456Pa$$W0rD

Checksum:

signature: c4252479d0e8f2408b148a0dc93d1c36

Request sale

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ns1="urn:PayTechnique" xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-

ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-

ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">

<SOAP-ENV:Body>

<ns1:sale>

<params xsi:type="ns1:PayTechniqueSoapSaleRequest">

<cardExpiration xsi:type="xsd:string">0120</cardExpiration>

<cardNumber xsi:type="xsd:string">4111111111111111</cardNumber>

<cardType xsi:type="xsd:string">VISA</cardType>

<cardVerificationCode xsi:type="xsd:string">112</cardVerificationCode>

<customerAddress xsi:type="xsd:string">123, Main Street

</customerAddress>

<customerCity xsi:type="xsd:string">Anytown</customerCity>

<customerCountry xsi:type="xsd:string">USA</customerCountry>

<customerEmail xsi:type="xsd:string">[email protected]

</customerEmail>

<customerIP xsi:type="xsd:string">123.123.123.123</customerIP>

<customerName xsi:type="xsd:string">John Doe</customerName>

<customerPhoneNumber xsi:type="xsd:string">1234567890

</customerPhoneNumber>

<customerState xsi:type="xsd:string">XX</customerState>

<customerZipCode xsi:type="xsd:string">99999</customerZipCode>

<initRecurring xsi:type="xsd:string">YES</initRecurring>

<merchantID xsi:type="xsd:string">MERCHANT-1</merchantID>

<orderAmount xsi:type="xsd:string">19.90</orderAmount>

<orderCurrency xsi:type="xsd:string">USD</orderCurrency>


23

<orderDescription xsi:type="xsd:string">Some Product

</orderDescription>

<orderReference xsi:type="xsd:string">ORDER-123456</orderReference>

<returnUrl xsi:type="xsd:string">http://example.com/return_url.php

</returnUrl>

<signature xsi:type="xsd:string">2c708af6666ebed6b7329ee2c9fdd363

</signature>

</params>

</ns1:sale>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Possible responses to the request sale

SUCCESS:







<SOAP-ENV:Body>

<ns1:saleResponse>

<saleReturn xsi:type="ns1:PayTechniqueSoapSaleResult">



<recurringToken xsi:type="xsd:string">9c82695bfd3ce6e5f8727950d0bd0e0c

</recurringToken>

<statusCode xsi:type="xsd:integer">200</statusCode>

<transactionStatus xsi:type="xsd:string">SUCCESS</transactionStatus>

<transactionType xsi:type="xsd:string">SALE</transactionType>

</saleReturn>

</ns1:saleResponse>

</SOAP-ENV:Body>


FAIL:








24

<SOAP-ENV:Body>

<ns1:saleResponse>

<saleReturn xsi:type="ns1:PayTechniqueSoapSaleResult">




<transactionError xsi:type="xsd:string">Insufficient Funds

</transactionError>

<transactionStatus xsi:type="xsd:string">FAIL</transactionStatus>

<transactionType xsi:type="xsd:string">SALE</transactionType>

</saleReturn>

</ns1:saleResponse>

</SOAP-ENV:Body>


Rebill request







<SOAP-ENV:Body>

<ns1:rebill>

<params xsi:type="ns1:PayTechniqueSoapRebillRequest">


<orderAmount xsi:type="xsd:string">9.90</orderAmount>

<orderDescription xsi:type="xsd:string">Subscription for ORDER-123456

</orderDescription>

<orderReference xsi:type="xsd:string">932413949</orderReference>

<originalOrderReference xsi:type="xsd:string">ORDER-123456

</originalOrderReference>

<recurringToken xsi:type="xsd:string">9c82695bfd3ce6e5f8727950d0bd0e0c

</recurringToken>

<signature xsi:type="xsd:string">4b409e1321ba48ab1cd020a922b28556

</signature>

</params>

</ns1:rebill>

</SOAP-ENV:Body>



25

Possible responses to the Rebill request

SUCCESS:







<SOAP-ENV:Body>

<ns1:rebillResponse>

<rebillReturn xsi:type="ns1:PayTechniqueSoapRebillResult">




<transactionStatus xsi:type="xsd:string">SUCCESS</transactionStatus>

<transactionType xsi:type="xsd:string">REBILL</transactionType>

</rebillReturn>

</ns1:rebillResponse>

</SOAP-ENV:Body>


FAIL:







<SOAP-ENV:Body>

<ns1:rebillResponse>

<rebillReturn xsi:type="ns1:PayTechniqueSoapRebillResult">




<transactionError xsi:type="xsd:string">Transaction declined

</transactionError>

<transactionStatus xsi:type="xsd:string">FAIL</transactionStatus>

<transactionType xsi:type="xsd:string">REBILL</transactionType>

</rebillReturn>

</ns1:rebillResponse>

</SOAP-ENV:Body>



26

Cancel request







<SOAP-ENV:Body>

<ns1:cancel>

<params xsi:type="ns1:PayTechniqueSoapCancelRequest">



<signature xsi:type="xsd:string">c4252479d0e8f2408b148a0dc93d1c36

</signature>

</params>

</ns1:cancel>

</SOAP-ENV:Body>


Possible responses to the request cancel

The request was accepted for processing, the final state is not defined:







<SOAP-ENV:Body>

<ns1:cancelResponse>

<cancelReturn xsi:type="ns1:PayTechniqueSoapCancelResult">




<transactionStatus xsi:type="xsd:string">ONHOLD</transactionStatus>

<transactionType xsi:type="xsd:string">CANCEL</transactionType>

</cancelReturn>

</ns1:cancelResponse>

</SOAP-ENV:Body>



27

Request completed with status REFUND:







<SOAP-ENV:Body>

<ns1:cancelResponse>

<cancelReturn xsi:type="ns1:PayTechniqueSoapCancelResult">




<transactionStatus xsi:type="xsd:string">REFUND</transactionStatus>

<transactionType xsi:type="xsd:string">CANCEL</transactionType>

</cancelReturn>

</ns1:cancelResponse>

</SOAP-ENV:Body>


Example of the response with an error SoapFault:


<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

<SOAP-ENV:Body>

<SOAP-ENV:Fault>

<faultcode>SOAP-ENV:Client</faultcode>

<faultstring>400 Bad Request</faultstring>

<detail>003 Invalid card number</detail>

</SOAP-ENV:Fault>

</SOAP-ENV:Body>


Documents

ShaiDham