campay

README

Campay Go SDK

This package provides a go client for interacting with the CamPay API

Installation

campay-go-sdk is compatible with modern Go releases in module mode, with Go installed:

go get github.com/NdoleStudio/campay-go-sdk

Alternatively the same can be achieved if you use import in a package:

import "github.com/NdoleStudio/campay-go-sdk"

Implemented

• Token
  • POST /token: Get access token
• Collect
  • POST /collect: Request Payment
• Withdraw
  • POST /withdraw: Withdraw funds to a mobile money account
• Transaction
  • GET /transaction/{reference}/: Get the status of a transaction
• Utilities
  • POST /api/utilities/airtime/transfer/: Transfers airtime to a mobile number
  • GET /api/utilities/transaction/{reference}/: Get the status of a transaction

Usage

Initializing the Client

An instance of the campay client can be created using New(). The http.Client supplied will be used to make requests to the API.

package main

import (
	"github.com/NdoleStudio/campay-go-sdk"
	"net/http"
)

func main()  {
	client := campay.New(
		campay.WithAPIUsername("" /* campay API Username */),
		campay.WithAPIPassword("" /* campay API Password */),
		campay.WithEnvironment(campay.DevEnvironment),
	)
}

Error handling

All API calls return an error as the last return object. All successful calls will return a nil error.

payload, response, err := campayClient.Token(context.Background())
if err != nil {
  //handle error
}

Token

This handles all API requests whose URL begins with /token/

Get access token

POST /token/: Get access token

token, _, err := campayClient.Token(context.Background())

if err != nil {
    log.Fatal(err)
}

log.Println(token.Token) // e.g eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsInVpZCI6Mn0...

Collect

This handles all API requests whose URL begins with /collect/

POST /collect/: Request Payment

This endpoint is used to request payment from users.

collectResponse, httpResponse, err := campayClient.Collect(context.Background(), campay.CollectOptions{
    Amount: 100,
    Currency: "XAF",
    From: "2376XXXXXXXX",
    Description: "Test",
    ExternalReference: "",
})

if err != nil {
    log.Fatal(err)
}

log.Prinln(collectResponse.Reference) // e.g 26676007-1c31-46d7-9c71-acb031cf0de4

Withdraw

This handles all API requests whose URL begins with /withdraw/

POST /withdraw: Withdraw funds to a mobile money account

Withdraw funds from an app to a mobile money account.

withdrawResponse, response, err := client.Withdraw(context.Background(), &WithdrawParams{
    Amount:            100,
    To:                "2376XXXXXXXX",
    Description:       "Test",
    ExternalReference: nil,
})

if err != nil {
    log.Fatal(err)
}

log.Println(withdrawResponse.Reference) // e.g 26676007-1c31-46d7-9c71-acb031cf0de4

Transaction

This handles all API requests whose URL begins with /transaction/

GET /transaction/{reference}/: Get the status of a transaction

Use this endpoint to check for the status of an initiated transaction.

transaction, httpResponse, err := campayClient.Transaction.Get(
	context.Background(),
	"bcedde9b-62a7-4421-96ac-2e6179552a1a"
)

if err != nil {
    log.Fatal(err)
}

log.Println(transaction.Reference) // e.g 26676007-1c31-46d7-9c71-acb031cf0de4

Utilities

POST /api/utilities/airtime/transfer/: Transfers airtime to a mobile number

transaction, httpResponse, err := client.Utilities.AirtimeTransferSync(context.Background(), &AirtimeTransferParams{
  Amount:            "100",
  To:                "237677777777",
  ExternalReference: "sample-external-ref",
})

if err != nil {
    log.Fatal(err)
}

log.Println(transaction.Reference) // e.g 26676007-1c31-46d7-9c71-acb031cf0de4

GET /api/utilities/transaction/{reference}/: Get the status of a transaction

transaction, httpResponse, err := client.Utilities.AirtimeTransferSync(context.Background(), "" /* Transaction reference */)
if err != nil {
    log.Fatal(err)
}

log.Println(transaction.Status) // e.g "SUCCESSFUL"

Testing

You can run the unit tests for this client from the root directory using the command below:

go test -v

Security

