Paywiser - Acquiring API

Register And Reserve (Redirect Solution)

When a user registers, a card validation transaction is initiated. If the card is successfully validated, the system proceeds with tokenization and reserves the requested amount on the card. The merchant can either host their own card form or use Paywiser’s hosted page for card details. During the authorization verification process, the user may be redirected to a 3D Secure (3DS) confirmation page if additional verification is needed.

To initiate a transaction using TxHandler, submit a form via HTTP POST to the specified

HTTP Request

POST https://office.paywiser.com/secure/txHandler.php

Request Parameters

Table of request Parameters response information
Parameter	DataType	Description
sid	Yes	Site id (unique identifier for the web site)
tid	No	Tracking id (must be unique for each transaction)
postback_url	Yes	Merchant can get update transaction status by asynchronous process. Once capture process complete or after 3D secure challenge process, will send postback to the provided URL. Capture process will return tx_action=SETTLEMENT while the 3ds challenge return tx_action = PREAUTH.
redirect_url	No	To redirect user back to merchant page
hash	Yes	md5 hash of strings concatenation from sid + timestamp + amounttotal + currency + rcode e.g. (in PHP): md5('22'.'1234568995265421'.'17.00'.'CNY'.'222b6c') REMARK : amounttotal = (item_amount_unit * item_quantity ) + amount_shipping + amount_tax – amount_coupon
timestamp	Yes	UNIX timestamp in seconds.
card_type	Yes	allcard
card_no	No	Credit card number. Empty card_no will redirect to Paywiser hosted card form.
card_exp_year	Condition	4-digit year expiration of the credit card. (e.g. 2020), required if card_no provided
card_exp_month	Condition	2-digit month expiration of the credit card. (eg. 05 – May), required if card_no provided
card_ccv	Condition	CVV/CVC2 credit card verification code, required if card_no provided
firstname	Yes	First name of the customer
lastname	Yes	Last name of the customer
phone	Yes	10 to 14 numeric digits
mobile	No	Mobile number
address	Yes	Customer address
suburb_city	Yes	Customer suburb or city
state	Yes	Customer state, 2 digit code for US/Canada
postcode	Yes	Customer postcode/zipcode
country	Yes	Customer country, ISO 3166 2 digit code
uip	Yes	Customer’s IP address.
currency	Yes	Transaction currency [currency in which the gateway is setup], ISO 3 letter code, e.g., USD
amount_shipping	Yes	Transaction shipping amount. 0.00 if nothing
amount_coupon	Yes	Coupon amount. 0.00 if nothing
amount_tax	Yes	Transaction shipping amount. 0.00 if nothing
item_quantity[]	Yes	Quantity of product
item_name[]	Yes	Name of product
item_no[]	Yes	ID of product
item_desc[]	Yes	Descriptions of product
item_amount_unit[]	Yes	Amount to do reserve, two decimal places
ref1	No	Provide this value will auto do payment and ignore checking ref2
ref2	No	Payment flow referrent, allow 3 value signs: only register without reserved, and then will provide token in ref1 parameter. signandpay: this value register and do reserved amount and then will provide token in ref1 parameter. pay: when payment with token which retrieved from register process that return in ref1 parameter. leave blank and empty ref1 will be used signandpay by default.
ref3	No	Merchant reference field
ref4	No	Merchant reference field
tx_action	Yes	PREAUTH

Request Parameters

