Accounts

An account represents a wallet on the Provenance blockchain. A program is responsible for creating their customer/end user accounts.

There are 2 main uses of accounts:

• Accounts associated with Profiles (users and business you create). These accounts are akin to a deposit account.
• Accounts used to manage business/accounting functions for your program.

All completed accounts are FDIC insured via Figure Pay bank partners.

Transactions are ledgered per-account.

Create an account for a program

Create an account and associate it with a program. The new program account will be associated with the current program, which is determined through authentication. There can be one primary account for a program, but can be multiple non-primary accounts.

Program account requests allow the option of explicitly including a unique id for idempotency.

POST /programs/accounts

{
  "id": "4ec32db7-72a6-4f2e-a1ee-d5d8aeaa8bfc",
  "name": "Funding Account",
  "is_primary": true
}

Response:

{
  "id": "4ec32db7-72a6-4f2e-a1ee-d5d8aeaa8bfc",
  "blockchain_address": "tp180pfr6g45upsrta04l2xd8v08x9jntljgx0gpo",
  "balance_coins": 0,
  "balance_usd": 0,
  "account_number": "100012347",
  "routing_number": "000123456788",
  "program_id": "8f9ff701-3f78-4f1f-8168-385854c6fd2a",
  "name": "Funding Account",
  "status": "OPEN"
}

Create an account for a profile

Create an account and associate it with a profile created on behalf of your end-users.

Account requests allow the option of explicitly including a unique id for idempotency.

An account cannot be created unless the associated profile is in the APPROVED state and has been KYC/AML verified.

POST /profiles/:profile_id/accounts

{
  "id": "be285151-9160-482a-9c8d-a29fc072086a",
  "name": "Account 1"
}

Response:

{
  "id": "be285151-9160-482a-9c8d-a29fc072086a",
  "blockchain_address": "tp180pfr6g45upsrta04l2xd8v08x9jntljgx0gzu",
  "balance_coins": 0,
  "balance_usd": 0,
  "account_number": "100012345",
  "routing_number": "000123456789",
  "program_id": "8f9ff701-3f78-4f1f-8168-385854c6fd2a",
  "name": "Account 1",
  "status": "OPEN"
}

User Consents

Figure provides a rich API for defining materials that must be acknowledged by end users in order to open and use an account. The API is described in detail on the Onboarding Consents page.

Retrieve an account

Fetch account information for a profile including the account ID, blockchain address, balance, ACH account and routing numbers, and the program ID.

GET /profiles/:profile_id/accounts/:account_id

Response:

{
  "id": "be285151-9160-482a-9c8d-a29fc072086a",
  "blockchain_address": "tp180pfr6g45upsrta04l2xd8v08x9jntljgx0gzu",
  "balance_coins": 25000,
  "balance_usd": 250,
  "account_number": "100012345",
  "routing_number": "000123456789",
  "program_id": "8f9ff701-3f78-4f1f-8168-385854c6fd2a",
  "name": "Account 1",
  "status": "OPEN"
}

Retrieve all accounts for a given profile

Fetch the accounts for a requested profile. Returns a list of each account's information, which includes the account ID, blockchain address, balance, ACH account and routing numbers, and the program ID.

GET /profiles/:profile_id/accounts

Response:

{
  [
    {
      "id": "be285151-9160-482a-9c8d-a29fc072086a",
      "blockchain_address": "tp180pfr6g45upsrta04l2xd8v08x9jntljgx0gzu",
      "balance_coins": 25000,
      "balance_usd": 250,
      "account_number": "100012345",
      "routing_number": "000123456789",
      "program_id": "8f9ff701-3f78-4f1f-8168-385854c6fd2a",
      "name": "Account 1",
      "status": "OPEN"
    },
    {
      "id": "aaf4bbd8-c3df-4da3-931c-2f3e4f76e0ff",
      "blockchain_address": "ew180pfr6g45upsrta04l2xd8v08x9jntljgx0gba",
      "balance_coins": 25000,
      "balance_usd": 250,
      "account_number": "100012346",
      "routing_number": "000123456790",
      "program_id": "8f9ff701-3f78-4f1f-8168-385854c6fd2a",
      "name": "Account 2",
      "status": "OPEN"
    }
  ]
}

