aurora

README

Aurora Go SDK

Official Go SDK for the Aurora API — a rule-based transaction processing engine.

Installation

go get github.com/kintsdev/aurora-go-sdk

Quick Start

package main

import (
	"context"
	"fmt"
	"log"

	aurora "github.com/kintsdev/aurora-go-sdk"
)

func main() {
	client := aurora.NewClient("your-api-key",
		aurora.WithBaseURL("https://api.example.com"),
	)

	resp, err := client.Process.Execute(context.Background(), &aurora.ProcessRequest{
		RuleID: "your-rule-id",
		Transaction: &aurora.Transaction{
			Amount:   250.00,
			Currency: "USD",
			Email:    "customer@example.com",
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Allowed: %v | Rejected: %v | Score: %d\n", resp.Allow, resp.Rejected, resp.Score)
}

Configuration

Client Options

Option	Description
WithBaseURL(url)	Set the API host (e.g. https://api.example.com). The path /api/v1 is appended automatically.
WithHTTPClient(client)	Provide a custom *http.Client.
WithTimeout(duration)	Set HTTP client timeout (default: 30s).

Authentication

The SDK sends the API key as a Bearer token in the Authorization header.

client := aurora.NewClient("your-api-key")

Process

Execute a rule against a transaction using client.Process.Execute().

With a Single Rule

resp, err := client.Process.Execute(ctx, &aurora.ProcessRequest{
    RuleID: "rule-id",
    Transaction: &aurora.Transaction{
        Amount:   100.00,
        Currency: "TRY",
        UserID:   "user-123",
    },
})

With a Ruleset

resp, err := client.Process.Execute(ctx, &aurora.ProcessRequest{
    RulesetID: "ruleset-id",
    Transaction: &aurora.Transaction{
        Amount:        500.00,
        Currency:      "EUR",
        PaymentMethod: "bank_deposit",
        SenderCountry: "DE",
    },
})

Response

type ProcessResponse struct {
    Allow          bool          // transaction is allowed
    AllowMessage   string        // message when allowed
    Rejected       bool          // transaction is rejected
    RejectMessage  string        // reason for rejection
    NeedInspect    bool          // transaction needs manual review
    InspectMessage string        // reason for inspection
    Score          int           // risk score
    Error          bool          // processing error occurred
    ErrorMessage   string        // error details
    ExecutionTime  time.Duration // rule execution duration
}

Transaction Fields

The Transaction struct supports 50+ fields across these categories:

Category	Fields
Core	Amount, Currency, Category, Date, Description
Payment	PaymentID, PaymentMethod, ReferenceID, MerchantID, MCC
Card	BinNumber, CardHolder, CardIssuer, CardLastFour, CardNetwork, CardToken, CardType
User	UserID, Email, Phone, IPAddress
Location	Country, Latitude, Longitude
Device	BrowserAgent, ConnectionType
Login	LastLoginIP, LastLoginTime
Profile	RegisteredIncome, IncomeMultiplier
Transfer	TransferType, TransferPurpose, SourceOfFunds, ExchangeRate, TargetCurrency, Relationship, IsFirstTransfer, TotalAmount24h, TransferCount24h
Sender	SenderName, SenderSurname, SenderCountry, SenderAddress, SenderIBAN, SenderIdentityPassport, SenderWalletID
Receiver	ReceiverName, ReceiverSurname, ReceiverCountry, ReceiverAddress, ReceiverIBAN, ReceiverIdentityPassport, ReceiverWalletID

Error Handling

API errors are returned as *aurora.APIError:

resp, err := client.Process.Execute(ctx, req)
if err != nil {
    var apiErr *aurora.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("API error %d: %s\n", apiErr.StatusCode, apiErr.Message)
    }
    log.Fatal(err)
}

License

MIT

Documentation

Index

• type APIError
  • func (e *APIError) Error() string
• type Client
  • func NewClient(apiKey string, opts ...Option) *Client
• type ErrorResponse
• type Option
  • func WithBaseURL(url string) Option
  • func WithHTTPClient(hc *http.Client) Option
  • func WithTimeout(d time.Duration) Option
• type ProcessRequest
• type ProcessResponse
• type ProcessService
  • func (s *ProcessService) Execute(ctx context.Context, req *ProcessRequest) (*ProcessResponse, error)
• type Transaction

Types

type APIError

type APIError struct {
	StatusCode int
	Message    string
}

APIError represents an error returned by the Aurora API.

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	Process *ProcessService
	// contains filtered or unexported fields
}

Client is the Aurora API client.

func NewClient

func NewClient(apiKey string, opts ...Option) *Client

NewClient creates a new Aurora API client.

type ErrorResponse

type ErrorResponse struct {
	Error string `json:"error"`
}

ErrorResponse represents an API error.

type Option

type Option func(*Client)

Option is a functional option for configuring the Client.

func WithBaseURL

func WithBaseURL(url string) Option

WithBaseURL sets the host URL (e.g. "https://api.example.com"). The API path (/api/v1) is appended automatically.

func WithHTTPClient

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient sets a custom HTTP client.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the HTTP client timeout.

type ProcessRequest

type ProcessRequest struct {
	RuleID        string       `json:"rule_id,omitempty"`
	RulesetID     string       `json:"ruleset_id,omitempty"`
	Transaction   *Transaction `json:"transaction,omitempty"`
	TransactionID string       `json:"transaction_id,omitempty"`
}

ProcessRequest represents a rule processing request.

type ProcessResponse

type ProcessResponse struct {
	Allow          bool          `json:"allow"`
	AllowMessage   string        `json:"allow_message,omitempty"`
	Error          bool          `json:"error"`
	ErrorMessage   string        `json:"error_message,omitempty"`
	ExecutionTime  time.Duration `json:"execution_time"`
	InspectMessage string        `json:"inspect_message,omitempty"`
	NeedInspect    bool          `json:"need_inspect"`
	RejectMessage  string        `json:"reject_message,omitempty"`
	Rejected       bool          `json:"rejected"`
	Score          int           `json:"score"`
}

ProcessResponse represents the result of rule processing.

type ProcessService

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

ProcessService handles rule processing operations.

func (*ProcessService) Execute

func (s *ProcessService) Execute(ctx context.Context, req *ProcessRequest) (*ProcessResponse, error)

Execute processes a transaction against a rule or ruleset and returns the result.

type Transaction

type Transaction struct {
	// Core transaction fields
	Amount      float64 `json:"amount,omitempty"`
	Currency    string  `json:"currency,omitempty"`
	Category    string  `json:"category,omitempty"`
	Date        string  `json:"date,omitempty"`        // format: 2006-02-01 15:04:05
	Description string  `json:"description,omitempty"` // description from payment gateway

	// Payment gateway fields
	PaymentID     string `json:"payment_id,omitempty"`
	PaymentMethod string `json:"payment_method,omitempty"` // cash_pickup, bank_deposit, mobile_wallet
	ReferenceID   string `json:"reference_id,omitempty"`
	MerchantID    string `json:"merchant_id,omitempty"`
	MCC           string `json:"mcc,omitempty"`

	// Card fields
	BinNumber    string `json:"bin_number,omitempty"`
	CardHolder   string `json:"card_holder,omitempty"` // card holder name
	CardIssuer   string `json:"card_issuer,omitempty"` // bank name
	CardLastFour string `json:"card_last_four,omitempty"`
	CardNetwork  string `json:"card_network,omitempty"` // visa, mastercard, american express, etc.
	CardToken    string `json:"card_token,omitempty"`   // hashed card bin non-reversible
	CardType     string `json:"card_type,omitempty"`    // debit, credit

	// User / customer fields
	UserID    string `json:"user_id,omitempty"`
	Email     string `json:"email,omitempty"`
	Phone     string `json:"phone,omitempty"`
	IPAddress string `json:"ip_address,omitempty"`

	// Location fields
	Country   string `json:"country,omitempty"` // derived from IP
	Latitude  string `json:"latitude,omitempty"`
	Longitude string `json:"longitude,omitempty"`

	// Device / connection fields
	BrowserAgent   string `json:"browser_agent,omitempty"`
	ConnectionType string `json:"connection_type,omitempty"` // wifi, mobile, ethernet, dsl, cable, etc.

	// Login history
	LastLoginIP   string `json:"last_login_ip,omitempty"`
	LastLoginTime string `json:"last_login_time,omitempty"`

	// Customer profile fields
	RegisteredIncome string `json:"registered_income,omitempty"`
	IncomeMultiplier string `json:"income_multiplier,omitempty"` // ratio of transaction amount to registered income

	// International money transfer fields
	TransferType     string `json:"transfer_type,omitempty"`
	TransferPurpose  string `json:"transfer_purpose,omitempty"` // family_support, education, business, medical, gift, other
	SourceOfFunds    string `json:"source_of_funds,omitempty"`  // salary, savings, business_income, investments, other
	ExchangeRate     string `json:"exchange_rate,omitempty"`
	TargetCurrency   string `json:"target_currency,omitempty"`
	Relationship     string `json:"relationship,omitempty"` // relationship to beneficiary
	IsFirstTransfer  string `json:"is_first_transfer,omitempty"`
	TotalAmount24h   string `json:"total_amount_24h,omitempty"`
	TransferCount24h string `json:"transfer_count_24h,omitempty"`

	// Sender fields
	SenderName             string `json:"sender_name,omitempty"`
	SenderSurname          string `json:"sender_surname,omitempty"`
	SenderCountry          string `json:"sender_country,omitempty"`
	SenderAddress          string `json:"sender_address,omitempty"`
	SenderIBAN             string `json:"sender_iban,omitempty"`
	SenderIdentityPassport string `json:"sender_identity_passport,omitempty"`
	SenderWalletID         string `json:"sender_wallet_id,omitempty"`

	// Receiver fields
	ReceiverName             string `json:"receiver_name,omitempty"`
	ReceiverSurname          string `json:"receiver_surname,omitempty"`
	ReceiverCountry          string `json:"receiver_country,omitempty"`
	ReceiverAddress          string `json:"receiver_address,omitempty"`
	ReceiverIBAN             string `json:"receiver_iban,omitempty"`
	ReceiverIdentityPassport string `json:"receiver_identity_passport,omitempty"`
	ReceiverWalletID         string `json:"receiver_wallet_id,omitempty"`
}

Transaction contains all the data fields that can be evaluated by rules.