kopokopo

Documentation

Overview

Package kopokopo Webhooks are a means of getting notified of events in the Kopo Kopo application. To receive webhooks, you need to create a webhook subscription.

Index

• Variables
• type AddPAYRecipient
  • func (apr AddPAYRecipient) Validate() error
• type Amount
• type Attribute
• type BuyGoodsTrans
  • func (bgt BuyGoodsTrans) Validate() error
• type Config
• type ContentType
• type CreatePaymentReq
  • func (cpr CreatePaymentReq) Validate() error
• type CreateWebhookReq
  • func (cwr CreateWebhookReq) Validate() error
• type Credentials
• type CustomerEvent
• type CustomerReq
• type CustomerResource
• type Destination
• type DestinationResource
• type Disbursements
• type Event
• type IncomingPaymentEvent
• type Links
• type PaymentRecipient
• type ProcessIncommingPaymentReq
• type ReceiveMpesaReq
  • func (rmr ReceiveMpesaReq) Validate() error
• type Resource
• type SDK
  • func NewSDK(conf Config) SDK
• type Subscriber

Variables

var (
	// ErrEmptyToken indicates missing or invalid bearer token.
	ErrEmptyToken = errors.New("empty token")

	// ErrInvalidPaymentChannel indicates missing or invalid payment channel.
	ErrInvalidPaymentChannel = errors.New("invalid payment channel")

	// ErrMaxMetadataSize indicates maximum metadata length
	ErrMaxMetadataSize = errors.New("maximum metadata size is 5")

	// ErrEmptyID indicates an empty reference or ID
	ErrEmptyID = errors.New("empty id")

	// ErrInvalidSettlementMethod indicates invalid settlement method
	ErrInvalidSettlementMethod = errors.New("invalid settlement method")
)

Types

type AddPAYRecipient

type AddPAYRecipient struct {
	Type             string           `json:"type,omitempty"`              // The type of the recipient eg. mobile wallet or bank account
	PaymentRecipient PaymentRecipient `json:"payment_recipient,omitempty"` // 	A JSON object containing details of the recipeint
}

AddPAYRecipient struct

func (AddPAYRecipient) Validate

func (apr AddPAYRecipient) Validate() error

Validate returns nil if the struct is valid

type Amount

type Amount struct {
	Value    string `json:"value,omitempty"`    // The amount of the transaction
	Currency string `json:"currency,omitempty"` // Currency
}

Amount struct

type Attribute

type Attribute struct {
	InitiationTime string                 `json:"initiation_time,omitempty"` // The timestamp of when the webhook event was created.
	Status         string                 `json:"status,omitempty"`          // A status string denoting the status of the Incoming Payment
	Resource       Resource               `json:"resource,omitempty"`        // A JSON Object encapsulating the event of the request
	Metadata       map[string]interface{} `json:"metadata,omitempty"`        // An optional JSON object containing a maximum of 5 key value pairs
	Links          Links                  `json:"_links,omitempty"`          // A JSON object containing links to the Webhook Event and the corresponding Buygoods Transaction resource

}

Attribute struct

type BuyGoodsTrans

type BuyGoodsTrans struct {
	Topic     string `json:"topic,omitempty"`      // The ID of the Webhook Event
	ID        string `json:"id,omitempty"`         // The topic of the webhook.
	CreatedAt string `json:"created_at,omitempty"` // The timestamp of when the webhook event was created.
	Event     Event  `json:"event,omitempty"`
	Links     Links  `json:"_links,omitempty"` // A JSON object containing links to the Webhook Event and the corresponding Buygoods Transaction resource
}

BuyGoodsTrans struct

func (BuyGoodsTrans) Validate

func (bgt BuyGoodsTrans) Validate() error

Validate returns nil if the struct is valid

type Config

type Config struct {
	BaseURL         string
	Credentials     Credentials
	MaxIdleConns    int
	IdleConnTimeout time.Duration
}

Config contains sdk configuration parameters.

type ContentType

type ContentType string

ContentType represents all possible content types.

type CreatePaymentReq

type CreatePaymentReq struct {
	DestinationType      string                 `json:"destination_type,omitempty"`      // Pay recipient type (bank_account, mobile_wallet, till or paybill
	DestinationReference string                 `json:"destination_reference,omitempty"` // Reference for the destination.
	Amount               Amount                 `json:"amount,omitempty"`                // A JSON object containing the currency and the amount to be transferred
	Description          string                 `json:"description,omitempty"`           // A reason for the payment
	Category             string                 `json:"category,omitempty"`              // Categorize the transaction
	Tags                 string                 `json:"tags,omitempty"`                  // Define your own tag to label the transaction with
	Metadata             map[string]interface{} `json:"metadata,omitempty"`              // A JSON containing upto a maximum of 5 key-value pairs for your own use
	Links                Links                  `json:"_links,omitempty"`                // A JSON containing a call back URL where the results of the Payment will be posted. MUST be a secure HTTPS (TLS) endpoint
}

