govenmo

README

govenmo

A Venmo API client library in Golang.

See the Venmo API documentation here at https://developer.venmo.com/docs/oauth.

See README for usage or GoDoc.

Concepts

Since all Venmo API requests must be authenticated using a user's OAuth token, the basic object is the Account, which holds information for the authenticated user and tokens.

The library assumes you have already obtained a user access token somehow, for example using the OAuth flow. Helpers for completing the OAuth flow might be added in the future.

Usage

Create account with user access token

Obtaining the token is not included in the library but is easy to implement.

account := Account{
	AccessToken:  "...",
	RefreshToken: "...",
}

Fetch user information including balance

err := account.Refresh()
if err != nil {
	// Handle error ...
}

Pay someone

target := Target{}
target.Email = "kbrisson@gmail.com"
// OR target.Phone = "..."
// OR target.User.Id = "..."

sentPayment, err := account.PayOrCharge(target, 5.27, "Thanks for the govenmo library!", "public")
if err != nil {
	// Handle error ...
}

Refresh single payment

payment := &Payment{}
payment.Id = "1111111111111111111"
err = account.RefreshPayment(payment)
if err != nil {
	// Handle error ...
}

Fetch multiple payments

var updatedSince time.Time
payments, err := account.PaymentsSince(updatedSince)
if err != nil {
	// Handle error ...
}
for _, payment := range payments {
	// Each payment is an instance of Payment.
	log.Println("Found payment:", payment.Note)
}

Complete a charge

updatedPayment, err := account.CompletePayment("paymentID", "approve")
if err != nil {
	// Handle error ...
}

Deny a charge

updatedPayment, err := account.CompletePayment("paymentID", "deny")
if err != nil {
	// Handle error ...
}

Cancel a charge

updatedPayment, err := account.CompletePayment("paymentID", "cancel")
if err != nil {
	// Handle error ...
}

Fetch friends

friends, err := account.FetchFriends()
if err != nil {
	// Handle error ...
}

for _, friend := range friends {
	// Each friend is an instance of User.
	log.Println("Found friend:", friend.DisplayName)
}

Settings

Enable Venmo sandbox mode. Note that the Venmo sandbox doesn't behave exactly like the production API.

govenmo.Environment = "sandbox"

Use local sandbox

// In your client
govenmo.Environment = "local_sandbox"

