R Rafina Panel guide
Guides / Payment and Shipping

Payment gateway

All of the store’s payment methods are turned on and configured from this page: bank gateways, BNPL gateways, card-to-card and split payment. The order of the gateways is the order the buyer sees on the checkout page.

Where is it? Rafina Panel → Payment gateway

The payment gateway list with on/off switches, the default option and move buttons
Overview: each gateway is a collapsible row; below the list come the “Cart with no common payment method” box and then the “General settings” box.

Setting up a gateway

  1. First register for a gateway on its own site. The “Register and get gateway” link inside each gateway’s row takes you to that site.
  2. In the gateway’s panel, enter the “Return address” (callback URL). Copy the address from this page’s “General settings” box using the “Copy” button.
  3. Open the gateway’s row by clicking its name and enter the keys the gateway gave you.
  4. Click “Test connection”. A green message means the keys were accepted; a red message gives the reason.
  5. Turn the “On” switch, and if you want this gateway first in the list and preselected, choose “Default”.
  6. Click “Save gateway settings” in the bar at the bottom of the page.
NoteBefore real sales, make a small test purchase and check that the order becomes “Paid” after returning from the gateway.

Gateway list

Two things are written under each gateway’s name: the amount unit that gateway works in (Rial or Toman) and the key status (“Key saved” or “Key not entered”). If a key is missing, a yellow warning badge appears beside the row so you can tell which gateway is incomplete without opening the rows. Toman and Rial conversion is automatic for each gateway and you don’t need to do anything.

OptionWhat it does
“On” switchShows or hides the gateway on the checkout page. Turning it off does not erase the entered keys. It works without opening the row.
“Default”The gateway that sits first in the payment list and is preselected. Only one enabled gateway can be the default.
Up and down buttons (“Move up one” and “Move down one”)They appear only beside enabled gateways and change their order on the checkout page. Disabled gateways are always at the bottom of the list.
WarningIf no gateway is on, the message “No gateway is on — customers cannot pay.” appears under the list and buyers have no way to pay.

Options shared by every gateway

When you open the row of any bank gateway you see these fields:

An open Zibal gateway row with display name, discount, fee, merchant key and the test connection button
An open bank gateway row (Zibal). Saved keys are shown as dots.
OptionWhat it doesDefault
Register and get gatewayA link to the gateway’s own site for registering and getting a key. It opens in a new tab.—
Gateway name (shown to customer)The name the buyer sees on the checkout page.The gateway’s own name
Short description (optional)A sentence under the gateway’s name on the checkout page.Empty
This gateway’s discount (percent)If the buyer chooses this gateway, this percent is deducted from the price of goods (after the discount code and excluding shipping). A green discount badge appears beside the gateway name.Zero (no discount)
Discount cap (Toman)The maximum discount amount for this gateway.No cap
This gateway’s fixed fee (Toman)An amount added to the order when this gateway is chosen. It appears in the payment summary as a “Payment gateway fee” row.Zero (no fee)
This gateway’s percentage feeA percent added to the order; calculated on the price of goods after the discount code plus shipping, and in a split payment on the amount of that installment.Zero
Fee cap (Toman)The maximum fee for this gateway, fixed plus percentage combined.No cap
Test connectionChecks the keys with the gateway itself without creating an order and writes the result under the button. If you have typed a key and not yet saved it, that one is tested; an empty field means the saved key.—
NoteKeys are no longer visible after saving and their field shows dots. To change one, type the new value; an empty field means the previous key is left untouched. A store manager who is not the site’s main administrator cannot see the keys at all.

Show for which categories

At the top of every open payment method row (gateways, card-to-card and split payment) there are two options:

OptionWhat it does
All categoriesThe method appears for any cart on the checkout page. This is each method’s default.
Only selected categoriesA searchable category list opens. The method appears on the checkout page only when all of the cart’s items are in one of these categories or their subcategories. Until you tick a category, the method stays available for everyone.

