1.1.3. Recurrent Transactions¶
Recurrent Payment General Flow¶
Recurrent payments are made in three steps:
- Initial payment – make initial payment to verify and authorize the credit card
- Card registration – get card reference ID card-ref-id and register customer’s card in customer’s profile
- 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¶
Process Initial Payment¶
In order to register the Customer’s card and get card-ref-id Merchant should process initial payment with MoneyNetint 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 pne-sandbox.moneynetint.com instead of production pne-gate.moneynetint.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://pne-gate.moneynetint.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://pne-gate.moneynetint.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 MoneyNetint |
| 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 MoneyNetint 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 |
Get Cardholder details with Card Reference Identifier¶
For integration purposes use staging environment pne-sandbox.moneynetint.com instead of production pne-gate.moneynetint.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://pne-gate.moneynetint.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://pne-gate.moneynetint.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 MoneyNetint 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 |
Process Recurrent Payment¶
Successful Recurrent Payment Diagram¶
For integration purposes use staging environment pne-sandbox.moneynetint.com instead of production pne-gate.moneynetint.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.
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
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 ,. MoneyNetint 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 MoneyNetint 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 MoneyNetint |
| merchant-order-id | Merchant order id |
| serial-number | Unique number assigned by MoneyNetint 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
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 MoneyNetint server and order id is returned, Merchant should poll for transaction status. When transaction is processed on MoneyNetint 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 pne-sandbox.moneynetint.com instead of production pne-gate.moneynetint.com. Status API calls are initiated through HTTPS POST request by using URL in the following format:
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 MoneyNetint |
| by-request-sn | Serial number assigned to the specific request by MoneyNetint. If this field exist in status request, status response return for this specific request. |
| control | Checksum used to ensure that it is MoneyNetint (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 MoneyNetint |
| merchant-order-id | Merchant order id |
| phone | Customer phone. |
| serial-number | Unique number assigned by MoneyNetint 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://pne-gate.moneynetint.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. |
| 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 MoneyNetint. 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