Skip to content
Farin Theme Guide
GuidesPayment, SMS and Shipping

Payment gateway

In this section you connect Iranian payment gateways to the shop, arrange their order on the checkout page, and set a discount or fee for each gateway. Completed payments are in “Payments”, and if you want, you can set up card-to-card with receipt review.

Where is it? Farin → Payment, SMS and Shipping → Payment gateway

Site administrator onlyThe “Payment gateway” section is open only to a user with the WordPress “Administrator” role. A WooCommerce shop manager does not see this section even if, in Access it is ticked. This restriction is more than hiding the menu; the server also refuses to save settings or run “Test connection” from anyone but the administrator, because the gateway key decides which account shoppers' money goes to.

Gateways work only when WooCommerce is active and the shop currency is Toman or Rial. If the currency is something else, a warning appears at the top of this page and Iranian gateways do not show on the checkout page. Change the currency in Currency Settings .

Gateways

This tab has several boxes: “Basics”, “Payment with VPN”, one box for each gateway, and finally “Return address”. Each box saves separately.

Setting up a gateway

  1. Get the keys from the gateway's panel. After approving your shop, each gateway gives you its own key or merchant code. If it asks, also register the return address written at the bottom of this tab in the gateway's panel.
  2. Open the gateway's box. Click the gateway's name to open its box and type the keys in “Gateway keys”.
  3. Click “Test connection”. If the keys are correct, a green message says the gateway returned a payment ID.
  4. Turn the gateway on and save. Flip the “Payment with … enabled” switch. From this moment shoppers see it on the checkout page.
  5. Make a small purchase. Before announcing it to shoppers, pay a real low-value order all the way through and check the result in “Payments”.

Basics

Basics box with the test mode switch, default gateway list and the yellow test mode warning
Test mode is on and no gateway is on yet; that is why the yellow warning says the Zibal test gateway is shown only to administrators.

The shopper sees the enabled gateways in the same order you arrange them in this tab. Wallet top-up and “rest of the amount by card” are paid through these same gateways; they need no separate setting.

OptionWhat it doesDefault
Test modePayments are sent to the gateway's test environment. In this mode gateways are shown only to shop administrators, and a regular shopper does not see them. If no gateway is on, the Zibal test gateway, which needs no key, is shown to administrators. When you turn it off, the panel asks whether you are sure, because from that moment payments are real.Off
Default gatewayThe gateway that comes first in the checkout list and is preselected. It must be on; if you choose an off gateway, the first enabled gateway becomes the default. A “Default” label appears next to the default gateway's name.First enabled gateway
Turn off test mode before real salesNo money moves in test mode. A payment that started in test mode and returns after the mode is turned off is not accepted, and no paid order is recorded. Zarinpal, Zibal, IDPay, BitPay and Aghayepardakht have a test environment. Other gateways are hidden in test mode so that testing is not done with real money.

Payment with VPN

Payment with VPN box with the VPN check switch, message text and the administrator's current IP
At the bottom of the box your own IP and the date of the Iran IP list are written. On a local site the IP is “Unknown or local” and payment stays open.

Iranian bank gateways do not accept payments from an IP outside Iran. Without this option, a shopper with a VPN on goes to the gateway and fails there. With this option, before sending the shopper to the gateway, Farin checks their IP against the list of Iranian IPs. If they are outside Iran, when they press “Place order” or “Pay” they see a window with the message text and an “OK” button and are not sent to the gateway. This check happens on placing an order, paying an order again and wallet top-up.

OptionWhat it doesDefault
Check for VPN before going to the gatewayTurns the IP check on or off. If the IP is unknown or local, payment goes ahead as usual. Cash on delivery, card-to-card and full payment by wallet are not checked.On
Message textThe message the shopper sees with a VPN on. Up to 200 characters. Leave it empty and the default text returns.“To pay through the bank gateway, please turn off your VPN or proxy and press ‘Pay’ again.”

Each gateway's box

