verixo

package module
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2026 License: MIT Imports: 10 Imported by: 0

README

verixo-go

Official Go SDK for the VerifiedCore API.

Install

go get github.com/titicodes/verixo-go

Verify: send one-time codes to your own users

Send a code to your user's phone at sign-up, login or 2FA, then check what they typed. VerifiedCore generates, delivers, rate-limits and expires the code.

import verixo "github.com/titicodes/verixo-go"

vc := verixo.New(os.Getenv("VC_API_KEY"))

// 1. Send a code
v, err := vc.Verify.Start(verixo.StartVerificationParams{To: "+2348031234567", IP: userIP})
if err != nil { return err }

// 2. Check the code your user typed
r, err := vc.Verify.Check(verixo.CheckVerificationParams{ID: v.ID, Code: userInput})
if err != nil { return err }
if r.Valid != nil && *r.Valid {
    // signed in
} else {
    fmt.Printf("%d attempts left
", r.AttemptsRemaining)
}

With a vc_test_ key nothing is sent or charged, and the code is always 123456, so you can build your flow end-to-end before going live.

Other calls: vc.Verify.Get(id), vc.Verify.List(page, size), vc.Verify.Settings() and vc.Verify.UpdateSettings(verixo.VerifySettingsUpdate{...}).

Failures return a *verixo.VerixoError whose Code says why, e.g. COUNTRY_NOT_ALLOWED, INVALID_NUMBER, RESEND_TOO_SOON or RATE_LIMITED:

var ve *verixo.VerixoError
if errors.As(err, &ve) && ve.Code == "RESEND_TOO_SOON" { /* ask the user to wait */ }

eSIM

packages, err := vc.ESim.ListPackages("NG", 7)

The client also has CallPlans, Wallet, Payment, Numbers, Sessions and Analytics; see the API docs.

Requirements

Go 1.21+.

Documentation

Overview

Package verixo is the official Go SDK for the VerifiedCore API.

Verify -- send one-time codes to your own users and check them: 

vc := verixo.New("vc_live_your_api_key")

v, err := vc.Verify.Start(verixo.StartVerificationParams{To: "+2348031234567"})
r, err := vc.Verify.Check(verixo.CheckVerificationParams{ID: v.ID, Code: userInput})
if err == nil && r.Valid != nil && *r.Valid { /* signed in */ }

Numbers: 

purchase, err := vc.Numbers.Purchase(verixo.PurchaseNumberParams{
    ServiceSlug: "whatsapp",
    CountryCode: "NG",
})

// Real-time push (non-blocking)
cancel := vc.Subscribe(purchase.SessionToken, func(push *verixo.OtpPush) {
    fmt.Printf("OTP: %s delivered in %dms\n", push.Otp, push.LatencyMs)
})
defer cancel()

// Or poll synchronously (fallback for serverless)
session, err := vc.Sessions.WaitForOtp(purchase.SessionToken, 90*time.Second, 0)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Analytics 

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

Analytics provides delivery-rate statistics.

func (*Analytics) Rates 

func (a *Analytics) Rates(serviceSlug string) (*AnalyticsRatesResult, error)

Rates returns public delivery-rate stats by country for a service. serviceSlug defaults to "whatsapp" if empty.

type AnalyticsRatesResult 

type AnalyticsRatesResult struct {
	Rates     []DeliveryRate `json:"rates"`
	UpdatedAt string         `json:"updatedAt"`
}

type CallPlan 

type CallPlan struct {
	ID                string       `json:"id"`
	Tier              CallPlanTier `json:"tier"`
	Name              string       `json:"name"`
	Minutes           int          `json:"minutes"` // -1 = unlimited
	PriceUsd          float64      `json:"priceUsd"`
	PerMin            float64      `json:"perMin"`
	Popular           bool         `json:"popular"`
	HighCostMinutes   int          `json:"highCostMinutes"`
	HighCostCountries []string     `json:"highCostCountries"`
	Features          []string     `json:"features"`
}

type CallPlanSubscription 

type CallPlanSubscription struct {
	ID                   string `json:"id"`
	UserID               string `json:"userId"`
	Tier                 string `json:"tier"`
	Status               string `json:"status"`
	MinutesUsed          int    `json:"minutesUsed"`
	MinutesTotal         int    `json:"minutesTotal"`
	HighCostMinutesUsed  int    `json:"highCostMinutesUsed"`
	HighCostMinutesTotal int    `json:"highCostMinutesTotal"`
	RenewsAt             string `json:"renewsAt"`
	CreatedAt            string `json:"createdAt"`
}

type CallPlanTier 

type CallPlanTier string
const (
	CallPlanTierBasic    CallPlanTier = "BASIC"
	CallPlanTierStandard CallPlanTier = "STANDARD"
	CallPlanTierPremium  CallPlanTier = "PREMIUM"
)

type CallPlans 

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

CallPlans provides methods for listing and subscribing to call plans.

func (*CallPlans) GetSubscription 

func (c *CallPlans) GetSubscription() (*CallPlanSubscription, error)

GetSubscription returns the authenticated user's active call-plan subscription.

func (*CallPlans) List 

func (c *CallPlans) List() ([]CallPlan, error)

List returns all available call plans.

func (*CallPlans) Subscribe 

func (c *CallPlans) Subscribe(params SubscribeCallPlanParams) (*CallPlanSubscription, error)

Subscribe purchases a call-plan subscription.

type CheckVerificationParams 

type CheckVerificationParams struct {
	// ID from Start, or set To to check the latest pending code for that number.
	ID   string `json:"id,omitempty"`
	To   string `json:"to,omitempty"`
	Code string `json:"code"`
}

type Client 

type Client struct {
	Numbers   *Numbers
	Sessions  *Sessions
	Analytics *Analytics
	ESim      *ESim
	CallPlans *CallPlans
	Payment   *Payment
	Wallet    *Wallet
	Verify    *Verify
	// contains filtered or unexported fields
}

Client is the top-level Verixo SDK client.

func New 

func New(apiKey string, opts ...Options) *Client

New creates a Verixo client authenticated with the given API key or JWT. API keys start with vc_test_ or vc_live_; JWTs are sent with a Bearer prefix.

func (*Client) Subscribe 

func (c *Client) Subscribe(sessionToken string, onOtp func(*OtpPush)) func()

Subscribe connects to the gateway's WebSocket and calls onOtp once when the OTP for sessionToken is delivered. It returns a cancel function; call it to disconnect and stop the goroutine.

STOMP frames are assembled manually to avoid a heavy dependency. The gateway speaks STOMP 1.1/1.2 over WebSocket (delivery-service's STOMP broker). 

purchase, _ := vc.Numbers.Purchase(verixo.PurchaseNumberParams{...})
cancel := vc.Subscribe(purchase.SessionToken, func(push *verixo.OtpPush) {
    fmt.Printf("OTP: %s in %dms\n", push.Otp, push.LatencyMs)
})
defer cancel()

type DeliveryRate 

type DeliveryRate struct {
	CountryCode     string  `json:"countryCode"`
	CountryName     string  `json:"countryName"`
	CountryFlag     string  `json:"countryFlag"`
	Rate            float64 `json:"rate"`
	Latency         string  `json:"latency"`
	TotalDeliveries int     `json:"totalDeliveries"`
	UpdatedAt       string  `json:"updatedAt"`
}

type ESim 

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

ESim provides methods for listing and purchasing eSIM packages via Airalo.

func (*ESim) List 

func (e *ESim) List() ([]ESimProfile, error)

List returns all eSIM profiles provisioned for the authenticated user.

func (*ESim) ListPackages 

func (e *ESim) ListPackages(countryCode string, days int) ([]ESimPackage, error)

ListPackages returns available eSIM packages for a country. days filters by minimum validity period (default 30).

func (*ESim) Purchase 

func (e *ESim) Purchase(params ESimPurchaseParams) (*ESimProfile, error)

Purchase buys an eSIM package. The gateway debits your wallet and returns activation info including the QR code URL and LPA activation code.

func (*ESim) Usage 

func (e *ESim) Usage(iccid string) (*ESimUsage, error)

Usage returns the current data balance for a provisioned eSIM by ICCID.

type ESimPackage 

type ESimPackage struct {
	PackageID    string  `json:"packageId"`
	Name         string  `json:"name"`
	CountryCode  string  `json:"countryCode"`
	DataGb       float64 `json:"dataGb"`
	ValidityDays int     `json:"validityDays"`
	PriceUsd     float64 `json:"priceUsd"`
	Slug         string  `json:"slug,omitempty"`
}

type ESimProfile 

type ESimProfile struct {
	ProfileID             string  `json:"profileId"`
	Iccid                 string  `json:"iccid"`
	ActivationCode        string  `json:"activationCode"`
	QrCodeURL             string  `json:"qrCodeUrl"`
	DirectAppleInstallURL string  `json:"directAppleInstallUrl"`
	SmdpAddress           string  `json:"smdpAddress"`
	MatchingID            string  `json:"matchingId"`
	ApnType               string  `json:"apnType"`
	ApnValue              string  `json:"apnValue"`
	IsRoaming             bool    `json:"isRoaming"`
	CarrierName           string  `json:"carrierName"`
	DataGbIncluded        float64 `json:"dataGbIncluded"`
	ValidityDays          int     `json:"validityDays"`
	CountryCode           string  `json:"countryCode"`
	Status                string  `json:"status"`
}

type ESimPurchaseParams 

type ESimPurchaseParams struct {
	PackageID   string  `json:"packageId"`
	CountryCode string  `json:"countryCode"`
	PriceUsd    float64 `json:"priceUsd"`
}

type ESimUsage 

type ESimUsage struct {
	Iccid       string  `json:"iccid"`
	RemainingMb float64 `json:"remainingMb"`
	TotalMb     float64 `json:"totalMb"`
	UsedPercent float64 `json:"usedPercent"`
	ExpiresAt   string  `json:"expiresAt"`
}

type InitiatePaymentParams 

type InitiatePaymentParams struct {
	CreditPackID      string  `json:"creditPackId"`
	UsdAmount         float64 `json:"usdAmount"`
	CreditsToAdd      int     `json:"creditsToAdd"`
	BonusCredits      int     `json:"bonusCredits,omitempty"`
	Currency          string  `json:"currency"`
	CustomerEmail     string  `json:"customerEmail"`
	CustomerName      string  `json:"customerName,omitempty"`
	CustomerPhone     string  `json:"customerPhone,omitempty"`
	PreferredProvider string  `json:"preferredProvider,omitempty"`
	CallbackURL       string  `json:"callbackUrl,omitempty"`
}

type Numbers 

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

Numbers provides methods for browsing and purchasing virtual phone numbers.

func (*Numbers) Purchase 

func (n *Numbers) Purchase(params PurchaseNumberParams) (*PurchaseResult, error)

Purchase buys a number for the given service + country. The server selects the best available number by Health Score automatically.

func (*Numbers) Search 

func (n *Numbers) Search(params SearchNumbersParams) (*SearchNumbersResult, error)

Search returns available numbers ranked by Health Score. No purchase is made.

type Options 

type Options struct {
	// BaseURL overrides the default production gateway URL.
	// Useful for local development: "http://localhost:8080"
	BaseURL string
}

Options configures the Verixo client.

type OtpPush 

type OtpPush struct {
	SessionToken string `json:"sessionToken"`
	Otp          string `json:"otp"`
	E164Number   string `json:"e164Number"`
	ServiceSlug  string `json:"serviceSlug"`
	PrivacyMode  bool   `json:"privacyMode"`
	DeliveredAt  string `json:"deliveredAt"`
	// Milliseconds between calling Subscribe and receiving this push.
	LatencyMs int64 `json:"-"`
}

type Payment 

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

Payment provides methods for initiating wallet top-ups.

func (*Payment) Initiate 

func (p *Payment) Initiate(params InitiatePaymentParams) (*PaymentInitResult, error)

Initiate starts a payment flow for adding credits to the wallet. The response includes a checkoutUrl (for redirect flows) or clientSecret (for Stripe embedded) depending on the currency and preferred provider.

type PaymentInitResult 

type PaymentInitResult struct {
	Success              bool     `json:"success"`
	Provider             string   `json:"provider"`
	TransactionID        string   `json:"transactionId"`
	CheckoutURL          string   `json:"checkoutUrl"`
	ClientSecret         string   `json:"clientSecret"`
	Reference            string   `json:"reference"`
	Currency             string   `json:"currency"`
	LocalAmount          float64  `json:"localAmount"`
	PaymentMethods       []string `json:"paymentMethods"`
	ErrorMessage         string   `json:"errorMessage"`
	UssdCode             string   `json:"ussdCode"`
	BankCode             string   `json:"bankCode"`
	VirtualAccountNumber string   `json:"virtualAccountNumber"`
	VirtualAccountBank   string   `json:"virtualAccountBank"`
}

type PurchaseNumberParams 

type PurchaseNumberParams struct {
	ServiceSlug string `json:"serviceSlug"`
	CountryCode string `json:"countryCode"`
	PrivacyMode bool   `json:"privacyMode,omitempty"`
	TestMode    bool   `json:"testMode,omitempty"`
	// SMS | WHATSAPP | VOICE | EMAIL | VIBER
	Channel string `json:"channel,omitempty"`
}

type PurchaseResult 

type PurchaseResult struct {
	SessionToken          string  `json:"sessionToken"`
	PurchaseID            string  `json:"purchaseId"`
	WebSocketTopic        string  `json:"webSocketTopic"`
	E164Number            string  `json:"e164Number"`
	HealthScoreAtPurchase float64 `json:"healthScoreAtPurchase"`
	ScoreColor            string  `json:"scoreColor"`
	CarrierType           string  `json:"carrierType"`
	AggregatorType        string  `json:"aggregatorType"`
	PriceUsd              float64 `json:"priceUsd"`
	SlaRemainingSeconds   int     `json:"slaRemainingSeconds"`
	SlaExpiresAt          string  `json:"slaExpiresAt"`
	PrivacyMode           bool    `json:"privacyMode"`
	ConfidenceLabel       string  `json:"confidenceLabel"`
	Channel               string  `json:"channel"`
}

type SearchNumbersParams 

type SearchNumbersParams struct {
	ServiceSlug string `json:"serviceSlug"`
	CountryCode string `json:"countryCode,omitempty"`
	MinScore    *int   `json:"minScore,omitempty"`
	Limit       *int   `json:"limit,omitempty"`
}

type SearchNumbersResult 

type SearchNumbersResult struct {
	Numbers        []VirtualNumber `json:"numbers"`
	TotalAvailable int             `json:"totalAvailable"`
	CountryCode    string          `json:"countryCode"`
	ServiceSlug    string          `json:"serviceSlug"`
}

type SessionState 

type SessionState string
const (
	SessionStatePending   SessionState = "PENDING"
	SessionStateDelivered SessionState = "DELIVERED"
	SessionStateRefunded  SessionState = "REFUNDED"
	SessionStateExpired   SessionState = "EXPIRED"
	SessionStateFailed    SessionState = "FAILED"
)

type SessionStatus 

type SessionStatus struct {
	SessionToken        string       `json:"sessionToken"`
	Status              SessionState `json:"status"`
	OtpCode             string       `json:"otpCode"`
	SlaRemainingSeconds int          `json:"slaRemainingSeconds"`
	FailureReason       string       `json:"failureReason"`
	AggregatorType      string       `json:"aggregatorType"`
	HealthScore         float64      `json:"healthScore"`
	PrivacyMode         bool         `json:"privacyMode"`
	Channel             string       `json:"channel"`
}

type Sessions 

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

Sessions provides methods for checking OTP delivery status.

func (*Sessions) Get 

func (s *Sessions) Get(sessionToken string) (*SessionStatus, error)

Get returns the current delivery status of a session.

func (*Sessions) WaitForOtp 

func (s *Sessions) WaitForOtp(sessionToken string, timeout, interval time.Duration) (*SessionStatus, error)

WaitForOtp polls until the session reaches a terminal state or the timeout elapses. Prefer Subscribe for real-time push; use this as a fallback in environments where a persistent connection isn't practical (e.g. serverless).

type StartVerificationParams 

type StartVerificationParams struct {
	// To is the destination in E.164 format, e.g. "+2348031234567".
	To string `json:"to"`
	// Channel is "sms" (the default when empty).
	Channel string `json:"channel,omitempty"`
	// IP is your end user's IP address; enables per-IP abuse limits.
	IP string `json:"ip,omitempty"`
}

type SubscribeCallPlanParams 

type SubscribeCallPlanParams struct {
	Tier             CallPlanTier `json:"tier"`
	PaymentProvider  string       `json:"paymentProvider,omitempty"`
	PaymentReference string       `json:"paymentReference,omitempty"`
}

type Verification 

type Verification struct {
	ID                string  `json:"id"`
	To                string  `json:"to"`
	Channel           string  `json:"channel"`
	Status            string  `json:"status"`
	AttemptsRemaining int     `json:"attemptsRemaining"`
	PriceUsd          float64 `json:"priceUsd"`
	TestMode          bool    `json:"testMode"`
	ExpiresAt         string  `json:"expiresAt"`
	CreatedAt         string  `json:"createdAt"`
	ApprovedAt        string  `json:"approvedAt,omitempty"`
	// Valid is set on Check responses: true only when the code was correct.
	Valid *bool `json:"valid,omitempty"`
}

Verification is one code sent to one of your users. Status is pending, approved, expired, failed or cancelled.

type VerificationList 

type VerificationList struct {
	Items []Verification `json:"items"`
	Page  int            `json:"page"`
	Size  int            `json:"size"`
	Total int            `json:"total"`
}

type Verify 

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

Verify sends one-time codes to YOUR users (sign-up, login, 2FA) and checks them. With a vc_test_ key nothing is sent or charged and the code is always "123456".

func (*Verify) Check 

func (v *Verify) Check(params CheckVerificationParams) (*Verification, error)

Check checks the code your user typed. Valid is true only when it matched. 

r, err := vc.Verify.Check(verixo.CheckVerificationParams{ID: v.ID, Code: "482913"})
if err == nil && r.Valid != nil && *r.Valid { signIn(user) }

func (*Verify) Get 

func (v *Verify) Get(id string) (*Verification, error)

Get returns one verification.

func (*Verify) List 

func (v *Verify) List(page, size int) (*VerificationList, error)

List returns your verification logs, newest first. Zero page/size use the server defaults.

func (*Verify) Settings 

func (v *Verify) Settings() (*VerifySettings, error)

Settings returns your Verify settings (brand name, countries, code length, TTL).

func (*Verify) Start 

func (v *Verify) Start(params StartVerificationParams) (*Verification, error)

Start sends a code by SMS. 

v, err := vc.Verify.Start(verixo.StartVerificationParams{To: "+2348031234567"})

func (*Verify) UpdateSettings 

func (v *Verify) UpdateSettings(update VerifySettingsUpdate) (*VerifySettings, error)

UpdateSettings changes only the fields that are set.

type VerifySettings 

type VerifySettings struct {
	BrandName        *string  `json:"brandName"`
	AllowedCountries []string `json:"allowedCountries"`
	CodeLength       int      `json:"codeLength"`
	TTLSeconds       int      `json:"ttlSeconds"`
	PausedUntil      *string  `json:"pausedUntil"`
}

type VerifySettingsUpdate 

type VerifySettingsUpdate struct {
	BrandName        *string  `json:"brandName,omitempty"`
	AllowedCountries []string `json:"allowedCountries,omitempty"`
	CodeLength       *int     `json:"codeLength,omitempty"`
	TTLSeconds       *int     `json:"ttlSeconds,omitempty"`
}

VerifySettingsUpdate changes only the fields that are non-nil.

type VerixoError 

type VerixoError struct {
	StatusCode int
	Body       string
	Message    string
	// Code is the machine-readable reason when the API sends one,
	// e.g. "COUNTRY_NOT_ALLOWED" or "RESEND_TOO_SOON" from Verify.
	Code string
}

VerixoError is returned for any non-2xx response from the API.

func (*VerixoError) Error 

func (e *VerixoError) Error() string

type VirtualNumber 

type VirtualNumber struct {
	NumberID     string  `json:"numberId"`
	Number       string  `json:"number"`
	E164Number   string  `json:"e164Number"`
	HealthScore  float64 `json:"healthScore"`
	NumberType   string  `json:"numberType"`
	CountryCode  string  `json:"countryCode"`
	CountryName  string  `json:"countryName"`
	CountryFlag  string  `json:"countryFlag"`
	PriceUsd     float64 `json:"priceUsd"`
	DeliveryRate float64 `json:"deliveryRate"`
	AvgLatencyMs *int64  `json:"avgLatencyMs"`
	Available    bool    `json:"available"`
	ScoreColor   string  `json:"scoreColor"`
	CarrierName  string  `json:"carrierName"`
}

type Wallet 

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

Wallet provides methods for checking balances and transaction history.

func (*Wallet) Balance 

func (w *Wallet) Balance() (*WalletBalance, error)

Balance returns the authenticated user's current wallet balance.

func (*Wallet) Transactions 

func (w *Wallet) Transactions(page, size int) (*WalletTransactionsResult, error)

Transactions returns paginated wallet transaction history.

type WalletBalance 

type WalletBalance struct {
	BalanceUsd   float64 `json:"balanceUsd"`
	RefundsToday int     `json:"refundsToday"`
}

type WalletTransaction 

type WalletTransaction struct {
	ID              string  `json:"id"`
	Type            string  `json:"type"`
	AmountUsd       float64 `json:"amountUsd"`
	Description     string  `json:"description"`
	ReferenceID     string  `json:"referenceId"`
	BalanceAfterUsd float64 `json:"balanceAfterUsd"`
	CreatedAt       string  `json:"createdAt"`
}

type WalletTransactionsResult 

type WalletTransactionsResult struct {
	Transactions []WalletTransaction `json:"transactions"`
	Total        int                 `json:"total"`
	Page         int                 `json:"page"`
	Size         int                 `json:"size"`
}

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.