SudoVirtualCardsClient

public protocol SudoVirtualCardsClient : AnyObject

Client used to interface with the Sudo Payment Platform service.

It is recommended to code to this interface, rather than the implementation class (DefaultSudoVirtualCardsClient) as the implementation class is only meant to be used for initializing an instance of the client.

  • Removes all keys associated with this client, resets any cached data, cleans up subscriptions, and purges any pending operations.

    It is important to note that this will clear ALL cached data related to all sudo services.

    Declaration

    Swift

    func reset() throws
  • createKeysIfAbsent() Asynchronous

    Create key pair and secret key for use by the Virtual Cards Client if they have not already been created.

    The key pair is used to register a public key with the service for the encryption of virtual card and transaction details.

    The secret key is used for client side encryption of user specific card metadata.

    Declaration

    Swift

    func createKeysIfAbsent() async throws -> CreateKeysIfAbsentResult

Mutations

  • Setup a funding source.

    Throws

    • InsufficientEntitlements.
    • VelocityExceeded.

    Declaration

    Swift

    func setupFundingSource(withInput input: SetupFundingSourceInput) async throws -> ProvisionalFundingSource

    Parameters

    input

    Funding Source input information.

    Return Value

    The provisional Funding Source.

  • Complete a provisional funding source.

    Throws

    • DuplicateFundingSource.
    • FundingSourceCompletionDataInvalid.
    • IdentityNotVerified.
    • ProvisionalFundingSourceNotFound.
    • UnacceptableFundingSource.

    Declaration

    Swift

    func completeFundingSource(withInput input: CompleteFundingSourceInput) async throws -> FundingSource

    Parameters

    input

    Parameters used to complete the funding source.

    Return Value

    The provisioned Funding Source.

  • Refresh a funding source.

    Throws

    • FundingSourceCompletionDataInvalid.
    • FundingSourceNotFound.
    • UnacceptableFundingSource.
    • FundingSourceRequiresUserInteraction.

    Declaration

    Swift

    func refreshFundingSource(withInput input: RefreshFundingSourceInput) async throws -> FundingSource

    Parameters

    input

    Parameters used to refresh the funding source.

    Return Value

    The refreshed Funding Source.

  • Provision a virtual card.

    Throws

    • SudoPlatformError.
    • SudoVirtualCardsError.

    Declaration

    Swift

    func provisionVirtualCard(withInput input: ProvisionVirtualCardInput, observer: ProvisionVirtualCardObservable?) async throws -> ProvisionalCardState

    Parameters

    input

    Parameters used to provision a Virtual Card.

    observer

    Observable for Provision Virtual Card API events.

    Return Value

    The newly provisioned card information.

  • Cancel a funding source.

    Throws

    Throws:

    • SudoPlatformError.
    • SudoVirtualCardsError.

    Declaration

    Swift

    func cancelFundingSource(withId id: String) async throws -> FundingSource

    Parameters

    id

    ID of the funding source to be cancelled.

    Return Value

    Funding source that was cancelled.

  • Request review of a funding source.

    Throws

    Throws:

    • SudoPlatformError.
    • SudoVirtualCardsError.

    Declaration

    Swift

    func reviewUnfundedFundingSource(withId id: String) async throws -> FundingSource

    Parameters

    id

    ID of the funding source to be reviewed.

    Return Value

    Funding source that was reviewed.

  • Cancel a provisional funding source.

    Throws

    Throws:

    • SudoPlatformError.
    • SudoVirtualCardsError.

    Declaration

    Swift

    func cancelProvisionalFundingSource(withId id: String) async throws -> ProvisionalFundingSource

    Parameters

    id

    ID of the provisional funding source to be cancelled.

    Return Value

    Provisional funding source that was cancelled and is in a failed state.

  • Update a virtual card.

    It is important to note that when updating a card, all fields are updated, therefore, any fields that should remain the same must include their original data.

    Throws

    • SudoPlatformError.

    Declaration

    Swift

    func updateVirtualCard(withInput input: UpdateVirtualCardInput) async throws -> SingleAPIResult<VirtualCard, PartialVirtualCard>

    Return Value

    • Success: The Virtual Card that was updated.
    • Partial: Partial record of updated Virtual Card.

  • Cancel a virtual card.

    Declaration

    Swift

    func cancelVirtualCard(withId id: String) async throws -> SingleAPIResult<VirtualCard, PartialVirtualCard>

    Parameters

    id

    ID of the card to cancel.

    Return Value

    • Success: Record of Virtual Card that was canceled.
    • Partial: Partial record of cancelled Virtual Card
  • Imports cryptographic keys from a key archive.

    Declaration

    Swift

    func importKeys(archiveData: Data) throws

    Parameters

    archiveData

    Key archive data to import the keys from.

