yellowcard

package
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Jun 19, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

Documentation

Overview

Package yellowcard provides types and client for the YellowCard payment API.

Index

Constants

View Source 
const (
	StatusCreated           = "created"
	StatusPendingApproval   = "pending_approval"
	StatusPendingSettlement = "pending_settlement" // Direct settlement only: awaiting crypto payment
	StatusProcess           = "process"
	StatusProcessing        = "processing"
	StatusPendingLiquidity  = "pending_liquidity" // Fiat mode: low YC balance, auto-retries 2hrs
	StatusPending           = "pending"
	StatusComplete          = "complete"
	StatusFailed            = "failed"
	StatusExpired           = "expired"
	StatusCancelled         = "cancelled"
	StatusPendingRefund     = "pending_refund"
	StatusRefundProcessing  = "refund_processing"
	StatusRefunded          = "refunded"
	StatusRefundFailed      = "refund_failed"
)

YellowCard payment event statuses (full lifecycle). See: https://docs.yellowcard.engineering/docs/events-api

View Source 
const (
	DisbursementPending         = "pending"
	DisbursementDirectSubmitted = "direct_submitted"
	DisbursementCryptoSent      = "crypto_sent"
	DisbursementFiatSubmitted   = "fiat_submitted"
	DisbursementProcessing      = "processing"
	DisbursementComplete        = "complete"
	DisbursementRefundPending   = "refund_pending"
	DisbursementRefundReceived  = "refund_received"
	DisbursementFailed          = "failed"
)

Internal disbursement tracking statuses (our system, not YellowCard).

View Source 
const (
	SettlementMethodDirect = "direct"
	SettlementMethodFiat   = "fiat"
)

Settlement method constants.

View Source 
const (
	ChannelTypeMomo = "momo"
	ChannelTypeBank = "bank"
)

Channel type constants.

View Source 
const (
	CustomerTypeRetail      = "retail"
	CustomerTypeInstitution = "institution"
)

Customer type constants.

View Source 
const (
	EventDisbursementComplete     = "DISBURSEMENT.COMPLETE"
	EventDisbursementFailed       = "DISBURSEMENT.FAILED"
	EventPaymentPendingSettlement = "PAYMENT.PENDING_SETTLEMENT"
	EventPaymentComplete          = "PAYMENT.COMPLETE"
	EventPaymentFailed            = "PAYMENT.FAILED"
	EventCollectionComplete       = "COLLECTION.COMPLETE"
	EventCryptoDeposit            = "CRYPTO.DEPOSIT"
)

Webhook event constants.

View Source 
const (
	CountryKenya   = "KE"
	CountryNigeria = "NG"
	CountryGhana   = "GH"
	CountryUganda  = "UG"
)

Country code constants (ISO 3166-2).

View Source 
const (
	CurrencyKES = "KES"
	CurrencyNGN = "NGN"
	CurrencyGHS = "GHS"
	CurrencyUGX = "UGX"
	CurrencyUSD = "USD"
)

Currency code constants (ISO 4217).

View Source 
const (
	CryptoCurrencyUSDC     = "USDC"
	CryptoCurrencyUSDT     = "USDT"
	CryptoNetworkXLM       = "XLM"
	CryptoNetworkTRC20     = "TRC20"
	CryptoNetworkERC20     = "ERC20"
	CryptoNetworkLightning = "LIGHTNING"
)

Cryptocurrency constants for SettlementInfo.

View Source 
const (
	RampTypeWithdraw = "withdraw"
)

Ramp type constants.

Variables

This section is empty.

Functions

func ParseStellarWalletAddress 

func ParseStellarWalletAddress(combined string) (address string, memo string, err error)

ParseStellarWalletAddress splits a YellowCard combined wallet address into the Stellar address and memo components. YellowCard returns XLM addresses in the format "{stellar_address}_{memo}" e.g.: 

"GDTY5CDJDVEI4RF5RE7HNIT26FCNA3DNXFNYNMZ6TNTLQTL34YG5NL5O_4084650351"

Types

type APIError 

type APIError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

APIError represents an error response from the YellowCard API.

type Account 

type Account struct {
	Available    float64 `json:"available"`
	Currency     string  `json:"currency"`
	CurrencyType string  `json:"currencyType"`
}

Account represents a YellowCard business account balance.

type AccountsResponse 

type AccountsResponse struct {
	Accounts []Account `json:"accounts"`
}

AccountsResponse wraps the accounts array returned from the account endpoint.

type Channel 

