Search…
Manage Funding Sources
Provides the essentials for a user to link their real payment methods with a virtual card.
Funding sources supply the means for a user to link a real funding source with a virtual card. A user can supply their credit or debit card as a method to fund a transaction performed on the virtual card.

Creating a Funding Source

A funding source is created by invoking a series of steps from the retrieval of funding source configuration to setup and completion of the creation process.
Any existing virtual cards funded by a cancelled funding source will become unfunded. These can be funded by creating a new funding source and setting the updateCardFundingSource parameter in the completeFundingSource method call to true.
Before creating a funding source, the identity of your user must first be verified via Secure Id Verification.
Currently only credit and debit cards are supported as funding sources
TypeScript
Swift
Kotlin
To begin the process of creating a funding source, call the setupFundingSource method:
try {
const provisionalFundingSource = await virtualCardsClient.setupFundingSource({
currency: 'USD',
type: FundingSourceType.CreditCard,
})
} catch (error) {
// Handle/notify user of errors
}
This will return a ProvisionalFundingSource from the Virtual Cards Service. To continue, you must then interact with the Stripe API to setup a payment intent.
For Stripe JS/Node, see the docs:
For Stripe React JS, see the docs:
First retrieve the Stripe API key as well as other information pertaining to the funding source provider using the getFundingSourceClientConfiguration method:
try {
const configuration =
await virtualCardsClient.getFundingSourceClientConfiguration()
} catch (error) {
// Handle/notify user of errors
}
Once a Payment Intent has been setup, call completeFundingSource to finish provisioning the FundingSource. The completeFundingSource call accepts an optional updateCardFundingSource parameter (default value is true). This parameter is a flag to indicate whether to automatically update unfunded cards' funding source when a new funding source is created:
const fundingSource = await virtualCardsClient.completeFundingSource({
id: provisionalFundingSource.id,
completionData: {
provider: 'stripe',
paymentMethod: setupIntentPaymentMethodAsString, // Retrieve from Stripe API
},
// Optional flag to indicate whether to automatically update unfunded cards' funding source when a new funding source is created (defaults to true)
updateCardFundingSource: true,
} catch (error) {
// Handle/notify user of errors
}
To begin the process of creating a funding source, call the setupFundingSource method:
try {
let provisionalFundingSource = try await virtualCardsClient.setupFundingSource(
withInput: SetupFundingSourceInput(
type: .creditCard,
currency: "USD"
)
)
} catch {
// Handle/notify user of errors
}
This will return a ProvisionalFundingSource from the Virtual Cards Service. To continue, you must use the Stripe API to setup a payment intent.
For Stripe iOS-Swift, see the docs:
First retrieve the Stripe API key as well as other information pertaining to the funding source provider using the getFundingSourceClientConfiguration method:
try {
let configuration =
try await virtualCardsClient.getFundingSourceClientConfiguration()
// `configuration` contains the list of funding source client configuration.
} catch {
// Handle/notify user of errors
}
To setup a payment intent in Stripe, call STPAPIClient.confirmSetupIntent(with:)
and ensure that the STPSetupIntentConfirmParams is populated with the card that is to be added as a funding source.
Card and Billing Details are required.
Once a Payment Intent has been setup, call completeFundingSource to finish provisioning the FundingSource:
try {
let fundingSource = try await virtualCardsClient.completeFundingSource(
withInput: CompleteFundingSourceInput(
id: id, // This is the identifier of the provisional Funding Source.
completionData: StripeCompletionDataInput(
paymentMethodId: paymentMethodId // This is the payment method identifier of the Stripe SetupIntent success response.
)
)
)
} catch {
// Handle/notify user of errors
}
To begin the process of creating a funding source, call the setupFundingSource method:
launch {
try {
val setupInput = SetupFundingSourceInput("USD", FundingSourceType.CREDIT_CARD)
val provisionalFundingSource = withContext(Dispatchers.IO) {
virtualCardsClient.setupFundingSource(
setupInput
)
}
// The returned [provisionalFundingSource] has been created.
} catch (e: FundingSourceException) {
// Handle/notify user of exception
}
}
The call to setupFundingSource will return a ProvisionalFundingSource containing provisioning data required to continue the funding source creation process. To continue, you must use the Stripe API to setup a payment intent.
For Stripe Android-Kotlin, see the docs:
First retrieve the Stripe API key as well as other information pertaining to the funding source provider using the getFundingSourceClientConfiguration method:
launch {
try {
val configuration = withContext(Dispatchers.IO) {
virtualCardsClient.getFundingSourceClientConfiguration()
}
// [configuration] contains the list of funding source client configuration.
} catch (e: FundingSourceException) {
// Handle/notify user of exception
}
}
To setup a payment intent in Stripe, call StripeClient.confirmSetupIntent(confirmSetupIntentParams: ConfirmSetupIntentParams) and ensure that the ConfirmSetupIntentParams input parameter is populated with card details and billing details that you wish to add as a funding source.
Card and Billing Details are required.
Once a payment intent has been setup, call the completeFundingSource method to finish the process of provisioning a funding source:
launch {
try {
val completionData = ProviderCompletionData(
paymentMethodId // This is the payment method identifier of the Stripe SetupIntent success response.
)
val completeInput = CompleteFundingSourceInput(
provisionalFundingSource.id,
completionData,
null
)
val fundingSource = withContext(Dispatchers.IO) {
virtualCardsClient.completeFundingSource(
completeInput
)
}
// The returned [fundingSource] has been created.
} catch (e: FundingSourceException) {
// Handle/notify user of exception
}
}

Cancelling a Funding Source

If a user decides they want to remove a funding source from their account, the ability to provide them with the means to do so is applied with the cancelFundingSource method.
When a funding source is cancelled, any associated active virtual cards will no longer be able to process transactions. Any such transactions will be declined.
This API call is idempotent, so any subsequent calls to this method with the same id will always yield the same result.
When a funding source is cancelled, the record of the funding source will not be deleted, but instead its state will be set to INACTIVE and will no longer be usable for provisioning virtual cards. This is because refunds are always returned to the same original funding source and so clients will need to be able to retain details about cancelled funding in case any such future refunds refer to them.
TypeScript
Swift
Kotlin
// Collect the input id however makes sense for your implementation.
// const fundingSourceId = fundingSource.id
try {
const fundingSource = await virtualCardsClient.cancelFundingSource(
fundingSourceId
)
// The returned `fundingSource` is now cancelled and in an INACTIVE state.
} catch {
// Handle/notify user of errors
}
do {
// Retrieve the id for canceling the funding source.
let fundingSource = try await self.virtualCardsClient.cancelFundingSource(withId: id)
// The returned funding source is now cancelled.
} catch {
// Handle/notify user of error
}
// Collect the input id however makes sense for your implementation.
// val fundingSourceId = fundingSource.id
try {
val fundingSource = withContext(Dispatchers.IO) {
virtualCardsClient.cancelFundingSource(fundingSourceId)
}
// The returned [fundingSource] is now cancelled.
} catch (e: FundingSourceException) {
// Handle/notify user of exception
}

Retrieving Funding Sources

Previously created (or cancelled) funding sources can be accessed in two ways: via its identifier (Single Funding Source by Id), or via a list method (List Funding Sources).
A fetch of single or multiple funding sources can be performed remotely or locally by specifying the appropriate CachePolicy as part of the input.

Single Funding Source by Id

To retrieve a single funding source given its unique id, use the getFundingSource method. This method will return the record in an active or inactive state if it exists.
TypeScript
Swift
Kotlin
try {
const fundingSource = await virtualCardsClient.getFundingSource({
id,
cachePolicy: CachePolicy.RemoteOnly,
})
// `fundingSource` contains the fundingSource object, else `undefined` if not found.
} catch {
// Handle/notify user of errors
}
do {
let fundingSource = try await self.virtualCardsClient.getFundingSource(
withId: id,
cachePolicy: .remoteOnly
)
// If the id matches a funding source, `fundingSource` will be returned, else nil.
} catch {
// Handle/notify user of error
}
launch {
try {
val fundingSource = withContext(Dispatchers.IO) {
virtualCardsClient.getFundingSource(
id,
cachePolicy = CachePolicy.REMOTE_ONLY
)
}
// If the [id] matches a funding source, [fundingSource] will be returned, else [null].
} catch (e: FundingSourceException) {
// Handle/notify user of exception
}
}

List Funding Sources

The ability to retrieve multiple or all funding sources available to the user is supported. The results can be paginated and can contain funding sources which may be active whilst others are inactive.
A call to a list API will return a ListOutput object containing a list of matching items and a nextToken to support pagination. If no results matching the input are found, the result will contain empty items.
TypeScript
Swift
Kotlin
try {
const listOutput = await virtualCardsClient.listFundingSources({
cachePolicy: CachePolicy.RemoteOnly,
limit: 20,
nextToken,
})
// `listOutput.items` contains the list of items matching the input.
// Page through the results if `listOutput.nextToken` != undefined.
} catch {
// Handle/notify user of errors
}
do {
let listOutput = try await self.virtualCardsClient.getFundingSources(
withLimit: 20,
nextToken: nextToken,
cachePolicy: .remoteOnly
)
// `listOutput.items` contains the list of items matching the input.
// Page through the results if `listOutput.nextToken` != nil.
} catch {
// Handle/notify user of error
}
launch {
try {
val listOutput = withContext(Dispatchers.IO) {
virtualCardsClient.listFundingSources(
limit = 20,
nextToken = nextToken,
cachePolicy = CachePolicy.REMOTE_ONLY
)
}
// [listOutput.items] contains the list of items matching the input.
// Page through results if [listOutput.nextToken] != null.
} catch (e: FundingSourceException) {
// Handle/notify user of exception
}
}