1.1.8. Card To Card Transfer

Direct Integration

Money transfer General Flow

Paywize supports few schemas of money transfer: Card2Card, Cash2Card or Deposit2Card. All of them could be initiated by customer itself or by Merchant using reccurent API. Simple Money transfer described in Sale Transactions for direct Card2Card transfer and in Payment Form Integration for integration by external form. Recurrent Money transfer transactions are made in three steps:

  • Initial payment – make initial payment to verify and authorize credit card
  • Card Registration – get cards reference ID card-ref-id and remember it
  • Money transfer – run money transfer using card-ref-id from previous step. In case of transfer from registered card merchant initiates transfer using given source-card-ref-id and destination-card-no or destination-card-ref-id. In case of transfer from account merchant initiates transfer using given destination-card-no or destination-card-ref-id
  • After the payment initiation Paywize returns new Order ID for the this transfer
  • Merchant starts polling Paywize
  • Paywize returns current status of the order. processing status means the order is still being processed
  • Paywize processes the payment using appropriate bank’s gateway
  • Merchant keeps polling Paywize by using Status API
  • Paywize returns current status of the order - approved, declined or filtered

Money transfer URL

For integration purposes use staging environment sandbox.paywize.com instead of production gate.paywize.com. Sale transactions are initiated through HTTPS POST request by using URL in the following format:

Money transfer transaction by ENDPOINTID

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.

https://gate.paywize.com/paynet/api/v2/transfer/ENDPOINTID – to make single currency transfer between two card numbers, for detailes see Sale Transactions
https://gate.paywize.com/paynet/api/v2/transfer-form/ENDPOINTID – to make single currency transfer between two card numbers, for detailes see Payment Form Integration
https://gate.paywize.com/paynet/api/v2/transfer-by-ref/ENDPOINTID – to make single currency transfer between two card-ref-id’s or from registered card-ref-id to card number

Money transfer transaction by ENDPOINTGROUPID

The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.

https://gate.paywize.com/paynet/api/v2/transfer/group/ENDPOINTGROUPID – to make multi currency transfer between two card numbers, for detailes see Sale Transactions
https://gate.paywize.com/paynet/api/v2/transfer-form/group/ENDPOINTGROUPID – to make multi currency transfer between two card numbers, for detailes see Payment Form Integration
https://gate.paywize.com/paynet/api/v2/transfer-by-ref/group/ENDPOINTGROUPID – to make multi currency transfer between two card-ref-id’s or from registered card-ref-id to card number

Process Money Transfer

Money transfer request parameters

Money transfer request parameter Length/Type Comment Necessity*
client_orderid 128/String Merchant order identifier. Mandatory
login 20/String Merchant’s login Mandatory
source-card-ref-id 20/Numeric Card reference id to source card, obtained at Card Registration step, not used for Transfer from account transactions Optional
destination-card-no 16-19/String Card number of destination card. Mandatory if destination-card-ref-id ommited. Ignored if destination-card-ref-id is not empty Conditional
destination-card-ref-id 20/Numeric Card reference id to destination card, obtained at Card Registration step. Mandatory if destination-card-no ommited. Conditional
order_desc 64k/String Order description Mandatory
amount 10/Numeric Amount to be transfered. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents Mandatory
currency 3/String Currency the transaction is charged in (three-letter currency code). Example of  valid parameter values are: USD for US Dollar EUR for European Euro Mandatory
cvv2 3-4/Numeric Customer’s CVV2 code for source card. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. May be empty or absent if bank gateway supports processing without CVV2, not used for Transfer from account transactions if destination-card-no is used Optional
ipaddress 20/String Customer’s IP address, included for fraud screening purposes. Mandatory
control 40/String Checksum generated by SHA-1. This is SHA-1 checksum of the concatenation login + client_orderid + source-card-ref-id (if present) + destination-card-ref-id (if present) + amount_in_cents + currency + merchant_control. Mandatory
first_name 128/String Sender first name, not used for Transfer from account transactions if destination-card-no is used Optional
middle_name 128/String Sender middle name, not used for Transfer from account transactions if destination-card-no is used Optional
last_name 128/String Sender last name, not used for Transfer from account transactions if destination-card-no is used Optional
ssn 32/Numeric Last four digits of the Sender’s social security number, not used for Transfer from account transactions if destination-card-no is used. Mandatory for some acquirers for cross-country transfers. Conditional
birthday 8/Numeric Sender date of birth, in the format MMDDYY, not used for Transfer from account transactions if destination-card-no is used Optional
address1 50/String Sender address line 1, not used for Transfer from account transactions if destination-card-no is used Optional
city 50/String Sender city, not used for Transfer from account transactions if destination-card-no is used Optional
state 2-3/String Sender’s state . Please see Reference for a list of valid state codes, not used for Transfer from account transactions if destination-card-no is used. Mandatory for USA, Canada and Australia. Conditional
zip_code 10/String Sender ZIP code, not used for Transfer from account transactions if destination-card-no is used Optional
country 2/String Sender country(two-letter country code). Please see Reference for a list of valid country codes, not used for Transfer from account transactions if destination-card-no is used Optional
phone 15/String Sender full international phone number, including country code, not used for Transfer from account transactions if destination-card-no is used Optional
cell_phone 15/String Sender full international cell phone number, including country code, not used for Transfer from account transactions if destination-card-no is used Optional
email 50/String Sender email address, not used for Transfer from account transactions if destination-card-no is used Optional
purpose 128/String Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +7123456789; gamer0001@ereality.com etc. This value will be used by fraud monitoring system. Optional
receiver_first_name 128/String Receiver first name Optional
receiver_middle_name 128/String Receiver middle name Optional
receiver_last_name 128/String Receiver last name Optional
receiver_resident Boolean (true/false) Is receiver a resident? Optional
redirect_url 1024/String URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Paywize gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Optional
server_callback_url 1024/String URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks Optional
* acquirer can redefine the necessity of some fields so they become mandatory instead of optional
** leading and trailing whitespace in input parameters will be omitted