type Channel struct {
	ID                      string                 `json:"id"`
	VendorID                string                 `json:"vendorId"`
	Country                 string                 `json:"country"`
	Currency                string                 `json:"currency"`
	CountryCurrency         string                 `json:"countryCurrency"`
	ChannelType             string                 `json:"channelType"`
	RampType                string                 `json:"rampType"`
	Status                  string                 `json:"status"`
	APIStatus               string                 `json:"apiStatus"`
	WidgetStatus            string                 `json:"widgetStatus"`
	SettlementType          string                 `json:"settlementType"`
	EstimatedSettlementTime int                    `json:"estimatedSettlementTime"`
	Min                     float64                `json:"min"`
	Max                     float64                `json:"max"`
	WidgetMin               float64                `json:"widgetMin,omitempty"`
	WidgetMax               float64                `json:"widgetMax,omitempty"`
	FeeLocal                float64                `json:"feeLocal"`
	FeeUSD                  float64                `json:"feeUSD"`
	Balancer                map[string]interface{} `json:"balancer,omitempty"`
	CreatedAt               string                 `json:"createdAt"`
	UpdatedAt               string                 `json:"updatedAt"`
}

Channel represents a YellowCard payment channel such as bank transfer or mobile money.

func FilterActiveChannels 

func FilterActiveChannels(channels []Channel, channelType string) []Channel

FilterActiveChannels returns channels that are active and match the specified type.

type ChannelsResponse 

type ChannelsResponse struct {
	Channels []Channel `json:"channels"`
}

ChannelsResponse wraps the channels array returned from the YellowCard channels endpoint.

type Destination 

type Destination struct {
	AccountNumber string `json:"accountNumber"`
	AccountName   string `json:"accountName"`
	AccountType   string `json:"accountType"`
	NetworkID     string `json:"networkId"`
	NetworkName   string `json:"networkName,omitempty"`
	AccountBank   string `json:"accountBank,omitempty"`
	Country       string `json:"country,omitempty"`
	PhoneNumber   string `json:"phoneNumber,omitempty"`
}

Destination represents where funds should be sent.

type Network 

type Network struct {
	ID                       string          `json:"id"`
	Name                     string          `json:"name"`
	Code                     json.RawMessage `json:"code"`
	Country                  string          `json:"country"`
	Status                   string          `json:"status"`
	AccountNumberType        string          `json:"accountNumberType"`
	CountryAccountNumberType string          `json:"countryAccountNumberType"`
	ChannelIDs               []string        `json:"channelIds"`
	CreatedAt                string          `json:"createdAt"`
	UpdatedAt                string          `json:"updatedAt"`
}

Network represents a bank or mobile money operator in the YellowCard system. The Code field is polymorphic: a plain string for MoMo networks (e.g. "M PESA") or a JSON object (branch-code map) for bank networks. Use CodeString() to safely extract the string form.

func FilterActiveNetworks 

func FilterActiveNetworks(networks []Network) []Network

FilterActiveNetworks returns networks that are active.

func FindNetworksByChannel 

func FindNetworksByChannel(networks []Network, channelID string) []Network

FindNetworksByChannel returns networks associated with a specific channel ID.

func (*Network) CodeString 

func (n *Network) CodeString() string

CodeString returns the network code as a string. For MoMo networks, this is the plain code (e.g. "M PESA"). For bank networks where code is an object, it returns an empty string.

type NetworksResponse 

type NetworksResponse struct {
	Networks []Network `json:"networks"`
}

NetworksResponse wraps the networks array returned from the YellowCard networks endpoint.

type Options 

type Options struct {
	ChannelID      string      `json:"channel_id"`
	Destination    Destination `json:"destination"`
	Sender         Sender      `json:"sender"`
	Reason         string      `json:"reason"`
	CustomerUID    string      `json:"customer_uid"`
	CustomerType   string      `json:"customer_type"`
	IdempotencyKey string      `json:"idempotency_key"`
}

Options contains YellowCard-specific payment options passed via InitializePaymentRequest.

type PaymentDetails 

type PaymentDetails struct {
	ID               string          `json:"id"`
	ChannelID        string          `json:"channelId"`
	SequenceID       string          `json:"sequenceId"`
	PartnerID        string          `json:"partnerId"`
	SessionID        string          `json:"sessionId,omitempty"`
	Currency         string          `json:"currency"`
	Country          string          `json:"country"`
	Amount           float64         `json:"amount"`
	ConvertedAmount  float64         `json:"convertedAmount"`
	Rate             float64         `json:"rate"`
	Reason           string          `json:"reason"`
	Status           string          `json:"status"`
	DirectSettlement bool            `json:"directSettlement"`
	Sender           Sender          `json:"sender"`
	Destination      Destination     `json:"destination"`
	SettlementInfo   *SettlementInfo `json:"settlementInfo,omitempty"`
	CreatedAt        string          `json:"createdAt"`
	UpdatedAt        string          `json:"updatedAt"`
	ExpiresAt        string          `json:"expiresAt"`
}

PaymentDetails contains full details of a payment retrieved by ID.

