client

Developer-friendly & type-safe Go SDK specifically catered to leverage client API.

Summary

SDK Installation

To add the SDK as a dependency to your project:

go get github.com/mollie/mollie-api-golang

SDK Example Usage

Example

package main

import (
	"context"
	client "github.com/mollie/mollie-api-golang"
	"github.com/mollie/mollie-api-golang/models/components"
	"github.com/mollie/mollie-api-golang/models/operations"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithTestmode(false),
		client.WithSecurity(components.Security{
			APIKey: client.Pointer(os.Getenv("CLIENT_API_KEY")),
		}),
	)

	res, err := s.Balances.List(ctx, operations.ListBalancesRequest{
		Currency:       client.Pointer("EUR"),
		From:           client.Pointer("bal_gVMhHKqSSRYJyPsuoPNFH"),
		Limit:          client.Pointer[int64](50),
		IdempotencyKey: client.Pointer("123e4567-e89b-12d3-a456-426"),
	})
	if err != nil {
		log.Fatal(err)
	}
	if res.Object != nil {
		// handle response
	}
}

Authentication

Per-Client Security Schemes

This SDK supports the following security schemes globally:

Name	Type	Scheme	Environment Variable
`APIKey`	http	HTTP Bearer	`CLIENT_API_KEY`
`OAuth`	oauth2	OAuth2 token	`CLIENT_O_AUTH`

You can set the security parameters through the WithSecurity option when initializing the SDK client instance. The selected scheme will be used by default to authenticate with the API for all operations that support it. For example:

package main

import (
	"context"
	client "github.com/mollie/mollie-api-golang"
	"github.com/mollie/mollie-api-golang/models/components"
	"github.com/mollie/mollie-api-golang/models/operations"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithSecurity(components.Security{
			APIKey: client.Pointer(os.Getenv("CLIENT_API_KEY")),
		}),
		client.WithTestmode(false),
	)

	res, err := s.Balances.List(ctx, operations.ListBalancesRequest{
		Currency:       client.Pointer("EUR"),
		From:           client.Pointer("bal_gVMhHKqSSRYJyPsuoPNFH"),
		Limit:          client.Pointer[int64](50),
		IdempotencyKey: client.Pointer("123e4567-e89b-12d3-a456-426"),
	})
	if err != nil {
		log.Fatal(err)
	}
	if res.Object != nil {
		// handle response
	}
}

Idempotency Key

This SDK supports the usage of Idempotency Keys. See our documentation on how to use it.

package main

import(
	"context"
	"os"
	"github.com/mollie/mollie-api-golang/models/components"
	client "github.com/mollie/mollie-api-golang"
	"log"
)

func main() {
    ctx := context.Background()

    s := client.New(
        client.WithSecurity(components.Security{
            APIKey: client.Pointer(os.Getenv("MOLLIE_API_KEY")),
        }),
    )

	request := &components.PaymentRequest{
		Description: client.Pointer("Description"),
		Amount: &components.Amount{
			Currency: "EUR",
			Value: "5.00",
		},
		RedirectURL: client.Pointer("https://example.org/redirect"),
	}

	idempotencyKey := client.Pointer("<some-idempotency-key>")

    payment1, _ := s.Payments.Create(
		ctx,
		nil, idempotencyKey,
		request,
	)

	payment2, _ := s.Payments.Create(
		ctx,
		nil, idempotencyKey,
		request,
	)

	log.Println("Payment with ID:", *payment1.PaymentResponse.ID)
	log.Println("Payment with ID:", *payment2.PaymentResponse.ID)

	if *payment1.PaymentResponse.ID == *payment2.PaymentResponse.ID {
		log.Println("Payments are the same")
	} else {
		log.Println("Payments are different")
	}
}

Add Custom User-Agent Header

The SDK allows you to append a custom suffix to the User-Agent header for all requests. This can be used to identify your application or integration when interacting with the API, making it easier to track usage or debug requests. The suffix is automatically added to the default User-Agent string generated by the SDK. You can add it when creating the client:

s := client.New(
	client.WithSecurity(components.Security{
		APIKey: client.Pointer(os.Getenv("MOLLIE_API_KEY")),
	}),
	client.WithCustomUserAgent("insert something here"),
)

Add Profile ID and Testmode to Client

The SDK allows you to define the profileId and testmode in the client. This way, you don't need to add this information to the payload every time when using OAuth. This will not override the details provided in the individual requests.

