Skip to content

README.md

Latest commit

 

History

History
238 lines (187 loc) · 10.3 KB

README.md

File metadata and controls

238 lines (187 loc) · 10.3 KB

ClientLinks

Overview

Available Operations

create

Link a new or existing organization to your OAuth application, in effect creating a new client. The response contains a clientLink where you should redirect your customer to.

Redirecting the Customer

The clientLink URL behaves similarly to a standard OAuth authorization URL. Therefore, after receiving the clientLink URL in the API response, you need to append the following query parameters before redirecting the customer:

  • client_id string (required)

    The client ID you received when you registered your OAuth app. The ID starts with app_. For example: app_abc123qwerty.

  • state string (required)

    A random string generated by your app to prevent CSRF attacks. This will be reflected in the state query parameter when the user returns to the redirect_uri after authorizing your app.

  • scope string (required)

    A space-separated list of permissions ('scopes') your app requires. See the permissions list for more information about the available scopes.

    We recommend at least : onboarding.read onboarding.write

  • approval_prompt string

    Can be set to force to force showing the consent screen to the merchant, even when it is not necessary. If you force an approval prompt and the user creates a new authorization, previously active authorizations will be revoked.

    Possible values: auto force (default: auto)

Example of a Complete Redirect URL

After adding the above url parameter your URL will look something like this and you can redirect your client to this page:

https://my.mollie.com/dashboard/client-link/{id}?client_id={your_client_id}&state={unique_state}&scope=onboarding.read%20onboarding.write

Error Handling

Error handling is also dealt with similar to the Authorize endpoint: the customer is redirected back to your app's redirect URL with the error and error_description parameters added to the URL.

🚧

A client link must be used within 30 days of creation. After that period, it will expire and you will need to create a new client link.

Example Usage: create-client-link-201-1

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.*;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.CreateClientLinkResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .security(Security.builder()
                    .organizationAccessToken(System.getenv().getOrDefault("ORGANIZATION_ACCESS_TOKEN", ""))
                    .build())
            .build();

        CreateClientLinkResponse res = sdk.clientLinks().create()
                .idempotencyKey("123e4567-e89b-12d3-a456-426")
                .clientLinkRequest(ClientLinkRequest.builder()
                    .owner(Owner.builder()
                        .email("john@example.org")
                        .givenName("John")
                        .familyName("Doe")
                        .locale(LocaleResponse.EN_US)
                        .build())
                    .name("Acme Corporation")
                    .address(ClientLinkRequestAddress.builder()
                        .country("NL")
                        .streetAndNumber("Main Street 123")
                        .postalCode("1234AB")
                        .city("Amsterdam")
                        .build())
                    .registrationNumber("12345678")
                    .vatNumber("NL123456789B01")
                    .legalEntity("nl-bv")
                    .registrationOffice("aachen")
                    .incorporationDate("2024-12-24")
                    .build())
                .call();

        if (res.clientLinkResponse().isPresent()) {
            System.out.println(res.clientLinkResponse().get());
        }
    }
}

Example Usage: create-client-link-201-2

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.*;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.CreateClientLinkResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .security(Security.builder()
                    .organizationAccessToken(System.getenv().getOrDefault("ORGANIZATION_ACCESS_TOKEN", ""))
                    .build())
            .build();

        CreateClientLinkResponse res = sdk.clientLinks().create()
                .idempotencyKey("123e4567-e89b-12d3-a456-426")
                .clientLinkRequest(ClientLinkRequest.builder()
                    .owner(Owner.builder()
                        .email("john@example.org")
                        .givenName("John")
                        .familyName("Doe")
                        .locale(LocaleResponse.EN_US)
                        .build())
                    .name("Acme Corporation")
                    .address(ClientLinkRequestAddress.builder()
                        .country("NL")
                        .streetAndNumber("Main Street 123")
                        .postalCode("1234AB")
                        .city("Amsterdam")
                        .build())
                    .registrationNumber("12345678")
                    .vatNumber("NL123456789B01")
                    .legalEntity("nl-bv")
                    .registrationOffice("aachen")
                    .incorporationDate("2024-12-24")
                    .build())
                .call();

        if (res.clientLinkResponse().isPresent()) {
            System.out.println(res.clientLinkResponse().get());
        }
    }
}

Example Usage: create-client-link-201-3

package hello.world;

import com.mollie.mollie.Client;
import com.mollie.mollie.models.components.*;
import com.mollie.mollie.models.errors.ErrorResponse;
import com.mollie.mollie.models.operations.CreateClientLinkResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ErrorResponse, Exception {

        Client sdk = Client.builder()
                .security(Security.builder()
                    .organizationAccessToken(System.getenv().getOrDefault("ORGANIZATION_ACCESS_TOKEN", ""))
                    .build())
            .build();

        CreateClientLinkResponse res = sdk.clientLinks().create()
                .idempotencyKey("123e4567-e89b-12d3-a456-426")
                .clientLinkRequest(ClientLinkRequest.builder()
                    .owner(Owner.builder()
                        .email("john@example.org")
                        .givenName("John")
                        .familyName("Doe")
                        .locale(LocaleResponse.EN_US)
                        .build())
                    .name("Acme Corporation")
                    .address(ClientLinkRequestAddress.builder()
                        .country("NL")
                        .streetAndNumber("Main Street 123")
                        .postalCode("1234AB")
                        .city("Amsterdam")
                        .build())
                    .registrationNumber("12345678")
                    .vatNumber("NL123456789B01")
                    .legalEntity("nl-bv")
                    .registrationOffice("aachen")
                    .incorporationDate("2024-12-24")
                    .build())
                .call();

        if (res.clientLinkResponse().isPresent()) {
            System.out.println(res.clientLinkResponse().get());
        }
    }
}

Parameters

Parameter Type Required Description Example
idempotencyKey Optional<String> ➖ A unique key to ensure idempotent requests. This key should be a UUID v4 string. 123e4567-e89b-12d3-a456-426
clientLinkRequest Optional<ClientLinkRequest> ➖ N/A

Response

CreateClientLinkResponse

Errors

Error Type Status Code Content Type
models/errors/ErrorResponse 404, 422 application/hal+json
models/errors/APIException 4XX, 5XX */*
⚡