{"id":20290605,"url":"https://github.com/gocardless/gocardless-pro-go","last_synced_at":"2025-04-11T11:02:05.165Z","repository":{"id":40547362,"uuid":"83719518","full_name":"gocardless/gocardless-pro-go","owner":"gocardless","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-09T10:26:28.000Z","size":1980,"stargazers_count":8,"open_issues_count":5,"forks_count":8,"subscribers_count":47,"default_branch":"master","last_synced_at":"2025-04-09T11:29:30.760Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/gocardless.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-03-02T20:04:49.000Z","updated_at":"2025-04-04T13:49:28.000Z","dependencies_parsed_at":"2023-02-17T18:31:23.148Z","dependency_job_id":"2c1621fe-f010-450e-b4d8-11e2093d1dc4","html_url":"https://github.com/gocardless/gocardless-pro-go","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fgocardless-pro-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fgocardless-pro-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fgocardless-pro-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fgocardless-pro-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gocardless","download_url":"https://codeload.github.com/gocardless/gocardless-pro-go/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248381716,"owners_count":21094525,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-14T15:08:26.681Z","updated_at":"2025-04-11T11:02:05.127Z","avatar_url":"https://github.com/gocardless.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go Client Library for GoCardless Pro API [![CircleCI](https://circleci.com/gh/gocardless/gocardless-pro-go-template/tree/master.svg?style=svg\u0026circle-token=68c31e704d9b0020a5f42b4b89b0a77a17bdac6c)](https://circleci.com/gh/gocardless/gocardless-pro-go-template/tree/master)\n\nThis library provides a simple wrapper around the [GoCardless API](http://developer.gocardless.com/api-reference).\n\n- [\"Getting started\" guide](https://developer.gocardless.com/getting-started/api/introduction/?lang=go) with copy and paste Go code samples\n- [API Reference](https://developer.gocardless.com/api-reference/2015-07-06)\n\n## Getting started\n\nMake sure your project is using Go Modules (it will have a `go.mod` file in its\nroot if it already is):\n\n``` sh\ngo mod init\ngo mod tidy\n```\n\nThen, reference gocardless-pro-go in a Go program with `import`:\n``` go\nimport (\n    gocardless \"github.com/gocardless/gocardless-pro-go/v4\"\n)\n```\n\n\nRun any of the normal `go` commands (`build`/`install`/`test`). The Go\ntoolchain will resolve and fetch the gocardless-pro-go module automatically.\n\nAlternatively, you can also explicitly `go get` the package into a project:\n\n```\ngo get -u github.com/gocardless/gocardless-pro-go@v4.5.0\n```\n\n## Initializing the client\n\nThe client is initialised with an access token, and is configured to use GoCardless live environment by default:\n\n```go\n    token := \"your_access_token\"\n    config, err := gocardless.NewConfig(token)\n    if err != nil {\n        fmt.Printf(\"got err in initialising config: %s\", err.Error())\n        return\n    }\n    client, err := gocardless.New(config)\n    if err != nil {\n\t\tfmt.Printf(\"error in initialisating client: %s\", err.Error())\n\t\treturn\n\t}\n```\n\n\nOptionally, the client can be customised with endpoint, for ex: sandbox environment\n```go\n    config, err := gocardless.NewConfig(token, gocardless.WithEndpoint(gocardless.SandboxEndpoint))\n    if err != nil {\n        fmt.Printf(\"got err in initialising config: %s\", err.Error())\n        return\n    }\n    client, err := gocardless.New(config)\n    if err != nil {\n\t\tfmt.Printf(\"error in initialisating client: %s\", err.Error())\n\t\treturn\n\t}\n```\n\nthe client can also be initialised with a customised http client, for ex;\n```go\n    customHttpClient := \u0026http.Client{\n        Timeout: time.Second * 10,\n    }\n    config, err := gocardless.NewConfig(token, gocardless.WithClient(customHttpClient))\n    if err != nil {\n        fmt.Printf(\"got err in initialising config: %s\", err.Error())\n        return\n    }\n    client, err := gocardless.New(config)\n    if err != nil {\n\t\tfmt.Printf(\"error in initialisating client: %s\", err.Error())\n\t\treturn\n\t}\n```\n\n## Examples \n\n### Fetching resources\n\nTo fetch single item, use the `Get` method\n\n```go\n    ctx := context.TODO()\n    customer, err := client.Customers.Get(ctx, \"CU123\")\n```\n\n### Listing resources\n\nTo fetch items in a collection, there are two options:\n\n* Fetching items one page at a time using `List` method: \n\n```go\n    ctx := context.TODO()\n    customerListParams := gocardless.CustomerListParams{}\n    customers, err := client.Customers.List(ctx, customerListParams)\n    for _, customer := range customers.Customers {\n        fmt.Printf(\"customer: %v\", customer)\n    }\n    cursor := customers.Meta.Cursors.After\n    customerListParams.After = cursor\n    nextPageCustomers, err := client.Customers.List(ctx, customerRemoveParams)\n```\n\n* Iterating through all of the items using a `All` method to get a lazily paginated list.\n  `All` will deal with making extra API requests to paginate through all the data for you:\n\n```go\n    ctx := context.TODO()\n    customerListParams := gocardless.CustomerListParams{}\n    customerListIterator := client.Customers.All(ctx, customerListParams)\n    for customerListIterator.Next() {\n        customerListResult, err := customerListIterator.Value(ctx)\n        if err != nil {\n            fmt.Printf(\"got err: %s\", err.Error())\n        } else {\n            fmt.Printf(\"customerListResult is %v\", customerListResult)\n        }\n    }\n```\n\n### Creating resources\n\nResources can be created with the `Create` method:\n\n```go\n    ctx := context.TODO()\n    customerCreateParams := gocardless.CustomerCreateParams{\n        AddressLine1: \"9 Acer Gardens\"\n        City:         \"Birmingham\",\n        PostalCode:   \"B4 7NJ\",\n        CountryCode:  \"GB\",\n        Email:        \"bbr@example.com\",\n        GivenName:    \"Bender Bending\",\n        FamilyName:   \"Rodgriguez\",\n    }\n\n    customer, err := client.Customers.Create(ctx, customerCreateParams)\n```\n\n### Updating Resources\n\nResources can be updates with the `Update` method:\n\n```go\n    ctx := context.TODO()\n    customerUpdateParams := CustomerUpdateParams{\n        GivenName: \"New Name\",\n    }\n\n    customer, err := client.Customers.Update(ctx, \"CU123\", customerUpdateParams)\n```\n\n### Removing Resources\n\nResources can be removed with the `Remove` method:\n\n```go\n    ctx := context.TODO()\n    customerRemoveParams := CustomerRemoveParams{}\n\n    customer, err := client.Customers.Remove(ctx, \"CU123\", customerRemoveParams)\n``` \n\n### Retrying requests\n\nThe library will attempt to retry most failing requests automatically (with the exception of those which are not safe to retry).\n\n`GET` requests are considered safe to retry, and will be retried automatically. Certain `POST` requests are made safe to retry by the use of an idempotency key, generated automatically by the library, so we'll automatically retry these too. Currently its retried for 3 times. If you want to override this behaviour(for example, to provide your own retry mechanism), then you can use the `WithoutRetries`.  This will not retry and return response object.\n\n```go\n    requestOption := gocardless.WithoutRetries()\n    customersCreateResult, err := client.Customers.Create(ctx, customerCreateParams, requestOption)\n```\n\n### Setting custom headers\n\nYou shouldn't generally need to customise the headers sent by the library, but you wish to\nin some cases (for example if you want to send an `Accept-Language` header when [creating a mandate PDF](https://developer.gocardless.com/api-reference/#mandate-pdfs-create-a-mandate-pdf)).\n```go\n    headers := make(map[string]string)\n    headers[\"Accept-Language\"] = \"fr\"\n    requestOption := gocardless.WithHeaders(headers)\n    customersCreateResult, err := client.Customers.Create(ctx, customerCreateParams, requestOption)\n```\n\nCustom headers you specify will override any headers generated by the library itself (for\nexample, an `Idempotency-Key` header with a randomly-generated value or one you've configured\nmanually). Custom headers always take precedence.\n```go\n    requestOption := gocardless.WithIdempotencyKey(\"test-idemptency-key-123\")\n    customersCreateResult, err := client.Customers.Create(ctx, customerCreateParams, requestOption)\n```\n\n### Handling webhooks\n\nGoCardless supports webhooks, allowing you to receive real-time notifications when things happen in your account, so you can take automatic actions in response, for example:\n\n* When a customer cancels their mandate with the bank, suspend their club membership\n* When a payment fails due to lack of funds, mark their invoice as unpaid\n* When a customer’s subscription generates a new payment, log it in their “past payments” list\n\nThe client allows you to validate that a webhook you receive is genuinely from GoCardless, and to parse it into Event objects(defined in event_service.go) which are easy to work with:\n\n```go\n    http.HandleFunc(\"/webhookEndpoint\", func(w http.ResponseWriter, r *http.Request) {\n        wh, err := NewWebhookHandler(\"secret\", EventHandlerFunc(func(event gocardless.Event) error {\n\t\t    parseEvent(event)\n        }))\n        wh.ServeHTTP(w,r)\n    })\n\n    func parseEvents(event Event) {\n        // work through list of events\n    }\n``` \n\n### Error Handling\n\nWhen the library returns an `error` defined by us rather than the stdlib, it can be converted into a `gocardless.APIError` using `errors.As`:\n\n```go\n    billingRequest, err := client.BillingRequests.Create(ctx, billingRequestCreateParams)\n\tif err != nil {\n\t\tvar apiErr *gocardless.APIError\n\t\tif errors.As(err, \u0026apiErr) {\n\t\t\tfmt.Printf(\"got err: %v\", apiErr.Message)\n\t\t}\n\t\treturn nil, err\n\t}\n```\n\n## Compatibility\n\nThis library requires go 1.20 and above.\n\n## Documentation\n\nTODO\n\n## Contributing\n\nThis client is auto-generated from Crank, a toolchain that we hope to soon open source. Issues should for now be reported on this repository.  __Please do not modify the source code yourself, your changes will be overridden!__\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgocardless%2Fgocardless-pro-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgocardless%2Fgocardless-pro-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgocardless%2Fgocardless-pro-go/lists"}