CreatePaymentReq struct

func (CreatePaymentReq) Validate

func (cpr CreatePaymentReq) Validate() error

Validate returns nil if the struct is valid

type CreateWebhookReq

type CreateWebhookReq struct {
	EventType string `json:"event_type,omitempty"` //The type of event you are subscribing to
	URL       string `json:"url,omitempty"`        // The http end point to send the webhook.
	Scope     string `json:"scope,omitempty"`      // The scope of the webhook subscription.
	ScopeRef  string `json:"scope_reference,omitempty"`
}

CreateWebhookReq struct

func (CreateWebhookReq) Validate

func (cwr CreateWebhookReq) Validate() error

Validate returns nil if the struct is valid

type Credentials

type Credentials struct {
	AppID  string `json:"app_id"` // Application key.
	Secret string `json:"secret"` // Application secret. Only revealed to the user when creating an application or during regeneration of client credentials.
	APIKey string `json:"api_key"`
}

Credentials contains the credentials

type CustomerEvent

type CustomerEvent struct {
	Type     string           `json:"type,omitempty"`     // The type of record (Mobile Money User)
	Resource CustomerResource `json:"resource,omitempty"` // The resource corresponding to the event.
}

CustomerEvent struct

type CustomerReq

type CustomerReq struct {
	Topic     string        `json:"topic,omitempty"`      // The ID of the Webhook Event
	ID        string        `json:"id,omitempty"`         // The topic of the webhook.
	CreatedAt string        `json:"created_at,omitempty"` // The timestamp of when the webhook event was created.
	Event     CustomerEvent `json:"event,omitempty"`
	Links     Links         `json:"_links,omitempty"` // A JSON object containing links to the Webhook Event and the corresponding Buygoods Transaction resource
}

CustomerReq struct

type CustomerResource

type CustomerResource struct {
	LastName    string `json:"last_name,omitempty"`    // Last name of payer
	FirstName   string `json:"first_name,omitempty"`   // First name of payer
	MiddleName  string `json:"middle_name,omitempty"`  // Middle name of payer
	PhoneNumber string `json:"phone_number,omitempty"` // The phone number that sent the payment
}

CustomerResource struct

type Destination

type Destination struct {
	Type     string              `json:"type,omitempty"`
	Resource DestinationResource `json:"resource,omitempty"`
}

Destination struct

type DestinationResource

type DestinationResource struct {
	Reference           string `json:"reference,omitempty"`         // The destination reference
	AccountName         string `json:"account_name,omitempty"`      // The name as indicated on the bank account
	AccountNumber       string `json:"account_number,omitempty"`    // The bank account number
	BankBranchReference string `json:"bank_branch_ref,omitempty"`   // An identifier identifying the destination bank branch
	SettlementMethod    string `json:"settlement_method,omitempty"` // EFT or RTS
	FirstName           string `json:"first_name,omitempty"`        // String	First name of the recipient
	LastName            string `json:"last_name,omitempty"`         // Last name of recipient
	Email               string `json:"email,omitempty"`             // Email of recipient
	PhoneNumber         string `json:"phone_number,omitempty"`      // Phone number
	Network             string `json:"network,omitempty"`           // The mobile network to which the phone number belongs
}

DestinationResource struct

type Disbursements

type Disbursements struct {
	Status                 string `json:"status,omitempty"`                  // The status of the disbursement
	Amount                 string `json:"amount,omitempty"`                  // The amount of the disbursement
	OriginationTime        string `json:"origination_time,omitempty"`        // The Timestamp of when the transaction took place
	TransactionalReference string `json:"transactional_reference,omitempty"` // The reference from the transaction. i.e mpesa reference It is null for eft transactions
}

Disbursements struct

type Event

type Event struct {
	Type     string   `json:"type,omitempty"`     // The type of transaction
	Resource Resource `json:"resource,omitempty"` // The resource corresponding to the event.
}

Event struct

type IncomingPaymentEvent

type IncomingPaymentEvent struct {
	Type       string    `json:"type,omitempty"` // The ID of the Webhook Event
	ID         string    `json:"id,omitempty"`   // The topic of the webhook.
	Attributes Attribute `json:"attributes,omitempty"`
}