s := client.New(
	client.WithSecurity(components.Security{
		OAuth: client.Pointer(os.Getenv("MOLLIE_OAUTH_KEY")),
	}),
	client.WithTestmode(true),
	client.WithProfileID("pfl_RjC8giiTQU"),
)

Available Resources and Operations

Available methods

Balances

List - List balances
Get - Get balance
GetPrimary - Get primary balance
GetReport - Get balance report
ListTransactions - List balance transactions

BalanceTransfers

Create - Create a Connect balance transfer
List - List all Connect balance transfers
Get - Get a Connect balance transfer

Capabilities

List - List capabilities

Captures

Create - Create capture
List - List captures
Get - Get capture

Chargebacks

List - List payment chargebacks
Get - Get payment chargeback
All - List all chargebacks

ClientLinks

Create - Create client link

Clients

List - List clients
Get - Get client

Customers

Create - Create customer
List - List customers
Get - Get customer
Update - Update customer
Delete - Delete customer
CreatePayment - Create customer payment
ListPayments - List customer payments

DelayedRouting

Create - Create a delayed route
List - List payment routes

Invoices

List - List invoices
Get - Get invoice

Mandates

Create - Create mandate
List - List mandates
Get - Get mandate
Revoke - Revoke mandate

Methods

List - List payment methods
All - List all payment methods
Get - Get payment method

Onboarding

Get - Get onboarding status
Submit - Submit onboarding data

Organizations

Get - Get organization
GetCurrent - Get current organization
GetPartner - Get partner status

PaymentLinks

Create - Create payment link
List - List payment links
Get - Get payment link
Update - Update payment link
Delete - Delete payment link
ListPayments - Get payment link payments

Payments

Create - Create payment
List - List payments
Get - Get payment
Update - Update payment
Cancel - Cancel payment
ReleaseAuthorization - Release payment authorization

Permissions

List - List permissions
Get - Get permission

Profiles

Create - Create profile
List - List profiles
Get - Get profile
Update - Update profile
Delete - Delete profile
GetCurrent - Get current profile

Refunds

Create - Create payment refund
List - List payment refunds
Get - Get payment refund
Cancel - Cancel payment refund
All - List all refunds

SalesInvoices

Create - Create sales invoice
List - List sales invoices
Get - Get sales invoice
Update - Update sales invoice
Delete - Delete sales invoice

Settlements

List - List settlements
Get - Get settlement
GetOpen - Get open settlement
GetNext - Get next settlement
ListPayments - List settlement payments
ListCaptures - List settlement captures
ListRefunds - List settlement refunds
ListChargebacks - List settlement chargebacks

Subscriptions

Create - Create subscription
List - List customer subscriptions
Get - Get subscription
Update - Update subscription
Cancel - Cancel subscription
All - List all subscriptions
ListPayments - List subscription payments

Terminals

List - List terminals
Get - Get terminal

Wallets

RequestApplePaySession - Request Apple Pay payment session

WebhookEvents

Get - Get a Webhook Event

Webhooks

Create - Create a webhook
List - List all webhooks
Update - Update a webhook
Get - Get a webhook
Delete - Delete a webhook
Test - Test a webhook

Global Parameters

Certain parameters are configured globally. These parameters may be set on the SDK client instance itself during initialization. When configured as an option during SDK initialization, These global values will be used as defaults on the operations that use them. When such operations are called, there is a place in each to override the global value, if needed.

For example, you can set profileId to "<id>" at SDK initialization and then you do not have to pass the same value on calls to operations like List. But if you want to do so you may, which will locally override the global setting. See the example code below for a demonstration.

Available Globals

The following global parameters are available. Global parameters can also be set via environment variable.

Name	Type	Description	Environment
ProfileID	string	The identifier referring to the profile you wish to retrieve the resources for. Most API credentials are linked to a single profile. In these cases the `profileId` can be omitted. For organization-level credentials such as OAuth access tokens however, the `profileId` parameter is required.	CLIENT_PROFILE_ID
Testmode	bool	Most API credentials are specifically created for either live mode or test mode. In those cases the `testmode` query parameter can be omitted. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting the `testmode` query parameter to `true`. Test entities cannot be retrieved when the endpoint is set to live mode, and vice versa.	CLIENT_TESTMODE
CustomUserAgent	string	Custom user agent string to be appended to the default Mollie SDK user agent.	CLIENT_CUSTOM_USER_AGENT

Example

package main

