irankish

README

IranKish Payment Gateway API for Go

The package is used for handling payments through Iranian IranKish payment gateway.

Based on IPG_TechnicalGuide.V9.pdf

For older version with SOAP check soap branch.

Install

go get -u github.com/aliforever/go-irankish-api

Usage

Variables:

terminalID := "" // <- Place your terminal ID 
acceptorID := "" // <- Place your acceptor ID
passphrase := "" // <- Place your Passphrase
publicKey := "" // <- Place your Public Key

ik, err := irankish.New(terminalID, acceptorID, passphrase, publicKey)
if err != nil {
    panic(err)
}

• MakeToken for normal Purchase:

paymentID := ""
requestID := ""
amount := 0
revertUri := ""

token, err := ik.MakePurchaseToken(paymentID, requestID, amount, revertUri)
if err != nil {
	panic(err)
}

fmt.Println(token)

After making token you can get a simple redirecting form as a html to redirect users to the gateway:

htmlForm := token.RedirectForm() // <- Token Received from Make Token Method

Also, you can either handle incoming POST requests from the gateway yourself or listen to package's incoming callbacks. Here's an example to listen and verify payments using package's callback

http.HandleFunc("/payment_callback", ik.CallbackHandler) // Registers a http handler for callbacks
go http.ListenAndServe(":8001", nil) // Run your http server

for request := range ik.IncomingCallbacks() {
    input, err := request.ParseUserInput()
    if err != nil {
        request.WriteResponse(http.StatusBadRequest, []byte(err.Error()))
        return
    }
    
    fmt.Println(fmt.Sprintf("%+v", input))
    
    if input.RetrievalReferenceNumber != "" && input.SystemTraceAuditNumber != "" {
        result, err := ik.VerifyPurchase(input.Token, input.RetrievalReferenceNumber, input.SystemTraceAuditNumber)
        if err != nil {
            request.WriteResponse(http.StatusBadRequest, []byte(err.Error()))
            fmt.Println(err)
            continue
        }
	
        fmt.Println(result)
    }
    
    request.WriteResponse(http.StatusOK, []byte("ok"))
}

-- Make sure to write the response or it will hang on the goroutine

• VerifyPayment:

token := ""
referenceNumber := ""
auditNumber := ""

result, err := ik.VerifyPurchase(token, referenceNumber, auditNumber)
if err != nil {
    request.WriteResponse(http.StatusBadRequest, []byte(err.Error()))
    panic(err)
}

fmt.Println(result)

Documentation

Index

• Constants
• func AddCallbackUrl(serverAddress, endpoint, callbackUrl string) error
• func NewAsanShp(prepaymentAmount, loanAmount, loanCount int64) asanShp
• func NewBillInfo(billID string, billPaymentID string) billInfo
• func NewMultiplexParameters() multiplexParameters
• type AdditionalParameter
• type IncomingRequest
  • func (i *IncomingRequest) ParseUserInput() (*UserInput, error)
  • func (i *IncomingRequest) WriteResponse(statusCode int, data []byte)
• type InquiryResult
• type IranKish
  • func New(terminalID, acceptorID, passphrase, publicKey string, logger Logger) (*IranKish, error)
  • func NewWithProxyHost(terminalID, acceptorID, passphrase, publicKey string, proxyAddress string, ...) (*IranKish, error)
  • func (i *IranKish) CallbackHandler(wr http.ResponseWriter, r *http.Request)
  • func (i *IranKish) IncomingCallbacks() <-chan IncomingRequest
  • func (i *IranKish) MakePurchaseToken(paymentID, requestID string, amount int64, revertUri string, ...) (*MakeTokenResult, error)
  • func (i *IranKish) SingleInquiryByReferenceNumber(referenceNumber string) (*InquiryResult, error)
  • func (i *IranKish) SingleInquiryByToken(token string) (*InquiryResult, error)
  • func (i *IranKish) VerifyPurchase(token, referenceNumber, auditNumber string) (*TransactionResult, error)
