Skip to content

README.md

Latest commit

 

History

History
861 lines (645 loc) · 41.1 KB

README.md

File metadata and controls

861 lines (645 loc) · 41.1 KB

Accounts

Overview

Available Operations

  • create - You can create business or individual accounts for your users (i.e., customers, merchants) by passing the required information to Moov. Requirements differ per account type and requested capabilities.

If you're requesting the wallet, send-funds, collect-funds, or card-issuing capabilities, you'll need to:

  • Send Moov the user platform terms of service agreement acceptance. This can be done upon account creation, or by patching the account using the termsOfService field. If you're creating a business account with the business type llc, partnership, or privateCorporation, you'll need to:
  • Provide business representatives after creating the account.
  • Patch the account to indicate that business representative ownership information is complete.

Visit our documentation to read more about creating accounts and verification requirements. Note that the mode field (for production or sandbox) is only required when creating a facilitator account. All non-facilitator account requests will ignore the mode field and be set to the calling facilitator's mode.

To access this endpoint using an access token you'll need to specify the /accounts.write scope.

  • list - List or search accounts to which the caller is connected.

All supported query parameters are optional. If none are provided the response will include all connected accounts. Pagination is supported via the skip and count query parameters. Searching by name and email will overlap and return results based on relevance. Accounts with AccountType guest will not be included in the response.

To access this endpoint using an access token you'll need to specify the /accounts.read scope.

  • get - Retrieves details for the account with the specified ID.

To access this endpoint using an access token you'll need to specify the /accounts/{accountID}/profile.read scope.

  • update - When can profile data be updated:

    • For unverified accounts, all profile data can be edited.
    • During the verification process, missing or incomplete profile data can be edited.
    • Verified accounts can only add missing profile data.

    When can't profile data be updated:

    • Verified accounts cannot change any existing profile data.

If you need to update information in a locked state, please contact Moov support.

To access this endpoint using an access token you'll need to specify the /accounts/{accountID}/profile.write scope.

  • disconnect - This will sever the connection between you and the account specified and it will no longer be listed as active in the list of accounts. This also means you'll only have read-only access to the account going forward for reporting purposes.

To access this endpoint using an access token you'll need to specify the /accounts/{accountID}/profile.disconnect scope.

  • listConnected - List or search accounts to which the caller is connected.

All supported query parameters are optional. If none are provided the response will include all connected accounts. Pagination is supported via the skip and count query parameters. Searching by name and email will overlap and return results based on relevance. Accounts with AccountType guest will not be included in the response.

To access this endpoint using an access token you'll need to specify the /accounts.read scope.

  • connect - Shares access scopes from the account specified to the caller, establishing a connection between the two accounts with the specified permissions.
  • getCountries - Retrieve the specified countries of operation for an account.

To access this endpoint using an access token you'll need to specify the /accounts/{accountID}/profile.read scope.

This endpoint will always overwrite the previously assigned values.

To access this endpoint using an access token you'll need to specify the /accounts/{accountID}/profile.write scope.

To access this endpoint using an access token you'll need to specify the /accounts/{accountID}/profile.read scope.

  • getTermsOfServiceToken - Generates a non-expiring token that can then be used to accept Moov's terms of service.

This token can only be generated via API. Any Moov account requesting the collect funds, send funds, wallet, or card issuing capabilities must accept Moov's terms of service, then have the generated terms of service token patched to the account. Read more in our documentation.

create

You can create business or individual accounts for your users (i.e., customers, merchants) by passing the required information to Moov. Requirements differ per account type and requested capabilities.

If you're requesting the wallet, send-funds, collect-funds, or card-issuing capabilities, you'll need to:

  • Send Moov the user platform terms of service agreement acceptance. This can be done upon account creation, or by patching the account using the termsOfService field. If you're creating a business account with the business type llc, partnership, or privateCorporation, you'll need to:
  • Provide business representatives after creating the account.
  • Patch the account to indicate that business representative ownership information is complete.

Visit our documentation to read more about creating accounts and verification requirements. Note that the mode field (for production or sandbox) is only required when creating a facilitator account. All non-facilitator account requests will ignore the mode field and be set to the calling facilitator's mode.

To access this endpoint using an access token you'll need to specify the /accounts.write scope.

Example Usage

package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.*;
import io.moov.sdk.models.errors.CreateAccountError;
import io.moov.sdk.models.errors.GenericError;
import io.moov.sdk.models.operations.CreateAccountResponse;
import java.lang.Exception;

public class Application {

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

        Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

