epoint

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 22, 2026 License: MIT Imports: 13 Imported by: 0

README

epoint-go

Go client for the epoint.az payment gateway.

Covers all 30 documented endpoints: payments, saved cards, refunds and payouts, split payments, pre-authorisation, installments, wallets, Apple Pay and Google Pay, invoices, and B2B transfers. No dependencies outside the standard library.

go get github.com/martian56/epoint-go

Quick start

package main

import (
	"context"
	"fmt"

	epoint "github.com/martian56/epoint-go"
)

func main() {
	client := epoint.New("i000000001", "your-private-key")

	payment, err := client.CreatePayment(context.Background(), 30.75, "order-1", &epoint.PaymentOptions{
		Description: "Test order",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(payment.RedirectURL())
}

Send the customer to payment.RedirectURL(). When they finish, epoint calls your result URL. Verify it before trusting it:

callback, err := client.VerifyCallback(data, signature)
if err != nil {
	http.Error(w, "invalid", http.StatusBadRequest)
	return
}
if callback.OK() {
	fulfil(callback.OrderID, callback.Transaction)
}

Configuration

client := epoint.New("i000000001", "your-private-key",
	epoint.WithBaseURL("https://epoint.az"),
	epoint.WithLanguage(string(epoint.LanguageAZ)),
	epoint.WithCurrency(string(epoint.CurrencyAZN)),
	epoint.WithRedirectURLs("https://shop.example/thanks", "https://shop.example/failed"),
	epoint.WithHTTPClient(customClient),
)

Or read from the environment with epoint.FromEnv(), which uses EPOINT_PUBLIC_KEY, EPOINT_PRIVATE_KEY, EPOINT_BASE_URL, EPOINT_LANGUAGE, EPOINT_SUCCESS_REDIRECT_URL and EPOINT_FAILED_REDIRECT_URL. Language and currency are set on the client and can be overridden per call through the options argument. Pass nil for the options when you do not need any.

Testing against the sandbox

There is a local sandbox that behaves like the real gateway, so you can build and test without a merchant account or real money:

client := epoint.New("i000000001", "sandbox_private_key_0000000001",
	epoint.WithBaseURL("http://localhost:8181"))

See epoint-sandbox. Switching to production means changing the base URL and the keys, nothing else.

Responses

Most methods return (*Response, error). Known fields have accessors, anything else is read through Get, String, or the raw map:

status, err := client.GetStatus(ctx, "te0000000001")
status.Status()          // "success"
status.OK()              // true
status.String("rrn")     // bank reference number
status.Raw               // the full response map

A declined payment is not an error. GetStatus returns normally with a status of epoint.StatusFailed, which you read through OK(). GetInstallmentPlans returns a slice and ListWallets returns a map.

Enums

Every value the API uses has a typed constant. They come from the sandbox's own definitions, so they match what production sends. Each type is a string, so a plain string still converts.

client := epoint.New(publicKey, privateKey,
	epoint.WithLanguage(string(epoint.LanguageEN)),
	epoint.WithCurrency(string(epoint.CurrencyUSD)),
)

status, err := client.GetStatus(ctx, transaction)
if err == nil && epoint.Status(status.Status()).Settled() {
	fulfil(orderID)
}
Type Values
Status new, success, failed, error, returned, server_error
CardStatus new, active, pending, rejected, expired, session_expired
InvoiceStatus waiting_for_payment, paid, canceled
B2BStatus PENDING, PROCESSING, SUCCESS, FAILED
OperationCode 001 card registration, 100 payment, 200 registration with payment
Language az, en, ru
Currency AZN, USD, EUR, RUB

Currency is not uniform across the API. Checkout takes all four, but split, pre-auth, refund, reverse, payout and wallet take AZN and nothing else. SupportedCurrencies and AZNOnly hold those two sets.

Status.Settled() reports whether the money moved and CardStatus.Usable() whether a card can be charged.

Methods

Group Methods
Checkout CreatePayment, CreatePaymentRequest, CreateAmexPayment, ChangePaymentSum
Status GetStatus, GetCardStatus, GetBankTransfer
Split CreateSplitPayment, SplitChargeSavedCard
Pre-auth Reserve, Capture
Saved cards RegisterCard, RegisterCardAndPay, ChargeSavedCard
Money back Refund, Reverse
Installments GetInstallmentPlans, PayByInstallment
Wallets ListWallets, PayWithWallet
Apple Pay, Google Pay CreateWidget
Invoices CreateInvoice, UpdateInvoice, GetInvoice, ListInvoices, SendInvoiceSMS, SendInvoiceEmail
B2B CreateBankTransfer, GetBankTransfer
Health Heartbeat

Errors

Use errors.As to inspect what went wrong:

Type Returned when
*GatewayError epoint returned status: error. Has Code, Status, Message, Payload.
*TransportError Network failure, or a non-JSON or 4xx/5xx response. Has StatusCode.
*SignatureError A callback's signature did not match, or its data would not decode 
var gwErr *epoint.GatewayError
if errors.As(err, &gwErr) {
	log.Printf("declined with code %s", gwErr.Code)
}

Signatures

Epoint signs with base64(sha1_raw(private_key + data + private_key)). The client builds and verifies these for you. The digest is the raw 20 bytes, not the hex string, which is where most hand-rolled integrations go wrong.

Not affiliated with Epoint

An independent client for developers integrating with epoint.az.

MIT licensed.

Documentation

Overview

Package epoint is a Go client for the epoint.az payment gateway.

It covers all 30 documented endpoints: payments, saved cards, refunds and payouts, split payments, pre-authorisation, installments, wallets, Apple Pay and Google Pay, invoices, and B2B transfers.

Create a client and start a payment: 

client := epoint.New("i000000001", "your-private-key")
payment, err := client.CreatePayment(ctx, 30.75, "order-1", nil)
if err != nil {
	return err
}
// send the customer to payment.RedirectURL()

Point BaseURL at the local sandbox to build and test without a merchant account: https://github.com/martian56/epoint-sandbox

Index

Constants

This section is empty.

Variables

View Source 
var AZNOnly = []Currency{CurrencyAZN}

Split, pre-auth, refund, reverse, payout and wallet take AZN and nothing else.

View Source 
var SupportedCurrencies = []Currency{CurrencyAZN, CurrencyUSD, CurrencyEUR, CurrencyRUB}

SupportedCurrencies are the ones checkout takes.

Functions

This section is empty.

Types

type B2BStatus added in v0.2.0 

type B2BStatus string

B2BStatus is the state of a business to business payment. 

const (
	B2BStatusPending    B2BStatus = "PENDING"
	B2BStatusProcessing B2BStatus = "PROCESSING"
	B2BStatusSuccess    B2BStatus = "SUCCESS"
	B2BStatusFailed     B2BStatus = "FAILED"
)

type BankTransfer 

type BankTransfer struct {
	OrderID        string
	Amount         float64
	Description    string
	IBAN           string
	Name           string
	TIN            string
	BankCode       string
	BankName       string
	Email          string
	Address        string
	AdditionalInfo string
	WebhookURL     string
}

type Callback 

type Callback struct {
	OrderID         string
	Status          string
	Code            string
	Message         string
	Transaction     string
	BankTransaction string
	OperationCode   string
	RRN             string
	CardMask        string
	CardName        string
	Amount          float64
	OtherAttr       any
	Raw             map[string]any
}

func VerifyCallback 

func VerifyCallback(privateKey, data, signature string) (*Callback, error)

func (*Callback) OK 

func (c *Callback) OK() bool

type CardStatus added in v0.2.0 

type CardStatus string

CardStatus is the state of a saved card. 

const (
	CardStatusNew            CardStatus = "new"
	CardStatusActive         CardStatus = "active"
	CardStatusPending        CardStatus = "pending"
	CardStatusRejected       CardStatus = "rejected"
	CardStatusExpired        CardStatus = "expired"
	CardStatusSessionExpired CardStatus = "session_expired"
)

func (CardStatus) Usable added in v0.2.0 

func (c CardStatus) Usable() bool

Usable reports whether the card can be charged.

type ChargeOptions 

type ChargeOptions struct {
	Description string
	Language    string
	Currency    string
}

type Client 

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

func FromEnv 

func FromEnv(opts ...Option) (*Client, error)

func New 

func New(publicKey, privateKey string, opts ...Option) *Client

func (*Client) Capture 

func (c *Client) Capture(ctx context.Context, transaction string, amount float64) (*Response, error)

func (*Client) ChangePaymentSum 

func (c *Client) ChangePaymentSum(ctx context.Context, amount float64, orderID string, opts *PaymentOptions) (*Response, error)

func (*Client) ChargeSavedCard 

func (c *Client) ChargeSavedCard(ctx context.Context, cardID string, amount float64, orderID string, opts *ChargeOptions) (*Response, error)

func (*Client) CreateAmexPayment 

func (c *Client) CreateAmexPayment(ctx context.Context, amount float64, orderID string, opts *PaymentOptions) (*Response, error)

func (*Client) CreateBankTransfer 

func (c *Client) CreateBankTransfer(ctx context.Context, transfer BankTransfer) (*Response, error)

func (*Client) CreateInvoice 

func (c *Client) CreateInvoice(ctx context.Context, amount float64, periodFrom, periodTo string, opts *InvoiceOptions) (*Response, error)

func (*Client) CreatePayment 

func (c *Client) CreatePayment(ctx context.Context, amount float64, orderID string, opts *PaymentOptions) (*Response, error)

func (*Client) CreatePaymentRequest 

func (c *Client) CreatePaymentRequest(ctx context.Context, amount float64, orderID string, opts *PaymentOptions) (*Response, error)

func (*Client) CreateSplitPayment 

func (c *Client) CreateSplitPayment(ctx context.Context, amount float64, orderID, splitAccount string, splitAmount float64, opts *PaymentOptions) (*Response, error)

func (*Client) CreateWidget 

func (c *Client) CreateWidget(ctx context.Context, amount float64, orderID, description string) (*Response, error)

func (*Client) GetBankTransfer 

func (c *Client) GetBankTransfer(ctx context.Context, orderID string) (*Response, error)

func (*Client) GetCardStatus 

func (c *Client) GetCardStatus(ctx context.Context, cardID string) (*Response, error)

func (*Client) GetInstallmentPlans 

func (c *Client) GetInstallmentPlans(ctx context.Context, orderID string, opts *InstallmentQueryOptions) ([]map[string]any, error)

func (*Client) GetInvoice 

func (c *Client) GetInvoice(ctx context.Context, invoiceID int) (*Response, error)

func (*Client) GetStatus 

func (c *Client) GetStatus(ctx context.Context, transaction string) (*Response, error)

func (*Client) Heartbeat 

func (c *Client) Heartbeat(ctx context.Context) (*Response, error)

func (*Client) ListInvoices 

func (c *Client) ListInvoices(ctx context.Context, kind, order string) (*Response, error)

func (*Client) ListWallets 

func (c *Client) ListWallets(ctx context.Context) (map[string]string, error)

func (*Client) PayByInstallment 

func (c *Client) PayByInstallment(ctx context.Context, amount float64, orderID, installmentCardID string, installmentMonth int, opts *PaymentOptions) (*Response, error)

func (*Client) PayWithWallet 

func (c *Client) PayWithWallet(ctx context.Context, walletID string, amount float64, orderID string, opts *ChargeOptions) (*Response, error)

func (*Client) Refund 

func (c *Client) Refund(ctx context.Context, cardID string, amount float64, orderID string, opts *ChargeOptions) (*Response, error)

func (*Client) RegisterCard 

func (c *Client) RegisterCard(ctx context.Context, opts *RegisterCardOptions) (*Response, error)

func (*Client) RegisterCardAndPay 

func (c *Client) RegisterCardAndPay(ctx context.Context, amount float64, orderID string, opts *PaymentOptions) (*Response, error)

func (*Client) Reserve 

func (c *Client) Reserve(ctx context.Context, amount float64, orderID string, opts *PaymentOptions) (*Response, error)

func (*Client) Reverse 

func (c *Client) Reverse(ctx context.Context, transaction string, opts *ReverseOptions) (*Response, error)

func (*Client) SendInvoiceEmail 

func (c *Client) SendInvoiceEmail(ctx context.Context, invoiceID int, email string) (*Response, error)

func (*Client) SendInvoiceSMS 

func (c *Client) SendInvoiceSMS(ctx context.Context, invoiceID int, phone string) (*Response, error)

func (*Client) SplitChargeSavedCard 

func (c *Client) SplitChargeSavedCard(ctx context.Context, cardID string, amount float64, orderID, splitAccount string, splitAmount float64, opts *ChargeOptions) (*Response, error)

func (*Client) UpdateInvoice 

func (c *Client) UpdateInvoice(ctx context.Context, invoiceID int, amount float64, periodFrom, periodTo string, opts *InvoiceOptions) (*Response, error)

func (*Client) VerifyCallback 

func (c *Client) VerifyCallback(data, signature string) (*Callback, error)

type Currency added in v0.2.0 

type Currency string

Currency is the payment currency. 

const (
	CurrencyAZN Currency = "AZN"
	CurrencyUSD Currency = "USD"
	CurrencyEUR Currency = "EUR"
	CurrencyRUB Currency = "RUB"
)

type GatewayError 

type GatewayError struct {
	Message string
	Code    string
	Status  string
	Payload map[string]any
}

func (*GatewayError) Error 

func (e *GatewayError) Error() string

type InstallmentQueryOptions 

type InstallmentQueryOptions struct {
	Amount   *float64
	Language string
	Currency string
}

type InvoiceOptions 

type InvoiceOptions struct {
	Name             string
	Description      string
	Phone            string
	Email            string
	TIN              string
	ContractNumber   string
	MerchantOrderID  string
	Hidden           bool
	SaveAsTemplate   bool
	AllowInstallment bool
}

type InvoiceStatus added in v0.2.0 

type InvoiceStatus string

InvoiceStatus is the state of an invoice. 

const (
	InvoiceStatusWaiting  InvoiceStatus = "waiting_for_payment"
	InvoiceStatusPaid     InvoiceStatus = "paid"
	InvoiceStatusCanceled InvoiceStatus = "canceled"
)

type Language added in v0.2.0 

type Language string

Language is the language of the hosted checkout page. 

const (
	LanguageAZ Language = "az"
	LanguageEN Language = "en"
	LanguageRU Language = "ru"
)

type OperationCode added in v0.2.0 

type OperationCode string

OperationCode says what the transaction did, as it comes back on a callback. 

const (
	OperationCardRegistration        OperationCode = "001"
	OperationPayment                 OperationCode = "100"
	OperationRegistrationWithPayment OperationCode = "200"
)

type Option 

type Option func(*Client)

func WithBaseURL 

func WithBaseURL(baseURL string) Option

func WithCurrency 

func WithCurrency(currency string) Option

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) Option

func WithLanguage 

func WithLanguage(language string) Option

func WithRedirectURLs 

func WithRedirectURLs(success, failure string) Option

type PaymentOptions 

type PaymentOptions struct {
	Description        string
	Language           string
	Currency           string
	SuccessRedirectURL string
	ErrorRedirectURL   string
	OtherAttr          any
}

type RegisterCardOptions 

type RegisterCardOptions struct {
	Description string
	Language    string
	ForPayouts  bool
}

type Response 

type Response struct {
	Raw map[string]any
}

func (*Response) Get 

func (r *Response) Get(key string) any

func (*Response) Message 

func (r *Response) Message() string

func (*Response) OK 

func (r *Response) OK() bool

func (*Response) RedirectURL 

func (r *Response) RedirectURL() string

func (*Response) Status 

func (r *Response) Status() string

func (*Response) String 

func (r *Response) String(key string) string

func (*Response) Transaction 

func (r *Response) Transaction() string

type ReverseOptions 

type ReverseOptions struct {
	Amount   *float64
	Language string
	Currency string
}

type SignatureError 

type SignatureError struct {
	Message string
}

func (*SignatureError) Error 

func (e *SignatureError) Error() string

type Status added in v0.2.0 

type Status string

Status is the status on a response or a callback. 

const (
	StatusNew         Status = "new"
	StatusSuccess     Status = "success"
	StatusFailed      Status = "failed"
	StatusError       Status = "error"
	StatusReturned    Status = "returned"
	StatusServerError Status = "server_error"
)

func (Status) Settled added in v0.2.0 

func (s Status) Settled() bool

Settled reports whether the status means the money moved.

type TransportError 

type TransportError struct {
	Message    string
	StatusCode int
}

func (*TransportError) Error 

func (e *TransportError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.