Table of request Parameters response information
Parameter	DataType	Description
sid	String	Has the sid where transaction was processed
status	String	OK – Success authorization and reserved amount EXC – failed
parent_txid	String	Parent transaction id
txid	String	The transaction ID
tx_action	String	Default Value - PREAUTH
amount	String	The reserved amount.
currency	String	The currency of reserved amount
comment	String	Description of the transaction status
descriptor	String	Gateway descriptor name
ref1	String	Card Token, merchant need to use this card token for next payment or future usage.
ref2	String	Merchant reference field
ref3	String	Merchant reference field
ref4	String	Merchant reference field

									
<form action="https://office.paywiser.com/secure/txHandler.php" method="post">
sid: <input type="text" name="sid" value="19"><BR>
tid: <input type="text" name="tid" value="5678"><BR>
postback_url: <input type="text" name="postback_url" value="http://mysite.com/postback.php"><BR>
redirect_url: <input type="text" name="redirect_url" value="http://mysite.com/redirect.php"><BR>
timestamp: <input type="text" name="timestamp" value="1234568995265421"><BR>
hash: <input type="text" name="hash" value="08ff1b1b14a09acfd67560baae229c4e"><BR>
firstname: <input type="text" name="firstname" value="Jack"><BR>
lastname: <input type="text" name="lastname" value="Tester"><BR>
phone: <input type="text" name="phone" value="1234567"><BR>
email: <input type="text" name="email" value="test@example.com"><BR>
address: <input type="text" name="address" value="12 Test Lane"><BR>
suburb_city: <input type="text" name="suburb_city" value="TestCity"><BR>
state: <input type="text" name="state" value="CA-ON"><BR>
postcode: <input type="text" name="postcode" value="41010"><BR>
country: <input type="text" name="country" value="CA"><BR>
ship_firstname: <input type="text" name="ship_firstname" value="Julie"><BR>
ship_lastname: <input type="text" name="ship_lastname" value="Tester"><BR>
ship_address: <input type="text" name="ship_address" value="13 Test Lane"><BR>
ship_suburb_city: <input type="text" name="ship_suburb_city" value="TestCity"><BR>
ship_state: <input type="text" name="ship_state" value="CA-ON"><BR>
ship_postcode: <input type="text" name="ship_postcode" value="41010"><BR>
ship_country: <input type="text" name="ship_country" value="CA"><BR>
currency_code: <input type="text" name="currency" value="USD"><BR>
amount_shipping: <input type="text" name="amount_shipping" value="0.30"><BR>
amount_tax: <input type="text" name="amount_tax" value="0.00"><BR>
amount_coupon: <input type="text" name="amount_coupon" value="0.00"><BR>
card_type: <input type="text" name="card_type" value="visa"><BR>
card_no: <input type="text" name="card_no" value="4018810000150015"><BR>
card_name: <input type="text" name="card_name" value="J Citizen"><BR>
card_ccv: <input type="text" name="card_ccv" value="123"><BR>
card_exp_month: <input type="text" name="card_exp_month" value="2014"><BR>
card_exp_year: <input type="text" name="card_exp_year" value="09"><BR>
ref2: <input type="text" name="ref2" value=""><BR>
ref3: <input type="text" name="ref3" value=""><BR>
ref4: <input type="text" name="ref4" value=""><BR>
<table>
<tr>
<td>
item_quantity: <input type="text" name="item_quantity[]" value="1">
item_name: <input type="text" name="item_name[]" value="fuel">
item_no: <input type="text" name="item_no[]" value="a234">
item_desc: <input type="text" name="item_desc[]" value="Pro 1">
item_amount_unit: <input type="text" name="item_amount_unit[]" value="15.00">
</td>
</tr>
</table>
<input type="submit" value="Submit">
</form>

Capture (Server to Server Solution)

Once customer finish charging, merchant need to send actual amount to capture from reserved amount and release the remaining amount.

To do this merchant need to request our Rest API POST /api/v1/index.php/{sid}/flagcapture HTTP/1.1 Host: https://office.paywiser.com Content-Type: application/x-www-form-urlencoded

HTTP Request

POST https://office.paywiser.com/api/v1/index.php/{sid}/flagcapture

Request Parameters

