1.1.5. Recurrent Transactions

Recurrent Payment General Flow

Recurrent payments are made in three steps:

  1. Initial payment – make initial payment to verify and authorize the credit card
  2. Card registration – get card reference ID card-ref-id and register customer’s card in customer’s profile
  3. Recurrent payment – run recurrent payment when a business event is triggered on the Merchant. Customer doesn’t have to re-enter card information, Merchant uses card-ref-id to authorize payment

Card Registration

Customer -> Merchant: Pick up recurrent service
activate Merchant
Merchant --> Customer: Show initial payment form
deactivate Merchant

Customer -> "Paywize": Submit initial payment information
activate "Paywize"
"Paywize" -> "Paywize": Process payment
"Paywize" --> Merchant: Payment approved

activate Merchant
Merchant -> "Paywize": Get card ref ID
"Paywize" --> Merchant: Return card ref ID
Merchant -> Merchant: Assign card ref ID to Customers profile
deactivate Merchant

"Paywize" --> Customer: Redirect to merchant website
deactivate "Paywize"

Customer -> Merchant: Goto payment status Page
activate Merchant
Merchant --> Customer: Payment sucessful
deactivate Merchant

Customer picks up a service from Merchant’s portfolio to register the credit card
Merchant shows Recurrent payment form to make the first payment.
Customer fills in the form and submits it to Paywize to make Initial Payment
Paywize processes the transaction using the appropriate bank’s gateway
Paywize notifies Merchant that Initial Payment transaction was successful
Merchant requests card refererence id card-ref-id from Paywize
Paywize returns card-ref-id
Merchant assigns card reference id to Customer’s profile
Paywize redirects the Customer to Merchnt’s website
Merchant shows the page saying that the card registration is succesful and initial payment approved

Process Initial Payment

In order to register the Customer’s card and get card-ref-id Merchant should process initial payment with Paywize by using one of the following APIs:

It is important to make the initial payment the most secure way in order to guarantee that a real card holder is registering the card. To insure this Merchant might use one of the following identification approaches or their combination: Verified by Visa, MasterCard SecureCode, random amount withdrawal verification, anti-fraud systems(e.g. MaxMind) check.

Process Card Registration

Merchant should get card-ref-id that will be used in future recurrent payments in order to avoid storing the credit card sensitive data which is required by PCI DSS. Card Registration ID is totally secure and cannot be used by fraudsters to carry ou fraudulent transaction even if they know it. This allows to securely save card-ref-id in Customer’s profile on the Merchant’s side.

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

Card Registration request URL

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

https://gate.paywize.com/paynet/api/v2/create-card-ref/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/create-card-ref/group/ENDPOINTGROUPID

Card registration request parameters

Registration request 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 the Merchant (and not a fraudster) who sends the request. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control.

As you may see from the parameters list Merchant has to supply orderid and client_orderid associated with the first payment transaction. It emphasizes that the first payment is a mandatory step to process recurrent payments.

Card Registration Response

Registration Response Parameter Description
type The type of response. May be create-card-ref-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
status See Status List for details.
card-ref-id Card reference ID to used in subsequent recurrent payments
unq-card-ref-id Unique card reference ID to each PAN. It can be used by Merchant for loyalty programs or fraud control.
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
error-code The error code is case of declined or error status
end-point-id Endpoint id used for the transaction

Card Registration Request Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid input your Invoice Number
orderid
merchant_control input your Control Key

String to sign
Signature
              
            
			
		
			
		
			
		

Get Cardholder details with Card Reference Identifier

For integration purposes use staging environment sandbox.paywize.com instead of production gate.paywize.com. Merchant requests Card details by sending HTTPS request to the server. In order to make this request Merchant is required to pass card-ref-id with the request. Use the following URL to make the request:

Cardholder details request URL

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

https://gate.paywize.com/paynet/api/v2/get-card-info/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/get-card-info/group/ENDPOINTGROUPID

Card Information request parameters

Information request Parameter Length/Type Comment Necessity*
login 20/String Merchant login name Mandatory
cardrefid 20/String Equals to card-ref-id obtained in Card Information Reference ID call during Card Registration stage Mandatory
control 128/String Checksum used to ensure that it is Merchant (and not a fraudster) that initiates the return request. This is SHA-1 checksum of the concatenation login + cardrefid + merchant_control. Mandatory

Get Card Information Response

