On-Ramping USD (ACH Pull Payments)

🤔 What is ACH Pull?

An ACH Pull lets a user permit Unblock to withdraw funds from a linked bank account. Plaid manages the secure bank connection. Your system never handles bank login credentials.

➡️ USD On-Ramp Flow with ACH Pull

1. Create ACH profile for the user in Unblock.
2. Create the bank link via API and receive a Plaid Link URL
3. Load Plaid Link so the user confirms the same bank account.
4. Verify link status until the account is ACTIVE.
5. Initiate the ACH pull for a chosen USD amount.
6. Monitor webhooks as the transfer and conversion progress.

⚙️ Integration Steps

Step 1: Ensure User Is Ready and Create ACH Profile

The user must be verified as FULL_USER. Then create their ACH profile:

API reference:
Create a user profile for linking bank accounts

curl --request POST \
     --url https://sandbox.getunblock.com/user/linked-bank-account/profile \
     --header 'Authorization: API-Key <YOUR_API_KEY>' \
     --header 'unblock-session-id: <USER_SESSION_ID>' \
     --header 'content-type: application/json' \
     --data '
{
    "currency": "USD",
    "investment_objective": "INCOME",
    "annual_income_range": "UNDER_25K"
}

Step 2: Create Bank Link and Get Plaid Link URL

Call Unblock to start the bank linking process. You must send the bank account details you expect the user to confirm.

This request returns a Plaid Link URL. You will load this URL on your frontend in the next step.

API reference:
Link bank account

curl --request PUT \
     --url https://sandbox.getunblock.com/user/linked-bank-account/link \
     --header 'Authorization: API-Key <YOUR_API_KEY>' \
     --header 'unblock-session-id: <USER_SESSION_ID>' \
     --header 'content-type: application/json' \
     --data '
{
  "currency": "USD",
  "account_type": "checking",
  "account_number": "1234567890",
  "routing_number": "021000021"
}

The response includes a Plaid Link URL used to confirm this account.

Step 3: Load Plaid Link and Have the User Confirm the Account

Open the Plaid Link URL returned in Step 2 on your frontend.

The user must select the same bank account that matches the account and routing numbers sent to Unblock.

Plaid handles authentication and consent. You do not receive bank credentials.

If the user selects a different account, the link will fail.

Step 4: Verify the Link Status

After starting the link process, poll Unblock until the linked account becomes ACTIVE.

API reference:
Get linked bank account info

Unlink if needed:
Unlink bank account

Request

curl --request GET \
     --url https://sandbox.getunblock.com/user/linked-bank-account \
     --header 'Authorization: API-Key <YOUR_API_KEY>' \
     --header 'unblock-session-id: <USER_SESSION_ID>'

Successful Response Example

{
    "profile_uuid": "5594401c-0072-4df2-be9c-d491c0754c21",
    "status": "ACTIVE",
    "linked_bank_accounts": [
        {
            "uuid": "abcdef01-1234-5678-90ab-cdef01234567",
            "status": "ACTIVE",
            "currency": "USD",
            "account_number": "******7890",
            "routing_number": "021000021",
            "account_type": "CHECKING",
            "bank_name": "Chase Bank"
        }
    ]
}

If the status is FAILED, the routing or account number likely did not match the account selected in Plaid. The user should unlink and try again.

Step 5: Initiate an ACH Pull

When the account is ACTIVE, start an ACH pull.

API reference:
Withdraw funds from linked bank account

Request

curl --request POST \
     --url https://sandbox.getunblock.com/user/linked-bank-account/pull \
     --header 'Authorization: API-Key <YOUR_API_KEY>' \
     --header 'unblock-session-id: <USER_SESSION_ID>' \
     --header 'content-type: application/json' \
     --data '
{
  "currency": "USD",
  "amount": 100.00
}

The response includes a process_uuid that you can use for tracking.

Key Considerations for USD ACH On-Ramps

Prerequisites

• User must be a FULL_USER. To reach this status, the user must provide all required applicant data:

  • Date of birth
  • Country
  • Phone
  • TIN (SSN)

  The user must also accept the Terms & Conditions through the SDK,
  or submit the third_party_end_user_agreement_hashes document signed by the user
  using POST /user.

• Create the ACH profile before linking: API reference:
  Create a user profile for linking bank accounts

  One Linked Account at a Time

A user can have only one linked bank account.

To switch accounts:

API reference:
Unlink bank account

DELETE /user/linked-bank-account/unlink

After unlinking, restart the linking flow from the beginning.

Settlement Time

ACH transfers take several business days to complete.
You will receive webhook events such as:

• OUTSIDE_TRANSFER_RECEIVED

These confirm when funds clear and when the conversion process begins.

Error Handling

A FAILED status on the linked bank account usually means the routing or account number did not match what Plaid returned.
Have the user unlink and repeat the linking steps.

Private Sandbox Testing

When testing in Sandbox, you must use mock data that matches the bank account selected in Plaid.

Plaid step

• Select the bank account that ends with 0000

Manual bank account details

{
  "currency": "USD",
  "account_type": "checking",
  "account_number": "4929500000",
  "routing_number": "011000138"
}