type PaymentRequest 

type PaymentRequest struct {
	ChannelID        string          `json:"channelId"`
	SequenceID       string          `json:"sequenceId"`
	Reason           string          `json:"reason"`
	Sender           Sender          `json:"sender"`
	Destination      Destination     `json:"destination"`
	CustomerUID      string          `json:"customerUID"`
	CustomerType     string          `json:"customerType"`
	ForceAccept      bool            `json:"forceAccept"`
	Amount           float64         `json:"amount,omitempty"`
	LocalAmount      float64         `json:"localAmount,omitempty"`
	Currency         string          `json:"currency,omitempty"`
	Country          string          `json:"country,omitempty"`
	DirectSettlement bool            `json:"directSettlement,omitempty"`
	SettlementInfo   *SettlementInfo `json:"settlementInfo,omitempty"`
}

PaymentRequest represents a disbursement request to the YellowCard API. Either Amount (USD) or LocalAmount must be specified, not both. ForceAccept is always set to true to skip the approval window.

For direct settlement, set DirectSettlement=true and include SettlementInfo with CryptoCurrency, CryptoNetwork, and CryptoAmount. YellowCard returns these plus WalletAddress, CryptoUSDRate, CryptoLocalRate, and ExpiresAt.

type PaymentResponse 

type PaymentResponse struct {
	ID                    string          `json:"id"`
	ChannelID             string          `json:"channelId"`
	SequenceID            string          `json:"sequenceId"`
	Currency              string          `json:"currency"`
	Country               string          `json:"country"`
	Amount                float64         `json:"amount"`
	ConvertedAmount       float64         `json:"convertedAmount"`
	Rate                  float64         `json:"rate"`
	Reason                string          `json:"reason"`
	Status                string          `json:"status"`
	ForceAccept           bool            `json:"forceAccept"`
	DirectSettlement      bool            `json:"directSettlement"`
	PartnerID             string          `json:"partnerId"`
	RequestSource         string          `json:"requestSource"`
	Attempt               int             `json:"attempt"`
	FiatWallet            string          `json:"fiatWallet"`
	Sender                Sender          `json:"sender"`
	Destination           Destination     `json:"destination"`
	SettlementInfo        *SettlementInfo `json:"settlementInfo,omitempty"`
	Reference             string          `json:"reference,omitempty"`
	NetworkFeeAmountUSD   float64         `json:"networkFeeAmountUSD,omitempty"`
	NetworkFeeAmountLocal float64         `json:"networkFeeAmountLocal,omitempty"`
	ServiceFeeAmountUSD   float64         `json:"serviceFeeAmountUSD,omitempty"`
	ServiceFeeAmountLocal float64         `json:"serviceFeeAmountLocal,omitempty"`
	PartnerFeeAmountUSD   float64         `json:"partnerFeeAmountUSD,omitempty"`
	PartnerFeeAmountLocal float64         `json:"partnerFeeAmountLocal,omitempty"`
	CreatedAt             string          `json:"createdAt"`
	UpdatedAt             string          `json:"updatedAt"`
	ExpiresAt             string          `json:"expiresAt"`
}

PaymentResponse is returned when a payment is successfully submitted.

type Rate 

type Rate struct {
	Buy       float64 `json:"buy"`
	Sell      float64 `json:"sell"`
	Locale    string  `json:"locale"`
	RateID    string  `json:"rateId"`
	Code      string  `json:"code"`
	UpdatedAt string  `json:"updatedAt"`
}

Rate represents exchange rate information between USD and a local currency.

type RatesResponse 

type RatesResponse struct {
	Rates []Rate `json:"rates"`
}

RatesResponse wraps the rates array returned from the YellowCard rates endpoint.

type Sender 

type Sender struct {
	Name               string `json:"name,omitempty"`
	Country            string `json:"country,omitempty"`
	Phone              string `json:"phone,omitempty"`
	Address            string `json:"address,omitempty"`
	DOB                string `json:"dob,omitempty"`
	Email              string `json:"email,omitempty"`
	IDNumber           string `json:"idNumber,omitempty"`
	IDType             string `json:"idType,omitempty"`
	AdditionalIDType   string `json:"additionalIdType,omitempty"`
	AdditionalIDNumber string `json:"additionalIdNumber,omitempty"`
	BusinessID         string `json:"businessId,omitempty"`
	BusinessName       string `json:"businessName,omitempty"`
}

Sender contains KYC details for the payment sender. Required fields depend on CustomerType: "retail" requires personal info, "institution" requires BusinessID and BusinessName.

type SettlementInfo 