IncomingPaymentEvent struct

type Links

type Links struct {
	Self     string `json:"self,omitempty"`
	Resource string `json:"resource,omitempty"`
	Callback string `json:"callback_url,omitempty"`
}

Links struct

type PaymentRecipient

type PaymentRecipient struct {
	// Mobile Wallet
	LastName    string `json:"last_name,omitempty"`    // Last name of the recipient
	FirstName   string `json:"first_name,omitempty"`   // First name of the recipient
	MiddleName  string `json:"middle_name,omitempty"`  // Middle name of the recipient
	PhoneNumber string `json:"phone_number,omitempty"` // The phone number of the recipient from which the payment will be made
	Email       string `json:"email,omitempty"`        // E-mail address of the recipient - optional
	Network     string `json:"network,omitempty"`      // The mobile network to which the phone number belongs
	// Bank Account
	AccountName         string `json:"account_name,omitempty"`      //The name as indicated on the bank account name
	BankBranchReference string `json:"bank_branch_ref,omitempty"`   // An identifier identifying the destination bank branch.
	AccountNumber       string `json:"account_number,omitempty"`    // The bank account number
	SettlementMethod    string `json:"settlement_method,omitempty"` // RTS
	// External Till
	TillName   string `json:"till_name,omitempty"`   // The name as indicated on the till
	TillNumber string `json:"till_number,omitempty"` // The till number
	// Paybill
	PayBillName          string `json:"paybill_name,omitempty"`           // The name referring to the paybill
	PayBillNumber        string `json:"paybill_number,omitempty"`         // The paybill business number
	PayBillAccountNumber string `json:"paybill_account_number,omitempty"` // The paybill account number
}

PaymentRecipient struct comprises of Mobile Wallet, Bank Account, External Till and Paybill recipients

type ProcessIncommingPaymentReq

type ProcessIncommingPaymentReq struct {
	Topic          string                 `json:"topic,omitempty"`           // The topic of the request.
	ID             string                 `json:"id,omitempty"`              // The ID of the Incoming Payment
	InitiationTime string                 `json:"initiation_time,omitempty"` // The timestamp of when the webhook event was created.
	Status         string                 `json:"status,omitempty"`          // A status string denoting the status of the Incoming Payment
	Event          IncomingPaymentEvent   `json:"event,omitempty"`           // A JSON Object encapsulating the event of the request
	Metadata       map[string]interface{} `json:"metadata,omitempty"`        // An optional JSON object containing a maximum of 5 key value pairs
	Links          Links                  `json:"_links,omitempty"`          // A JSON object containing links to the Webhook Event and the corresponding Buygoods Transaction resource
}

ProcessIncommingPaymentReq struct

type ReceiveMpesaReq

type ReceiveMpesaReq struct {
	PaymentChannel string                 `json:"payment_channel,omitempty"` // The payment channel to be used eg. M-PESA
	TillNumber     string                 `json:"till_number,omitempty"`     // The online payments till number from the Kopo Kopo dashboard to which the payment will be made
	Subscriber     Subscriber             `json:"subscriber,omitempty"`      // A Subscriber JSON object see below
	Amount         Amount                 `json:"amount,omitempty"`          // An Amount JSON object containing currency and amount
	Metadata       map[string]interface{} `json:"metadata,omitempty"`        // An optional JSON object containing a maximum of 5 key value pairs
	Links          Links                  `json:"_links,omitempty"`          // A JOSN object containing the call back URL where the result of the Incoming Payment will be posted
}

ReceiveMpesaReq struct

func (ReceiveMpesaReq) Validate

func (rmr ReceiveMpesaReq) Validate() error

Validate returns nil if the struct is valid

type Resource

