Funding Source Schema

{
  "created": String,
  "token": String,
  "type": String,
  "state": String,
  "nickname": String,
  "account_name": String,
  "last_four": String
}


created	An ISO 8601 string representing when this funding source was added to the Privacy account. This may be `null`
token	A globally unique identifier for this Funding Source
type	Type of funding source, see Enumerations for list
state	State of funding source, see Enumerations for list
nickname	The nickname given to the Funding Source or `null` if it has no nickname
account_name	Account name identifying the funding source. This may be `null`
last_four	The last 4 digits of the account (e.g. bank account, debit card) associated with this funding account. This may be `null`

Add Funding Source (Enterprise)

API Reference: Add funding source

There are two ways to add a funding source: either via adding a bank account's information (BANK) or via adding a Plaid processor token (PLAID).

Bank account: Use the bank account's routing and account numbers to add the account as a funding source. Returns a Funding Source object containing the bank information.

In the production environment, funding sources will be set to a PENDING state until micro-deposit validation is completed, while funding accounts in Sandbox will be set to an ENABLED state automatically.

Plaid processor token: Privacy has partnered with Plaid to make it easier for our mutual customers to authenticate end-user bank account details without having to handle and store this sensitive data. Customers can now simply pass a Plaid processor token to the specified Privacy endpoint, at which time Privacy will use the token to retrieve bank account and routing numbers directly from Plaid.

To use Plaid with Privacy and create a Plaid processor token, first follow the instructions on Plaid's docs.

Add a bank account as a funding source using the processor token (created in the previous step). Returns a Funding Source object containing the bank information, or a JSON object containing the Plaid error fields shown below. More documentation on these fields can be found on the Errors page in Plaid's documentation.

Note that the funding source must be a checking account. You can filter out other accounts using the account_filters field of the request body when making a token with Plaid.

POST https://api.privacy.com/v1/funding_sources

Sample Request

curl https://api.privacy.com/v1/funding_sources \
  -X POST \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
   "validation_method": "BANK",
   "routing_number": "011103093",
   "account_number": "13719713158835300",
   "account_name": "Sandbox"
}
'

Sample Response

{
    "created": "2020-07-08 17:57:36",
    "token": "b0f0d91a-3697-46d8-85f3-20f1a585cbea",
    "type": "DEPOSITORY_CHECKING",
    "state": "PENDING",
    "nickname": "",
    "account_name": "Sandbox",
    "last_four": "5263"
}


validation_method (required)	The selected method of adding a funding source. String. Permitted values: `BANK`, `PLAID`.
account_number (required and permitted only if validation_method is `BANK`)	The account number of the bank account. String.
routing_number (required and permitted only if validation_method is `BANK`)	The routing number of the bank account. String.
processor_token (required and permitted only if validation_method is `PLAID`)	The processor token associated with the bank account. String.
account_token (required for multi-account users only)	Token identifying the account that the bank account will be associated with. Only applicable if using account enrollment. See Managing Your Program for more information. String. Permitted values: 36-digit version 4 UUID (including hyphens).
account_name (optional and permitted only if validation_method is `BANK`)	The name associated with the bank account. This property is only for identification purposes, and has no bearing on the external properties of the bank. String.

Plaid Error Schema

{
  "error_data": {
    "error_code": String,
    "error_type": String,
    "error_message": String
  }
}

Verify Bank Account (Enterprise)

API Reference: Verify bank account

Verify a bank account as a funding source by providing received micro-deposit amounts.

POST https://api.privacy.com/v1/funding_sources/{funding_source_token}/verify

Sample Request

curl https://api.privacy.com/v1/funding_sources/b0f0d91a-3697-46d8-85f3-20f1a585cbea/verify \
  -X POST \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
   "micro_deposits": ["11", "23"]
}
'

Sample Response

{
    "created": "2020-07-08 17:57:36",
    "token": "b0f0d91a-3697-46d8-85f3-20f1a585cbea",
    "type": "DEPOSITORY_CHECKING",
    "state": "ENABLED",
    "nickname": "",
    "account_name": "Sandbox",
    "last_four": "5263"
}


funding_source_token (required, path parameter)	The token of the funding source to verify. String. Permitted values: 36-digit version 4 UUID (including hyphens).
micro_deposits (required)	An array of dollar amounts (in cents) received in two credit transactions. List. Permitted values: Two-digit number amounts.
account_token (required for multi-account users only)	Token identifying the account that the bank account will be associated with. Only applicable if using account enrollment. See Managing Your Program for more information. String. Permitted values: 36-digit version 4 UUID (including hyphens).

Update Bank Account (Enterprise)

API Reference: Update bank account

Update a bank account. Returns a Funding Source object containing the new bank information.

PATCH https://api.privacy.com/v1/funding_sources/{funding_source_token}

Sample Request

curl https://api.privacy.com/v1/funding_sources/b0f0d91a-3697-46d8-85f3-20f1a585cbea \
  -X PATCH \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
   "state": "DELETED"
}
'

Sample Response

{
    "created": "2020-07-08 17:57:36",
    "token": "b0f0d91a-3697-46d8-85f3-20f1a585cbea",
    "type": "DEPOSITORY_CHECKING",
    "state": "DELETED",
    "nickname": "",
    "account_name": "Sandbox",
    "last_four": "5263"
}


funding_source_token (required, path parameter)	The token of the bank account to edit. String. Permitted values: 36-digit version 4 UUID (including hyphens).
state (required)	The desired state of the bank account. If a bank account is set to `DELETED`, all cards linked to this account will no longer be associated with it. If there are no other bank accounts in state `ENABLED` on the account, authorizations will not be accepted on the card until a new funding account is added. String. Permitted values: `ENABLED`, `DELETED`.
account_token (required for multi-account users only)	Token identifying the account that the bank account will be associated with. Only applicable if using account enrollment. See Managing Your Program for more information. String. Permitted values: 36-digit version 4 UUID (including hyphens).

List Funding Sources

API Reference: List funding sources

List all funding sources under the program associated with the calling API key. An account_token can be passed in as a query parameter to filter for only the funding sources associated with a single account.

GET https://api.privacy.com/v1/funding_sources

Sample Request

curl 'https://api.privacy.com/v1/funding_sources?account_token=b68b7424-aa69-4cbc-a946-30d90181b621' \
  -H 'Accept: application/json' \
  -H "Authorization: api-key YOUR_API_KEY"

Sample Response

{
   "data": [
      { 
        "created": "2020-07-08 17:57:36",
        "token": "b0f0d91a-3697-46d8-85f3-20f1a585cbea",
        "type": "DEPOSITORY_CHECKING",
        "state": "ENABLED",
        "nickname": "",
        "account_name": "Sandbox",
        "last_four": "5263"
      },
        "created": "2021-01-01 16:42:21",
        "token": "b013627e-c678-4d6a-9b22-4741e377d604a",
        "type": "DEPOSITORY_CHECKING",
        "state": "ENABLED",
        "nickname": "",
        "account_name": "Sandbox2",
        "last_four": "1234"
      }
    ],
  "total_entries": 2,
  "total_pages": 1,
  "page": 1
}

Enumerations

FundingSource.state


ENABLED	The funding source is available to use for card creation and transactions
PENDING	The funding source is still being verified e.g. bank micro-deposits verification

FundingSource.type


CARD_DEBIT	Debit card
DEPOSITORY_CHECKING	Bank checking account
DEPOSITORY_SAVINGS	Bank savings account