Configuration

Configuration

payvand.Config is one struct for every provider. Each gateway validates the fields it needs inside New, so a misconfigured terminal fails when you wire it rather than when a customer pays.

type Config struct {
	MerchantID  string            // merchant / business identifier
	TerminalID  string            // terminal or acceptor identifier
	Username    string            // terminal user name
	Password    string            // terminal password
	MerchantKey string            // API key, bearer token or private key
	IBAN        string            // settlement account, for multiplexing gateways
	Extra       map[string]string // anything provider specific
}

Mapping

Gateway	MerchantKey	MerchantID	TerminalID	Username	Password	IBAN
Zarinpal	merchant id (36 chars)
Zibal	merchant
Vandar	API key	business name (refunds only)
PayWeb	bearer token
IDPay	API key
Pay.ir	API key
NextPay	API key
PayPing	bearer token
BitPay.ir	API key
YekPay	merchant id
Sadad · Bank Melli	base64 terminal key	merchant id	terminal id
Parsian	login account (pin)					settlement IBAN
Iran Kish	acquirer RSA public key		terminal id	acceptor id	terminal password
Mellat			terminal id	user name	password
Saman · SEP			terminal number
Pasargad	RSA private key	merchant code	terminal code
AsanPardakht		merchant configuration id		usr header	pwd header
Sepehr · Bank Saderat			terminal id
TOP	EShop pin
Jibit · PPG v3	API key				secret key
SnappPay	OAuth client secret	OAuth client id		merchant user	merchant password
TorobPay	OAuth client secret	OAuth client id		merchant user	merchant password
Digipay	OAuth client secret	OAuth client id		merchant user	merchant password
Tara				merchant user	merchant password
Virtual	—	—	—	—	—	—

Notes per gateway

Sadad — MerchantKey is the base64 terminal key, used to build the 3DES signature of every call. It is not the merchant id.

Iran Kish — MerchantKey holds the acquirer's RSA public key (PEM). TerminalID and Password must be hexadecimal strings, because the protocol concatenates and hex-decodes them while building the authentication envelope.

Pasargad — MerchantKey is the RSA private key. Both a PEM block (PKCS#1 or PKCS#8) and the .NET <RSAKeyValue> XML that Pasargad still distributes are accepted, so you can paste whichever the panel gave you. Pasargad also requires the invoice date of the purchase at verification time; it is returned in PurchaseResponse.Extra[pasargad.InvoiceDateKey] — persist it with the order.

Vandar — refunds go through the business API, which needs MerchantID (the business name) and usually a bearer token, set with vandar.WithAccessToken.

Parsian — IBAN is only needed when you enable settlement to an IBAN with parsian.WithSettlementToIBAN or pass explicit shares.

AsanPardakht — Username and Password are sent as the usr and pwd headers, not as a body field.

Zibal / Pay.ir — both have a reserved sandbox identity, selected with payvand.WithSandbox(true): Zibal switches the merchant to zibal, Pay.ir switches the API key to test.

IDPay — the sandbox is a header (X-SANDBOX: 1), also driven by payvand.WithSandbox(true).

Jibit — MerchantKey is the API key and Password the secret key of the PPG client. Payvand exchanges them for a bearer token on the first call, caches it, and re-authenticates once when Jibit answers security.auth_required.

SnappPay / TorobPay / Digipay — four credentials, two pairs. Username and Password are the merchant user of the OAuth password grant; MerchantID and MerchantKey are the OAuth client id and client secret sent as HTTP basic authentication. Digipay additionally pins the contract version with the Digipay-Version header, overridable through digipay.WithAPIVersion, and has a UAT host reached with payvand.WithSandbox(true).

Tara — only Username and Password, the credentials of the Tara panel. The same user name is posted with the token when the payer is redirected, so it must match the terminal the token was issued for.

Loading from the environment

cfg := payvand.Config{
    MerchantKey: os.Getenv("PAY_MERCHANT_KEY"),
    MerchantID:  os.Getenv("PAY_MERCHANT_ID"),
    TerminalID:  os.Getenv("PAY_TERMINAL_ID"),
    Username:    os.Getenv("PAY_USERNAME"),
    Password:    os.Getenv("PAY_PASSWORD"),
    IBAN:        os.Getenv("PAY_IBAN"),
}

gw, err := pv.Gateway(payvand.Name(os.Getenv("PAY_GATEWAY")), cfg)

Unknown names return payvand.ErrGatewayNotRegistered, so a typo in the configuration fails loudly at start-up.

Several terminals at once

Nothing is global. Build one gateway per terminal and keep them in a map:

type terminal struct {
    Gateway payvand.Name
    Config  payvand.Config
    Options []payvand.Option
}

gateways := map[string]payvand.Gateway{}
for id, t := range terminals {
    gw, err := pv.Gateway(t.Gateway, t.Config, t.Options...)
    if err != nil {
        return fmt.Errorf("terminal %s: %w", id, err)
    }
    gateways[id] = gw
}

Keeping credentials safe

• Never commit terminal keys. The repository .gitignore already excludes *.pem, *.key, *.p12 and keys/.
• PurchaseResponse.Raw, VerifyResponse.Raw and the logger receive provider payloads; redact them before they reach a log aggregator.
• Rotate a key by rebuilding the gateway — nothing is cached between calls.

Next: Options · Supported Gateways