Transfer Response

Transfer response parameter Description
type The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Order id assigned to the order by Paywize
merchant-order-id Merchant order id
serial-number Unique number assigned by Paywize server to particular request from the Merchant.
error-message If status is error this parameter contains the reason for decline or error details
error-code The error code is case of error status
end-point-id Endpoint id used for the transaction

Transfer Response Example

type=async-response
&serial-number=00000000-0000-0000-0000-00000456f9e1
&merchant-order-id=902B4FF5
&paynet-order-id=3622255
&end-point-id=212

3D redirect

If your gate supports 3D Secure you need to send status request and process html return parameter to send customer to 3D Secure Authorisation. The simplified schema looks like:

Customer -> Merchant: Initiate transaction
activate Merchant

Merchant -> "Paywize": transfer-by-ref
activate "Paywize"
"Paywize" --> Merchant: async-response
Merchant -> "Paywize": status
"Paywize" --> Merchant: html
deactivate "Paywize"
Merchant --> Customer: urldecode(html)
deactivate Merchant

html field is always present for 3D gates in status response, whether clients card supports 3D Secure or not.

If source-card-ref-id is specified upon completion of 3D authorization process by the Customer he/she is automatically redirected to redirect_url. The redirection is performed as an HTTPS POST request with the parameters specified in the following table.

Redirect parameter Description
status See Status List for details.
orderid Order id assigned to the order by Paywize
merchant_order Merchant order id
client_orderid Merchant order id
error_message If status is declined or error this parameter contains the reason for decline or error details
control Checksum used to ensure that it is Paywize (and not a fraudster) that initiates the request. This is SHA-1 checksum of the concatenation status + orderid + client_orderid + merchant-control.
descriptor Gate descriptor

If Merchant has passed server_callback_url in original Sale request Paywize will call this URL. Merchant may use it for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. The parameters sent to this URL are specified in sale, return Callback Parameters

Server callback result

Upon completion by the System of 3D request processing it returns the result on the specified server_callback_url with the following parameters described in sale, return Callback Parameters

The checksum is used to ensure that the callback is initiated for a particular Merchant, and not for anybody else claiming to be such Merchant. This SHA-1 checksum, the control parameter, is created by concatenation of the parameters values in the following order:

  • status
  • orderid
  • client_orderid
  • merchant_control

A complete string example may look as follows:

approvedS279G323P4T1209294c258d6536ababe653E8E45B5-7682-42D8-6ECC-FB794F6B11B1

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter. For the above-mentioned example the control will take the following value:

e04bd50531f45f9fc76917ac78a82f3efaf0049c

