Options

Options

Everything is configured with functional options, and every provider extra is opt-in: leave an option out and the parameter is simply not sent.

Provider options have the same type as the shared ones (payvand.Option), so they compose in one list:

import "github.com/amiranmanesh/payvand/gateway/zibal"

gw, err := pv.Gateway(payvand.Zibal, cfg,
    payvand.WithSandbox(true),          // shared
    payvand.WithTimeout(15*time.Second),// shared
    zibal.WithFeeMode(1),               // provider specific
    zibal.WithMultiplexing(
        zibal.Share{BankAccount: "IR…", Amount: 90_000},
        zibal.Share{SubMerchantID: "sub-1", Amount: 60_000},
    ),
)

Options given to Client.Gateway are applied after the ones given to payvand.Init, so a call can override an application default.

Shared options

Option	Effect
WithTimeout(d)	bounds a single gateway call; default 30s
WithHTTPClient(c)	any Do(*http.Request) (*http.Response, error) — tracing, proxying, mocking
WithLogger(l)	request/response events; payvand.SlogLogger{Logger: …} adapts log/slog
WithSandbox(b)	switches providers that have a test environment
WithBaseURL(u)	overrides the provider host — sandboxes and tests
WithRetry(n, backoff)	retries network errors and 5xx responses, doubling the pause
WithHeader(k, v)	an extra header on every request
WithUserAgent(ua)	overrides the User-Agent
WithSkipTLSVerify(b)	last resort for a Shaparak host with an incomplete chain

Provider options

gateway/zarinpal

Option	Effect
WithCurrency(c)	pins the unit sent to Zarinpal, for Toman terminals
WithWages(…)	split settlement between IBANs
WithDefaultDescription(s)	used when a request carries no description (Zarinpal requires one)

gateway/zibal

Option	Effect
WithLedger(id)	routes settlement to a specific ledger
WithFeeMode(n)	who pays the fee: 0 merchant, 1 payer, 2 ledger
WithMobileCardCheck(b)	the paying card must belong to the mobile number
WithMultiplexing(…)	split settlement by amount
WithPercentMultiplexing(…)	split settlement by percentage
WithDefaultDescription(s)	fallback description

gateway/vandar

Option	Effect
WithPort(p)	selects a specific IPG port of the business
WithComment(s)	comment shown in the Vandar panel
WithAccessToken(t)	bearer token of the business API, needed by refunds
WithOrderAsFactorNumber(b)	sends the order id as the factor number
WithDefaultDescription(s)	fallback description

gateway/payweb

Option	Effect
WithDefaultComment(s)	fallback comment
WithCardRestriction(b)	forwards the first AllowedCards entry, restricting the payment to that card

gateway/idpay, gateway/bitpay

Option	Effect
WithDefaultDescription(s)	fallback description

gateway/payir

Option	Effect
WithOrderAsFactorNumber(b)	sends the order id as the factor number
WithDefaultDescription(s)	fallback description

gateway/nextpay

Option	Effect
WithCurrency(c)	pins the unit sent to NextPay
WithAutoVerify(b)	lets NextPay verify the transaction itself
WithDefaultDescription(s)	payer description

gateway/payping

Option	Effect
WithPayerIdentity(s)	identity on the receipt; defaults to the request mobile or email
WithDefaultDescription(s)	fallback description

gateway/yekpay

Option	Effect
WithCurrencies(from, to)	ISO 4217 numeric pair; defaults to Rial in, Rial out
WithAddress(s)	payer address, when the contract requires it
WithDefaultDescription(s)	fallback description

gateway/sadad

Option	Effect
WithApplicationName(s)	merchant application name shown to the payer
WithAdditionalData(s)	free text kept with the transaction
WithMobileAsUserID(b)	sends the mobile as Sadad's UserId, offering saved cards

gateway/parsian

Option	Effect
WithMultiplexing(shares…)	switches to the multiplexed service and splits by IBAN
WithSettlementToIBAN(b)	multiplexed service, full amount to Config.IBAN
WithAdditionalData(s)	free text kept with the transaction
WithMobileAsOriginator(b)	sends the mobile as the originator

gateway/irankish

Option	Effect
WithTransactionType(s)	overrides "Purchase" — bills and top-ups use their own values
WithMobileAsCmsID(b)	sends the mobile as the CMS preservation id