        CreateAccount req = CreateAccount.builder()
                .accountType(CreateAccountType.BUSINESS)
                .profile(CreateProfile.builder()
                    .business(CreateBusinessProfile.builder()
                        .legalBusinessName("Whole Body Fitness LLC")
                        .build())
                    .build())
                .build();

        CreateAccountResponse res = sdk.accounts().create()
                .request(req)
                .call();

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

Parameters

Parameter Type Required Description
request CreateAccount ✔️ The request object to use for the request.

Response

CreateAccountResponse

Errors

Error Type Status Code Content Type
models/errors/GenericError 400, 409 application/json
models/errors/CreateAccountError 422 application/json
models/errors/APIException 4XX, 5XX */*

list

List or search accounts to which the caller is connected.

All supported query parameters are optional. If none are provided the response will include all connected accounts. Pagination is supported via the skip and count query parameters. Searching by name and email will overlap and return results based on relevance. Accounts with AccountType guest will not be included in the response.

To access this endpoint using an access token you'll need to specify the /accounts.read scope.

Example Usage

package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.CreateAccountType;
import io.moov.sdk.models.components.Security;
import io.moov.sdk.models.operations.ListAccountsRequest;
import io.moov.sdk.models.operations.ListAccountsResponse;
import java.lang.Exception;

public class Application {

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

        Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

        ListAccountsRequest req = ListAccountsRequest.builder()
                .type(CreateAccountType.BUSINESS)
                .skip(60L)
                .count(20L)
                .build();

        ListAccountsResponse res = sdk.accounts().list()
                .request(req)
                .call();

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

Parameters

Parameter Type Required Description
request ListAccountsRequest ✔️ The request object to use for the request.

Response

ListAccountsResponse

Errors

Error Type Status Code Content Type
models/errors/APIException 4XX, 5XX */*

get

Retrieves details for the account with the specified ID.

To access this endpoint using an access token you'll need to specify the /accounts/{accountID}/profile.read scope.

Example Usage

package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.Security;
import io.moov.sdk.models.operations.GetAccountResponse;
import java.lang.Exception;

public class Application {

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

        Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

        GetAccountResponse res = sdk.accounts().get()
                .accountID("2f93a6cf-3b3b-4c17-8d3b-110dfadccea4")
                .call();

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

Parameters

Parameter Type Required Description
accountID String ✔️ N/A

Response

GetAccountResponse

Errors

Error Type Status Code Content Type
models/errors/APIException 4XX, 5XX */*

update

When can profile data be updated:

  • For unverified accounts, all profile data can be edited.
  • During the verification process, missing or incomplete profile data can be edited.
  • Verified accounts can only add missing profile data.

When can't profile data be updated:

  • Verified accounts cannot change any existing profile data.

If you need to update information in a locked state, please contact Moov support.

To access this endpoint using an access token you'll need to specify the /accounts/{accountID}/profile.write scope.

Example Usage

package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.*;
import io.moov.sdk.models.errors.GenericError;
import io.moov.sdk.models.errors.PatchAccountError;
import io.moov.sdk.models.operations.UpdateAccountResponse;
import java.lang.Exception;
import java.util.Map;

public class Application {

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

        Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

        UpdateAccountResponse res = sdk.accounts().update()
                .accountID("433cb9d1-5943-4fd5-91b4-2aef5b30e2e7")
                .patchAccount(PatchAccount.builder()
                    .profile(PatchProfile.builder()
                        .individual(PatchIndividual.builder()
                            .name(IndividualNameUpdate.builder()
                                .firstName("Jordan")
                                .middleName("Reese")
                                .lastName("Lee")
                                .suffix("Jr")
                                .build())
                            .phone(PhoneNumber.builder()
                                .number("8185551212")
                                .countryCode("1")
                                .build())
                            .email("jordan.lee@classbooker.dev")
                            .address(AddressUpdate.builder()
                                .addressLine1("123 Main Street")
                                .addressLine2("Apt 302")
                                .city("Boulder")
                                .stateOrProvince("CO")
                                .postalCode("80301")
                                .country("US")
                                .build())
                            .birthDate(BirthDateUpdate.builder()
                                .day(9L)
                                .month(11L)
                                .year(1989L)
                                .build())
                            .build())
                        .business(PatchBusiness.builder()
                            .businessType(BusinessType.LLC)
                            .address(AddressUpdate.builder()
                                .addressLine1("123 Main Street")
                                .addressLine2("Apt 302")
                                .city("Boulder")
                                .stateOrProvince("CO")
                                .postalCode("80301")
                                .country("US")
                                .build())
                            .phone(PhoneNumber.builder()
                                .number("8185551212")
                                .countryCode("1")
                                .build())
                            .email("jordan.lee@classbooker.dev")
                            .taxID(TaxIDUpdate.builder()
                                .ein(TaxIDUpdateEin.builder()
                                    .number("12-3456789")
                                    .build())
                                .build())
                            .industryCodes(IndustryCodes.builder()
                                .naics("713940")
                                .sic("7991")
                                .mcc("7997")
                                .build())
                            .industry("electronics-appliances")
                            .build())
                        .build())
                    .metadata(Map.ofEntries(
                        Map.entry("optional", "metadata")))
                    .termsOfService(TermsOfServicePayloadUpdate.builder()
                        .manual(ManualTermsOfServiceUpdate.builder()
                            .acceptedIP("172.217.2.46")
                            .acceptedUserAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.71 Safari/537.36")
                            .build())
                        .build())
                    .customerSupport(PatchAccountCustomerSupport.builder()
                        .phone(PhoneNumber.builder()
                            .number("8185551212")
                            .countryCode("1")
                            .build())
                        .email("jordan.lee@classbooker.dev")
                        .address(AddressUpdate.builder()
                            .addressLine1("123 Main Street")
                            .addressLine2("Apt 302")
                            .city("Boulder")
                            .stateOrProvince("CO")
                            .postalCode("80301")
                            .country("US")
                            .build())
                        .build())
                    .build())
                .call();

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

Parameters

Parameter Type Required Description
accountID String ✔️ N/A
patchAccount PatchAccount ✔️ N/A

Response

UpdateAccountResponse

Errors

Error Type Status Code Content Type
models/errors/GenericError 400, 409 application/json
models/errors/PatchAccountError 422 application/json
models/errors/APIException 4XX, 5XX */*

disconnect

This will sever the connection between you and the account specified and it will no longer be listed as active in the list of accounts. This also means you'll only have read-only access to the account going forward for reporting purposes.

To access this endpoint using an access token you'll need to specify the /accounts/{accountID}/profile.disconnect scope.

Example Usage

package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.Security;
import io.moov.sdk.models.errors.GenericError;
import io.moov.sdk.models.operations.DisconnectAccountResponse;
import java.lang.Exception;

public class Application {

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

        Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