Each change is saved immediately and “Saved” appears beside it; you don’t need to click the save button at the bottom of the page. The same check also runs when the order is placed, so a restricted method can’t be accepted by any trick.

NoteA cart with an item outside the selected categories does not see that method. If you have restricted all methods to specific categories, leave at least one on “All categories” so no cart is left without a payment method. Gateways that come from another plugin and BNPL purchases (which have their own scope in Installment sales ) are separate from this option.

A cart with no shared payment method

When each method is restricted to its own category (for example Zarinpal only for gold and PayPing only for cosmetics), a cart with items from both categories sees neither method. The “Cart with no common payment method” box under the gateway list says what happens with such a cart:

The cart with no common payment method box with three options and a message text
The “Cart with no common payment method” box. The third option is dimmed until “Split payment” is turned on.
OptionWhat it does
Message onlyDefault. The buyer can add any item to the cart, but a message appears in the cart and on the checkout page saying which cart items each method accepts, so they can buy the cart as two orders.
Don’t add incompatible items to the cartAn item that has no common payment method with the items in the cart is not added, and the buyer immediately gets a message to place the current order first or empty the cart. This check applies to every way of adding (product page, card, buy again, buy next).
Pay each group with its own gateway, one after anotherThe buyer places one order and sees only the “Separate payment for each group” option on the checkout page. On the installments page, each group’s amount (the items one gateway accepts) is paid with that gateway: for example a ring with Zarinpal and then a lipstick with PayPing. Each installment’s amount is fixed and shipping goes with the first group. The order is finalized after the last group is paid. This option needs “Split payment” turned on, and that section’s deadlines apply to it as well.

The “Message text” is optional; if left empty, the default text is shown. Changes are saved immediately.

NoteIf at least one payment method is on for “All categories”, this situation never arises and no message is shown.

Each gateway's keys

GatewayGateway-specific fields
Card-to-cardhas its own section; explained below.
DigiPay (BNPL)The “Username”, “Password”, “Client ID” and “Client Secret” that DigiPay gives you, and the “Send products to DigiPay (Crawler)” switch: if on, the product list, prices and stock are sent to DigiPay so buyers can find them inside the DigiPay app; if off, no information is sent (off by default).
Zarinpal“Merchant code (Merchant ID)”, the 36-character code Zarinpal gives after approving the gateway.
SnappPay (BNPL)“Service address (Base URL)” (for real sales, the default value), “Merchant ID (Client ID)” and “Merchant key (Client Secret)” from the merchants portal, and the “Service username” and “Service password” issued for calling the service (not the portal username).
Torob Pay (BNPL)The same five fields as SnappPay. The “Merchant ID” is called “Torob Pay merchant code” and the “Merchant key” is called “Torob Pay key” in the Torob Pay panel.
Zibal“Merchant key”. For testing you can use the value zibal there.
IDPayThe “API key” from the “Web service” section of the IDPay panel.
BitPayThe “API key” from the web service section of the BitPay panel.
PayPingThe “API token” from the PayPing panel.
AghayepardakhtThe “Gateway PIN”. With the value sandbox it works in test mode.
Asan Pardakht“Web service username”, “Web service password” and “Merchant configuration ID (MerchantConfigurationId)”, the number given beside the username.
Sadad (Bank Melli)“Merchant number (MerchantId)”, “Terminal number (TerminalId)” and “Terminal key”, the base64 string that Sadad gives with the terminal. The amount is sent in Rial; there is no public test environment and the connection is tested on the site itself.
Parsian (PEC)“Merchant ID (LoginAccount)”, a 20-character string from the Parsian panel. It is not the same as the terminal number.
Iran Kish“Terminal number (Terminal ID)”, “Terminal password (Password)” and “Acceptor ID”, all digits only, and the “Public key”, the full text from BEGIN to END. A note under this gateway says to run a connection test and a trial purchase before serious use.
Behpardakht Mellat“Terminal number (terminalId)”, “Username (userName)” and “Password (userPassword)” that the bank gives with the terminal; the web service username and password, not the panel login.
Saman (SEP)“Terminal number (Terminal ID)”. It is the same terminal for BluPay too, provided BluPay is activated on it.
An open DigiPay gateway row with four keys and the switch to send products to DigiPay
The DigiPay gateway; the “Send products to DigiPay (Crawler)” switch is at the bottom of the row.