If you discover any security related issues, please email arnoldewin@gmail.com instead of using the GitHub issues.

Credits

• Acho Arnold
• All Contributors

License

This project is licensed under the MIT License - see the LICENSE file for details

Documentation

Index

• Variables
• type AirtimeTransferParams
• type AirtimeTransferResponse
• type CallbackRequest
• type Client
  • func New(options ...ClientOption) *Client
  • func (client *Client) Collect(ctx context.Context, params *CollectParams) (*CollectResponse, *Response, error)
  • func (client *Client) Token(ctx context.Context) (*Token, *Response, error)
  • func (client *Client) ValidateCallback(signature string, webhookKey []byte) error
  • func (client *Client) Withdraw(ctx context.Context, params *WithdrawParams) (*WithdrawResponse, *Response, error)
  • func (client *Client) WithdrawSync(ctx context.Context, params *WithdrawParams) (*Transaction, *Response, error)
• type ClientOption
  • func WithAPIPassword(apiPassword string) ClientOption
  • func WithAPIUsername(apiUsername string) ClientOption
  • func WithEnvironment(environment Environment) ClientOption
  • func WithHTTPClient(httpClient *http.Client) ClientOption
• type CollectParams
• type CollectResponse
• type Environment
  • func (e Environment) String() string
• type Response
  • func (r *Response) Error() error
• type Token
• type Transaction
  • func (transaction *Transaction) IsPending() bool
  • func (transaction *Transaction) IsSuccessfull() bool
• type UtilitiesTransaction
  • func (transaction *UtilitiesTransaction) IsPending() bool
  • func (transaction *UtilitiesTransaction) IsSuccessfull() bool
• type WithdrawParams
• type WithdrawResponse

Variables

var (
	// DevEnvironment is the development Environment
	DevEnvironment = Environment("https://demo.campay.net")

	// ProdEnvironment is the production Environment
	ProdEnvironment = Environment("https://www.campay.net")
)

Types

type AirtimeTransferParams

type AirtimeTransferParams struct {
	Amount            string `json:"amount"`
	To                string `json:"to"`
	ExternalReference string `json:"external_reference"`
}

AirtimeTransferParams are parameters for transferring airtime

type AirtimeTransferResponse

type AirtimeTransferResponse struct {
	Reference string `json:"reference"`
	Status    string `json:"status"`
}

AirtimeTransferResponse is gotten after transferring airtime

type CallbackRequest

type CallbackRequest struct {
	Status            string `json:"status" query:"status"`
	Reference         string `json:"reference" query:"reference"`
	Amount            string `json:"amount" query:"amount"`
	Currency          string `json:"currency" query:"currency"`
	Operator          string `json:"operator" query:"operator"`
	Code              string `json:"code" query:"code"`
	OperatorReference string `json:"operator_reference" query:"operator_reference"`
	Signature         string `json:"signature" query:"signature"`
	ExternalReference string `json:"external_reference" query:"external_reference"`
}

CallbackRequest is the notification request that is sent when a payment is made

type Client

type Client struct {
	Transaction *transactionService
	Utilities   *utilitiesService
	// contains filtered or unexported fields
}

Client is the campay API client. Do not instantiate this client with Client{}. Use the New method instead.

func New

func New(options ...ClientOption) *Client

New creates and returns a new campay.Client from a slice of campay.ClientOption.

func (*Client) Collect

func (client *Client) Collect(ctx context.Context, params *CollectParams) (*CollectResponse, *Response, error)

Collect Requests a Payment POST /collect/ API Doc: https://documenter.getpostman.com/view/2391374/T1LV8PVA#31757962-2e07-486b-a6f4-a7cc7a06d032

func (*Client) Token

func (client *Client) Token(ctx context.Context) (*Token, *Response, error)

Token Gets the access token POST /token/ API Doc: https://documenter.getpostman.com/view/2391374/T1LV8PVA#8803168b-d451-4d65-b8cc-85e385bc3050

func (*Client) ValidateCallback

func (client *Client) ValidateCallback(signature string, webhookKey []byte) error

ValidateCallback checks if the signature was encrypted with the webhook key

func (*Client) Withdraw

func (client *Client) Withdraw(ctx context.Context, params *WithdrawParams) (*WithdrawResponse, *Response, error)