All parameters are sent via POST method.

Server callback result example

status=declined
&error-message=Decline, refer to card issuer
&error-code=107
&paynet-order-id=S279G323P4T1209294
&merchant-order-id=c258d6536ababe65

Transfer Request Debug

endpointid or groupid input your ENDPOINTID
login
client_orderid make it or use your internal invoice ID
source-card-ref-id
credit_card_number enter the beginning of the sequence, and then "i"
card_printed_name
expire_month
expire_year
destination-card-no
destination-card-ref-id
order_desc
amount
currency
cvv2
ipaddress
first_name
middle_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
email
receiver_ffirst_name
receiver_fmiddle_name
receiver_flast_name
receiver_resident
purpose
merchant_control input your Control Key
redirect_url
server_callback_url
merchant_data

String to sign
Signature
               
             
                 
             
                 
             
                 
             

Order status

Merchant must use Order status API call to get the customer’s order transaction status. After any type of transaction is sent to Paywize server and order id is returned, Merchant should poll for transaction status. When transaction is processed on Paywize server side it returns it’s status back to Merchant and at this moment the Merchant is ready to show the customer transaction result, whether it’s approved or declined.

Status API URL

Status API calls are initiated through HTTPS POST request by using URL in the following format:
https://gate.paywize.com/paynet/api/v2/status/ENDPOINTID
for integration purposes use staging environment sandbox.paywize.com instead of production gate.paywize.com

The End point ID is an entry point for incoming Merchant’s transactions and is actually the only Paywize object which is exposed via API.

Order status call parameters