import (
	"context"
	client "github.com/mollie/mollie-api-golang"
	"github.com/mollie/mollie-api-golang/models/components"
	"github.com/mollie/mollie-api-golang/models/operations"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithTestmode(false),
		client.WithProfileID("<id>"),
		client.WithCustomUserAgent("<value>"),
		client.WithSecurity(components.Security{
			APIKey: client.Pointer(os.Getenv("CLIENT_API_KEY")),
		}),
	)

	res, err := s.Balances.List(ctx, operations.ListBalancesRequest{
		Currency:       client.Pointer("EUR"),
		From:           client.Pointer("bal_gVMhHKqSSRYJyPsuoPNFH"),
		Limit:          client.Pointer[int64](50),
		IdempotencyKey: client.Pointer("123e4567-e89b-12d3-a456-426"),
	})
	if err != nil {
		log.Fatal(err)
	}
	if res.Object != nil {
		// handle response
	}
}

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retry.Config object to the call by using the WithRetries option:

package main

import (
	"context"
	client "github.com/mollie/mollie-api-golang"
	"github.com/mollie/mollie-api-golang/models/components"
	"github.com/mollie/mollie-api-golang/models/operations"
	"github.com/mollie/mollie-api-golang/retry"
	"log"
	"models/operations"
	"os"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithTestmode(false),
		client.WithSecurity(components.Security{
			APIKey: client.Pointer(os.Getenv("CLIENT_API_KEY")),
		}),
	)

	res, err := s.Balances.List(ctx, operations.ListBalancesRequest{
		Currency:       client.Pointer("EUR"),
		From:           client.Pointer("bal_gVMhHKqSSRYJyPsuoPNFH"),
		Limit:          client.Pointer[int64](50),
		IdempotencyKey: client.Pointer("123e4567-e89b-12d3-a456-426"),
	}, operations.WithRetries(
		retry.Config{
			Strategy: "backoff",
			Backoff: &retry.BackoffStrategy{
				InitialInterval: 1,
				MaxInterval:     50,
				Exponent:        1.1,
				MaxElapsedTime:  100,
			},
			RetryConnectionErrors: false,
		}))
	if err != nil {
		log.Fatal(err)
	}
	if res.Object != nil {
		// handle response
	}
}

If you'd like to override the default retry strategy for all operations that support retries, you can use the WithRetryConfig option at SDK initialization:

package main

import (
	"context"
	client "github.com/mollie/mollie-api-golang"
	"github.com/mollie/mollie-api-golang/models/components"
	"github.com/mollie/mollie-api-golang/models/operations"
	"github.com/mollie/mollie-api-golang/retry"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithRetryConfig(
			retry.Config{
				Strategy: "backoff",
				Backoff: &retry.BackoffStrategy{
					InitialInterval: 1,
					MaxInterval:     50,
					Exponent:        1.1,
					MaxElapsedTime:  100,
				},
				RetryConnectionErrors: false,
			}),
		client.WithTestmode(false),
		client.WithSecurity(components.Security{
			APIKey: client.Pointer(os.Getenv("CLIENT_API_KEY")),
		}),
	)

	res, err := s.Balances.List(ctx, operations.ListBalancesRequest{
		Currency:       client.Pointer("EUR"),
		From:           client.Pointer("bal_gVMhHKqSSRYJyPsuoPNFH"),
		Limit:          client.Pointer[int64](50),
		IdempotencyKey: client.Pointer("123e4567-e89b-12d3-a456-426"),
	})
	if err != nil {
		log.Fatal(err)
	}
	if res.Object != nil {
		// handle response
	}
}

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or an error, they will never return both.

By Default, an API error will return apierrors.APIError. When custom error responses are specified for an operation, the SDK may also return their associated error. You can refer to respective Errors tables in SDK docs for more details on possible error types for each operation.

For example, the List function may return the following errors:

Error Type	Status Code	Content Type
apierrors.ErrorResponse	400, 404	application/hal+json
apierrors.APIError	4XX, 5XX	/

Example

package main

import (
	"context"
	"errors"
	client "github.com/mollie/mollie-api-golang"
	"github.com/mollie/mollie-api-golang/models/apierrors"
	"github.com/mollie/mollie-api-golang/models/components"
	"github.com/mollie/mollie-api-golang/models/operations"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithTestmode(false),
		client.WithSecurity(components.Security{
			APIKey: client.Pointer(os.Getenv("CLIENT_API_KEY")),
		}),
	)

	res, err := s.Balances.List(ctx, operations.ListBalancesRequest{
		Currency:       client.Pointer("EUR"),
		From:           client.Pointer("bal_gVMhHKqSSRYJyPsuoPNFH"),
		Limit:          client.Pointer[int64](50),
		IdempotencyKey: client.Pointer("123e4567-e89b-12d3-a456-426"),
	})
	if err != nil {

		var e *apierrors.ErrorResponse
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *apierrors.APIError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}
	}
}

