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. Start Plaid Link on your frontend for the user to select a bank account.
3. Send account and routing numbers to Unblock to create the link.
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"
} 

Step 2: Start Plaid Link Flow

Integrate Plaid Link on your frontend. Use it to obtain the account_number and routing_number for the user’s selected bank account. Follow Plaid’s documentation for setup.

API reference (Plaid flow context):
Initiate a payment via Plaid

Step 3: Link the External Bank Account with Unblock

Links a bank account to the user's profile for fiat-to-crypto transactions:

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"
}

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"
}