Status parameter Description
login Merchant login name
client_orderid Merchant order identifier of the transaction for which the status is requested
orderid Order id assigned to the order by Paywize
by-request-sn Serial number assigned to the specific request by Paywize. If this field exist in status request, status response return for this specific request.
control Checksum used to ensure that it is Paywize (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. See Order status API call authorization through control parameter for more details about generating control checksum.

Order Status Response

Status Response Parameter Description
type The type of response. May be status-response
status See Status List for details.
amount Amount of the initial transaction.
paynet-order-id Order id assigned to the order by Paywize
merchant-order-id Merchant order id
phone Customer phone.
html HTML code of 3D authorization form, encoded in application/x-www-form-urlencoded MIME format. Merchant must decode this parameter before showing the form to the Customer. The Paywize System returns the following response parameters when it gets 3D authorization form from the Issuer Bank. It contains auth form HTML code which must be passed through without any changes to the client’s browser. This parameter exists and has value only when the redirection HTML is already available. For non-3D this never happens. For 3D HTML has value after some short time after the processing has been started.
serial-number Unique number assigned by Paywize server to particular request from the Merchant.
gate-partial-reversal Processing gate support partial reversal (enabled or disabled).
gate-partial-capture Processing gate support partial capture (enabled or disabled).
transaction-type Transaction type (sale, reversal, capture, preauth).
processor-rrn Bank Receiver Registration Number.
processor-tx-id Acquirer transaction identifier.
receipt-id Electronical link to receipt https://gate.paywize.com/paynet/view-receipt/ENDPOINTID/receipt-id/
name Cardholder name.
cardholder-name Cardholder name.
card-exp-month Card expiration month.
card-exp-year Card expiration year.
card-hash-id Unique card identifier to use for loyalty programs or fraud checks.
destination-hash-id Unique card identifier to use for loyalty programs or fraud checks.
email Customer e-mail.
bank-name Bank name by customer card BIN.
last-four-digits Last four digits of customer credit card number.
bin Bank BIN of customer credit card number.
card-type Type of customer credit card (VISA, MASTERCARD, etc).
dest-bank-name Destination bank name by customer card BIN.
dest-last-four-digits Destination last four digits of customer credit card number.
dest-bin Destination bank BIN of customer credit card number.
dest-card-type Type of destination customer credit card (VISA, MASTERCARD, etc).
terminal-id Acquirer terminal identifier to show in receipt.
paynet-processing-date Acquirer transaction processing date.
approval-code Bank approval code.
order-stage The current stage of the transaction processing. See Order Stage for details
loyalty-balance The current bonuses balance of the loyalty program for current operation. if available
loyalty-message The message from the loyalty program. if available
loyalty-bonus The bonus value of the loyalty program for current operation. if available
loyalty-program The name of the loyalty program for current operation. if available
descriptor Bank identifier of the payment recipient.
error-message If status in declined, error, filtered this parameter contains the reason for decline
error-code The error code is case status in declined, error, filtered.
by-request-sn Serial number from status request, if exists in request. Warning parameter amount always shows initial transaction amount, even if status is requested by-request-sn.
verified-3d-status See:ref:3d_secure_status_list for details
verified-rsc-status See Random Sum Check Status List for details

Order Status Response Example

type=status-response
&serial-number=00000000-0000-0000-0000-00000456f9e6
&merchant-order-id=902B4FF5
&processor-tx-id=PNTEST-3622257
&paynet-order-id=3622257
&status=approved
&amount=10.42
&descriptor=3D
&transaction-type=transfer
&receipt-id=93c8ea85-9126-3d72-bca2-98e999107c82
&name=CARD+HOLDER
&cardholder-name=CARD+HOLDER
&card-exp-month=12
&card-exp-year=2099
&email=john.smith%40gmail.com
&processor-rrn=511000302615
&approval-code=965452
&order-stage=transfer_approved
&merchantdata=VIP+customer
&last-four-digits=1111
&bin=444455
&card-type=VISA
&phone=12063582043
&bank-name=UNKNOWN
&dest-bank-name=CITIBANK
&dest-bin=520306
&dest-last-four-digits=9001
&dest-card-type=MASTERCARD
&paynet-processing-date=2015-04-20+22%3A53%3A37+MSK
&card-hash-id=212609
&destination-card-hash-id=212608
&verified-3d-status=AUTHENTICATED
&verified-rsc-status=AUTHENTICATED

Status request authorization through control parameter

The checksum is used to ensure that it is Merchant (and not a fraudster) that sends the request to Paywize. This SHA-1 checksum, the parameter control, is created by concatenating of the values of the parameters in the following order:

  • login
  • client_orderid
  • orderid
  • merchant_control

For example assume the following values are corresponds the parameters above:

Parameter name Parameter Value
login cool_merchant
client_orderid 5624444333322221111110
orderid 9625
merchant_control r45a019070772d1c4c2b503bbdc0fa22

The complete string example may look as follows:

cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for authorizing the callback. For the example control above will take the following value:

c52cfb609f20a3677eb280cc4709278ea8f7024c

Order status Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid input your Invoice Number
orderid
merchant_control input your Control Key
by-request-sn

String to sign
Signature
              
            
			 
		
			
		
>
			
		

Payment Form Integration

Payment Form integration is relevant for merchants who are not able to accept customer card details (merchant’s website must complete PCI DSS certification). In case of Payment Form integration merchant is released of accepting payment details and all this stuff is completely implemented on the Paywize gateway side. In addition merchant may customize the look and feel of the Payment Form. Merchant must send the template to his/her Manager for approval before it could be used.

Payment Form API URL

For integration purposes use staging environment sandbox.paywize.com instead of production gate.paywize.com. Payment Form transactions are initiated through HTTPS POST request by using URL in the following format:

Form Transaction by ENDPOINTID

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.

https://gate.paywize.com/paynet/api/v2/sale-form/ENDPOINTID - for sale transactions
https://gate.paywize.com/paynet/api/v2/preauth-form/ENDPOINTID - for preauth transactions
https://gate.paywize.com/paynet/api/v2/transfer-form/ENDPOINTID - for transfer transactions

Form Transaction by ENDPOINTGROUPID

The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.

https://gate.paywize.com/paynet/api/v2/sale-form/group/ENDPOINTGROUPID - for sale transactions
https://gate.paywize.com/paynet/api/v2/preauth-form/group/ENDPOINTGROUPID - for preauth transactions
https://gate.paywize.com/paynet/api/v2/transfer-form/group/ENDPOINTGROUPID - for transfer transactions

General Payment Form Process Flow

    Customer -> Merchant: Checkout
activate Merchant

alt sale
Merchant -> "Paywize": sale-form/ENDPOINTID
activate "Paywize"
else preauth
    Merchant -> "Paywize": preauth-form/ENDPOINTID
else transfer
    Merchant -> "Paywize": transfer-form/ENDPOINTID
end

"Paywize" --> Merchant: status=processing
deactivate "Paywize"
deactivate Merchant

Customer -> Customer: Input cardholder data
Customer -> "Paywize": Submit form
activate "Paywize"
"Paywize" -> "Paywize": Processing
"Paywize" --> Customer: Redirect to **redirect_url**
deactivate "Paywize"

Customer -> Merchant: Return to the Shop

alt status
  loop
     Merchant -> "Paywize": status/ENDPOINTID
     activate "Paywize"
     "Paywize" --> Merchant: status=processing
     deactivate "Paywize"
    end
  else callback
   ... transaction processing ...
   "Paywize" --> Merchant: Callback notification
end

Checkout – Customer proceeds to order checkout.
Merchant initiates a transaction by sending HTTPS POST request to the specified URL. It should be either /sale-form/ENDPOINTID or /preauth-form/ENDPOINTID depending which transaction SMS or DMS should be accomlished.
Paywize gateway returns response which contains an additional parameter redirect-url. This is the URL where merchant must redirect Customer’s browser to.
See details about response format in Payment Form Response.
Merchant sends HTTP 302 redirect to Customer’s browser using URL which is obtained from the redirect-url response parameter.
Customer fills in payment details and submits the Payment Form.
Paywize gateway processes the transaction according to 3D or Non 3D process.
When sale authorization is completed Paywize gateway redirects the Customer’s browser to redirect_url request parameter provided by merchant in the original request accomplished at step 2. See details in Payment Form final redirect.

Payment form fields

This form contains the following fields:

Form field name Description
credit_card_number Customer’s credit card number 4455555555555544
expire_month Credit card expiration month 01 or 12
expire_year Credit card expiration year 2016
cvv2 Card security code 432

Initiating a transaction with Payment Form

Merchant must supply the following parameters to initiate a sale transaction using payment form template.

Payment Form Request Parameters

Request parameter name Length/Type Comment Necessity*
client_orderid 128/String Merchant order identifier. Mandatory
order_desc 64k/String Brief order description Mandatory
first_name 50/String Customer’s first name Mandatory
last_name 50/String Customer’s last name Mandatory
ssn 4/Numeric Last four digits of the customer’s social security number. Optional
birthday 8/Numeric Customer’s date of birth, in the format YYYYMMDD. Optional
address1 50/String Customer’s address line 1. Mandatory
city 50/String Customer’s city. Mandatory
state 2/String Customer’s state (two-letter state code). Please see Two-Letter Country Codes for a list of valid state codes. Mandatory for USA, Canada and Australia Conditional
zip_code 10/String Customer’s ZIP code Mandatory
country 2/String Customer’s country(two-letter country code). Please see Two-Letter Country Codes for a list of valid country codes. Mandatory
phone 15/String Customer’s full international phone number, including country code. Mandatory
cell_phone 15/String Customer’s full international cell phone number, including country code. Optional
email 50/String Customer’s email address. Mandatory
amount 10/Numeric Amount to be charged. The amount has to be specified in the highest units with . delimiter. 10.5 for USD means 10 US Dollars and 50 Cents Mandatory
currency 3/String Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro Mandatory
ipaddress 20/String Customer’s IP address, included for fraud screening purposes. Mandatory
site_url 128/String URL the original sale is made from. Optional
control 40/String Checksum generated by SHA-1. See Request authorization through control parameter for more details. Mandatory
redirect_url 1024/String URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Paywize gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Mandatory
server_callback_url 1024/String URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks Optional
preferred_language 2/String Customer’s two-letter language code for multi-language payment forms Optional
* acquirer can redefine the necessity of some fields so they become mandatory instead of optional
* leading and trailing whitespace in input parameters will be omitted

Payment Form Response

Response parameter name Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Order id assigned to the order by Paywize
merchant-order-id Merchant order id
serial-number Unique number assigned by Paywize server to particular request from the Merchant.
error-message If status is declined or error this parameter contains the reason for decline or error details
error-code The error code in case of declined or error status
redirect-url The URL to the page where the Merchant should redirect the client’s browser. Merchant should send HTTP 302 redirect, see General Payment Form Process Flow

Payment Form final redirect

Upon completion of Payment Form process by the Customer he/she is automatically redirected to redirect_url. The redirection is performed as an HTTPS POST request with the parameters specified in the following table.

Redirect parameter name Description
status See Status List for details.
orderid Order id assigned to the order by Paywize
merchant_order Merchant order id
client_orderid Merchant order id
error_message If status is declined or error this parameter contains the reason for decline or error details
control Checksum used to ensure that it is Paywize (and not a fraudster) that initiates the request. This is SHA-1 checksum of the concatenation status + orderid + client_orderid + merchant-control.
descriptor Gate descriptor

If Merchant has passed server_callback_url in original Payment Form request Paywize will call this URL. Merchant may use it for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. The parameters sent to this URL are specified in Sale, Return Callback Parameters

Payment Form Template Sample

<html>
<head>
<script type="text/javascript">
  function isCCValid(r){var n=r.length;if(n>19||13>n)return!1;
    for(i=0,s=0,m=1,l=n;i<l;i++)d=parseInt(r.substring(l-i-1,l-i),10)*m,s+=d>=10?d%10+1:d,1==m?m++:m--;
    return s%10==0?!0:!1}
</script>
</head>
<body>
<h3>Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION</h3>
<h3>Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT</h3>

<form action="${ACTION}" method="post">
  <div>Cardholder name: <input name="${CARDHOLDER}" type="text" maxlength="64"/></div>
  <div><label for="cc-number">Credit Card Number</label> <input id="cc-number" name="${CARDNO}" type="text" maxlength="19" autocomplete="cc-number"/></div>
  <div>Card verification value: <input name="${CVV2}" type="text" maxlength="4" autocomplete="off"/></div>
  <div>
    Expiration date:
    <select class="expiry-month" name="${EXPMONTH}" size="1" autocomplete="cc-exp-month" >
      <option value="01">January</option><option value="02">February</option><option value="03">March</option>
      <option value="04">April</option><option value="05">May</option><option value="06">June</option>
      <option value="07">July</option><option value="08">August</option><option value="09">September</option>
      <option value="10">October</option><option value="11">November</option><option value="12">December</option>
    </select>
      <select class="expiry-year" id="cc-exp-year" name="${EXPYEAR}" size="1" autocomplete="cc-exp-year">
      ${EXPIRE_YEARS}
    </select>
  </div>
  $!{INTERNAL_SECTION}
  #if($!card_error)
  <div style="color: red;">$!card_error</div>
  #end
  <input name="submit" onclick="return isCCValid(document.getElementById('cardnumber').value);" type="submit" value="Pay"/>
</form>
</body>
</html>

Payment form autofill

If you want to use autofill in your payment form, certain element attributes <id> <autocomplete> <label for> should be hardcoded in the following manner:

<label for="cc-number">Credit Card Number</label><span class="form-label-comment">The 13-19 digits on the front of your card</span>
<input class="card-number-field" id="cc-number" name="${CARDNO}" type="text" maxlength="19" autocomplete="cc-number" />

Our default payment form template supports autocomplete. In case if you want to add additional fields for autocomplete, this specification should be used for naming references.

Payment form macros

Field Name Macro Field Value Macro Description
${CARDNO} ${CARDNOVALUE} Customer’s credit card number.
${EXPMONTH} n/a Credit card expiration month
${EXPYEAR} n/a Credit card expiration year
${CVV2} ${CVV2VALUE} Card security code 432
${CARDHOLDER} ${CARDHOLDER_VALUE} Card printed name
${MERCHANT} n/a End point display name
${SKIN_VERSION} n/a CSS skin version
${ORDERDESCRIPTION} n/a Order description
${CUSTOMER_FIRST_NAME} n/a Customer first name sent by merchant via input parameters
${CUSTOMER_LAST_NAME} n/a Customer last name sent by merchant via input parameters
${CUSTOMER_EMAIL} n/a Customer E-mail address sent by merchant via input parameters
${AMOUNT} n/a Amount
${CURRENCY} n/a Currency
${PAYNET_ORDER_ID} n/a Paywize order id
${MERCHANT_ORDER_ID} n/a Merchant order id
${refresh_interval} n/a Refresh interval recommended by system
${uuid} n/a Internal
${INTERNAL_SECTION} n/a Internal for iFrame integration
${CUSTOMER_IP_COUNTRY_ISO_CODE} n/a Customer country defined by IP Address
${PREFERRED_LANGUAGE} n/a Customer language sent by merchant via input parameters
${BROWSER_LANGUAGE} n/a Customer language defined by browser settings
${CUSTOMER_LANGUAGE} n/a Customer language sent by merchant via input parameters or defined by browser settings if first is not set

Wait Page Template Sample

<html>
<head>
<script type="text/javascript">
  function fc(t) {
    document.getElementById("seconds-remaining").innerHTML = t;
    (t > 0) ? setTimeout(function(){fc(--t);}, 1000) : document.checkform.submit();}
</script>
</head>
<body onload="fc($!refresh_interval)">
<h3>Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION</h3>
<h3>Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT</h3>
Please wait, your payment is being processed, remaining <span id="seconds-remaining">&nbsp;</span> seconds.
<form name="checkform" method="post">
  <input type="hidden" name="tmp" value="$!uuid"/>
      $!{INTERNAL_SECTION}
  <input type="submit" value="Check" />
</form>
</body>
</html>

Wait Page macros

Field Name Macro Field Value Macro Description
${MERCHANT} n/a End point display name
${SKIN_VERSION} n/a CSS skin version
${ORDERDESCRIPTION} n/a Order description
${AMOUNT} n/a Amount
${CURRENCY} n/a Currency
${PAYNET_ORDER_ID} n/a Paywize order id
${MERCHANT_ORDER_ID} n/a Merchant order id
${refresh_interval} n/a Refresh interval recommended by system
${uuid} n/a Internal
${INTERNAL_SECTION} n/a Internal for iFrame integration
${CUSTOMER_IP_COUNTRY_ISO_CODE} n/a Customer country defined by IP Address
${PREFERRED_LANGUAGE} n/a Customer language send by merchant via input parameters
${BROWSER_LANGUAGE} n/a Customer language defined by browser settings
${CUSTOMER_LANGUAGE} n/a Customer language send by merchant via input parameters or defined by browser settings if first is not set

Finish Page Macros

Field Name Macro Field Value Macro Description
${STATUS} n/a Order status
${PAYNET_ORDER_ID} n/a System order id
${MERCHANT_ORDER_ID} n/a Merchant order id
${ERROR_MESSAGE} n/a Contains the reason for decline or error details
${SKIN_VERSION} n/a CSS skin version
${CUSTOMER_IP_COUNTRY_ISO_CODE} n/a Customer country defined by IP Address
${PREFERRED_LANGUAGE} n/a Customer language send by merchant via input parameters
${BROWSER_LANGUAGE} n/a Customer language defined by browser settings
${CUSTOMER_LANGUAGE} n/a Customer language send by merchant via input parameters or defined by browser settings if first is not set

Request authorization through control parameter

The checksum is used to ensure that it is a particular Merchant (and not a fraudster) that initiates the transaction. This SHA-1 checksum, the parameter control, is created by concatenation of the parameters values in the following order:

  • ENDPOINTID/ENDPOINTGROUPID
  • client_orderid
  • minimal monetary units amount (i.e. cent, penny etc.)
  • email
  • merchant_control

A complete string example may look as follows:

59I6email@client.com3E8E45B5-2-42D8-6ECC-FBF6B11B1

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter (see Payment Form Request Parameters) which is required for request authorization. For the above-mentioned example the control will take the following value:

d02e67236575a8e02dea5e094f3c8f12f0db43d7

Payment Form Request Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
client_orderid make it or use your internal invoice ID
order_desc
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
amount
email
currency
ipaddress
site_url
purpose
merchant_control input your Control Key
redirect_url
server_callback_url
merchant_data

String to sign
Signature
				  
				
			
		
			
		
			
		

Order status

Merchant must use Order status API call to get the customer’s order transaction status. After any type of transaction is sent to Paywize server and order id is returned, Merchant should poll for transaction status. When transaction is processed on Paywize server side it returns it’s status back to Merchant and at this moment the Merchant is ready to show the customer transaction result, whether it’s approved or declined.

Status API URL

For integration purposes use staging environment sandbox.paywize.com instead of production gate.paywize.com. Status API calls are initiated through HTTPS POST request by using URL in the following format:

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://gate.paywize.com/paynet/api/v2/status/ENDPOINTID
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
https://gate.paywize.com/paynet/api/v2/status/group/ENDPOINTGROUPID

Order status call parameters

Status Call Parameter Description
login Merchant login name
client_orderid Merchant order identifier of the transaction for which the status is requested
orderid Order id assigned to the order by Paywize
control Checksum used to ensure that it is Paywize (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. See Order status API call authorization through control parameter for more details about generating control checksum.
by-request-sn Serial number from status request

Order Status Response

Status Response Parameter Description
type The type of response. May be status-response
status See Status List for details.
amount Amount of the initial transaction.
currency Currency of the initial transaction.
paynet-order-id Order id assigned to the order by Paywize
merchant-order-id Merchant order id
phone Customer phone.
html HTML code of 3D authorization form, encoded in application/x-www-form-urlencoded MIME format. Merchant must decode this parameter before showing the form to the Customer. The Paywize System returns the following response parameters when it gets 3D authorization form from the Issuer Bank. It contains auth form HTML code which must be passed through without any changes to the client’s browser. This parameter exists and has value only when the redirection HTML is already available. For non-3D this never happens. For 3D HTML has value after some short time after the processing has been started.
serial-number Unique number assigned by Paywize server to particular request from the Merchant.
last-four-digits Last four digits of customer credit card number.
bin Bank BIN of customer credit card number.
card-type Type of customer credit card (VISA, MASTERCARD, etc).
gate-partial-reversal Processing gate support partial reversal (enabled or disabled).
gate-partial-capture Processing gate support partial capture (enabled or disabled).
transaction-type Transaction type (sale, reversal, capture, preauth).
processor-rrn Bank Receiver Registration Number.
processor-tx-id Acquirer transaction identifier.
receipt-id Electronical link to receipt https://gate.paywize.com/paynet/view-receipt/ENDPOINTID/receipt-id/
cardholder-name Cardholder name.
card-exp-month Card expiration month.
card-exp-year Card expiration year.
card-hash-id Unique card identifier to use for loyalty programs or fraud checks.
email Customer e-mail.
bank-name Bank name by customer card BIN.
terminal-id Acquirer terminal identifier to show in receipt.
paynet-processing-date Acquirer transaction processing date.
approval-code Bank approval code.
order-stage The current stage of the transaction processing. See Order Stage for details.
loyalty-balance The current bonuses balance of the loyalty program for current operation. if available
loyalty-message The message from the loyalty program. if available
loyalty-bonus The bonus value of the loyalty program for current operation. if available
loyalty-program The name of the loyalty program for current operation. if available
descriptor Bank identifier of the payment recipient.
error-message If status in declined, error, filtered this parameter contains the reason for decline
error-code The error code is case status in declined, error, filtered.
by-request-sn Serial number from status request, if exists in request. Warning parameter amount always shows initial transaction amount, even if status is requested by-request-sn.
verified-3d-status See 3d Secure Status List for details
verified-rsc-status See Random Sum Check Status List for details

Order Status Response Example

type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5eec
&merchant-order-id=6132tc
&processor-tx-id=9568-47ed-912d-3a1067ae1d22
&paynet-order-id=161944
&status=approved
&amount=7.56
&descriptor=no
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=cancel
&receipt-id=2050-3c93-a061-8a19b6c0068f
&name=FirstName
&cardholder-name=FirstName
&card-exp-month=3
&card-exp-year=2028
&email=no
&processor-rrn=510458047886
&approval-code=380424
&order-stage=cancel_approved
&last-four-digits=1111
&bin=444455
&card-type=VISA
&phone=%2B79685787194
&bank-name=UNKNOWN
&paynet-processing-date=2015-04-14+10%3A23%3A34+MSK
&by-request-sn=00000000-0000-0000-0000-0000005b5ece
&card-hash-id=1569311
&verified-3d-status=AUTHENTICATED
&verified-rsc-status=AUTHENTICATED

Status request authorization through control parameter

The checksum is used to ensure that it is Merchant (and not a fraudster) that sends the request to Paywize. This SHA-1 checksum, the parameter control, is created by concatenating of the values of the parameters in the following order:

  • login
  • client_orderid
  • orderid
  • merchant_control

For example assume the following values are corresponds the parameters above:

Parameter Name Parameter Value
login cool_merchant
client_orderid 5624444333322221111110
orderid 9625
merchant_control r45a019070772d1c4c2b503bbdc0fa22

The complete string example may look as follows:

cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for authorizing the callback. For the example control above will take the following value:

c52cfb609f20a3677eb280cc4709278ea8f7024c

Order status Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid input your Invoice Number
orderid
merchant_control input your Control Key
by-request-sn

String to sign
Signature