• type Logger
• type MakeTokenResult
  • func (m *MakeTokenResult) RedirectForm() string
• type Proxy
  • func NewProxy(httpUri string, logger Logger) *Proxy
  • func NewProxyWithMux(httpUri string, mux *http.ServeMux, logger Logger) *Proxy
  • func (p *Proxy) EnableCallbackUrls() *Proxy
  • func (p *Proxy) SetHomePageHandler(handler func(writer http.ResponseWriter, r *http.Request)) *Proxy
  • func (p *Proxy) SetTargetUrl(target *url.URL) *Proxy
  • func (p *Proxy) Start() error
• type Response
• type TransactionResult
• type UserInput

Constants

const (
	IranKishShaparakUrl = "https://ikc.shaparak.ir"
	TokenUrl            = "/api/v3/tokenization/make"
	RedirectUrl         = IranKishShaparakUrl + "/iuiv3/IPG/Index/"
	ConfirmationUrl     = "/api/v3/confirmation/purchase"
	InquiryUrl          = "/api/v3/inquiry/single"
)

const (
	TransactionTypePurchase  transactionType = "Purchase"
	TransactionTypeBill      transactionType = "Bill"
	TransactionTypeAsnShpWPP transactionType = "AsanShpWPP"
)

Functions

func AddCallbackUrl

func AddCallbackUrl(serverAddress, endpoint, callbackUrl string) error

func NewAsanShp

func NewAsanShp(prepaymentAmount, loanAmount, loanCount int64) asanShp

func NewBillInfo

func NewBillInfo(billID string, billPaymentID string) billInfo

func NewMultiplexParameters

func NewMultiplexParameters() multiplexParameters

Types

type AdditionalParameter

type AdditionalParameter struct {
	Key   string `json:"Key"`
	Value string `json:"Value"`
}

type IncomingRequest

type IncomingRequest struct {
	Request *http.Request

	Done chan bool
	// contains filtered or unexported fields
}

func (*IncomingRequest) ParseUserInput

func (i *IncomingRequest) ParseUserInput() (*UserInput, error)

func (*IncomingRequest) WriteResponse

func (i *IncomingRequest) WriteResponse(statusCode int, data []byte)

type InquiryResult

type InquiryResult struct {
	ResponseCode             string          `json:"responseCode"`
	Description              string          `json:"description"`
	Status                   bool            `json:"status"`
	Result                   json.RawMessage `json:"result"`
	TokenIdentity            string          `json:"tokenIdentity"`
	TerminalID               string          `json:"terminalId"`
	AcceptorID               string          `json:"acceptorId"`
	RetrievalReferenceNumber string          `json:"retrievalReferenceNumber"`
	SystemTraceAuditNumber   string          `json:"systemTraceAuditNumber"`
	Amount                   int64           `json:"amount"`
	TransactionDate          int64           `json:"transactionDate"`
	TransactionTime          int64           `json:"transactionTime"`
	RequestID                string          `json:"requestId"`
	PaymentID                string          `json:"paymentId"`
	IsMultiplex              bool            `json:"isMultiplex"`
	IsVerified               bool            `json:"isVerified"`
	IsReversed               bool            `json:"isReversed"`
	MaskedPan                string          `json:"maskedPan"`
	SHA256OfPan              string          `json:"sha256OfPan"`
	TransactionType          transactionType `json:"transactionType"`
}

type IranKish

type IranKish struct {
	// contains filtered or unexported fields
}

func New

func New(terminalID, acceptorID, passphrase, publicKey string, logger Logger) (*IranKish, error)

func NewWithProxyHost

func NewWithProxyHost(
	terminalID,
	acceptorID,
	passphrase,
	publicKey string,
	proxyAddress string,
	logger Logger,
) (*IranKish, error)

func (*IranKish) CallbackHandler

func (i *IranKish) CallbackHandler(wr http.ResponseWriter, r *http.Request)

