Skip to content

02 Create and configure an API client

Jump to bottom
Victor Hugo Avelar Ossorio edited this page Aug 20, 2024 · 2 revisions

Initializing a new client

Configuration

Using API Tokens for Authentication

To interact with Mollie's API and authenticate your requests, you can create a new config object in test mode by providing your API token. This token serves as the authentication key for your API calls. The code snippet below demonstrates how to achieve this in Go:

// Create a new config object in test mode and use an API token
config := mollie.NewConfig(true, mollie.ApiTokenEnv)

The library provides convenient helper functions to simplify the initialization of API clients. By using these functions, you can avoid the need for manual parameter passing.

config := mollie.NewAPITestingConfig(true)

With the above code snippet, you can initialize a configuration object for your API client using the library's helper function. The NewAPITestingConfig function fetches the API token from the library's predefined environment variable (MOLLIE_API_TOKEN) and enables the idempotency feature automatically.

By utilizing this helper function, you streamline the setup process, making it more straightforward and less error-prone when creating your API client.

Using Organization Access Tokens

To interact with Mollie's API and authenticate your requests on behalf of an organization, you can create a new config object in test mode using an access token as the authentication key.

// Create a new config object in test mode and use an access token
// as authentication key for an organization.
config := mollie.NewConfig(true, mollie.OrgTokenEnv)

The library provides helper functions to simplify the initialization of API clients with an organization access token. Using these functions, you can avoid the need for manual parameter passing.

// ... config instantiation.

// Initialize a configuration struct using an organization access token from the library-specific
// environment variable (MOLLIE_ORG_TOKEN). The second parameter is a boolean value to enable
// the idempotency feature.
config := mollie.NewOrgTestingConfig(true)

By utilizing the NewOrgTestingConfig helper function, you can conveniently set up the configuration object for your API client with an organization access token. The function automatically fetches the token from the library-specific environment variable (MOLLIE_ORG_TOKEN) and enables the idempotency feature.

Using organization access tokens is essential when you need to perform actions on behalf of an organization within the Mollie API. These tokens ensure secure and authorized interactions while enabling idempotency guarantees consistent and reliable operations.

Enabling Idempotency for Request Duplication Prevention

Mollie allows you to ensure idempotency in your API requests to prevent duplication of operations. By enabling idempotency, a unique idempotency key (UUID by default) will be added to the custom header of each request. This ensures that even if a request is sent multiple times, the operation will be executed only once. The following code illustrates how to enable idempotency in your API client:

//... config instantiation.

// Enable idempotency by adding a unique idempotency key to each request header.
_ := config.ToggleIdempotency()

API client

Once you have your API configuration, you can proceed to create an API client that will handle requests to Mollie's API.

// config instantiation

mollieApiClient, err := mollie.NewClient(nil, config)
if err != nil {
  panic(err)
 }

The client leverages services to interact with Mollie's API, which provides support for the following resources:

  1. Payments: Facilitates interactions related to payments, including creation, management, and status retrieval.
  2. Chargebacks: Allows handling of chargebacks for disputed payments.
  3. PaymentMethods: Access information about various payment methods accepted by Mollie.
  4. Invoices: Enables handling of invoices related to transactions and subscription payments.
  5. Organizations: Manages organization-specific data and settings.
  6. Profiles: Handles profile-related actions, such as creating and managing profiles.
  7. Refunds: Facilitates refunds for specific transactions.
  8. Shipments: Deals with shipping-related actions for orders or deliveries.
  9. Orders: Manages orders and order-related information.
  10. Settlements: Provides access to settlement information and status.
  11. Captures: Deals with capturing authorized payments.
  12. Subscriptions: Manages subscription-related actions, including creation, modification, and cancellation.
  13. Customers: Handles customer data, including creating and updating customer profiles.
  14. Miscellaneous: Contains various miscellaneous functionalities and resources.
  15. Mandates: Interacts with mandates for recurring payments or direct debits.
  16. Permissions: Manages permissions for API access and usage.
  17. Onboarding: Facilitates the onboarding process for new users or accounts.
  18. PaymentLinks: Handles payment links for easy payment collection.
  19. Partners: Deals with partner-specific functionalities and integrations.
  20. Balances: Provides access to account balances and other related data.

Each service in Mollie's API follows a consistent set of HTTP verbs to perform supported operations:

  • List: This verb is used to retrieve multiple resources, typically returned as a list or collection.
  • Get: The "Get" verb allows you to retrieve a specific resource identified by a unique identifier or key.
  • Create: The "Create" verb is utilized to create a new resource on the server.
  • Update: By using the "Update" verb, you can modify or update a specific resource.
  • Delete: The "Delete" verb enables the removal of a resource from the server.

Certain services offer alternative methods for retrieving information that are specific to each resource. To explore the complete list of these methods, you can refer to the official Go reference documentation. The documentation will provide comprehensive details on the available options to access and retrieve resource-specific information, enabling you to choose the most suitable approach for your particular use case.

API client helper methods

The client has some helper methods for specific use cases, this methods are mostly to make some operations in the code manageable and easy to perform.

Specify a custom authentication key

Consider the following scenario: you have your developer key stored within the specified environment variable of a library. This key is frequently used and has a long Time-To-Live (TTL). However, there arises a situation where you need to access information related to a particular "profile" or account (whether in production or development). To avoid duplicating or copy-pasting code, you can leverage the WithAuthenticationValue method. By using this method, any string you provide can serve as an authentication key, facilitating the retrieval process seamlessly.

config := mollie.NewAPITestingConfig(true)

client, err := mollie.NewClient(nil, config)
if err != nil {
  panic(err)
 }

// to use a custom auth key
client.WithAuthenticationValue("your_custom_key")

ℹ️ The WithAuthenticationValue method plays a significant role in the testing suite of this library. It is extensively utilized to ensure effective and thorough testing of the library's functionalities and authentication mechanisms. By leveraging this method, test scenarios can be created and executed efficiently, validating the reliability and security of the library's authentication procedures.

ℹ️ The WithAuthenticationValue method is a useful alternative when environment variables cannot be used to set your API key. This might occur due to implementation constraints, permission limitations, or access level restrictions. See https://github.com/VictorAvelar/mollie-api-go/issues/387

For detailed information and specific methods available for each resource, please refer to Mollie's official API documentation.

Identifying the Authentication Key Type (API Token vs. Organization Access Token)

When working with Mollie's API, you may use either a regular API token or an organization access token as the authentication key. To distinguish between these two types, the library provides a HasAccessToken method. This method allows you to determine if the authorization key used in the client is an access token and act accordingly based on the result.

// Check if the authentication key is an access token.
isAccessToken := client.HasAccessToken()

if isAccessToken {
    // Perform operations specific to organization access tokens.
    // You can include fields required for organization access in your requests.
} else {
    // Perform operations specific to regular API tokens.
    // Some fields may not be required when using regular API tokens.
}

This way, you can ensure that the API requests contain the necessary fields depending on whether you are using a regular API token or an organization access token.

Clone this wiki locally