Queries

  • Get the funding source client configuration.

    Declaration

    Swift

    @available(*, deprecated, message: "Use getVirtualCardsConfig instead to retrieve the FundingSourceClientConfiguration")
    func getFundingSourceClientConfiguration() async throws -> [FundingSourceClientConfiguration]

    Return Value

    The configuration of the client funding source data.

  • Get a provisional card using the id parameter. If the card cannot be found, nil will be returned.

    • Parameters

      • id: ID of the card to be retrieved.
      • cachePolicy: Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of identical API calls.
    • Throws

      • SudoPlatformError.

    Declaration

    Swift

    func getProvisionalCard(withId id: String, cachePolicy: CachePolicy) async throws -> ProvisionalCard?

    Return Value

    Card associated with id, or nil if the card cannot be found.

  • Get a list of provisional cards. If no cards can be found, an empty list will be returned.

    Throws

    Throws:

    • SudoPlatformError.

    Declaration

    Swift

    func listProvisionalCards(
        withLimit limit: Int?,
        nextToken: String?,
        cachePolicy: CachePolicy
    ) async throws -> ListAPIResult<ProvisionalCard, PartialProvisionalCard>

    Parameters

    limit

    Number of cards to return. If nil, the limit is 10.

    nextToken

    Generated token by previous calls to listProvisionalCards. This is used for pagination. This value should be pre-generated from a previous pagination call, otherwise it will throw an error. It is important to note that the same structured API call should be used if using a previously generated nextToken.

    cachePolicy

    Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of identical API calls.

    Return Value

    • Success: Cards associated with user, or empty array if no card can be found.
    • Partial: Mix of success and partial cards associated with user.
  • Get a card using the id parameter. If the card cannot be found, nil will be returned.

    • Parameters

      • id: ID of the card to be retrieved.
      • cachePolicy: Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of identical API calls.

    Throws

    Throws:

    • SudoPlatformError.

    Declaration

    Swift

    func getVirtualCard(
        withId id: String,
        cachePolicy: CachePolicy
    ) async throws -> VirtualCard?

    Return Value

    Card associated with id, or nil if the card cannot be found.

  • Get the current VirtualCardsConfig. If the config cannot be found, nil will be returned.

    • Parameters

      • cachePolicy: Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of identical API calls.

    Throws

    Throws:

    • SudoPlatformError.

    Declaration

    Swift

    func getVirtualCardsConfig(
        cachePolicy: CachePolicy
    ) async throws -> VirtualCardsConfig?

    Return Value

    Virtual card config associated with account, or nil if the coinfig cannot be found.

  • Get a list of cards. If no cards can be found, an empty list will be returned.

    Throws

    Throws:

    • SudoPlatformError.

    Declaration

    Swift

    func listVirtualCards(
        withLimit limit: Int?,
        nextToken: String?,
        cachePolicy: CachePolicy
    ) async throws -> ListAPIResult<VirtualCard, PartialVirtualCard>

    Parameters

    limit

    Number of cards to return. If nil, the limit is 10.

    nextToken

    Generated token by previous calls to getCards. This is used for pagination. This value should be pre-generated from a previous pagination call, otherwise it will throw an error. It is important to note that the same structured API call should be used if using a previously generated nextToken.

    cachePolicy

    Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of identical API calls.

    Return Value

    • Success: Cards associated with user, or empty array if no card can be found.
    • Partial: Mix of success and partial cards associated with user.
  • Get a funding source using the id parameter. If the funding source cannot be found, nil will be returned.

    Throws

    Throws:

    • SudoPlatformError.

    Declaration

    Swift

    func getFundingSource(
        withId id: String,
        cachePolicy: CachePolicy
    ) async throws -> FundingSource?

    Parameters

    id

    ID of the funding source to be retrieved.

    cachePolicy

    Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of identical API calls.

    Return Value

    FundingSource associated with id, or nil if the funding source cannot be found.

  • Get a list of funding sources. If no funding sources can be found, an empty list will be returned.

    Throws

    Throws:

    • SudoPlatformError.

    Declaration

    Swift

    func listFundingSources(
        withLimit limit: Int?,
        nextToken: String?,
        cachePolicy: CachePolicy
    ) async throws -> ListOutput<FundingSource>

    Parameters

    limit

    Number of funding sources to return. If nil, the limit is 10.

    nextToken

    Generated token by previous calls to getFundingSources. This is used for pagination. This value should be pre-generated from a previous pagination call, otherwise it will throw an error. It is important to note that the same structured API call should be used if using a previously generated nextToken.

    cachePolicy

    Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of identical API calls.

    Return Value

    FundingSources or empty array if no funding source can be found.

  • Get a list of provisional funding sources. If no provisional funding sources can be found, an empty list will be returned.

    Throws

    Throws:

    • SudoPlatformError.

    Declaration

    Swift

    func listProvisionalFundingSources(
        withFilter filter: ProvisionalFundingSourceFilterInput?,
        limit: Int?,
        nextToken: String?,
        cachePolicy: CachePolicy
    ) async throws -> ListOutput<ProvisionalFundingSource>

    Parameters

    filter

    The filter to be applied to the list of provisional funding sources to return.

    limit

    Number of funding sources to return. If nil, the limit is 10.

    nextToken

    Generated token by previous calls to getProvisionalFundingSources. This is used for pagination. This value should be pre-generated from a previous pagination call, otherwise it will throw an error. It is important to note that the same structured API call should be used if using a previously generated nextToken.

    cachePolicy

    Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of identical API calls.

    Return Value

    FundingSources matching filter, or empty array if no funding source can be found.

  • Export the cryptographic keys to a key archive.

    Declaration

    Swift

    func exportKeys() throws -> Data

    Return Value

    Key archive data.