Card-to-card

The buyer transfers the amount to one of your cards and sends a receipt image. Until the receipt arrives, the order is “Pending payment” and does not hold stock; once a receipt is submitted it becomes “Pending review” so you can approve or reject it. Until at least one account is added, this method is not visible on the checkout page. Only the site’s main administrator can change card-to-card accounts and settings. The card-to-card row has no registration link or fee fields; its display name, short description, discount and discount cap work like the other gateways.

An open card-to-card row with one destination account, caps, and the deadline and receipt section
A card-to-card row with one destination account and the “Deadline and receipt” section.

Destination accounts

OptionWhat it does
Bank nameIf left empty, it is filled in automatically from the card number.
Account holder nameRequired; the buyer uses this name to confirm they are paying into the right account.
Card number16 digits. An invalid number gets an error right there.
IBAN (optional)24 digits after IR.
Total deposit cap for this accountThe sum of all deposits into this account, not one transaction. An order automatically goes to the account that has room for its amount and is closer to its cap; a full account is no longer chosen. Empty or zero means no cap.
Per-transaction capThe maximum amount of one card-to-card transfer to this account, the limit the bank sets per transfer. A larger order goes to another account, and if no account accepts it, card-to-card is not shown for that cart. Empty or zero means no cap.
Note for buyer (optional)A sentence shown to the buyer under this card, for example “A Paya transfer takes one business day”.
Up, down and “Delete this account”Reorders the accounts or removes an account.
“+ Add account”Adds a new account.

When a total cap is set for an account and saved, a usage line appears under that field: “Approved · Pending · Remaining”. The “Reset approved” button zeroes that account’s approved amount (for example when the account’s monthly limit has renewed) and does not touch the amount of pending orders.

Deadline and receipt

OptionWhat it doesDefault
Payment and receipt deadline (hours)The time the buyer has after placing the order to deposit the amount and send the receipt, from 1 to 168 hours. If no receipt arrives, the order is cancelled automatically and the stock is returned. The buyer’s page has a countdown.24
Maximum receipt imagesHow many images are accepted per receipt, 1 to 5.3
Maximum size per image (MB)1 to 10 MB. JPG, PNG and WebP only.5
Require payer’s card numberThe buyer must enter the card they paid from; you can find the deposit in the account statement sooner. The number is stored masked only.On
Buyer guidance textThe text shown above the receipt form. If left empty, the default text appears.Default text
NotePending receipts are viewed and approved or rejected in “Orders” through the “Receipts pending review” link and the “Receipt” column. On approval, the order becomes paid and the usual payment messages are sent. To be notified of a new receipt, set up the “New card-to-card receipt” template in SMS panel or Email panel .

Pay in several installments

Every bank card has a daily payment limit. With this method, the buyer pays a large order in several installments and by several methods, for example part by gateway and part by card-to-card. The order is held until fully paid. BNPL gateways (SnappPay, Torob Pay, DigiPay) never become installments.