The response will return error string or a Boolean true or false. The transaction status will return by asynchronous processing in postback_url provided from parent transaction.
Name	type	Required	Description
sid	path	Yes	Site id (unique identifier for the web site)
parent_txid	body	Yes	The transaction reference of previous register or reserved transaction.
tid	body	No	Tracking id (must be unique for each transaction)
amount	body	Yes	Actual amount that customer need to pay
hash	body	Yes	md5 hash of strings concatenation from sid+amount+rcode [e.g. in PHP : md5('22'.'7.00'.'222b6c')]

							
<?php
$sid="xx";
$rcode ="xxxxxxxx";
$request['parent_txid'] = '12345678';
$request['amount'] = '7.45';
$request[hash] = md5($sid. $request['amount']. $rcode);
if(!$curl = curl_init("http://office.paywiser.com/api/v1/index.php/$sid/flagcapture"))
echo "cURL initialization failure: ".curl_error($curl);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($request));
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 0);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
if ( !$response = curl_exec($curl))
echo "cURL execution failure: ".curl_error($curl);
curl_close ($curl);
echo "Response: ";
echo "<pre>";
print_r($response);
echo "</pre>";
?>

Asynchronous Notification

The response will be sent to the postback_url given in register or reserve request. The transaction is completed when you receive the response tx_action=SETTLEMENT.

Request Parameters

Table of request Parameters response information
Parameter	DataType	Description
sid	String	Has the sid where transaction was processed
status	String	Has the value "OK" for a successful transaction, or "EXC" for a failed transaction.
parent_txid	String	Parent transaction id
txid	String	The transaction ID
tx_action	String	SETTLEMENT or PREAUTH
amount	String	The amount processed.
currency	String	The currency in which the transaction was processed
comment	String	Response from the gateway
descriptor	String	Gateway descriptor name
tid	String	From the original transaction
error	String	If an error has occurred, then the status value will equal "EXC" and these parameters will be sent as well. Detailed error will be present only if we receive it from the processing gateway.
error_type	String	error_type
error_sys	String	The system that caused the error (client or server)
error_msg	String	The error message
error_info	String	Error information that contains the bank message and bank code
error_code	String	error_code
vrfy	String	This is a SHA-256 hash so the data can be verified to ensure your post-back data was not modified. To generate a hash with SHA-256, use the string: sid;rcode;txid;status;amount;currency;txaction

Reserve (Redirect Solution)

Merhant can request transaction by using token that retrived from register processing by using [ref1] reponse parameter. The process need to verify authorisation, it may redirect to 3Ds confirmation page if need. To process a transaction using TxHandler, post a form via HTTP POST to https://office.paywiser.com/secure/txHandler.php.

HTTP Request

POST https://office.paywiser.com/secure/txHandler.php

Request Parameters

Table of request Parameters response information
Parameter	DataType	Description
sid	Yes	Site id (unique identifier for the website)
tid	No	Tracking id (must be unique for each transaction)
postback_url	Yes	Merchant can get update transaction status by asynchronous process. Once capture process is complete or after the 3D secure challenge process, a postback will be sent to the provided URL. Capture process will return tx_action=SETTLEMENT while the 3D challenge will return tx_action = PREAUTH.
redirect_url	No	To redirect user back to the merchant page
hash	Yes	MD5 hash of strings concatenation from sid + timestamp + amounttotal + currency + rcode. e.g. (in PHP): `md5('22'.'1234568995265421'.'17.00'.'CNY'.'222b6c')`
timestamp	Yes	Format: hhmmss
card_type	Yes	allcard
firstname	Yes	First name of the customer
lastname	Yes	Last name of the customer
phone	Yes	10 to 14 numeric digits
mobile	No	Mobile number
address	Yes	Customer address
suburb_city	Yes	Customer suburb or city
state	Yes	Customer state, 2-digit code for US/Canada
postcode	Yes	Customer postcode/zipcode
country	Yes	Customer country, ISO 3166 2-digit code
uip	Yes	Customer’s IP address
currency	Yes	Transaction currency (currency in which the gateway is set up), ISO 3-letter code (e.g., USD)
amount_shipping	Yes	Transaction shipping amount. 0.00 if nothing
amount_coupon	Yes	Coupon amount. 0.00 if nothing
amount_tax	Yes	Transaction tax amount. 0.00 if nothing
item_quantity[]	Yes	Quantity of product
item_name[]	Yes	Name of product
item_no[]	Yes	ID of product
item_desc[]	Yes	Descriptions of product
item_amount_unit[]	Yes	Amount to reserve, two decimal places
ref1	Yes	Token given by the register process
ref2	No	Merchant reference field
ref3	No	Merchant reference field
ref4	No	Merchant reference field
tx_action	Yes	Value: “PREAUTH”