Withdraw funds to a mobile money account POST /withdraw/ API Doc: https://documenter.getpostman.com/view/2391374/T1LV8PVA#885dbde0-b0dd-4514-a0f9-f84fc83df12d

func (*Client) WithdrawSync

func (client *Client) WithdrawSync(ctx context.Context, params *WithdrawParams) (*Transaction, *Response, error)

WithdrawSync transfers money to a mobile number and waits for the transaction to be completed. POST /withdraw/ API Doc: https://documenter.getpostman.com/view/2391374/T1LV8PVA#885dbde0-b0dd-4514-a0f9-f84fc83df12d

type ClientOption

type ClientOption interface {
	// contains filtered or unexported methods
}

ClientOption are options for constructing a client

func WithAPIPassword

func WithAPIPassword(apiPassword string) ClientOption

WithAPIPassword sets the campay API password

func WithAPIUsername

func WithAPIUsername(apiUsername string) ClientOption

WithAPIUsername sets the campay API username

func WithEnvironment

func WithEnvironment(environment Environment) ClientOption

WithEnvironment sets the campay endpoint for API requests By default, ProdEnvironment is used.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient sets the underlying HTTP client used for requests. By default, http.DefaultClient is used.

type CollectParams

type CollectParams struct {
	Amount            uint   `json:"amount"`
	Currency          string `json:"currency"`
	From              string `json:"from"`
	Description       string `json:"description"`
	ExternalReference string `json:"external_reference"`
}

CollectParams is the details needed to initialize a payment

type CollectResponse

type CollectResponse struct {
	Reference string `json:"reference"`
	UssdCode  string `json:"ussd_code"`
	Operator  string `json:"operator"`
}

CollectResponse is the response after calling the collect endpoint

type Environment

type Environment string

Environment is the URL of the campay environment

func (Environment) String

func (e Environment) String() string

type Response

type Response struct {
	HTTPResponse *http.Response
	Body         *[]byte
}

Response captures the http response

func (*Response) Error

func (r *Response) Error() error

Error ensures that the response can be decoded into a string inc ase it's an error response

type Token

type Token struct {
	Token     string `json:"token"`
	ExpiresIn int64  `json:"expires_in"`
}

Token is the authentication token

type Transaction

type Transaction struct {
	Reference         string  `json:"reference"`
	Status            string  `json:"status"`
	Amount            float64 `json:"amount"`
	Currency          string  `json:"currency"`
	Operator          string  `json:"operator"`
	Code              string  `json:"code"`
	OperatorReference string  `json:"operator_reference"`
}

Transaction contains details of an initiated transaction

func (*Transaction) IsPending

func (transaction *Transaction) IsPending() bool

IsPending checks if a transaction is pending

func (*Transaction) IsSuccessfull

func (transaction *Transaction) IsSuccessfull() bool

IsSuccessfull checks if a transaction is successfull

type UtilitiesTransaction

type UtilitiesTransaction struct {
	Reference         string  `json:"reference"`
	ExternalReference string  `json:"external_reference"`
	Status            string  `json:"status"`
	Amount            float64 `json:"amount"`
	Currency          string  `json:"currency"`
	Operator          string  `json:"operator"`
	Code              string  `json:"code"`
	Type              string  `json:"type"`
	Reason            string  `json:"reason"`
}

UtilitiesTransaction represent a utility transaction

func (*UtilitiesTransaction) IsPending

func (transaction *UtilitiesTransaction) IsPending() bool

IsPending checks if a transaction is pending

func (*UtilitiesTransaction) IsSuccessfull

func (transaction *UtilitiesTransaction) IsSuccessfull() bool

IsSuccessfull checks if a transaction is successfull

type WithdrawParams

type WithdrawParams struct {
	Amount            uint    `json:"amount"`
	To                string  `json:"to"`
	Description       string  `json:"description"`
	ExternalReference *string `json:"external_reference,omitempty"`
}

WithdrawParams are the details needed to perform a withdrawal

type WithdrawResponse

type WithdrawResponse struct {
	Reference string `json:"reference"`
	Status    string `json:"status"`
}

WithdrawResponse is the response after doing a withdrawal request