type Resource struct {
	ID                     string          `json:"id,omitempty"`        // The api reference of the transaction
	Amount                 float64         `json:"amount,omitempty"`    // The amount of the transaction
	Status                 string          `json:"status,omitempty"`    // The status of the transaction
	System                 string          `json:"system,omitempty"`    // The mobile money system
	Currency               string          `json:"currency,omitempty"`  // Currency
	Reference              string          `json:"reference,omitempty"` // The mpesa reference
	TransactionalReference string          `json:"transactional_reference,omitempty"`
	TillNumber             string          `json:"till_number,omitempty"`  // The till number to which the payment was made
	SendingTill            string          `json:"sending_till,omitempty"` // The till number of the sender
	AccountName            string          `json:"account_name,omitempty"`
	AccountNumber          string          `json:"account_number,omitempty"`
	BankBranchReference    string          `json:"bank_branch_ref,omitempty"`
	SettlementMethod       string          `json:"settlement_method,omitempty"`
	SendingMerchant        string          `json:"sending_merchant,omitempty"`    // Name of merchant
	SenderPhoneNumber      string          `json:"sender_phone_number,omitempty"` // The phone number that sent the payment
	OriginationTime        string          `json:"origination_time,omitempty"`    // The transaction timestamp
	SenderLastName         string          `json:"sender_last_name,omitempty"`    // Last name of payer
	SenderFirstName        string          `json:"sender_first_name,omitempty"`   // First name of payer
	SenderMiddleName       string          `json:"sender_middle_name,omitempty"`  // Middle name of payer
	Destination            Destination     `json:"destination,omitempty"`         // The destination of the settlement transfer
	Disbursements          []Disbursements `json:"disbursements,omitempty"`       // These are the disbursements in that particular transfer batch
}

Resource struct

type SDK

type SDK interface {

	// The client credentials flow is the simplest OAuth 2 grant,
	// with a server-to-server exchange of your application’s client_id, client_secret
	// for an OAuth application access token.
	GetToken() (tokenResp, error)

	// The request is used to revoke a particular token at a time.
	RevokeToken(token string) error

	// It can be used to check the validity of your access tokens, and find out other
	// information such as which user and which scopes are associated with the token.
	// The client secret will not be displayed as that is to remain confidential with the application owner.
	TokenIntrospection(token string) (tokenIntrospectionResp, error)

	// Shows details about the token used for authentication.
	TokenInformation(token string) (tokenInfo, error)

	// Create a webhook subscription
	CreateWebhook(token string, webookReq CreateWebhookReq) (string, error)

	// Before processing webhook events, make sure that they originated from Kopo Kopo.
	// Each request is signed with the api_key you got when creating an oauth application on the platform.
	ValidateWebhook(webhookURL string) (BuyGoodsTrans, error)

	// Notifies your application when a Buygoods Transaction has been received.
	C2BSubscription(webhookURL string) (BuyGoodsTrans, error)

	// Notifies your application when a B2b (External Till to Till transaction) has been received.
	// These are payments recieved from other tills and not subscribers.
	B2BSubscription(webhookURL string) (BuyGoodsTrans, error)

	// Notifies your application when another Kopo Kopo merchant transfers funds
	// to your Kopo Kopo merchant account (Merchant to Merchant)
	M2MSubscription(webhookURL string) (BuyGoodsTrans, error)

	// Notifies your application when a Buygoods Transaction has been reversed
	C2BReversalSubscription(webhookURL string) (BuyGoodsTrans, error)

	// Settlement Transfer Completed
	SettlementSub(webhookURL string) (BuyGoodsTrans, error)

	// Customer Created
	CusomerCreationSub(webhookURL string) (CustomerReq, error)

	// Receive payments from M-PESA users via STK Push.
	ReceiveMpesaPayment(token string, receiveMpesaReq ReceiveMpesaReq) (string, error)

	// ProcessIncommingMpesaPayment After a Incoming Payment is initiated,
	// a Incoming Payment Result will be posted asynchronously to the call back URL specified in the Incoming Payment.
	ProcessIncommingMpesaPayment(grantType string) (string, error)

	// With an Incoming Payment location url, you can query what the status of the Incoming Payment is.
	// If a corresponding Incoming Payment Result exists, it will be bundled in the payload of the result.
	QueryIncommingMpesaPayment(token, id string) (IncomingPaymentEvent, error)

	// AddPayRecipients Add external entities that will be the destination of your payments.
	AddPayRecipients(token string, recipient AddPAYRecipient) (string, error)

	// CreatePayment Create an outgoing payment to a third party.
	// The final result of the Payment will be posted asynchronously to your systems
	// via the call back URL provided in the request.
	CreatePayment(token string, payment CreatePaymentReq) (string, error)
}

SDK contains Kopokopo API.

func NewSDK

func NewSDK(conf Config) SDK

NewSDK returns new mainflux SDK instance.

type Subscriber

type Subscriber struct {
	LastName    string `json:"last_name,omitempty"`    // Last name of the subscriber
	FirstName   string `json:"first_name,omitempty"`   // First name of the subscriber
	MiddleName  string `json:"middle_name,omitempty"`  // Middle name of the subscriber
	PhoneNumber string `json:"phone_number,omitempty"` // The phone number of the subscriber from which the payment will be made
	Email       string `json:"email,omitempty"`        // E-mail address of the subscriber - optional
}

Subscriber struct