Skip to main content

Go SDK

The official Go SDK for Pelago.

Installation​

go get github.com/polyflow/pelago-go

Quick Start​

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/polyflow/pelago-go"
)

func main() {
    client := pelago.NewClient(pelago.Config{
        APIKey:      os.Getenv("PELAGO_API_KEY"),
        APISecret:   os.Getenv("PELAGO_API_SECRET"),
        Environment: pelago.Production,
    })

    payment, err := client.Payments.Create(context.Background(), &pelago.PaymentParams{
        Amount:         99.99,
        Currency:       "USD",
        Cryptocurrency: "USDC",
        Network:        "stellar",
        MerchantWallet: "GXXXXX...",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Payment URL: %s\n", payment.URL)
}

Configuration​

client := pelago.NewClient(pelago.Config{
    // Required
    APIKey:    "pk_live_xxxxx",
    APISecret: "sk_live_xxxxx",

    // Optional
    Environment: pelago.Production, // pelago.Production or pelago.Sandbox
    Timeout:     30 * time.Second,  // Request timeout
    MaxRetries:  3,                 // Auto-retry failed requests
    HTTPClient:  &http.Client{},    // Custom HTTP client
})

Payments​

Create Payment​

payment, err := client.Payments.Create(ctx, &pelago.PaymentParams{
    Amount:         100.00,
    Currency:       "USD",
    Cryptocurrency: "USDC",
    Network:        "stellar",
    MerchantWallet: "GXXXXX...",
    RedirectURL:    "https://mystore.com/success",
    WebhookURL:     "https://mystore.com/api/webhook",
    ExpiresIn:      1800,
    Metadata: map[string]string{
        "orderId":       "ORD-12345",
        "customerEmail": "[email protected]",
    },
})

Retrieve Payment​

payment, err := client.Payments.Retrieve(ctx, "pay_abc123")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Status: %s\n", payment.Status)

List Payments​

payments, err := client.Payments.List(ctx, &pelago.PaymentListParams{
    Status:     "completed",
    Limit:      20,
    CreatedGTE: "2025-01-01T00:00:00Z",
})

for _, p := range payments.Data {
    fmt.Printf("%s: %.2f\n", p.ID, p.Amount)
}

Refunds​

refund, err := client.Refunds.Create(ctx, &pelago.RefundParams{
    PaymentID: "pay_abc123",
    Amount:    50.00,
    Reason:    "Customer request",
})

Webhooks​

package main

import (
    "io"
    "net/http"
    "os"

    "github.com/polyflow/pelago-go"
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    signature := r.Header.Get("X-Pelago-Signature")
    timestamp := r.Header.Get("X-Pelago-Timestamp")

    event, err := pelago.VerifyWebhook(
        body,
        signature,
        timestamp,
        os.Getenv("WEBHOOK_SECRET"),
    )
    if err != nil {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    switch event.Type {
    case "payment.completed":
        orderID := event.Data.Metadata["orderId"]
        fulfillOrder(orderID)
    case "payment.failed":
        notifyCustomer(event.Data.Metadata["customerEmail"])
    }

    w.WriteHeader(http.StatusOK)
    w.Write([]byte(`{"received": true}`))
}

func main() {
    http.HandleFunc("/webhook", webhookHandler)
    http.ListenAndServe(":8080", nil)
}

Error Handling​

import "github.com/polyflow/pelago-go/errors"

payment, err := client.Payments.Create(ctx, params)
if err != nil {
    var pelagoErr *errors.PelagoError
    if errors.As(err, &pelagoErr) {
        switch pelagoErr.Type {
        case "authentication_error":
            log.Println("Check your API keys")
        case "invalid_request_error":
            log.Printf("Invalid param: %s\n", pelagoErr.Param)
        case "rate_limit_error":
            log.Println("Rate limited, slow down")
        default:
            log.Printf("Error: %s\n", pelagoErr.Message)
        }
    }
    return
}

Gin Framework Integration​

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/polyflow/pelago-go"
)

var client *pelago.Client

func main() {
    client = pelago.NewClient(pelago.Config{
        APIKey:      os.Getenv("PELAGO_API_KEY"),
        APISecret:   os.Getenv("PELAGO_API_SECRET"),
        Environment: pelago.Production,
    })

    r := gin.Default()
    r.POST("/api/checkout", createPayment)
    r.POST("/api/webhook", handleWebhook)
    r.Run(":8080")
}

func createPayment(c *gin.Context) {
    var req struct {
        Amount  float64 `json:"amount"`
        OrderID string  `json:"orderId"`
    }
    c.BindJSON(&req)

    payment, err := client.Payments.Create(c.Request.Context(), &pelago.PaymentParams{
        Amount:         req.Amount,
        Currency:       "USD",
        Cryptocurrency: "USDC",
        Network:        "stellar",
        MerchantWallet: os.Getenv("MERCHANT_WALLET"),
        Metadata:       map[string]string{"orderId": req.OrderID},
    })
    if err != nil {
        c.JSON(500, gin.H{"error": err.Error()})
        return
    }

    c.JSON(200, gin.H{"paymentUrl": payment.URL})
}

func handleWebhook(c *gin.Context) {
    body, _ := io.ReadAll(c.Request.Body)
    
    event, err := pelago.VerifyWebhook(
        body,
        c.GetHeader("X-Pelago-Signature"),
        c.GetHeader("X-Pelago-Timestamp"),
        os.Getenv("WEBHOOK_SECRET"),
    )
    if err != nil {
        c.JSON(401, gin.H{"error": "Invalid signature"})
        return
    }

    // Process event...
    c.JSON(200, gin.H{"received": true})
}

Next Steps​