Skip to main content
Save a billing address for virtual card issuance on the caller’s account. The address is saved as a BILLING user address and can later be passed to createVirtualCard as userAddressId. When authUserId is provided, the address is saved for that authorized user’s underlying user while remaining attached to the caller’s account. The authUserId must be an ACTIVE non-owner authorized user assignment on the caller’s account. If an identical billing address already exists for the target cardholder on the caller’s account, the existing address is returned instead of creating a duplicate. Matching is done on address fields, account, target user, and BILLING type.
Prerequisites: a Bearer token with the CREATE_VIRTUALCARD scope.
The billing address must be verifiableThis mutation stores the billing address. It must be a real, deliverable US address (US, USA, or United States) with a correct city, state, and ZIP, and PO boxes are not accepted. The USPS/Smarty check runs when a virtual card is created — an address that can’t be verified there causes card creation to fail with VC-0025. See Address Formatting Requirements for the full field rules and examples.

​
How it fits together

  1. Save an address with addVirtualCardAddress — you get back a userAddressId.
  2. Pass that userAddressId to createVirtualCard. It takes precedence over any inline billingAddress.
  3. Reuse the same userAddressId across as many cards as you like — the address is stored once on the account.
You can also skip pre-saving entirely and pass a billingAddress object inline on createVirtualCard; a matching saved address will be reused, or a new one created.

​
Next steps

Add virtual card address

The full mutation contract — parameters, responses, examples, and error codes.

Create a virtual card

Put the saved userAddressId to work issuing a card.