gateway/mellat

Option	Effect
WithAdditionalData(s)	free text kept with the transaction
WithPayerID(s)	Mellat payer identifier; "0" when unset
WithoutSettle(b)	skips bpSettleRequest inside Verify — only if you settle separately

gateway/saman

Option	Effect
WithGetMethod(b)	asks SEP to return the payer with a GET instead of a POST form
WithMobile(b)	sends the mobile so the page offers saved cards

gateway/pasargad

Option	Effect
WithAction(s)	overrides the action code; "1003" is a purchase
WithPayerDetails(b)	sends the payer mobile and email
WithoutTransactionCheck(b)	skips CheckTransactionResult before settling

gateway/asanpardakht

Option	Effect
WithServiceType(n)	overrides the service type id; 1 is a purchase
WithPaymentID(s)	bill payment identifier
WithSettlements(…)	split settlement between IBANs
WithAdditionalData(s)	free text kept with the transaction
WithoutSettlement(b)	skips the settlement call inside Verify
WithCancelInsteadOfReverse(b)	Refund calls Cancel — only valid before settlement

gateway/sepehr

Option	Effect
WithPayload(s)	free field echoed back with the callback
WithPayerDetails(b)	sends the mobile and national code

gateway/top

Option	Effect
WithAdditionalInfo(s)	free text kept with the transaction
WithUserID(s)	identifies the payer when no mobile is available
WithSetData(d)	enables the post-confirmation SetData push (once per transaction)

gateway/jibit

Option	Effect
WithWage(rial)	fee added on top of every purchase
WithUserIdentifier(s)	merchant side payer id, so Jibit remembers their cards
WithPayerCardMatching(b)	sends AllowedCards[0], rejecting any other card
WithCancellableRefunds(b)	holds the refund transfer until it is verified
WithAdditionalData(k, v)	key/value echoed in the panel and the reports
WithDefaultDescription(s)	description used when the request carries none

gateway/snapppay

Option	Effect
WithCart(carts…)	fixed basket sent with every purchase
WithCartBuilder(fn)	builds the basket from the purchase request
WithDefaultCategory(s)	product category of the default single-line basket
WithPaymentMethod(s)	overrides the INSTALLMENT product type
WithAutoSettle(b)	off: Verify stops after verification and you call Settle
WithScope(s)	overrides the online-merchant OAuth scope

gateway/torobpay

Option	Effect
WithCart(carts…)	fixed basket sent with every purchase
WithCartBuilder(fn)	builds the basket from the purchase request
WithDefaultCategory(s)	product category of the default single-line basket
WithPaymentMethod(s)	overrides the ONLINE_CREDIT product type

gateway/digipay

Option	Effect
WithTicketType(t)	TypeIPG, TypeCredit, TypeWallet (default), TypeBNPL, TypeCreditCard
WithAgent(s)	the Agent header — WEB, MOBILE, …
WithAPIVersion(s)	the Digipay-Version header
WithPreferredGateway(g)	GatewayWallet or GatewayIPG for a wallet ticket
WithBasket(v) / WithBasketBuilder(fn)	the basketDetailsDto the credit products need
WithSplitDetails(v)	marketplace split settlement

gateway/tara

Option	Effect
WithServiceID(s)	routes the amount to one of the merchant's services
WithInvoiceItems(items…)	fixed invoice sent with every purchase
WithInvoiceBuilder(fn)	builds the invoice lines from the purchase request
WithDefaultGroup(code, title)	club group of the default single-line invoice
WithDefaultUnit(u)	unit of measure code; Tara's default, 5, means "piece"
WithClientIP(ip)	payer IP used when the request carries none

gateway/virtual

Option	Effect
WithDecline(b)	every payment comes back declined
WithRedirectURL(u)	sends the payer to a page of your own instead of the callback
WithFailingVerify(b)	verification always fails, to exercise the recovery path

Writing an option of your own

Provider options are ordinary functions over *core.Options, so nothing stops you from writing one in your own code — for example a logger that redacts:

func withRedactedLogging(l payvand.Logger) payvand.Option {
    return func(o *payvand.Options) { o.Logger = l }
}

Next: Errors · Testing