An open split payment row with caps, allowed methods and first installment settings
The “Split payment” row with the “First installment” section.
OptionWhat it does
When to offer to the buyerThree modes: “On any cart”, “From an amount and above” and “Only above one gateway installment’s cap”. A cart larger than one gateway installment’s cap sees this method in every mode, since it can’t be paid in a single payment. A status line under this option says which carts this method is currently shown for, or why it isn’t shown.
From what amount to offerOnly in “From an amount and above” mode: carts with a total from this amount up see this method.
These carts can be paid only by split paymentOnly in the “On any cart” and “From an amount and above” modes. On means a cart that sees this method sees no other payment method on the checkout page. Useful for a store that wants card-to-card to be paid only as an installment: leave card-to-card on in the gateway list and tick it in “Later installment methods”. Off by default.
Cap per gateway installmentThe daily limit of a bank card. A total above this puts this method first in the payment list.
Cap per card-to-card installmentZero means no cap. If the card-to-card accounts have caps, those caps are respected too.
Minimum amount per installmentThe buyer does not pay an installment smaller than this. If the remainder is less for the last installment, the remainder is the amount.
Allowed methods for each installmentTick the gateways allowed in installments. “All enabled gateways” means every enabled gateway.
Minimum share of first installment (percent of cart)The first installment must be a final payment for the order to be placed. Zero means no percentage minimum.
Minimum first installment amountWhichever is larger of the percent and the amount becomes the minimum; it never exceeds the whole cart.
First installment exactly this amountOn means the first installment is accepted at neither less nor more than this minimum; on the installments page the amount box is locked and the amount shortcut buttons are hidden. Later installments are free. If the whole cart is less than this amount, the first installment is the whole cart. Off by default.
First installment methodsThe gateways allowed for the first installment. If none is selected, the allowed methods above apply.
Later installment methodsThe gateways for later installments, for example only card-to-card. None means the allowed methods above.
First installment deadline (minutes)An order whose first installment hasn’t been finally paid within this many minutes is cancelled and the items return to stock. A card-to-card that has no receipt yet doesn’t count as paid. Zero means off.
Deadline for all installments (minutes)For example 4320 means three days. An order with no payment at all by this time is cancelled and stock is returned; an order with part of its money received is not cancelled and you are notified.
Note for buyer (optional)Shown at the top of the installments payment page.
NoteA card-to-card installment does not hold item stock until a receipt is submitted, and the order stays “Pending payment”.

General settings

The general settings box with the test mode switch and the gateway return address
The “General settings” box.
OptionWhat it doesDefault
Test mode (Sandbox)Moves gateways that have a test environment to that environment. No real money moves. Turn it off before real sales.Off
Gateway return address (Callback URL)The address you must enter in the gateway’s panel. Each gateway has its own address: this same pattern, with that gateway’s ID in place of the end of the address. The “Copy” button copies it.—

Save

The bar at the bottom of the page says whether you have unsaved changes (“You have unsaved changes” or “All changes saved”). No change takes effect on the site until you click “Save gateway settings”. If part of the card-to-card settings can’t be saved, a “These items were not saved:” list is shown with the reason for each.

FAQ and troubleshooting

Zarinpal gives the error “code -10” or “Terminal ip not valid”.

It means the IP address of the server the site uses to call Zarinpal is not registered for this merchant, or the merchant is a test one. Ask hosting support for the outgoing IP address (on shared hosting it differs from the site’s IP) and register it in the Zarinpal panel.

SnappPay or Torob Pay says “access denied” or code 403.

These services only accept requests from a server IP registered with them. Send the server’s IP to that service’s support.

Torob Pay gives the error “invalid Basic header” or code 1017.

The “Torob Pay merchant code” or “Torob Pay key” was not entered correctly. Copy both again from the Torob Pay panel.

The Torob Pay connection test says the amount is invalid.

BNPL gateways have a minimum amount. As long as the “Connection is established” message appears, the keys are right; the service’s message is written only beside it.

Card-to-card is not shown on the checkout page.

Either no account is registered, or the cart total exceeds the per-transaction cap and remaining room of all accounts.

I don’t see “Split payment”.

The status line under “When to offer to the buyer” gives the reason. The most common is that the option is on “Only above one gateway installment’s cap”, so a small cart doesn’t see it; choose and save “On any cart” or “From an amount and above”. If the status line says no other method is on for installments, turn on at least one more gateway; card-to-card with no destination account doesn’t count.