Methods: Transactions

  • Get a transaction using the id parameter. If the transaction cannot be found, nil will be returned.

    Throws

    Throws:

    • SudoPlatformError.

    Declaration

    Swift

    func getTransaction(
        withId id: String,
        cachePolicy: CachePolicy
    ) async throws -> Transaction?

    Parameters

    id

    ID of the transaction to be retrieved.

    cachePolicy

    Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of identical API calls.

    Return Value

    Transaction associated with id, or nil if the transaction cannot be found.

  • Get a list of transactions by card id. If no transactions can be found, an empty list will be returned.

    Throws

    Throws:

    • SudoPlatformError.

    Declaration

    Swift

    func listTransactions(
        withCardId cardId: String,
        limit: Int?,
        nextToken: String?,
        dateRange: DateRangeInput?,
        sortOrder: SortOrderInput?,
        cachePolicy: CachePolicy
    ) async throws -> ListAPIResult<Transaction, PartialTransaction>

    Parameters

    cardId

    Identifier of the card for which associated transactions will be returned.

    limit

    Number of transactions to return. If nil, the limit is up to 1MB of data returned from the service.

    nextToken

    Generated token by previous calls to listTransactions. This is used for pagination. This value should be pre-generated from a previous pagination call, otherwise it will throw an error.

    dateRange

    Range of upper and lower date limits for records.

    sortOrder

    Order in which records are returned (based on date).

    cachePolicy

    Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of identical API calls.

    Return Value

    • Success: Transactions associated with the virtual card, or empty array if no transaction can be found.
    • Partial: Mix of complete and partial Transactions associated with the virtual card.
  • Get a list of transactions by card id and transaction type. If no transactions can be found, an empty list will be returned.

    Throws

    Throws:

    • SudoPlatformError.

    Declaration

    Swift

    func listTransactions(
        withCardId cardId: String,
        withTransactionType transactionType: TransactionType,
        limit: Int?,
        nextToken: String?,
        cachePolicy: CachePolicy
    ) async throws -> ListAPIResult<Transaction, PartialTransaction>

    Parameters

    cardId

    Identifier of the card for which associated transactions will be returned.

    transactionType

    The type of transactions to retrieve.

    limit

    Number of transaction to return. If nil, the limit is up to 1MB of data returned from the service.

    nextToken

    Generated token by previous calls to listTransactions. This is used for pagination. This value should be pre-generated from a previous pagination call, otherwise it will throw an error.

    cachePolicy

    Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of identical API calls.

    Return Value

    • Success: Transactions of specific type associated with the virtual card, or empty array if no transaction can be found.
    • Partial: Mix of complete and partial Transactions associated with the virtual card.
  • Get a list of transactions. If no transactions can be found, an empty list will be returned.

    Throws

    Throws:

    • SudoPlatformError.

    Declaration

    Swift

    func listTransactions(
        withLimit limit: Int?,
        nextToken: String?,
        dateRange: DateRangeInput?,
        sortOrder: SortOrderInput?,
        cachePolicy: CachePolicy
    ) async throws -> ListAPIResult<Transaction, PartialTransaction>

    Parameters

    limit

    Number of transaction to return. If nil, the limit is 10.

    nextToken

    Generated token by previous calls to listTransactions. This is used for pagination. This value should be pre-generated from a previous pagination call, otherwise it will throw an error.

    dateRange

    Range of upper and lower date limits for records.

    sortOrder

    Order in which records are returned (based on date).

    cachePolicy

    Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of identical API calls.

    Return Value

    • Success: Transactions associated with user, or empty array if no transaction can be found.
    • Partial: Mix of complete and partial Transactions associated with user.

Subscriptions

Sandbox APIs

  • Sandbox API to obtain data normally returned by full Plaid Link flow. Useful for testing ahead of full Plaid Link integration during application development.

    Declaration

    Swift

    func sandboxGetPlaidData(
        institutionId: String,
        plaidUsername: String
    ) async throws -> SandboxPlaidData

    Parameters

    institutionId

    ID of Plaid sandbox institution to use

    plaidUsername

    Username of Plaid sandbox user to obtain data for

    Return Value

    SandboxPlaidData object containing sandbox Plaid data for populating completion data before calling completeFundingSource

  • Sandbox API to set a funding source to refresh state to facilitate testing

    Declaration

    Swift

    func sandboxSetFundingSourceToRequireRefresh(
        fundingSourceId: String
    ) async throws -> FundingSource

    Parameters

    id

    ID of funding source to set to refresh state. Must identify a bank account funding source.

    Return Value

    FundingSource that has been set to refresh state