Documentation ¶
Overview ¶
Package starling provides a client for using the Starling API.
Usage:
import "github.com/astravexton/starling"
Construct a new Starling client, then call various methods on the API to access different functions of the Starling API. For example:
client := starling.NewClient(nil) // retrieve transactions for the current user txns, _, err := client.Transactions(ctx, nil)
The majority of the API calls will require you to pass in an access token:
ts := oauth2.StaticTokenSource( &oauth2.Token{AccessToken: "TOKEN"}, ) ctx := context.Background() tc := oauth2.NewClient(ctx, ts) client := starling.NewClient(tc)
The Starling API documentation is available at https://developer.starlingbank.com/docs.
Example (Account) ¶
package main import ( "context" "fmt" "log" "net/url" "os" "time" "github.com/astravexton/starling" "github.com/joho/godotenv" "golang.org/x/oauth2" ) func main() { godotenv.Load(".env") ts := oauth2.StaticTokenSource(&oauth2.Token{AccessToken: os.Getenv("STARLING_DEV_TOKEN")}) ctx := context.Background() tc := oauth2.NewClient(ctx, ts) baseURL, _ := url.Parse(starling.ProdURL) opts := starling.ClientOptions{BaseURL: baseURL} client := starling.NewClientWithOptions(tc, opts) acct, _, err := client.Accounts(ctx) if err != nil { log.Fatalf("Whoops: %v", err) } // Last month since := time.Now().AddDate(0, -1, 0) txns, _, err := client.Feed(ctx, acct[0].UID, acct[0].DefaultCategory, since) if err != nil { log.Fatalf("Whoops: %v", err) } for _, txn := range txns { fmt.Println(txn.TransactionTime, txn.Amount, txn.Amount.Currency, txn.Direction) } }
Output:
Example (Balance) ¶
package main import ( "context" "fmt" "log" "net/url" "os" "github.com/astravexton/starling" "github.com/joho/godotenv" "golang.org/x/oauth2" ) func main() { godotenv.Load(".env") ts := oauth2.StaticTokenSource(&oauth2.Token{AccessToken: os.Getenv("STARLING_DEV_TOKEN")}) ctx := context.Background() tc := oauth2.NewClient(ctx, ts) baseURL, _ := url.Parse(starling.ProdURL) opts := starling.ClientOptions{BaseURL: baseURL} client := starling.NewClientWithOptions(tc, opts) acct, _, err := client.Accounts(ctx) if err != nil { log.Fatalf("Whoops: %v", err) } bal, _, err := client.AccountBalance(ctx, acct[0].UID) if err != nil { log.Fatalf("Whoops: %v", err) } fmt.Printf("%v", bal) }
Output:
Example (Card) ¶
package main import ( "context" "fmt" "log" "net/url" "os" "github.com/astravexton/starling" "github.com/joho/godotenv" "golang.org/x/oauth2" ) func main() { godotenv.Load(".env") ts := oauth2.StaticTokenSource(&oauth2.Token{AccessToken: os.Getenv("STARLING_DEV_TOKEN")}) ctx := context.Background() tc := oauth2.NewClient(ctx, ts) baseURL, _ := url.Parse(starling.ProdURL) opts := starling.ClientOptions{BaseURL: baseURL} client := starling.NewClientWithOptions(tc, opts) cards, _, err := client.Cards(ctx) if err != nil { log.Fatalf("Whoops: %v", err) } for _, card := range cards { fmt.Println(card.PublicToken, card.Enabled) } }
Output:
Index ¶
- Constants
- func Validate(r *http.Request, publicKey string) (bool, error)
- type Account
- type AccountID
- type AccountSummary
- type Address
- type AddressHistory
- type Amount
- type AuthError
- type Balance
- type Card
- type Client
- func (c *Client) AccountBalance(ctx context.Context, accountUID string) (*Balance, *http.Response, error)
- func (c *Client) AccountID(ctx context.Context, accountUID string) (*AccountID, *http.Response, error)
- func (c *Client) Accounts(ctx context.Context) ([]AccountSummary, *http.Response, error)
- func (c *Client) AddressHistory(ctx context.Context) (*AddressHistory, *http.Response, error)
- func (c *Client) Cards(ctx context.Context) ([]Card, *http.Response, error)
- func (c *Client) CreateRecurringTransfer(ctx context.Context, accountUID string, uid string, ...) (string, *http.Response, error)
- func (c *Client) CreateSavingsGoal(ctx context.Context, accountUID string, uid string, sgReq SavingsGoalRequest) (*http.Response, error)
- func (c *Client) CreateScheduledPayment(ctx context.Context, p ScheduledPayment) (string, *http.Response, error)
- func (c *Client) DeleteDirectDebitMandate(ctx context.Context, uid string) (*http.Response, error)
- func (c *Client) DeleteRecurringTransfer(ctx context.Context, accountUID string, uid string) (*http.Response, error)
- func (c *Client) DeleteSavingsGoal(ctx context.Context, accountUID string, uid string) (*http.Response, error)
- func (c *Client) DirectDebitMandate(ctx context.Context, uid string) (*DirectDebitMandate, *http.Response, error)
- func (c *Client) DirectDebitMandates(ctx context.Context) ([]DirectDebitMandate, *http.Response, error)
- func (c *Client) Do(ctx context.Context, req *http.Request, v interface{}) (*http.Response, error)
- func (c *Client) EnableCard(ctx context.Context, cardUID string, en bool) (*http.Response, error)
- func (c *Client) EnableCardOption(ctx context.Context, cardUID, option string, en bool) (*http.Response, error)
- func (c *Client) Feed(ctx context.Context, act, cat string, since time.Time) ([]FeedItem, *http.Response, error)
- func (c *Client) FeedItem(ctx context.Context, act, cat, itm string) (*FeedItem, *http.Response, error)
- func (c *Client) MakeLocalPayment(ctx context.Context, p LocalPayment) (*http.Response, error)
- func (c *Client) NewRequest(method, urlStr string, body interface{}) (*http.Request, error)
- func (c *Client) RecurringTransfer(ctx context.Context, accountUID string, uid string) (*RecurringTransferRequest, *http.Response, error)
- func (c *Client) SavingsGoal(ctx context.Context, accountUID string, uid string) (*SavingsGoal, *http.Response, error)
- func (c *Client) SavingsGoalPhoto(ctx context.Context, accountUID string, uid string) (*Photo, *http.Response, error)
- func (c *Client) SavingsGoals(ctx context.Context, accountUID string) ([]SavingsGoal, *http.Response, error)
- func (c *Client) ScheduledPayments(ctx context.Context) ([]PaymentOrder, *http.Response, error)
- func (c *Client) TransferFromSavingsGoal(ctx context.Context, accountUID string, goalUID string, a Amount) (string, *http.Response, error)
- func (c *Client) TransferToSavingsGoal(ctx context.Context, accountUID string, goalUID string, a Amount) (string, *http.Response, error)
- type ClientOptions
- type CurrencyFlag
- type DateRange
- type DirectDebitMandate
- type Error
- type ErrorDetail
- type Errors
- type FeedItem
- type FeedRoundUp
- type LocalPayment
- type MasterCardFeedItem
- type PaymentAmount
- type PaymentOrder
- type Photo
- type RecurrenceRule
- type RecurringTransferRequest
- type SavingsGoal
- type SavingsGoalRequest
- type ScheduledPayment
- type SpendingCategory
- type WebHookFeedItem
- type WebHookPayload
Examples ¶
Constants ¶
const ( // ProdURL for the production instance of the Starling API ProdURL = "https://api.starlingbank.com/" // SandboxURL for the sandbox instance of the Starling API SandboxURL = "https://api-sandbox.starlingbank.com/" )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Account ¶
type Account struct { UID string `json:"id"` Name string `json:"name"` AccountNumber string `json:"accountNumber"` SortCode string `json:"sortCode"` Currency string `json:"currency"` IBAN string `json:"iban"` BIC string `json:"bic"` CreatedAt string `json:"createdAt"` }
Account represents bank account details
type AccountID ¶
type AccountID struct { ID string `json:"accountIdentifier"` BankID string `json:"bankIdentifier"` IBAN string `json:"iban"` BIC string `json:"bic"` }
AccountID represents the identifiers for an individual account
type AccountSummary ¶
type AccountSummary struct { UID string `json:"accountUid"` DefaultCategory string `json:"defaultCategory"` Currency string `json:"currency"` CreatedAt string `json:"createdAt"` }
AccountSummary represents the basic account details
type Address ¶
type Address struct { Line1 string `json:"line1"` Line2 string `json:"line2"` Line3 string `json:"line3"` PostTown string `json:"postTown"` CountryCode string `json:"countryCode"` PostCode string `json:"postCode"` }
Address is the physical address of the customer
type AddressHistory ¶
type AddressHistory struct { Current Address `json:"current"` Previous []Address `json:"previous"` }
AddressHistory are the current and previous physical addresses
type Amount ¶
type Amount struct { Currency string `json:"currency"` // ISO-4217 3 character currency code MinorUnits int64 `json:"minorUnits"` // Amount in the minor units of the given currency; eg pence in GBP, cents in EUR }
Amount represents the value and currency of a monetary amount
type Balance ¶
type Balance struct { Cleared Amount `json:"clearedBalance"` Effective Amount `json:"effectiveBalance"` PendingTxns Amount `json:"pendingTransactions"` Overdraft Amount `json:"acceptedOverdraft"` Amount Amount `json:"amount"` }
Balance represents the balance on an account
type Card ¶
type Card struct { CardUID string `json:"cardUid"` PublicToken string `json:"publicToken"` Enabled bool `json:"enabled"` Cancelled bool `json:"cancelled"` ActivationRequested bool `json:"activationRequested"` Activated bool `json:"activated"` WalletNotificationsEnaled bool `json:"walletNotificationsEnabled"` PosEnabled bool `json:"posEnabled"` AtmEnabled bool `json:"atmEnabled"` OnlineEnabled bool `json:"onlineEnabled"` MobileWalletEnabled bool `json:"mobileWalletEnabled"` GamblingEnabled bool `json:"gamblingEnabled"` MagStripeEnabled bool `json:"magStripeEnabled"` EndOfCardNumber string `json:"endOfCardNumber"` CurrencyFlags []CurrencyFlag `json:"currencyFlags"` CardAssociationUID string `json:"cardAssociationUid"` GamblingToBeEnabledAt time.Time `json:"gamblingToBeEnabledAt"` }
Card represents card details
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client holds configuration items for the Starling client and provides methods that interact with the Starling API.
func NewClient ¶
NewClient returns a new Starling API client. If a nil httpClient is provided, http.DefaultClient will be used. To use API methods which require authentication, provide an http.Client that will perform the authentication for you (such as that provided by the golang.org/x/oauth2 library). Inspiration: https://github.com/google/go-github/blob/master/github/github.go
func NewClientWithOptions ¶
func NewClientWithOptions(cc *http.Client, opts ClientOptions) *Client
NewClientWithOptions takes ClientOptions, configures and returns a new client.
func (*Client) AccountBalance ¶
func (c *Client) AccountBalance(ctx context.Context, accountUID string) (*Balance, *http.Response, error)
AccountBalance returns the the account balance for the current customer.
func (*Client) AccountID ¶
func (c *Client) AccountID(ctx context.Context, accountUID string) (*AccountID, *http.Response, error)
AccountID returns the identifiers for an individual account
func (*Client) AddressHistory ¶
AddressHistory returns the the customer details for the current customer.
func (*Client) CreateRecurringTransfer ¶
func (c *Client) CreateRecurringTransfer(ctx context.Context, accountUID string, uid string, rtr RecurringTransferRequest) (string, *http.Response, error)
CreateRecurringTransfer sets up the recurring transfer for a savings goal. It takes the UID of the savings goal, along with a RecurringTransferRequest and returns the UID of the recurring transfer. It also returns the http response in case this is required for further processing. An error is returned on failure.
func (*Client) CreateSavingsGoal ¶
func (c *Client) CreateSavingsGoal(ctx context.Context, accountUID string, uid string, sgReq SavingsGoalRequest) (*http.Response, error)
CreateSavingsGoal creates an individual savings goal based on a UID. It returns the http response in case this is required for further processing. An error will be returned if the API is unable to create the goal.
func (*Client) CreateScheduledPayment ¶
func (c *Client) CreateScheduledPayment(ctx context.Context, p ScheduledPayment) (string, *http.Response, error)
CreateScheduledPayment creates a scheduled payment. It returns the UID for the scheduled payment.
func (*Client) DeleteDirectDebitMandate ¶
DeleteDirectDebitMandate deletes an individual DirectDebitMandate for the current customer.
func (*Client) DeleteRecurringTransfer ¶
func (c *Client) DeleteRecurringTransfer(ctx context.Context, accountUID string, uid string) (*http.Response, error)
DeleteRecurringTransfer deletes the recurring transfer for a savings goal. It takes the UID of the savings goal and returns no content. It returns the http response in case this is required for further processing. An error is returned on failure.
func (*Client) DeleteSavingsGoal ¶
func (c *Client) DeleteSavingsGoal(ctx context.Context, accountUID string, uid string) (*http.Response, error)
DeleteSavingsGoal deletes a savings goal for the current customer. It returns http.StatusNoContent on success. No payload is returned.
func (*Client) DirectDebitMandate ¶
func (c *Client) DirectDebitMandate(ctx context.Context, uid string) (*DirectDebitMandate, *http.Response, error)
DirectDebitMandate returns a single DirectDebitMandate for the current customer.
func (*Client) DirectDebitMandates ¶
func (c *Client) DirectDebitMandates(ctx context.Context) ([]DirectDebitMandate, *http.Response, error)
DirectDebitMandates returns the DirectDebitMandates for the current customer.
func (*Client) Do ¶
Do sends a request and returns the response. An error is returned if the request cannot be sent or if the API returns an error. If a response is received, the body response body is decoded and stored in the value pointed to by v. Inspiration: https://github.com/google/go-github/blob/master/github/github.go
func (*Client) EnableCard ¶
EnableCard enables a card.
func (*Client) EnableCardOption ¶
func (c *Client) EnableCardOption(ctx context.Context, cardUID, option string, en bool) (*http.Response, error)
EnableCardOption enables a specific card option with the list of valid options being: atm, gambling, mag-stripe, mobile-wallet, online, pos
func (*Client) Feed ¶
func (c *Client) Feed(ctx context.Context, act, cat string, since time.Time) ([]FeedItem, *http.Response, error)
Feed returns a slice of Items for a given account and category. It returns an error if unable to retrieve the feed.
func (*Client) FeedItem ¶
func (c *Client) FeedItem(ctx context.Context, act, cat, itm string) (*FeedItem, *http.Response, error)
FeedItem returns a feed Item for a given account and category. It returns an error if unable to retrieve the feed Item. Note: FeedItem uses the v2 API which is still under active development.
func (*Client) MakeLocalPayment ¶
MakeLocalPayment creates a local payment.
func (*Client) NewRequest ¶
NewRequest creates an HTTP Request. The client baseURL is checked to confirm that it has a trailing slash. A relative URL should be provided without the leading slash. If a non-nil body is provided it will be JSON encoded and included in the request. Inspiration: https://github.com/google/go-github/blob/master/github/github.go
func (*Client) RecurringTransfer ¶
func (c *Client) RecurringTransfer(ctx context.Context, accountUID string, uid string) (*RecurringTransferRequest, *http.Response, error)
RecurringTransfer returns the recurring savings for savings goal based on a UID. It also returns the http response in case this is required for further processing. An error will be returned if unable to retrieve the recurring savings set-up from the API.
func (*Client) SavingsGoal ¶
func (c *Client) SavingsGoal(ctx context.Context, accountUID string, uid string) (*SavingsGoal, *http.Response, error)
SavingsGoal returns an individual savings goal based on a UID. It also returns the http response in case this is required for further processing. An error will be returned if unable to retrieve goals from the API.
func (*Client) SavingsGoalPhoto ¶
func (c *Client) SavingsGoalPhoto(ctx context.Context, accountUID string, uid string) (*Photo, *http.Response, error)
SavingsGoalPhoto returns the photo for savings goal based on a UID. It also returns the http response in case this is required for further processing. An error will be returned if unable to retrieve the photo from the API.
func (*Client) SavingsGoals ¶
func (c *Client) SavingsGoals(ctx context.Context, accountUID string) ([]SavingsGoal, *http.Response, error)
SavingsGoals returns the savings goals for the current user. It also returns the http response in case this is required for further processing. It is possible that the user has no savings goals in which case a nil value will be returned. An error will be returned if unable to retrieve goals from the API.
func (*Client) ScheduledPayments ¶
ScheduledPayments retrieves a list of all the payment orders on the customer account. These may be orders for previous immediate payments or scheduled payment orders for future or on-going payments.
func (*Client) TransferFromSavingsGoal ¶
func (c *Client) TransferFromSavingsGoal(ctx context.Context, accountUID string, goalUID string, a Amount) (string, *http.Response, error)
TransferFromSavingsGoal transfers money out of a savings goal. It returns the http response in case this is required for further processing. An error will be returned if the API is unable to transfer the amount out of the savings goal.
func (*Client) TransferToSavingsGoal ¶
func (c *Client) TransferToSavingsGoal(ctx context.Context, accountUID string, goalUID string, a Amount) (string, *http.Response, error)
TransferToSavingsGoal transfers money into a savings goal. It returns the http response in case this is required for further processing. An error will be returned if the API is unable to transfer the amount into the savings goal.
type ClientOptions ¶
ClientOptions is a set of options that can be specified when creating a Starling client
type CurrencyFlag ¶
type DateRange ¶
DateRange holds two dates that represent a range. It is typically used when providing a range when querying the API.
type DirectDebitMandate ¶
type DirectDebitMandate struct { UID string `json:"uid"` Reference string `json:"reference"` Status string `json:"status"` Source string `json:"source"` Created string `json:"created"` Cancelled string `json:"cancelled"` OriginatorName string `json:"originatorName"` OriginatorUID string `json:"originatorUid"` }
DirectDebitMandate represents a single mandate
type ErrorDetail ¶
type ErrorDetail struct {
Message string `json:"message"`
}
ErrorDetail holds the details of an error message
type FeedItem ¶
type FeedItem struct { FeedItemUID string `json:"feedItemUid"` CategoryUID string `json:"categoryUid"` AccountUID string `json:"accountUid"` Amount Amount `json:"amount"` SourceAmount Amount `json:"sourceAmount"` Direction string `json:"direction"` UpdatedAt time.Time `json:"updatedAt"` TransactionTime time.Time `json:"transactionTime"` SettlementTime time.Time `json:"settlementTime"` RetryAllocationUntilTime time.Time `json:"retryAllocationUntilTime"` Source string `json:"source"` SourceSubType string `json:"sourceSubType"` Status string `json:"status"` TransactionApplicationUserUID string `json:"transactionApplicationUserUid"` CounterPartyType string `json:"counterPartyType"` CounterPartyUID string `json:"counterPartyUid"` CounterPartyName string `json:"counterPartyName"` CounterPartySubEntityUID string `json:"counterPartySubEntityUid"` CounterPartySubEntityName string `json:"counterPartySubEntityName"` CounterPartySubEntityIdentifier string `json:"counterPartySubEntityIdentifier"` CounterPartSubEntitySubIdentifier string `json:"counterPartSubEntitySubIdentifier"` ExchangeRate float64 `json:"exchangeRate"` TotalFees float64 `json:"totalFees"` TotalFeeAmount Amount `json:"totalFeeAmount"` Reference string `json:"reference"` Country string `json:"country"` SpendingCategory string `json:"spendingCategory"` UserNote string `json:"userNote"` RoundUp FeedRoundUp `json:"roundUp"` HasAttachment bool `json:"hasAttachment"` ReceiptPresent bool `json:"receiptPresent"` }
Item is a single customer transaction in their feed
type FeedRoundUp ¶
type LocalPayment ¶
type LocalPayment struct { Payment PaymentAmount `json:"payment"` DestinationAccountUID string `json:"destinationAccountUid"` Reference string `json:"reference"` }
LocalPayment represents a local payment
type MasterCardFeedItem ¶
type MasterCardFeedItem struct { MerchantIdentifier string `json:"merchantIdentifier"` MCC int32 `json:"mcc"` PosTimestamp time.Time `json:"posTimestamp"` CardLast4 string `json:"cardLast4"` }
MasterCardFeedItem defines the structure of the MasterCard feed item
type PaymentAmount ¶
PaymentAmount represents the currency and amount of a payment
type PaymentOrder ¶
type PaymentOrder struct { UID string `json:"paymentOrderId"` Currency string `json:"currency"` Amount float64 `json:"amount"` Reference string `json:"reference"` ReceivingContactAccountUID string `json:"receivingContactAccountId"` RecipientName string `json:"recipientName"` Immediate bool `json:"immediate"` RecurrenceRule RecurrenceRule `json:"recurrenceRule"` StartDate string `json:"startDate"` NextDate string `json:"nextDate"` CancelledAt string `json:"cancelledAt"` PaymentType string `json:"paymentType"` MandateUID string `json:"mandateId"` }
PaymentOrder is a single PaymentOrder
type Photo ¶
type Photo struct {
Base64EncodedPhoto string `json:"base64EncodedPhoto"` // A text (base 64) encoded picture to associate with the savings goal
}
Photo is a photo associated to a savings goal
type RecurrenceRule ¶
type RecurrenceRule struct { StartDate string `json:"startDate"` Frequency string `json:"frequency"` Interval int32 `json:"interval,omitempty"` Count int32 `json:"count,omitempty"` UntilDate string `json:"untilDate,omitempty"` WeekStart string `json:"weekStart"` }
RecurrenceRule defines the pattern for recurring events
type RecurringTransferRequest ¶
type RecurringTransferRequest struct { UID string `json:"transferUid,omitempty"` RecurrenceRule RecurrenceRule `json:"recurrenceRule"` Amount `json:"currencyAndAmount"` }
RecurringTransferRequest represents a request to create scheduled payment into a savings goal
type SavingsGoal ¶
type SavingsGoal struct { UID string `json:"uid"` // Unique identifier of the savings goal Name string `json:"name"` // Name of the savings goal Target Amount `json:"target"` TotalSaved Amount `json:"totalSaved"` SavedPercentage int32 `json:"savedPercentage"` // Percentage of target currently deposited in the savings goal }
SavingsGoal is a goal defined by a customer to hold savings
type SavingsGoalRequest ¶
type SavingsGoalRequest struct { Name string `json:"name"` // Name of the savings goal Currency string `json:"currency"` // ISO-4217 3 character currency code of the savings goal Target Amount `json:"target"` Base64EncodedPhoto string `json:"base64EncodedPhoto"` // A text (base 64) encoded picture to associate with the savings goal }
SavingsGoalRequest is a request to create a new savings goal
type ScheduledPayment ¶
type ScheduledPayment struct { LocalPayment Schedule RecurrenceRule `json:"recurrenceRule"` }
ScheduledPayment represents a scheduled payment
type SpendingCategory ¶
type SpendingCategory struct {
SpendingCategory string `json:"spendingCategory"`
}
SpendingCategory is the category associated with a transaction
type WebHookFeedItem ¶
type WebHookFeedItem struct { FeedItem AccountUID string `json:"accountUid"` FeedItemFailureReason string `json:"feedItemFailureReason"` MasterCardFeedDetails MasterCardFeedItem `json:"masterCardFeedDetails"` }
WebHookFeedItem defines the structure of the Starling web hook feed item
type WebHookPayload ¶
type WebHookPayload struct { WebhookEventUID string `json:"webhookEventUid"` EventTimestamp time.Time `json:"eventTimestamp"` Content WebHookFeedItem `json:"content"` AccountHolderUID string `json:"accountHolderUid"` }
WebHookPayload defines the structure of the Starling web hook payload