Each gateway has its own box. The box header shows the gateway's name and logo, its type (intermediary gateway or direct bank gateway) and the unit the gateway calculates in (Toman or Rial). Converting the amount to the gateway's unit is automatic and you need do nothing. The label beside it tells the status:

  • Off: The gateway is not on the checkout page.
  • On: The gateway is on and all its keys are filled in.
  • Incomplete key: The gateway is on but one of its key fields is empty; until it is filled, it is not shown to shoppers.

With the two arrow buttons at the top of the box, move the gateway up or down the list. The checkout page order is this order, and the default gateway always comes first. If the shopper's wallet covers the whole order, the wallet stays above all.

Open Zarinpal box with the merchant code, the Test connection button, the checkout name and text, and the discount and fee fields
Zarinpal box: from the top, the on switch, “Gateway keys” with “Test connection”, “On the checkout page” and “This gateway's discount or fee”.
OptionWhat it doesDefault
Payment with … enabledBrings the gateway to the checkout page, provided its keys are complete.Off
Gateway keysThe fields each gateway needs to recognize your shop. Their list is below.Empty
Test connectionWith the values currently in the fields, even if not yet saved, it asks the gateway for a 10,000 Toman payment. If the gateway returns a payment ID, the message says the connection is working and which address the shopper would be sent to; otherwise it shows the gateway's own error message. No one is charged and nothing is saved.
NameThe name the shopper sees in the list of payment methods. Up to 60 characters.Online payment via the gateway name
Text under the nameA short sentence under the gateway's name. Up to 200 characters.Secure payment with all Shetab member bank cards.
Discount percentThe percentage taken off the amount when this gateway is chosen. From 0 to 100.0
Discount capThe largest discount, in the shop's currency. 0 means no cap.0
Fixed feeAn amount added to the order when this gateway is chosen.0
Fee percentA percentage added on top of the fixed fee. From 0 to 100.0
Fee capThe largest fee, fixed and percentage together. 0 means no cap.0

Gateway discount and fee

A discount and a fee both change the amount the shopper pays. Both are calculated on the sum of items after the coupon and without shipping, and each has its own line on the checkout page: “Discount for paying with …” and “Fee for paying with …”. When the gateway is changed, these lines change too.

Example: the sum of items is 2,000,000 Toman, “Discount percent” is 5 and “Discount cap” is 50,000 Toman. Five percent is 100,000 Toman, but the cap brings it to 50,000 Toman.

The discount is tied to that gatewayAn order placed with a gateway's discount or fee is paid in “Pay order” only with that same gateway, so that the discount is not taken with another method such as card-to-card or wallet. If you turn that gateway off later, the shopper has to place a new order to pay. If the shopper has a wallet, the wallet is calculated after these lines and covers the rest of the amount.

Each gateway's keys

Farin has these ten gateways. Fields marked “secret” are hidden after saving (explained below).

GatewayFieldsNote
ZarinpalMerchant code (secret)The 36-character code Zarinpal gives after approving the gateway. In test mode any 36-character merchant code is accepted.
ZibalMerchant key (secret)From the Zibal panel, the gateway page. No key is needed in test mode.
IDPayAPI key (secret)From the “Web service” section of the IDPay panel.
PayPingAPI token (secret)From the “Developers” section of the PayPing panel. Amount in Toman.
BitPayAPI key (secret)From the BitPay panel, the web service section. Test mode needs BitPay's own test key.
AghayepardakhtGateway PIN (secret)From the Aghayepardakht panel, the gateway page. In test mode the PIN sandbox is sent and your own PIN is not needed.
Saman Bank (SEP)Terminal numberDirect bank gateway.
Behpardakht MellatTerminal number, username (secret), password (secret)Direct bank gateway.
Parsian E-CommercePIN (LoginAccount) (secret)Direct bank gateway.
Asan PardakhtWeb service username (secret), web service password (secret), merchant configuration IDA numeric ID that Asan Pardakht gives alongside the web service username.
Zibal box with a saved merchant key and the green Saved label
Zibal after saving the key: the field is empty and a green “Saved” label shows that the key is on the server.
Keys are hidden after savingSecret fields (merchant code, keys, token, PIN, and bank username and password) are never sent back to the browser after saving, even to the main administrator. Instead the field stays empty and a “Saved” label appears; if the key is long, its last four characters are shown beside the dots so you know which key is saved. To change it, type the new key in the same field and save. An empty field keeps the previous key on saving. The terminal number and Asan Pardakht's configuration ID are not secrets and are visible.