        DisconnectAccountResponse res = sdk.accounts().disconnect()
                .accountID("cfdfea7d-f185-4de5-ba90-b09f14fe6683")
                .call();

        // handle response
    }
}

Parameters

Parameter Type Required Description
accountID String ✔️ N/A

Response

DisconnectAccountResponse

Errors

Error Type Status Code Content Type
models/errors/GenericError 400, 409 application/json
models/errors/APIException 4XX, 5XX */*

listConnected

List or search accounts to which the caller is connected.

All supported query parameters are optional. If none are provided the response will include all connected accounts. Pagination is supported via the skip and count query parameters. Searching by name and email will overlap and return results based on relevance. Accounts with AccountType guest will not be included in the response.

To access this endpoint using an access token you'll need to specify the /accounts.read scope.

Example Usage

package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.Security;
import io.moov.sdk.models.operations.ListConnectedAccountsForAccountRequest;
import io.moov.sdk.models.operations.ListConnectedAccountsForAccountResponse;
import java.lang.Exception;

public class Application {

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

        Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

        ListConnectedAccountsForAccountRequest req = ListConnectedAccountsForAccountRequest.builder()
                .accountID("7e09ffc8-e508-4fd4-a54e-21cff90a1824")
                .skip(60L)
                .count(20L)
                .build();

        ListConnectedAccountsForAccountResponse res = sdk.accounts().listConnected()
                .request(req)
                .call();

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

Parameters

Parameter Type Required Description
request ListConnectedAccountsForAccountRequest ✔️ The request object to use for the request.

Response

ListConnectedAccountsForAccountResponse

Errors

Error Type Status Code Content Type
models/errors/APIException 4XX, 5XX */*

connect

Shares access scopes from the account specified to the caller, establishing a connection between the two accounts with the specified permissions.

Example Usage

package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.*;
import io.moov.sdk.models.errors.ConnectAccountRequestValidationError;
import io.moov.sdk.models.errors.GenericError;
import io.moov.sdk.models.operations.ConnectAccountResponse;
import java.lang.Exception;
import java.util.List;

public class Application {

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

        Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

