Link a customer's bank account

Reuse your own Plaid connection to link a customer’s bank account to Natural, so their wallet can be funded from their bank.

This guide is only relevant if you have a Plaid account for your platform.

Get a processor token

If you already use Plaid, reuse the customer’s existing connection instead of Natural asking them to link their bank again.

Run Plaid Link for the customer's bank

Run your existing Plaid Link flow for the customer’s institution. On success, Plaid gives you a public_token.

Create a processor token scoped to Natural

Exchange the public_token for your own Plaid access_token, then call Plaid /processor/token/create for the selected account_id with processor: "natural". Plaid returns a processor_token scoped to that one account. You keep the Plaid item and access token; Natural only receives the processor token.

Send the processor token to Natural

Pass the processor_token to POST /external-accounts/processor-token with the customer’s partyId.

The full Plaid walkthrough lives in Link a bank account. Nothing about obtaining the token changes when the account belongs to a customer: the only difference is that partyId is the customer’s party.

Link the account

Call POST /external-accounts/processor-token with the customer’s partyId and processorToken.

import uuid
from naturalpay import Natural

# Acts as the agent that holds external_accounts.create on the customer.
agent_client = Natural(
    x_agent_id="agt_019cd1798d637a4da75dce386343931d",
    x_instance_id=str(uuid.uuid4()),
)

accounts = agent_client.external_accounts.create_from_processor_token(
    party_id="pty_019cd1798d617f65a79cb965dda9eac3",
    processor_token="processor-sandbox-abc123",
    institution_name="Chase",
    idempotency_key=str(uuid.uuid4()),
)

print(accounts.data[0].id)

import Natural from "@naturalpay/sdk";

const client = new Natural();
const accounts = await client.externalAccounts.createFromProcessorToken(
  {
    partyId: "pty_019cd1798d617f65a79cb965dda9eac3",
    processorToken: "processor-sandbox-abc123",
    institutionName: "Chase",
    idempotencyKey: crypto.randomUUID(),
  },
  {
    xAgentId: "agt_019cd1798d637a4da75dce386343931d",
    xInstanceId: crypto.randomUUID(),
  },
);

console.log(accounts.data[0].id);

natural external-accounts createFromProcessorToken \
  --party-id pty_019cd1798d617f65a79cb965dda9eac3 \
  --processor-token processor-sandbox-abc123 \
  --institution-name Chase \
  --x-agent-id agt_019cd1798d637a4da75dce386343931d \
  --x-instance-id "$(uuidgen)" \
  --idempotency-key "$(uuidgen)"

Using my Procurement Agent, link this Plaid processor token as a bank account for customer
pty_019cd1798d617f65a79cb965dda9eac3: processor-sandbox-abc123 (Chase).

curl -X POST https://api.natural.com/external-accounts/processor-token \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Agent-ID: agt_019cd1798d637a4da75dce386343931d" \
  -H "X-Instance-ID: $(uuidgen)" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "partyId": "pty_019cd1798d617f65a79cb965dda9eac3",
        "processorToken": "processor-sandbox-abc123",
        "institutionName": "Chase"
      }
    }
  }'

Keep track of the account

Store the eac_* id from the link response for your own records and account picker. GET /external-accounts lists the accounts linked to your own party, so it will not show a customer’s accounts; the link response is where you capture theirs. With the account linked, the customer’s wallet can be funded from their bank, and your agent can move money on their behalf.

Overview

Common use cases

Products

Guides

Link a customer's bank account

Get a processor token

Link the account

Keep track of the account

​Get a processor token

​Link the account

​Keep track of the account

Get a processor token

Link the account

Keep track of the account