{"id":51020640,"url":"https://github.com/samaasi/paystack-sdk-go","last_synced_at":"2026-06-28T21:00:43.956Z","repository":{"id":333698292,"uuid":"1137534099","full_name":"samaasi/paystack-sdk-go","owner":"samaasi","description":"A comprehensive, zero-dependency Go SDK for the Paystack API","archived":false,"fork":false,"pushed_at":"2026-06-17T14:25:17.000Z","size":155,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-17T16:48:10.651Z","etag":null,"topics":["api-client","context-aware","fintech","go","go-module","golang","idempotency","payment-gateway","payments","paystack","paystack-go","paystack-sdk","transactions","webhooks"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samaasi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-19T13:50:17.000Z","updated_at":"2026-06-17T14:48:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/samaasi/paystack-sdk-go","commit_stats":null,"previous_names":["samaasi/paystack-sdk-go"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/samaasi/paystack-sdk-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samaasi%2Fpaystack-sdk-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samaasi%2Fpaystack-sdk-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samaasi%2Fpaystack-sdk-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samaasi%2Fpaystack-sdk-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samaasi","download_url":"https://codeload.github.com/samaasi/paystack-sdk-go/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samaasi%2Fpaystack-sdk-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34903523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","context-aware","fintech","go","go-module","golang","idempotency","payment-gateway","payments","paystack","paystack-go","paystack-sdk","transactions","webhooks"],"created_at":"2026-06-21T16:00:25.996Z","updated_at":"2026-06-28T21:00:43.944Z","avatar_url":"https://github.com/samaasi.png","language":"Go","funding_links":[],"categories":["Financial"],"sub_categories":["Search and Analytic Databases"],"readme":"# Paystack SDK for Go\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/samaasi/paystack-sdk-go/v2.svg)](https://pkg.go.dev/github.com/samaasi/paystack-sdk-go/v2)\n[![Go Report Card](https://goreportcard.com/badge/github.com/samaasi/paystack-sdk-go/v2)](https://goreportcard.com/report/github.com/samaasi/paystack-sdk-go/v2)\n[![GitHub release](https://img.shields.io/github/v/release/samaasi/paystack-sdk-go)](https://github.com/samaasi/paystack-sdk-go/releases/latest)\n[![codecov](https://codecov.io/gh/samaasi/paystack-sdk-go/branch/master/graph/badge.svg)](https://codecov.io/gh/samaasi/paystack-sdk-go)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA comprehensive and robust Go SDK for the [Paystack API](https://paystack.com/docs/api/). This library provides a clean, idiomatic Go interface for integrating Paystack payments into your applications.\n\n## Features\n\n- **Full API Coverage**: Comprehensive support for all 24 Paystack services (Transactions, Customers, Transfers, etc.).\n- **Smart Retries \u0026 Rate Limiting**: Built-in exponential backoff that respects Paystack's `429 Retry-After` headers and strictly avoids retrying non-retryable `4xx` errors.\n- **Automatic Idempotency**: Automatically generates UUIDv4 `Idempotency-Key` headers for all `POST` and `PUT` requests to prevent duplicate charges on network retries.\n- **Generic Pagination Iterators**: Best-in-class `paystackapi.Iterator[T]` for elegantly fetching paginated list endpoints.\n- **Strongly Typed \u0026 Safe**: Uses strictly typed enums (`paystackapi.Currency`, `paystackapi.Channel`, etc.) rather than raw strings to prevent runtime errors.\n- **100% Mockable**: Every service client is exposed as a Go `interface` allowing effortless unit testing via `gomock`.\n- **Webhook IP Allowlisting**: Defense-in-depth webhook signature verification and official IP address validation.\n- **Zero Dependencies**: Relies solely on the Go standard library for a lightweight footprint and maximum security.\n\n## Installation\n\n```bash\ngo get github.com/samaasi/paystack-sdk-go/v2@v2.0.0\n```\n\n## Usage\n\n### Initialization\n\nInitialize the client with your secret key.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\n\tpaystack \"github.com/samaasi/paystack-sdk-go\"\n)\n\nfunc main() {\n\tapiKey := os.Getenv(\"PAYSTACK_SECRET_KEY\")\n\tclient := paystack.NewClient(apiKey)\n\t\n\t// You can also pass options\n\t// client := paystack.NewClient(apiKey, \n\t//     paystack.WithBaseURL(\"https://api.paystack.co\"),\n\t//     paystack.WithMaxRetries(5),\n\t//     paystack.WithTimeout(10 * time.Second),\n\t// )\n}\n```\n\n### Configuration\n\nYou can configure the client with the following options:\n\n- `WithBaseURL(url string)`: Override the default Paystack API base URL.\n- `WithMaxRetries(retries int)`: Set the maximum number of retries for failed requests (default: 3).\n- `WithTimeout(timeout time.Duration)`: Set the timeout for HTTP requests (default: 30s).\n- `WithHTTPClient(client *http.Client)`: Use a custom HTTP client.\n\n### Making Requests\n\nExample: Initializing a transaction.\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tpaystack \"github.com/samaasi/paystack-sdk-go/v2\"\n\t\"github.com/samaasi/paystack-sdk-go/v2/paystackapi\"\n\t\"github.com/samaasi/paystack-sdk-go/service/transactions\"\n)\n\nfunc main() {\n\tclient := paystack.NewClient(os.Getenv(\"PAYSTACK_SECRET_KEY\"))\n\n\treq := \u0026transactions.InitializeRequest{\n\t\tEmail:    \"customer@email.com\",\n\t\tAmount:   \"500000\", // in kobo\n\t\tCurrency: paystackapi.CurrencyNGN,\n\t\tMetadata: paystackapi.Metadata{\n\t\t\t\"cart_id\": \"398\",\n\t\t\t\"custom_fields\": []map[string]interface{}{\n\t\t\t\t{\n\t\t\t\t\t\"display_name\":  \"Invoice ID\",\n\t\t\t\t\t\"variable_name\": \"invoice_id\",\n\t\t\t\t\t\"value\":         \"INV-001\",\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t}\n\n\tresp, err := client.Transactions.Initialize(context.Background(), req)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tfmt.Printf(\"Authorization URL: %s\\n\", resp.Data.AuthorizationURL)\n}\n```\n\n### Pagination with Iterators\n\nThe SDK provides a generic Iterator pattern to effortlessly fetch records across multiple pages without manually handling `Meta` cursors or next-page logic.\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\tpaystack \"github.com/samaasi/paystack-sdk-go/v2\"\n\t\"github.com/samaasi/paystack-sdk-go/v2/paystackapi\"\n\t\"github.com/samaasi/paystack-sdk-go/service/transactions\"\n)\n\nfunc main() {\n\tclient := paystack.NewClient(\"sk_test_...\")\n\tctx := context.Background()\n\n\titer := paystackapi.NewIterator(func(ctx context.Context, page, perPage int) (paystackapi.Response[[]transactions.VerifyData], error) {\n\t\tresp, err := client.Transactions.List(ctx, \u0026transactions.ListTransactionParams{\n\t\t\tPage:    \u0026page,\n\t\t\tPerPage: \u0026perPage,\n\t\t})\n\t\tif err != nil {\n\t\t\treturn paystackapi.Response[[]transactions.VerifyData]{}, err\n\t\t}\n\t\treturn resp.Response, nil\n\t})\n\n\tfor iter.Next(ctx) {\n\t\ttx := iter.Value()\n\t\tfmt.Printf(\"Transaction ID: %d, Status: %s\\n\", tx.ID, tx.Status)\n\t}\n\n\tif err := iter.Err(); err != nil {\n\t\tlog.Fatal(\"Error during iteration:\", err)\n\t}\n}\n```\n\n### Webhook Verification\n\nEasily and securely verify incoming webhooks from Paystack using HMAC validation and IP Allowlisting.\n\n```go\npackage main\n\nimport (\n\t\"log\"\n\t\"net/http\"\n\n\t\"github.com/samaasi/paystack-sdk-go/webhook\"\n)\n\nfunc webhookHandler(w http.ResponseWriter, r *http.Request) {\n\t// Defense-in-depth: Verify request originates from Paystack's official IPs\n\tif !webhook.IsFromPaystackIP(r) {\n\t\thttp.Error(w, \"Unauthorized IP\", http.StatusUnauthorized)\n\t\treturn\n\t}\n\n\t// Parse and verify the payload signature using your secret key\n\tvar event webhook.Event\n\tif err := webhook.Parse(r, \"PAYSTACK_SECRET_KEY\", \u0026event); err != nil {\n\t\tlog.Printf(\"Webhook validation failed: %v\", err)\n\t\thttp.Error(w, \"Invalid signature\", http.StatusUnauthorized)\n\t\treturn\n\t}\n\n\tlog.Printf(\"Received event: %s\", event.Event)\n\tw.WriteHeader(http.StatusOK)\n}\n```\n\n### Idempotency Keys\n\nTo prevent duplicate operations, you can pass an Idempotency Key using the context.\n\n```go\nimport (\n\t\"context\"\n\t\"github.com/samaasi/paystack-sdk-go/paystackapi\"\n)\n\nfunc main() {\n\t// ... init client ...\n\n\tctx := context.Background()\n\t// Add Idempotency Key to context\n\tctx = paystackapi.WithIdempotencyKey(ctx, \"unique-transaction-id-123\")\n\n\t// The key will be sent in the header as 'Idempotency-Key'\n\tresp, err := client.Transactions.Initialize(ctx, req)\n}\n```\n\n### Custom Headers\n\nYou can also pass arbitrary custom headers via context.\n\n```go\nctx := paystackapi.WithCustomHeader(context.Background(), \"X-Custom-Header\", \"Value\")\n```\n\n## Supported Services\n\n- Apple Pay\n- Bulk Charges\n- Charges\n- Customers\n- Disputes\n- Integration\n- Miscellaneous (Banks, Countries, etc.)\n- Payment Pages\n- Payment Requests\n- Plans\n- Products\n- Refunds\n- Settlements\n- Splits\n- Status\n- Subaccounts\n- Subscriptions\n- Terminal\n- Transactions\n- Transfer Control\n- Transfer Recipients\n- Transfers\n- Verification\n- Virtual Accounts\n\n## Examples\n\nRunnable examples are available under [`examples/`](examples/):\n\n| Example | Description |\n|---|---|\n| [`initialize_transaction/`](examples/initialize_transaction/main.go) | Initialize a transaction and redirect to the Paystack checkout URL |\n| [`verify_webhook/`](examples/verify_webhook/main.go) | IP allowlist + HMAC signature verification + event dispatch |\n| [`pagination/`](examples/pagination/main.go) | Paginate a transaction list using the generic iterator |\n| [`charge_returning_customer/`](examples/charge_returning_customer/main.go) | Charge an existing authorization with typed error handling |\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\nTo get started:\n\n1. Fork the repository.\n2. Create a new branch (`git checkout -b feature/amazing-feature`).\n3. Commit your changes (`git commit -m 'Add some amazing feature'`).\n4. Push to the branch (`git push origin feature/amazing-feature`).\n5. Open a Pull Request.\n\nPlease ensure you run tests before submitting:\n\n```bash\ngo test ./...\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamaasi%2Fpaystack-sdk-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamaasi%2Fpaystack-sdk-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamaasi%2Fpaystack-sdk-go/lists"}