Retrieve account transactions

As noted above, transactions are ledgered per-account.

This response will be paginated.

GET /profiles/:profile_id/accounts/:account_id/transactions \
  --data-urlencode "types=CARD, INBOUND_ACH, MINT, NETWORK_FEE, OUTBOUND_ACH, OUTBOUND_WIRE, REDEMPTION, SYSTEM, TRANSFER" \
  --data-urlencode "starting_at=2022-01-06" \
  --data-urlencode "ending_before=2022-01-08" \
  --data-urlencode "next_cursor=2022-01-07T15:52:23.442264-05:00" \
  --data-urlencode "limit=100" \

{
  "data": [
    {
      "amount_coins": 7500,
      "blockchain_transaction_hash": "BA5EBA11BA5EBA11BA5EBA11BA5EBA11BA5EBA11BA5EBA11BA5EBA11BA5EBA11",
      "card": {
        "id": "v-401-0cbd4f31-20fb-4d3c-ad9e-103254b89268",
        "pan_last_four": "1234",
        "card_transaction_details": {
          "merchant_id": "000",
          "merchant_name": "Main Street Music",
          "mcc": "0100",
          "merchant_address": {
            "line1": "123 Main St.",
            "line2": null,
            "building_number": "2",
            "country": "USA",
            "country_subdivision_major": "NY",
            "country_subdivision_minor": null,
            "postal_code": "10001",
            "street": "Main St.",
            "city": "New York"
          },
          "response_code": "0",
          "response_description": "Posted"
        }
      },
      "created_dt": "2022-01-02T03:04:05.123456-05:00",
      "from": {
        "id": "8772b886-d12b-4439-8fff-bc7bfce237b9",
        "blockchain_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
        "name": "Example Account Name",
        "account_details": {
          "account_type": "PROFILE_ACCOUNT",
          "id": "7e0259ef-84c1-4112-866d-946894a43fbc",
          "profile_details": {
            "profile_type": "PERSONAL",
            "username": "username-example",
            "full_name": "Example User"
          }
        }
      },
      "from_address": "tp1ldxvn7am23xx987yhchra5hwfvglk5lu05m2u3",
      "id": "1a8f7f2c-775c-429c-be90-c246764e2c4b",
      "note": "Descriptive message associated with the transaction",
      "posted_dt": "2022-01-03T03:04:05.123456-05:00",
      "status": "COMPLETE",
      "type": "CARD",
      "updated_dt": "2022-01-03T03:04:05.123456-05:00"
    }
  ],
  "limit": 1,
  "next_cursor": "2022-01-07T15:52:23.442376-05:00"
}

Retrieve account cards

Fetch the cards for a requested account. Returns a list of each card's information, which includes the account ID, expiration, last four digits, and status.

GET /profiles/:profile_id/accounts/:account_id/cards

[
  {
    "account_id": "0cbd4f31-20fb-4d3c-ad9e-103254b89268",
    "created_dt": "2022-01-02T03:04:05.123456-05:00",
    "expiration": "2024-11-31",
    "id": "v-401-0cbd4f31-20fb-4d3c-ad9e-103254b89268",
    "pan_last_four": "1234",
    "status": "ACTIVE",
    "updated_dt": "2022-01-02T03:04:05.123457-05:00"
  },
  {
    "account_id": "8eadaeb3-19bf-47cc-844c-46474d901637",
    "created_dt": "2022-01-02T03:04:05.123456-05:00",
    "expiration": "2026-07-12",
    "id": "v-401-4f016e58-ba5f-4a54-b727-85cdda1fd61e",
    "pan_last_four": "7261",
    "status": "ACTIVE",
    "updated_dt": "2022-01-02T03:04:05.123457-05:00"
  }
]