go-thunes

README

go-thunes

Go SDK for Thunes Money Transfer API.

---

CHINESE README

中文说明

Main Features

🌍 Worldwide Money Transfers: Send money across 130+ countries through mobile wallets, bank accounts, and cash pickup 💱 Quotation Management: Lock exchange rates and calculate fees before creating transactions 🔄 Transaction Lifecycle: Complete transaction flow from quotation to confirmation with status tracking 💰 Balance Monitoring: Track available, pending, and credit balances across currencies 🏦 Payer Information: Access payer data (banks and mobile wallets) with filters ⚡ Auto Retries: Built-in mechanism with backoff when network issues happen

Installation

go get github.com/yylego/go-thunes

Prerequisites

• Thunes API credentials (Base URL, Request Token, Request Secret)
• Configure environment variables when testing:

  export THUNES_BASE_URL="https://api.thunes.com"
  export THUNES_REQUEST_KEY="your-request-key"
  export THUNES_REQUEST_SECRET="your-request-secret"
  

Usage

Complete transaction workflow from quotation to confirmation:

package main

import (
	"context"
	"encoding/hex"
	"fmt"
	"log"
	"os"

	"github.com/yylego/go-thunes/thunes"
	"github.com/google/uuid"
	"github.com/yylego/must"
)

func main() {
	// Initialize client
	client := thunes.NewClient(&thunes.Config{
		BaseURL:       must.Nice(os.Getenv("THUNES_BASE_URL")),
		RequestKey:    must.Nice(os.Getenv("THUNES_REQUEST_KEY")),
		RequestSecret: must.Nice(os.Getenv("THUNES_REQUEST_SECRET")),
	})

	ctx := context.Background()

	// Generate unique ID
	quotationID := newUUID()

	// Step 1: Create quotation
	quotation, exc := client.CreateQuotation(ctx, &thunes.CreateQuotationParam{
		ExternalID:      quotationID,
		PayerID:         "3460",
		Mode:            thunes.DestinationAmount,
		TransactionType: "C2C",
		Source: &thunes.SourceInput{
			CountryIsoCode: "KHM",
			Currency:       "USD",
		},
		Destination: &thunes.DestinationInput{
			Amount:   "100",
			Currency: "CNY",
		},
	})
	if exc != nil {
		log.Fatal(exc)
	}
	fmt.Printf("Quotation created: %s\n", quotation.ExternalID)

	// Step 2: Retrieve quotation
	quotation, exc = client.GetQuotation(ctx, quotationID)
	if exc != nil {
		log.Fatal(exc)
	}
	fmt.Printf("Quotation retrieved: Rate=%s\n", quotation.WholesaleFxRate)

	// Step 3: Create transaction
	transactionID := newUUID()
	transaction, exc := client.CreateTransaction(ctx, quotationID, &thunes.CreateTransactionParam{
		ExternalID: transactionID,
		CreditPartyIdentifier: map[string]string{
			"msisdn": "+86xxxxxxxxxx",
		},
		Beneficiary: map[string]string{
			"lastname":  "Zhang",
			"firstname": "San",
		},
		Sender: map[string]string{
			"lastname":         "Li",
			"firstname":        "Si",
			"country_of_birth": "CHN",
			"nationality":      "CHN",
		},
		PurposeOfRemittance: "PERSONAL_TRANSFER",
		CallbackUrl:         "https://your-callback-url.com/webhook",
	})
	if exc != nil {
		log.Fatal(exc)
	}
	fmt.Printf("Transaction created: %s\n", transaction.ExternalID)

	// Step 4: Retrieve transaction
	transaction, exc = client.GetTransaction(ctx, transactionID)
	if exc != nil {
		log.Fatal(exc)
	}
	fmt.Printf("Transaction status: %s\n", transaction.StatusMessage)

	// Step 5: Confirm transaction
	transaction, exc = client.ConfirmTransaction(ctx, transactionID)
	if exc != nil {
		log.Fatal(exc)
	}
	fmt.Printf("Transaction confirmed: %s\n", transaction.StatusMessage)

	// Step 6: Check final status
	transaction, exc = client.GetTransaction(ctx, transactionID)
	if exc != nil {
		log.Fatal(exc)
	}
	fmt.Printf("Final status: %s (Class: %s)\n", transaction.StatusMessage, transaction.StatusClass)
}

func newUUID() string {
	u := uuid.New()
	return hex.EncodeToString(u[:])
}

⬆️ Source: Source

API Reference

• GetPing() - Health check endpoint
• CreateQuotation() - Create quotation with locked exchange rate
• GetQuotation() - Retrieve quotation using external ID
• CreateTransaction() - Create transaction from quotation
• GetTransaction() - Retrieve transaction using external ID
• ConfirmTransaction() - Confirm transaction and proceed with transfer
• GetBalances() - Retrieve account balances across currencies
• GetPayers() - Retrieve payer options (banks and wallets)
• GetPayerRates() - Retrieve payer exchange rates using specified currency
• GetCountries() - Retrieve supported countries

Important Notes

• Quotation Expiration: Quotations expire after 24 hours (standard behavior)
• Two-Step Transaction: Must invoke CreateTransaction() then ConfirmTransaction()
• External ID: Must be unique when creating each quotation and transaction
• Callback URL: Configure webhook endpoint to receive transaction status updates
• Balance Management: ConfirmTransaction() moves funds from available to pending balance
• Testing: Use if false {} blocks in tests to prevent actual money transfers

Official Documentation

• Thunes Platform
• Thunes API Documentation
• Money Transfer API v2

📄 License

MIT License. See LICENSE.

---

🤝 Contributing

Contributions are welcome! Report bugs, suggest features, and contribute code:

• 🐛 Found a mistake? Open an issue on GitHub with reproduction steps
• 💡 Have a feature idea? Create an issue to discuss the suggestion
• 📖 Documentation confusing? Report it so we can improve
• 🚀 Need new features? Share the use cases to help us understand requirements
• ⚡ Performance issue? Help us optimize through reporting slow operations
• 🔧 Configuration problem? Ask questions about complex setups
• 📢 Follow project progress? Watch the repo to get new releases and features
• 🌟 Success stories? Share how this package improved the workflow
• 💬 Feedback? We welcome suggestions and comments

---

🔧 Development

New code contributions, follow this process:

1. Fork: Fork the repo on GitHub (using the webpage UI).
2. Clone: Clone the forked project (git clone https://github.com/yourname/repo-name.git).
3. Navigate: Navigate to the cloned project (cd repo-name)
4. Branch: Create a feature branch (git checkout -b feature/xxx).
5. Code: Implement the changes with comprehensive tests
6. Testing: (Golang project) Ensure tests pass (go test ./...) and follow Go code style conventions
7. Documentation: Update documentation to support client-facing changes and use significant commit messages
8. Stage: Stage changes (git add .)
9. Commit: Commit changes (git commit -m "Add feature xxx") ensuring backward compatible code
10. Push: Push to the branch (git push origin feature/xxx).
11. PR: Open a merge request on GitHub (on the GitHub webpage) with detailed description.

Please ensure tests pass and include relevant documentation updates.

---

🌟 Support

Welcome to contribute to this project via submitting merge requests and reporting issues.

Project Support:

• ⭐ Give GitHub stars if this project helps you
• 🤝 Share with teammates and (golang) programming friends
• 📝 Write tech blogs about development tools and workflows - we provide content writing support
• 🌟 Join the ecosystem - committed to supporting open source and the (golang) development scene

Have Fun Coding with this package! 🎉🎉🎉

---

GitHub Stars