type SettlementInfo struct {
	WalletAddress   string  `json:"walletAddress,omitempty"`
	CryptoCurrency  string  `json:"cryptoCurrency"`
	CryptoNetwork   string  `json:"cryptoNetwork"`
	CryptoAmount    float64 `json:"cryptoAmount,omitempty"`
	CryptoUSDRate   float64 `json:"cryptoUSDRate,omitempty"`
	CryptoLocalRate float64 `json:"cryptoLocalRate,omitempty"`
	WalletTag       string  `json:"walletTag,omitempty"`
	LnInvoice       string  `json:"lnInvoice,omitempty"`
	ExpiresAt       string  `json:"expiresAt,omitempty"`
}

SettlementInfo contains crypto settlement details for direct settlement mode.

In the request, specify CryptoCurrency, CryptoNetwork, and CryptoAmount. In the response, YellowCard populates these plus WalletAddress, CryptoUSDRate, CryptoLocalRate, and ExpiresAt.

For Stellar/USDC, YellowCard returns the address and memo as a combined string: 

"walletAddress": "GDTY5CDJ...NL5O_4084650351"

Format: {stellar_address}_{memo} — use ParseStellarWalletAddress() to split.

type WebhookEvent 

type WebhookEvent struct {
	Event     string         `json:"event"`
	Timestamp string         `json:"timestamp"`
	Data      WebhookPayload `json:"data"`
}

WebhookEvent represents an incoming webhook payload from YellowCard.

type WebhookPayload 

type WebhookPayload struct {
	PaymentID        string          `json:"id"`
	SequenceID       string          `json:"sequenceId"`
	Status           string          `json:"status"`
	Amount           float64         `json:"amount"`
	ConvertedAmount  float64         `json:"convertedAmount"`
	Currency         string          `json:"currency"`
	Country          string          `json:"country"`
	Rate             float64         `json:"rate"`
	DirectSettlement bool            `json:"directSettlement"`
	SettlementInfo   *SettlementInfo `json:"settlementInfo,omitempty"`
	CreatedAt        string          `json:"createdAt"`
	UpdatedAt        string          `json:"updatedAt"`
}

WebhookPayload contains the payment data embedded in a webhook event.

type YellowcardAdapter 

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

YellowcardAdapter implements the payment.PaymentProvider interface for YellowCard.

func NewYellowcardAdapter 

func NewYellowcardAdapter(publicKey, secretKey, baseURL string) *YellowcardAdapter

NewYellowcardAdapter creates a new YellowCard adapter with HMAC request signing.

func (*YellowcardAdapter) GetAccount 

func (y *YellowcardAdapter) GetAccount(ctx context.Context) ([]Account, error)

GetAccount retrieves account balances.

func (*YellowcardAdapter) GetAvailableBalance 

func (y *YellowcardAdapter) GetAvailableBalance(ctx context.Context) (float64, error)

GetAvailableBalance returns the available USD balance.

func (*YellowcardAdapter) GetChannels 

func (y *YellowcardAdapter) GetChannels(ctx context.Context, country string) ([]Channel, error)

GetChannels retrieves available payment channels for a country.

func (*YellowcardAdapter) GetNetworks 

func (y *YellowcardAdapter) GetNetworks(ctx context.Context, country string) ([]Network, error)

GetNetworks retrieves available banks and mobile money operators for a country.

func (*YellowcardAdapter) GetPaymentStatus 

func (y *YellowcardAdapter) GetPaymentStatus(ctx context.Context, transactionID string) (payment.PaymentStatus, error)

GetPaymentStatus retrieves the current status of a disbursement.

func (*YellowcardAdapter) GetRate 

func (y *YellowcardAdapter) GetRate(ctx context.Context, currency string) (int64, error)

GetRate returns the exchange rate for USD to the specified currency in stroops.

func (*YellowcardAdapter) GetRates 

func (y *YellowcardAdapter) GetRates(ctx context.Context, currency string) ([]Rate, error)

GetRates retrieves exchange rates for a currency.

func (*YellowcardAdapter) InitializePayment 

func (y *YellowcardAdapter) InitializePayment(ctx context.Context, req payment.InitializePaymentRequest) (string, error)

InitializePayment creates a disbursement request with forceAccept enabled.

func (*YellowcardAdapter) LookupPayment 

func (y *YellowcardAdapter) LookupPayment(ctx context.Context, paymentID string) (*PaymentDetails, error)

LookupPayment retrieves payment details by ID.

func (*YellowcardAdapter) ProcessPayment 

func (y *YellowcardAdapter) ProcessPayment(ctx context.Context, transactionID string) (payment.PaymentStatus, error)

ProcessPayment retrieves the current status of a disbursement.

func (*YellowcardAdapter) SubmitPayment 

func (y *YellowcardAdapter) SubmitPayment(ctx context.Context, req PaymentRequest) (*PaymentResponse, error)

SubmitPayment sends a disbursement request to YellowCard.

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.