func (*IranKish) IncomingCallbacks

func (i *IranKish) IncomingCallbacks() <-chan IncomingRequest

func (*IranKish) MakePurchaseToken

func (i *IranKish) MakePurchaseToken(
	paymentID,
	requestID string,
	amount int64,
	revertUri string,
	params ...AdditionalParameter,
) (*MakeTokenResult, error)

func (*IranKish) SingleInquiryByReferenceNumber

func (i *IranKish) SingleInquiryByReferenceNumber(referenceNumber string) (*InquiryResult, error)

func (*IranKish) SingleInquiryByToken

func (i *IranKish) SingleInquiryByToken(token string) (*InquiryResult, error)

func (*IranKish) VerifyPurchase

func (i *IranKish) VerifyPurchase(token, referenceNumber, auditNumber string) (*TransactionResult, error)

type Logger

type Logger interface {
	Println(v ...any)
}

type MakeTokenResult

type MakeTokenResult struct {
	Token             string          `json:"token"`
	InitiateTimestamp int64           `json:"initiateTimeStamp"`
	ExpiryTimestamp   int64           `json:"expiryTimeStamp"`
	TransactionType   transactionType `json:"transactionType"`
	BillInfo          interface{}     `json:"billInfo"`
	// contains filtered or unexported fields
}

func (*MakeTokenResult) RedirectForm

func (m *MakeTokenResult) RedirectForm() string

type Proxy

type Proxy struct {
	// contains filtered or unexported fields
}

Proxy is to run a http proxy server to redirect requests

This is because there's IP limit on payment gateways
Each payment gateway is only allowed to be accessed by specific ip addresses
You can run this proxy server in an allowed IP address and initiate your gateway using WithProxy

func NewProxy

func NewProxy(httpUri string, logger Logger) *Proxy

func NewProxyWithMux

func NewProxyWithMux(httpUri string, mux *http.ServeMux, logger Logger) *Proxy

func (*Proxy) EnableCallbackUrls

func (p *Proxy) EnableCallbackUrls() *Proxy

EnableCallbackUrls by calling this method /add_callback_url endpoint will be activated

This is to proxy back callback (revert url) requests to specified endpoints

func (*Proxy) SetHomePageHandler

func (p *Proxy) SetHomePageHandler(handler func(writer http.ResponseWriter, r *http.Request)) *Proxy

func (*Proxy) SetTargetUrl

func (p *Proxy) SetTargetUrl(target *url.URL) *Proxy

SetTargetUrl is used to replace payment gateway's base url

func (*Proxy) Start

func (p *Proxy) Start() error

type Response

type Response struct {
	ResponseCode string          `json:"responseCode"`
	Description  string          `json:"description"`
	Status       bool            `json:"status"`
	Result       json.RawMessage `json:"result"`
}

type TransactionResult

type TransactionResult struct {
	ResponseCode             string `json:"responseCode"`
	SystemTraceAuditNumber   string `json:"systemTraceAuditNumber"`
	RetrievalReferenceNumber string `json:"retrievalReferenceNumber"`
	TransactionDate          int64  `json:"transactionDate"`
	TransactionTime          int64  `json:"transactionTime"`
	ProcessCode              string `json:"processCode"`
	BillType                 string `json:"billType"`
	BillId                   string `json:"billId"`
	PaymentId                string `json:"paymentId"`
	Amount                   string `json:"amount"`
	DuplicateVerify          bool   `json:"duplicateVerify"` // indicates if payment is already verified
}

type UserInput

type UserInput struct {
	Token                    string
	AcceptorID               string
	MerchantID               string
	ResponseCode             string
	PaymentID                string
	RequestID                string
	Sha256OfPan              string
	RetrievalReferenceNumber string
	SystemTraceAuditNumber   string
	Amount                   string
	MaskedPan                interface{}
	Ttl                      string
	Sha1OfPan                interface{}
}