On saving, spaces on both sides and invisible characters that sometimes come along when copying a key are removed, and Persian digits are converted to Latin (except in secret fields, which stay exactly as you typed them).

IDPay box with the API key field
IDPay: one “API key” field, taken from the “Web service” section of the IDPay panel.
PayPing box with the API token field and the amount in Toman
PayPing calculates in Toman; “Amount in Toman” is written at the top of the box.
BitPay box with the API key field and the test mode note
BitPay: for test mode, put BitPay's own test key in this same field.
Aghayepardakht box with the gateway PIN field
Aghayepardakht: in test mode it works without a PIN too.
Saman Bank box with the terminal number field
Saman Bank asks only for a terminal number and, since it is not a secret, it stays visible after saving.
Behpardakht Mellat box with terminal number, username and password
Behpardakht Mellat has three fields; the username and password are hidden after saving.
Parsian E-Commerce box with the PIN field
Parsian: the PIN the bank gives under the name LoginAccount.
Asan Pardakht box with web service username and password and the merchant configuration ID
Asan Pardakht: web service username and password, and the numeric merchant configuration ID.

Plugin gateways

If you have installed another gateway plugin (for example the Digipay or Zarinpal plugin), a box with its name appears before “Return address”. These gateways appear on Farin's checkout page with their own name, logo and fields beside the gateways above. The box shows only whether they are on or off, and the “Settings” link takes you to that gateway's page in WooCommerce.

Return address

Return address box with the site's wc-api/farin_pay address
Your site's return address; on a live site your own domain replaces localhost.

After paying, the shopper returns to this address and Farin asks the gateway about the payment. Some gateways ask for the return address or the domain at registration. The site's domain must be the same one registered in the gateway's panel; if you change the domain or move from http to https , update it in the gateway's panel too.

Payments

Payments table with the columns order, gateway, amount and result and three orders: pending, failed and paid
Three test payments with Zibal: one pending, one failed with its reason and one paid with the bank tracking code.

This tab is view-only. Orders that were paid, or were meant to be paid, with one of Farin's gateways are listed from newest to oldest, 30 per page.

ColumnWhat it shows
ordersThe order number and its date. Click the number to open the order page with all its notes.
GatewayThe gateway of the latest payment attempt. If that attempt was in test mode, a “Test” label appears beside it.
AmountThe order total.
Result“Paid” with the bank tracking code, “Failed” with the reason the gateway gave, or “Pending”.

“Pending” means the shopper went to the gateway but the payment has not yet been confirmed. When the gateway is unreachable, the order also stays pending, because the bank may have taken the money. If the shopper paid less than the order's current amount (for example the order changed after they went to the gateway), the order is not recorded as paid and stays in WooCommerce's “On hold” status for your review; read the order note before shipping.

One receipt, one orderA bank tracking code that has paid one order is not accepted on another order.

Card-to-card

The shopper deposits the order amount to the shop's card and sends the receipt from the order page. Until you review it, the order stays in WooCommerce's “On hold” status and the stock of its items is held for them. An order becomes paid only with your approval.

Preview

Preview box with the message “No card is on”
Until a card is on, the preview is empty.

What the shopper sees after placing an order, with your enabled cards. It refreshes with every save. The form in this preview sends nothing.

Receipts awaiting review

Receipts awaiting review box with the message “No receipts awaiting review”
When no receipt has arrived, this box says “No receipts awaiting review”.

Each receipt shows the destination card and the shopper's card (with the bank logo), the cardholder's name, the tracking number, the deposit time, the order amount at the moment of sending and the receipt image. Click the image to open it large. You can do two things:

  • “Approve and mark paid”: Before approving, the panel asks “Did you see the deposit in the account?”. On approval the order is recorded as paid and WooCommerce's usual process (emails, SMS, preparation) begins. The name of the person who approved stays in the order note.
  • “Reject receipt”: Choose one of the ready-made reasons or write your own, and press “Reject and notify buyer”. The reason is recorded as a note to the buyer; WooCommerce emails it, and if the “Note to buyer” SMS is on in SMS Panel it is sent as SMS too. The shopper can send a new receipt, and their deadline is extended by at least as much as the first deadline.