Set a maximum payment or charge amount. (Why?... because when you first start using the production API you probably don't want a bug in your code to be able to send thousands of dollars.)

max := float64(50)
govenmo.MaxPayment = &max

Enable logging

govenmo.EnableLogging(nil)  // you can also pass a Logger

Run the local sandbox

The package local_sandbox mimics the real Venmo sandbox so that you don't have to hit it as much during testing.

Local sandbox returns the sandbox's hardcoded POST /payments responses. It also mimics GET /me and GET /payments/1111111111111111111. Other requests are proxied to the real sandbox and would require a valid token.

Like the real sandbox, it's not a replica of the Venmo production API and the values returned in the responses might not be the same as what you send in your request.

cd local_sandbox
go run main.go

The local sandbox must be running for the (limited) tests.

License

MIT. See LICENSE.md.

Documentation

Overview

Package govenmo provides a Venmo client. Use it to retrieve payments, fetch account infromation, make payments, complete charges, and list Venmo friends. You must provide your own OAuth tokens.

Index

• Constants
• Variables
• func EnableLogging(newLogger *log.Logger)
• type Account
  • func (a *Account) CompletePayment(paymentId, action string) (updatedPayment Payment, err error)
  • func (account *Account) FetchFriends() (friends []User, err error)
  • func (a *Account) PayOrCharge(target Target, amount float64, note string, audience string) (sentPayment Payment, err error)
  • func (a *Account) PaymentsSince(updatedSince time.Time) (payments []Payment, err error)
  • func (a *Account) Refresh() error
  • func (a *Account) RefreshPayment(payment *Payment) error
• type Error
• type Pagination
• type Payment
• type Target
• type Time
  • func (venmoTime *Time) Scan(src interface{}) error
  • func (venmoTime *Time) UnmarshalJSON(data []byte) error
  • func (venmoTime *Time) Value() (driver.Value, error)
• type User

Constants

const VenmoTimeFormat = "2006-01-02T15:04:05"

Variables

var Environment string = "production"

var MaxPayment *float64 = nil

Functions

func EnableLogging

func EnableLogging(newLogger *log.Logger)

Call EnableLogging to start logging. If you pass nil, a default logger will be used. Or, you can pass a Logger instance.

Types

type Account

type Account struct {
	AccessToken  string  `json:"access_token"`
	RefreshToken string  `json:"refresh_token"`
	Balance      float64 `json:"balance,string"`
	ExpiresIn    int64   `json:"expires_in"`
	TokenType    string  `json:"bearer"`
	User         `json:"user"`
}

Account is the basic type used for all API calls in govenmo. To make an API call you should create and Account with valid OAuth tokens. Account includes User.

func (*Account) CompletePayment

func (a *Account) CompletePayment(paymentId, action string) (updatedPayment Payment, err error)

CompletePayment allows you to 'approve', 'deny', or 'cancel' a pending charge request.

func (*Account) FetchFriends

func (account *Account) FetchFriends() (friends []User, err error)

FetchFriends retrieves all Venmo friends for an Account. It follows 'next' links.

func (*Account) PayOrCharge

func (a *Account) PayOrCharge(target Target, amount float64, note string, audience string) (sentPayment Payment, err error)

PayOrCharge creates a Venmo payment with the Account as a Actor.

func (*Account) PaymentsSince

func (a *Account) PaymentsSince(updatedSince time.Time) (payments []Payment, err error)

PaymentsSince fetches payments for an Account updated since a Time. Note that Venmo's 'updated at' logic is somewhat imprecise. There is currently no way to specify a limit, and PaymentsSince will follow 'next' links to retrieve the entire result set.

func (*Account) Refresh

func (a *Account) Refresh() error

Refresh retrieves account information, including balance and biographical info from the Venmo api.

func (*Account) RefreshPayment

func (a *Account) RefreshPayment(payment *Payment) error

RefreshPayment updates a Payment object with the most current state from the Venmo API. For multiple requests using PaymentsSince would be advisable.

type Error

type Error struct {
	Message string
	Code    int
}

Error stores error information from the Venmo API. This is used internally.

type Pagination

type Pagination struct {
	Next string
}

Pagination stores the 'next' link that indicates a continuation of the Venmo response. This may be incorrect when retrieved from the sandbox environments. This is used internally.

type Payment

type Payment struct {
	Id            string
	Status        string
	Action        string
	Actor         User
	Amount        float64
	Audience      string
	DateCompleted *Time `json:"date_completed"`
	DateCreated   *Time `json:"date_created"`
	Note          string
	Target        Target
	Fee           *float64
	Refund        *string
	Medium        string
}

Payment stores a payment retrieved from the Venmo API. See the Venmo API docs.

type Target

type Target struct {
	Email string
	Phone string
	Type  string
	User  User
}

type Time

type Time struct {
	time.Time
}

Venmo use a time format that's not compatible with Go's default. The custom Time type allows parsing their time format. It is also designed to be insertable into a Postgres DB (see Scan).

func (*Time) Scan

func (venmoTime *Time) Scan(src interface{}) error

func (*Time) UnmarshalJSON

func (venmoTime *Time) UnmarshalJSON(data []byte) error

func (*Time) Value

func (venmoTime *Time) Value() (driver.Value, error)

type User

type User struct {
	Username          string  `json:"username"`
	Id                string  `json:"id"`
	Email             *string `json:"email"`
	DisplayName       string  `json:"display_name"`
	FirstName         string  `json:"first_name"`
	LastName          string  `json:"last_name"`
	Phone             *string `json:"phone"`
	About             string  `json:"about"`
	ProfilePictureUrl string  `json:"profile_picture_url"`
	FriendsCount      int64   `json:"friends_count"`
	IsFriend          *bool   `json:"is_friend"`
	DateJoined        Time    `json:"date_joined"`
}