Add Virtual Card Address

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.

mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) {
  addVirtualCardAddress(input: $input) {
    userAddressId
    streetAddressLine1
    streetAddressLine2
    country
    city
    state
    postalCode
  }
}

Parameters

Parameter	Type	Required	Description
input	AddVirtualCardAddressInput!	Yes	Wrapper object for the billing address request.
input.billingAddress	VirtualCardBillingAddressInput!	Yes	Billing address to save for virtual card issuance.
input.billingAddress.streetAddressLine1	String!	Yes	Street address. PO boxes are not accepted by the issuer.
input.billingAddress.streetAddressLine2	String	No	Optional apartment, suite, or secondary address line. Empty values are saved as `null`; non-empty values are trimmed.
input.billingAddress.country	String!	Yes	Country name. Currently only United States addresses are supported by the card issuer.
input.billingAddress.city	String!	Yes	City. Saved in uppercase.
input.billingAddress.state	String!	Yes	State name or two-letter US state code. Saved in uppercase.
input.billingAddress.postalCode	String!	Yes	5-digit US ZIP code. Saved in uppercase.
input.authUserId	UUID	No	Authorized user ID (UAC role assignment ID). When provided, the address is saved for that authorized cardholder.

Response

{
  "data": {
    "addVirtualCardAddress": {
      "userAddressId": "1f6b2c3d-4e5f-4a67-9a10-2b3c4d5e6f70",
      "streetAddressLine1": "123 Main St",
      "streetAddressLine2": "Apt 5",
      "country": "United States",
      "city": "NEW YORK",
      "state": "NY",
      "postalCode": "10001"
    }
  }
}

Response fields

Field	Type	Description
`userAddressId`	UUID	Saved billing address ID. Pass this value as `userAddressId` to `createVirtualCard`.
`streetAddressLine1`	String	Street address line 1.
`streetAddressLine2`	String	Street address line 2, or `null` when not provided.
`country`	String	Country name.
`city`	String	City saved on the address.
`state`	String	State saved on the address.
`postalCode`	String	Postal code saved on the address.

Example requests

Save a billing address for the caller:

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "query": "mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) { addVirtualCardAddress(input: $input) { userAddressId streetAddressLine1 streetAddressLine2 country city state postalCode } }",
  "variables": {
    "input": {
      "billingAddress": {
        "streetAddressLine1": "123 Main St",
        "streetAddressLine2": "Apt 5",
        "country": "United States",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001"
      }
    }
  }
}'

Save a billing address for an authorized user:

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "query": "mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) { addVirtualCardAddress(input: $input) { userAddressId streetAddressLine1 streetAddressLine2 country city state postalCode } }",
  "variables": {
    "input": {
      "authUserId": "8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d",
      "billingAddress": {
        "streetAddressLine1": "456 Market St",
        "streetAddressLine2": "Suite 200",
        "country": "United States",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105"
      }
    }
  }
}'

const response = await fetch('https://transactional-graph.staging.fluzapp.com/api/v1/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${accessToken}`,
  },
  body: JSON.stringify({
    query: `
      mutation AddVirtualCardAddress(
        $input: AddVirtualCardAddressInput!
      ) {
        addVirtualCardAddress(input: $input) {
          userAddressId
          streetAddressLine1
          streetAddressLine2
          country
          city
          state
          postalCode
        }
      }
    `,
    variables: {
      input: {
        authUserId: '8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d',
        billingAddress: {
          streetAddressLine1: '456 Market St',
          streetAddressLine2: 'Suite 200',
          country: 'United States',
          city: 'San Francisco',
          state: 'CA',
          postalCode: '94105',
        },
      },
    },
  }),
});

const data = await response.json();
console.log('Virtual card address saved:', data.data.addVirtualCardAddress);

Error codes

Code	Message	Description
`ARG-0001`	Invalid arguments received	A required address field is missing, a value is empty, or `authUserId` is not a valid UUID.
`AUTH-0008`	Invalid user access	The Bearer token could not be resolved to a caller. Verify the token is valid.
`AUTH-0031`	The requested scopes must be granted by the user first.	The token is missing the `CREATE_VIRTUALCARD` scope required to save virtual card addresses.
`AUTH-0034`	No authorized user found with this id on the caller’s account.	The `authUserId` does not exist on the caller’s account, is not ACTIVE, or refers to an OWNER assignment.
`VC-0001`	Please try another payment method. If you continue experiencing issues, please contact our support team.	A general failure occurred while saving the billing address. Please retry or contact support.

Next steps

Create a virtual card

Pass the returned userAddressId into createVirtualCard.

Set a virtual card PIN

Required before the card can be used for in-person or PIN-prompted transactions.

​Parameters

​Response

​Response fields

​Example requests

​Error codes

​Next steps

Create a virtual card

Set a virtual card PIN

Parameters

Response

Response fields

Example requests

Error codes

Next steps