1.1.3. Synchronous account verification

Account verification transaction diagram

The Merchant should use Paywize API as described in General Account verification Process Flow. Account verification is not supportd for 3D gates.

Merchant -> "Paywize": Account verification request
activate "Paywize"
"Paywize" --> Merchant: Order ID

"Paywize" -> Acquirer: Process Account verification
activate Acquirer

Acquirer --> "Paywize": Processing result
deactivate Acquirer

"Paywize" --> Merchant: Final status
deactivate "Paywize"

Account verification request Customer checks out the order and Merchant sends Account verification request to Paywize server with specified parameters described in Account verification Request Parameters.
Process Account verification Paywize server forwards Account verification request to bank acquirer synchronously.
Processing result The bank responds to Paywize server with approve or decline for requested Account verification.
Final status Paywize server returns status to Merchant.

Process Account verification transaction

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

Account verification 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/sync/account-verification/ENDPOINTID – for account verification transaction

Account verification Request Parameters

In order to initiate a Account verification transaction Merchant sends an HTTPS POST request with the parameters specified in Account verification Request Parameters Table below

Account verification Request Parameters Length/Type Comment Necessity*
client_orderid 128/String Merchant order identifier. Mandatory
order_desc 64k/String Brief order description Mandatory
card_printed_name 128/String Card printed name Mandatory
first_name 50/String Customer’s first name Optional
last_name 50/String Customer’s last name Optional
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-3/String Customer’s state . Please see Reference for a list of valid state codes. Conditional
zip_code 10/String Customer’s ZIP code Mandatory
country 2/String Customer’s country(two-letter country code). Please see Reference for a list of valid country codes. Mandatory
phone 15/String Customer’s full international phone number, including country code. Optional
cell_phone 15/String Customer’s full international cell phone number, including country code. Optional
email 50/String Customer’s email address. Mandatory
credit_card_number 20/Numeric Customer’s credit card number. Mandatory
expire_month 2/Numeric Credit card expiration month Mandatory
expire_year 4/Numeric Credit card expiration year Mandatory
cvv2 3-4/Numeric Customer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. Mandatory
ipaddress 20/String Customer’s IP address, included for fraud screening purposes. Mandatory
site_url 128/String URL the original Account verification is made from. 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
control 40/String Checksum generated by SHA-1. See Request authorization through control parameter for more details. Mandatory
server_callback_url 128/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 Account verifications data in Merchant’s database. See more details at [Merchant URL callbacks]({% post_url 2015-02-19-merchant-callbacks %}) Optional
merchant_data 64k/String Any additional information for this transaction which may be useful in Merchant’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Merchant Callback. 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

Please note the following characters must be escaped in the parameter values: & + .

Account verification Request Example

client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=%2B12063582043
&cell_phone=%2B19023384543
&email=john.smith@gmail.com
&ipaddress=65.153.12.232
&site_url=www.google.com
&credit_card_number=4538977399606732
&card_printed_name=CARD HOLDER
&expire_month=12
&expire_year=2099
&cvv2=123
&purpose=www.twitch.tv/dreadztv
&server_callback_url=http://doc.paywize.com/doc/dummy.htm
&merchant_data=VIP customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

Unsuccessful Synchronous Account verification Response

Account verification Response Parameter Description
type The type of response. May be validation-error, error.
merchant-order-id Merchant order id
serial-number Unique number assigned by Paywize server to particular request from the Merchant.
error-message Error details
error-code The error code

Unsuccessful Account verification Response Example

type=validation-error
&serial-number=00000000-0000-0000-0000-000000000048
&merchant-order-id=MID-9b62ff31-a183-4f7a-be2c-694d13cdd2ab
&error-message=INVALID_CONTROL_CODE
&error-code=2

Successful Synchronous Account verification Response

Status Response Parameter Description
type The type of response. May be status-response
status See Status List for details.
paynet-order-id Order id assigned to the order by Paywize
merchant-order-id Merchant order id
phone Customer phone.
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/
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.
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.
card-ref-id Card referense ID to used in subsequent recurrent payments
verified-3d-status See 3d Secure Status List for details
verified-rsc-status See Random Sum Check Status List for details
merchantdata If provided in initial request, merchant_data parameter and its value will be included in status response.

Successful Account verification Response Example

type=status-response
&serial-number=00000000-0000-0000-0000-00000456fa77
&merchant-order-id=avaw23wefd
&processor-tx-id=PNTEST-3622351
&paynet-order-id=3622351
&status=approved
&amount=0.00
&currency=GBP
&descriptor=Minatory
&transaction-type=account_verification
&receipt-id=54d9a433-5199-38d6-b531-61f383298121
&name=CARD+HOLDER
&cardholder-name=CARD+HOLDER
&card-exp-month=12
&card-exp-year=2099
&email=john.smith%40gmail.com
&processor-rrn=514174311400
&approval-code=473741
&order-stage=av_approved
&merchantdata=VIP+customer
&last-four-digits=6732
&bin=453897
&card-type=VISA
&phone=12063582043
&bank-name=MITSUBISHI+UFJ+NICOS+CO.+LTD.
&auth-response-code=00
&terminal-id=12345678
&paynet-processing-date=2015-05-21+16%3A08%3A30+MSK
&acquirer-processing-date=2015-05-21+16%3A08%3A30+MSK
&by-request-sn=00000000-0000-0000-0000-00000456fa76
&card-hash-id=212643
&card-ref-id=50705
&verified-3d-status=AUTHENTICATED
&verified-rsc-status=AUTHENTICATED

Account verification Request Debug

endpointid input your ENDPOINTID
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
email
ipaddress
site_url
credit_card_number enter the beginning of the sequence, and then "i"
card_printed_name
expire_month
expire_year
cvv2
purpose
merchant_control input your Control Key
server_callback_url
merchant_data

String to sign
Signature
              
            
  

   





Server callback result

Upon completion by the System it returns the result on the specified server_callback_url with the following parameters described in Account verification, 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

Account verification 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
  • client_orderid
  • email
  • merchant_control

A complete string example may look as follows:

1902B4FF5john.smith@gmail.comB17F59B4-A7DC-41B4-8FF9-37D986B43D20

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

45dec98f9d69000a9f41bdb4ace47a7755fd47cd