Response Parameters

Instant response will be sent once the success reserved by system.
Parameter	DataType	Description
sid	String	Has the sid where the transaction was processed
status	String	OK – Success authorization and reserved amount EXC – Failed
parent_txid	String	Parent transaction id
txid	String	The transaction ID
tx_action	String	Default Value - PREAUTH
amount	String	The reserved amount
currency	String	The currency of the reserved amount
comment	String	Description of the transaction status
descriptor	String	Gateway descriptor name
ref1	String	If there is a token returned from the gateway
ref2	String	Merchant reference field
ref3	String	Merchant reference field
ref4	String	Merchant reference field

									
<form action="https://office.paywiser.com/secure/txHandler.php" method="post">
sid: <input type="text" name="sid" value="19"><BR>
tid: <input type="text" name="tid" value="5678"><BR>
postback_url: <input type="text" name="postback_url" value="http://mysite.com/postback.php"><BR>
redirect_url: <input type="text" name="redirect_url" value="http://mysite.com/redirect.php"><BR>
timestamp: <input type="text" name="timestamp" value="1234568995265421"><BR>
hash: <input type="text" name="hash" value="08ff1b1b14a09acfd67560baae229c4e"><BR>
firstname: <input type="text" name="firstname" value="Jack"><BR>
lastname: <input type="text" name="lastname" value="Tester"><BR>
phone: <input type="text" name="phone" value="1234567"><BR>
email: <input type="text" name="email" value="test@example.com"><BR>
address: <input type="text" name="address" value="12 Test Lane"><BR>
suburb_city: <input type="text" name="suburb_city" value="TestCity"><BR>
state: <input type="text" name="state" value="CA-ON"><BR>
postcode: <input type="text" name="postcode" value="41010"><BR>
country: <input type="text" name="country" value="CA"><BR>
ship_firstname: <input type="text" name="ship_firstname" value="Julie"><BR>
ship_lastname: <input type="text" name="ship_lastname" value="Tester"><BR>
ship_address: <input type="text" name="ship_address" value="13 Test Lane"><BR>
ship_suburb_city: <input type="text" name="ship_suburb_city" value="TestCity"><BR>
ship_state: <input type="text" name="ship_state" value="CA-ON"><BR>
ship_postcode: <input type="text" name="ship_postcode" value="41010"><BR>
ship_country: <input type="text" name="ship_country" value="CA"><BR>
currency_code: <input type="text" name="currency" value="USD"><BR>
amount_shipping: <input type="text" name="amount_shipping" value="0.30"><BR>
amount_tax: <input type="text" name="amount_tax" value="0.00"><BR>
amount_coupon: <input type="text" name="amount_coupon" value="0.00"><BR>
ref1: <input type="text" name="ref1" value="cardtoken"><BR>
ref2: <input type="text" name="ref2" value=""><BR>
ref3: <input type="text" name="ref3" value=""><BR>
ref4: <input type="text" name="ref4" value=""><BR>
<table>
<tr>
<td>
item_quantity: <input type="text" name="item_quantity[]" value="1">
item_name: <input type="text" name="item_name[]" value="fuel">
item_no: <input type="text" name="item_no[]" value="a234">
item_desc: <input type="text" name="item_desc[]" value="pro 2">
item_amount_unit: <input type="text" name="item_amount_unit[]" value="15.00">
</td>
</tr>
</table>
<input type="submit" value="Submit">
</form>

Refund (Server to Server Solution)

Merchant can request refund via Rest API POST /api/v1/index.php/{ptxid}/refund HTTP/1.1 Host: https://office.paywiser.com Content-Type: application/x-www-form-urlencoded

HTTP Request

POST https://office.paywiser.com/api/v1/index.php/{ptxid}/refund

Response Parameters