Server Selection

Override Server URL Per-Client

The default server can be overridden globally using the WithServerURL(serverURL string) option when initializing the SDK client instance. For example:

package main

import (
	"context"
	client "github.com/mollie/mollie-api-golang"
	"github.com/mollie/mollie-api-golang/models/components"
	"github.com/mollie/mollie-api-golang/models/operations"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithServerURL("https://api.mollie.com/v2"),
		client.WithTestmode(false),
		client.WithSecurity(components.Security{
			APIKey: client.Pointer(os.Getenv("CLIENT_API_KEY")),
		}),
	)

	res, err := s.Balances.List(ctx, operations.ListBalancesRequest{
		Currency:       client.Pointer("EUR"),
		From:           client.Pointer("bal_gVMhHKqSSRYJyPsuoPNFH"),
		Limit:          client.Pointer[int64](50),
		IdempotencyKey: client.Pointer("123e4567-e89b-12d3-a456-426"),
	})
	if err != nil {
		log.Fatal(err)
	}
	if res.Object != nil {
		// handle response
	}
}

Custom HTTP Client

The Go SDK makes API calls that wrap an internal HTTP client. The requirements for the HTTP client are very simple. It must match this interface:

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

The built-in net/http client satisfies this interface and a default client based on the built-in is provided by default. To replace this default with a client of your own, you can implement this interface yourself or provide your own client configured as desired. Here's a simple example, which adds a client with a 30 second timeout.

import (
	"net/http"
	"time"

	"github.com/mollie/mollie-api-golang"
)

var (
	httpClient = &http.Client{Timeout: 30 * time.Second}
	sdkClient  = client.New(client.WithClient(httpClient))
)

This can be a convenient way to configure timeouts, cookies, proxies, custom headers, and other low-level configuration.

Special Types

This SDK defines the following custom types to assist with marshalling and unmarshalling data.

Date

types.Date is a wrapper around time.Time that allows for JSON marshaling a date string formatted as "2006-01-02".

Usage

d1 := types.NewDate(time.Now()) // returns *types.Date

d2 := types.DateFromTime(time.Now()) // returns types.Date

d3, err := types.NewDateFromString("2019-01-01") // returns *types.Date, error

d4, err := types.DateFromString("2019-01-01") // returns types.Date, error

d5 := types.MustNewDateFromString("2019-01-01") // returns *types.Date and panics on error

d6 := types.MustDateFromString("2019-01-01") // returns types.Date and panics on error

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
.devcontainer		.devcontainer
.github/workflows		.github/workflows
.speakeasy		.speakeasy
docs		docs
internal		internal
models		models
optionalnullable		optionalnullable
retry		retry
types		types
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
RELEASES.md		RELEASES.md
USAGE.md		USAGE.md
balances.go		balances.go
balancetransfers.go		balancetransfers.go
capabilities.go		capabilities.go
captures.go		captures.go
chargebacks.go		chargebacks.go
client.go		client.go
clientlinks.go		clientlinks.go
clients.go		clients.go
customers.go		customers.go
delayedrouting.go		delayedrouting.go
go.mod		go.mod
go.sum		go.sum
invoices.go		invoices.go
mandates.go		mandates.go
methods.go		methods.go
onboarding.go		onboarding.go
organizations.go		organizations.go
paymentlinks.go		paymentlinks.go
payments.go		payments.go
permissions.go		permissions.go
profiles.go		profiles.go
refunds.go		refunds.go
salesinvoices.go		salesinvoices.go
settlements.go		settlements.go
subscriptions.go		subscriptions.go
terminals.go		terminals.go
wallets.go		wallets.go
webhookevents.go		webhookevents.go
webhooks.go		webhooks.go

License

mollie/mollie-api-golang

Folders and files

Latest commit

History

Repository files navigation

client

Summary

Table of Contents

SDK Installation

SDK Example Usage

Example

Authentication

Per-Client Security Schemes

Idempotency Key

Add Custom User-Agent Header

Add Profile ID and Testmode to Client

Available Resources and Operations

Global Parameters

Available Globals

Example

Retries

Error Handling

Example

Server Selection

Override Server URL Per-Client

Custom HTTP Client

Special Types

Date

Usage

Development

Maturity

Contributions

SDK Created by Speakeasy

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Uh oh!

Uh oh!

Languages