maib

README

Go MAIB ECommerce SDK

Copyright (C) 2023 Nejintev Nicolai

This library is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this library.  If not, see <https://www.gnu.org/licenses/>.

This library provides tools to interact with MAIB ECommerce in a type safe way.

This library is UNOFFICIAL, inspired by public Integration Guide and implementations shared by MAIB.

Unlike other implementations, you don't need to run any openssl commands to change the certificate's format. Only the default .pfx pkcs#12 file is needed.

Installation

Inside your Go module, run

go get github.com/NikSays/go-maib-ecomm

Documentation

Documentation and examples are available at Go Reference.

Testing

If you need to regenerate the testing certificates, run the ./genCrt.sh script in the ./testdata folder.

To test the package just run go test ./... .

Documentation

Overview

Package maib provides tools to interact with the MAIB ECommerce system in a type safe way.

Requirements

To use this module you should:

• Understand how MAIB ECommerce works
• Have a .pfx certificate
• Register as a merchant in MAIB

Usage

1. Use NewClient to set up a Client that communicates with the MAIB ECommerce system.
2. Send a Request with Client.Send (The requests described in the ECommerce documentation are implemented in the requests package).
3. Decode the returned map into a result struct with requests.DecodeResult.

Error Handling

Use errors.As to check the type and the contents of the errors returned by Client.Send:

• types.ErrMalformedPayload is returned before sending the request if it has failed validation.
• types.ErrMAIB is returned if the response has a non-200 code, or its body starts with "error:".
• types.ErrParse is returned if the response has an invalid structure, or a response field has an unexpected datatype.

See the example to get an understanding of the full flow.

Example

// In this example we will
// * Create a Client
// * Execute an SMS transaction and decode the response
// * Check the created transaction's status
// Errors are ignored for brevity, please handle them in your code.

// Create new client to send requests to MAIB ECommerce
client, _ := NewClient(Config{
	PFXPath:                 "cert.pfx",
	Passphrase:              "p4ssphr4s3",
	MerchantHandlerEndpoint: "https://example.org/handler",
})

// Execute an SMS transaction (-v) for 10 Euro.
// Equivalent to this POST request:
// command=v&amount=1000&currency=978&language=en&client_ip_addr=127.0.0.1&description=10+EUR+will+be+charged
res, _ := client.Send(requests.RegisterTransaction{
	TransactionType: requests.RegisterTransactionSMS,
	Amount:          1000,
	Currency:        types.CurrencyEUR,
	ClientIPAddress: "127.0.0.1",
	Description:     "10 EUR will be charged",
	Language:        types.LanguageEnglish,
})

// Decode response map into RegisterTransactionResult struct,
// to get the ID of the created transaction.
newTransaction, _ := requests.DecodeResponse[requests.RegisterTransactionResult](res)

// Send a Transaction Status request.
// Equivalent to this POST request:
// command=c&trans_id=<TransactionID>&client_ip_addr=127.0.0.1
res, _ = client.Send(requests.TransactionStatus{
	TransactionID:   newTransaction.TransactionID,
	ClientIPAddress: "127.0.0.1",
})

// Decode response map into TransactionStatusResult struct,
// to get the transaction result.
status, _ := requests.DecodeResponse[requests.TransactionStatusResult](res)

// Print the result of the transaction
fmt.Println(status.Result)

Index

• type Client
  • func NewClient(config Config) (*Client, error)
  • func (c *Client) Send(req Request) (map[string]any, error)
• type Config
• type Request
• type Sender

Examples

• Package

Types

type Client

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

Client is a Sender that uses HTTPS with mutual TLS to communicate with the MAIB ECommerce system. It is safe for concurrent use.

Must be initiated with NewClient.

func NewClient

func NewClient(config Config) (*Client, error)

NewClient reads and parses the PFX certificate file and returns a *Client that uses the certificate for mutual TLS.

func (*Client) Send

func (c *Client) Send(req Request) (map[string]any, error)

Send validates a Request, and sends it to the ECommerce system. The value returned on success can be parsed into a result struct using requests.DecodeResponse

type Config

type Config struct {
	// Path to .pfx certificate issued by MAIB.
	PFXPath string
	// Passphrase to the certificate.
	Passphrase string
	// API communication URL issued by MAIB.
	MerchantHandlerEndpoint string
}

Config is the configuration required to set up a Client.

type Request

type Request interface {
	// Values returns the payload as a URL value map,
	// that can be encoded into a querystring to be sent to the ECommerce system.
	Values() (url.Values, error)

	// Validate goes through the fields of the payload, and returns an error
	// if any one of them does not fit the requirements.
	Validate() error
}

Request is a payload that can be sent to the ECommerce system.

type Sender

type Sender interface {
	Send(req Request) (map[string]any, error)
}

Sender allows sending requests to the MAIB ECommerce system.

This interface is makes it easy to substitute Client with a different behavior. E.g. using a mock for testing.

Send validates the Request before sending it, and checks the response for errors. The response is then parsed into a map that can be decoded into a result struct using requests.DecodeResponse.