Instant response will be sent once the success reserved by system.
Name	Type	Required	Description
ptxid	path	Yes	The transaction reference of previous register or reserved transaction.
parent_txid	body	Yes	The transaction reference of previous register or reserved transaction.
tid	body	No	Tracking id (must be unique for each transaction)
amount	body	Yes	Actual amount that customer to pay
postback_url	-	-	The URL of the page used to receive the TxHandler postback. The response can be read from $_POST array.
hash	body	Yes	md5 hash of sid+timestamp+amount+currency+rcode e.g. in PHP : `md5('22'.'1234568995265421'.'17.00'.'CNY'.'222b6c')`

Response Parameter

Instant response will be sent once the refund request received by system.
Name	Data Type	Description
status	String	EXC – Refund Request failed PEND – Refund Request Pending Approval
txid	String	The transaction ID
error	-	If an error has occurred, then the status value will equal "EXC" and these parameters will be sent as well. Detailed error will be present only if we receive it from the processing gateway.
error_type	String	error_type
error_sys	String	The system that caused the error (client or server)
error_msg	String	Refund Submitted
error_info	String	Error information that contains the bank message and bank code
error_code	String	error_code
comment	String	Status OK - Refund Submitted Status EXC – Reason of Failure

									
<?php  
$request['sid'] = '27';  
$request[ptxid] = '1654567402734657';  
$request['postback_url'] = 'http://localhost/postback.php';  
$request['hash'] = 3acfebafaeb8b5e2d7e414ab8c0be152;  
$request['timestamp'] = '1234567898765';  
$request['currency'] = EUR;  
$request['amount'] = '10.00';  
$request['tx_action'] = "REFUND";  
$url = ' https://office.paywiser.com/api/v1/index.php/1654567402734657/refund';  
$ch = curl_init($url);  
curl_setopt($ch, CURLOPT_POST, 1);  
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);  
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);  
curl_setopt($ch, CURLOPT_HEADER, 0);  
curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1);  
curl_setopt($ch, CURLOPT_FORBID_REUSE, 1);  
echo "<pre>";  
$post = curl_exec($ch);  
if (!$post) {  
$error = curl_error($ch);  
var_dump($error);  
echo "<br>";  
}  
var_dump($request);  
echo "<br>";  
var_dump($post);  
echo "<br>";  
?>

Appendix A : Testing Credit Cards

Frictionless

User will immediately receive a fully authenticated 3D Secure result and authorisation decision, in response to the request.

Card Scheme	Card Number
Visa	4176660000000027
Mastercard	5299990270000368
Amex	375987000169677
Discover	36849800000679

Device Fingerprint (DFP)

The issuer requests more information about the device that initiated the transaction (note: this is not a biometric fingerprint! - depending on the issuer this can be the cardholder’s browser or other information used for risk analysis). The information is transferred electronically without the cardholder experiencing any change in the flow and simulates a scenario where the card issuer is satisfied with the authenticity of the cardholder (frictionless experience).

Card Scheme	Card Number
Visa	4176660000000068
Mastercard	5299990270000392
Amex	375987000169776
Discover	36816499999982

Challenge

For the purpose of this test case, user will bring to comfirmation page for One-Time Password (OTP). Different OTPs are provided to simulate a successful or unsuccessful cardholder challenge.

Card Scheme	Card Number	Success OTP	Fail OTP
Visa	4176660000000092	0101	3333
Mastercard	5299910010000015	4445	9999
Amex	375987000000005	5678	3333
Discover	6011947300799885	5678	3333
Visa	4176660000000118	0101	3333
Mastercard	5204730000001011	4445	9999
Amex	374245001711000	5678	3333
Discover	6011947499999957	5678	3333

Acquiring API

Card Tokenize

Register And Reserve (Redirect Solution)

HTTP Request

Request Parameters

Request Parameters

Capture (Server to Server Solution)

HTTP Request

Request Parameters

Asynchronous Notification

Request Parameters

Reserve (Redirect Solution)

HTTP Request

Request Parameters

Response Parameters

Refund (Server to Server Solution)

HTTP Request

Response Parameters

Response Parameter

Appendix A : Testing Credit Cards

Frictionless

Device Fingerprint (DFP)

Challenge