Information Response Parameter Description
type The type of response. May be get-card-info-response, validation-error, error. If type equals error, error-message and error-code parameters contain error details.
card-printed-name Card holder name
expire-year Card expiration year
expire-month Card expiration month
bin Bank Identification Number
last-four-digits The last four digits of PAN
serial-number Unique number assigned by Paywize server to particular request from the Merchant.
error-message If status is validation-error or error this parameter contains the reason for decline or error details
error-code The error code is case of validation-error or error status

Get Card Information Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
card-ref-id
merchant_control input your Control Key

String to sign
Signature
              
            
  

   









Process Recurrent Payment

Successful Recurrent Payment Diagram

Merchant -> Merchant: Start recurrent payment
Merchant -> Merchant: Get card ref id from customers profile

Merchant -> "Paywize": Make recurrent payment
activate "Paywize"
"Paywize" --> Merchant: type=async-response, OrderID
... transaction processing ...
Merchant -> "Paywize": Poll status (status/ENDPOINTID)
"Paywize" --> Merchant: type=status-response, status=processing
... transaction processing ...
Merchant -> "Paywize": Poll status (status/ENDPOINTID)
"Paywize" --> Merchant: type=status-response, status=approved
deactivate "Paywize"

Merchant’s application triggers an event that requires to withdraw some amount from the Customer’s card
Merchant gets Card Reference ID card-ref-id in Customer’s profile
Merchant initialtes recurrent payment using guven card-ref-id
Paywize returns new Order ID for the recurrent payment
Merchant starts polling Paywize by using Order Status API
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 Order Status API
Paywize returns current status of the order - approved
See more details about asynchronous status polling at Order Status API

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

Recurrent Payment request URL

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

https://gate.paywize.com/paynet/api/v2/make-rebill/ENDPOINTID – to make recurrent payment SALE
https://gate.paywize.com/paynet/api/v2/make-rebill-preauth/ENDPOINTID – to make recurrent payment AUTH

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/make-rebill/group/ENDPOINTGROUPID – to make recurrent payment SALE
https://gate.paywize.com/paynet/api/v2/make-rebill-preauth/group/ENDPOINTGROUPID – to make recurrent payment AUTH

Recurrent Payment request parameters

Payment request parameter Length/Type Comment Necessity*
client_orderid 128/String Merchant order identifier. Mandatory
login 20/String Merchant’s login Mandatory
cardrefid 20/String Card reference id obtained at Card Registration step Mandatory
order_desc 64k/String Order description Mandatory
amount 10/Numeric Amount to be charged. 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
enumerate_amounts 128/String This parameter may comprise multiple amounts, separated with ,. Paywize will cycle through the amounts of the list, try to make a payment on that amount, until there are no more amounts from the list, or not get approved. Optional
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. 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 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 + cardrefid + amount_in_cents + currency + merchant_control. Mandatory
comment 50/String A short somment 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. Parameter is mandatory for 3D flow and optional for Non 3D. Pass http://google.com if you are not sure. 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
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

* leading and trailing whitespace in input parameters will be omitted

Recurrent Response

Recurrent 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

Recurrent Response Example

type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935

Recurrent Response Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid make it or use your internal invoice ID
cardrefid
amount
currency
enumerate_amounts
cvv2
ipaddress
comment
order_desc
merchant_control input your Control Key

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 Request 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.
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.
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.
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.

Order Status Response Example

type=status-response
&serial-number=00000000-0000-0000-0000-00000aa68276
&merchant-order-id=pg1sbw
&processor-tx-id=15222817
&paynet-order-id=15222817
&status=approved
&amount=20000.00
&descriptor=no
&transaction-type=sale
&receipt-id=18042926-d652-331c-b5a0-3e1dbacf69b2
&name=HOLDER
&cardholder-name=HOLDER
&card-exp-month=3
&card-exp-year=2016
&email=gmail.com
&processor-rrn=187722741
&approval-code=610669
&order-stage=sale_approved
&last-four-digits=7682
&bin=427655
&card-type=VISA
&phone=%2B79633014273
&bank-name=SBERBANK
&dest-bank-name=SBERBANK
&dest-bin=427655
&dest-last-four-digits=7682
&dest-card-type=VISA
&paynet-processing-date=2015-04-06+22%3A00%3A27+MSK
&by-request-sn=00000000-0000-0000-0000-00000a8d3992
&card-hash-id=1664889
&verified-3d-status=AUTHENTICATED
&verified-rsc-status=AUTHENTICATED
&merchantdata=promo

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 concatenation of these parameters values in the following order:

  • login
  • client_orderid
  • orderid
  • merchant_control

For example, assume these parameters have the values as listed below:

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