        ConnectAccountResponse res = sdk.accounts().connect()
                .accountID("456cb5b6-20dc-4585-97b4-745d013adb1f")
                .shareScopes(ShareScopes.builder()
                    .principalAccountID("c520f1b9-0ba7-42f5-b977-248cdbe41c69")
                    .allowScopes(List.of(
                        ApplicationScope.TRANSFERS_WRITE,
                        ApplicationScope.PAYMENT_METHODS_READ))
                    .build())
                .call();

        // handle response
    }
}

Parameters

Parameter Type Required Description
accountID String ✔️ N/A
shareScopes ShareScopes ✔️ N/A

Response

ConnectAccountResponse

Errors

Error Type Status Code Content Type
models/errors/GenericError 400, 409 application/json
models/errors/ConnectAccountRequestValidationError 422 application/json
models/errors/APIException 4XX, 5XX */*

getCountries

Retrieve the specified countries of operation for an account.

To access this endpoint using an access token you'll need to specify the /accounts/{accountID}/profile.read scope.

Example Usage

package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.Security;
import io.moov.sdk.models.operations.GetAccountCountriesResponse;
import java.lang.Exception;

public class Application {

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

        Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

        GetAccountCountriesResponse res = sdk.accounts().getCountries()
                .accountID("a2026036-cc26-42c1-beef-950662d13b5d")
                .call();

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

Parameters

Parameter Type Required Description
accountID String ✔️ N/A

Response

GetAccountCountriesResponse

Errors

Error Type Status Code Content Type
models/errors/APIException 4XX, 5XX */*

assignCountries

Assign the countries of operation for an account.

This endpoint will always overwrite the previously assigned values.

To access this endpoint using an access token you'll need to specify the /accounts/{accountID}/profile.write scope.

Example Usage

package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.AccountCountries;
import io.moov.sdk.models.components.Security;
import io.moov.sdk.models.errors.AssignCountriesError;
import io.moov.sdk.models.errors.GenericError;
import io.moov.sdk.models.operations.AssignAccountCountriesResponse;
import java.lang.Exception;
import java.util.List;

public class Application {

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

        Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

        AssignAccountCountriesResponse res = sdk.accounts().assignCountries()
                .accountID("46736fa8-4bf7-4144-8e0e-dbea1eb0805b")
                .accountCountries(AccountCountries.builder()
                    .countries(List.of(
                        "United States"))
                    .build())
                .call();

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

Parameters

Parameter Type Required Description
accountID String ✔️ N/A
accountCountries AccountCountries ✔️ N/A

Response

AssignAccountCountriesResponse

Errors

Error Type Status Code Content Type
models/errors/GenericError 400, 409 application/json
models/errors/AssignCountriesError 422 application/json
models/errors/APIException 4XX, 5XX */*

getMerchantProcessingAgreement

Retrieve a merchant account's processing agreement.

To access this endpoint using an access token you'll need to specify the /accounts/{accountID}/profile.read scope.

Example Usage

package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.Security;
import io.moov.sdk.models.operations.GetMerchantProcessingAgreementResponse;
import java.lang.Exception;

public class Application {

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

        Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

        GetMerchantProcessingAgreementResponse res = sdk.accounts().getMerchantProcessingAgreement()
                .accountID("6180d9b9-2377-4190-8530-70a99d31a578")
                .call();

        if (res.responseStream().isPresent()) {
            // handle response
        }
    }
}

Parameters

Parameter Type Required Description
accountID String ✔️ N/A

Response

GetMerchantProcessingAgreementResponse

Errors

Error Type Status Code Content Type
models/errors/APIException 4XX, 5XX */*

getTermsOfServiceToken

Generates a non-expiring token that can then be used to accept Moov's terms of service.

This token can only be generated via API. Any Moov account requesting the collect funds, send funds, wallet, or card issuing capabilities must accept Moov's terms of service, then have the generated terms of service token patched to the account. Read more in our documentation.

Example Usage

package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.Security;
import io.moov.sdk.models.operations.GetTermsOfServiceTokenResponse;
import java.lang.Exception;

public class Application {

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

        Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

        GetTermsOfServiceTokenResponse res = sdk.accounts().getTermsOfServiceToken()
                .call();

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

Parameters

Parameter Type Required Description
origin Optional<String> ➖ Indicates the domain from which the request originated. Required if referer header is not present.
referer Optional<String> ➖ Specifies the URL of the resource from which the request originated. Required if origin header is not present.

Response

GetTermsOfServiceTokenResponse

Errors

Error Type Status Code Content Type
models/errors/APIException 4XX, 5XX */*