Check the account before approvingApproving a receipt means the order is paid, even if no money has arrived. Always find the deposit in the bank statement. If the same tracking number or an image like this receipt is on another order, or the order amount changed after the receipt was sent, a yellow warning appears above the receipt. A tracking number that was already sent for another order is not accepted at all.

This same box is on the edit page of every card-to-card order. A WooCommerce shop manager without access to the “Payment gateway” section reviews receipts from there. While any receipt is awaiting review, “Card-to-card receipt” with the number of receipts shows in the dashboard's top bar.

Card-to-card

Card-to-card box with the on switch, and the name and text on the checkout page
Turn on card-to-card and set the name the shopper sees on the checkout page.
OptionWhat it doesDefault
Card-to-card on the checkout pageBrings this method to the checkout page. Until you have at least one card on, the shopper does not see it.Off
Name on the checkout pageUp to 60 characters.Card-to-card
Text under the nameUp to 300 characters.After placing the order you see the shop's card number; deposit the amount and send the receipt right there.

Shop cards

Shop cards box with the message “You have not added a card yet” and the Add card button
“Add card” opens a new row for a card.

You can add up to ten cards. Each card has these fields: “Card number”, “Account holder's name”, “Sheba number (optional)”, “Note to buyer (optional)” and an “On” switch. The shopper sees only the cards that are on; change their order with the “Move up” arrow.

  • The bank is recognized from the card number, and its logo is shown to you and to the shopper.
  • A card number that is not valid is not saved, and the panel tells you before saving. The account holder's name is also required so the shopper is sure they are depositing to the right account.
  • An incorrect Sheba is not saved, but the card itself is saved.
  • If you delete a card, orders deposited to it still show it.

Rules

Rules box with the deposit deadline, maximum receipt images, size of each image, three switches and the note to buyer
Defaults: 24-hour deadline, up to 3 receipt images, each image up to 5 MB.
OptionWhat it doesDefault
Deadline to deposit and send the receiptFrom 1 to 168 hours. If no receipt arrives by the end of the deadline, the order is canceled and the stock of its items is released. An order whose receipt is under review is never canceled automatically.24 hours
Maximum receipt imagesHow many images the shopper can send with each receipt. From 1 to 5.3
Size of each imageFrom 1 to 10 MB.5 MB
Receipt image requiredWithout an image, the receipt is not sent. If you turn it off, “Tracking number required” turns on by itself so there is something to review.On
Shopper's card number requiredFor finding the deposit in the statement. Only the first six and last four digits of the shopper's card are kept.On
Tracking number requiredThe shopper must write the deposit's tracking number.Off
Note to buyerThe text that appears under the cards, before the receipt form. Up to 1000 characters.Deposit exactly this amount and write the order number in the deposit description. The order is confirmed after the receipt is reviewed.
Where receipt images are keptImages are rebuilt before saving so that hidden data inside the file (such as the photo's location) is removed, are kept under a random name in a separate folder, and only shop staff can open them.

Frequently Asked Questions

I turned the gateway on but the shopper does not see it.

Check three things: the label on the gateway's box is not “Incomplete key”, “Test mode” is off (in that mode only administrators see gateways), and the shop currency is Toman or Rial.

I can no longer see the key I saved. How do I know it is right?

For security, keys are not shown after saving. Press “Test connection”; with an empty field, the saved key is the one tested. If the key is long, its last four characters beside “Saved” also help.

Our shop manager does not see the Payment gateway section.

This is intentional. The gateway key decides which account the money goes to, so this section is only for the site's main administrator and cannot be opened through “Access” either. A shop manager reviews card-to-card receipts from the order page itself.

A shopper says they cannot pay with a VPN.

Iranian bank gateways do not accept foreign IPs, and with the “Check for VPN before going to the gateway” option Farin tells the shopper exactly that. They must turn the VPN off and press “Pay” again.

Farin Theme · 1405