---
description: >-
  Pull transactions collect funds from a customer's card or bank account.
  Supports credit/debit cards and ACH transfers.
---

# Pulling Funds

Pull (collect) transactions withdraw funds from a customer's payment method. The Inyo Gateway supports:

- **Credit/Debit Cards** — Via tokenized card data (see [Tokenizing Cards](../../tokenizing-cards.md))
- **ACH Bank Transfers** — Via bank account and routing number

All pull transactions use the same endpoint:

```
POST https://sandbox-gw.simpleps.com/v2/payment
```

## Request Structure

### Root Object

| Field | Type | Required | Description |
|---|---|---|---|
| `externalPaymentId` | string | ✅ | Your unique payment identifier (idempotency key) |
| `ipAddress` | string | ✅ | Payer's IPv4 or IPv6 address |
| `paymentType` | string | ✅ | `"PULL"` |
| `capture` | boolean | ✅ | `true` = auto-capture; `false` = pre-auth only (cards only) |
| `amount` | object | ✅ | Transaction amount |
| `sender` | object | ✅ | Payer information, address, and payment method |

### `amount` Object

| Field | Type | Required | Description |
|---|---|---|---|
| `total` | number | ✅ | Payment amount (must be ≥ 1) |
| `currency` | string | ✅ | ISO 4217 currency code (e.g., `"USD"`) |

### `sender` Object

| Field | Type | Required | Description |
|---|---|---|---|
| `firstName` | string | ✅ | Payer's first name |
| `lastName` | string | ✅ | Payer's last name |
| `address` | object | ✅ | Billing address |
| `paymentMethod` | object | ✅ | Card or bank account details |

### `sender.address` Object

| Field | Type | Required | Description |
|---|---|---|---|
| `countryCode` | string | ✅ | ISO Alpha-2 country code (e.g., `"US"`) |
| `stateCode` | string | ✅ | State abbreviation (e.g., `"NY"`) |
| `city` | string | ✅ | City name |
| `line1` | string | ✅ | Street address line 1 |
| `line2` | string | ❌ | Street address line 2 |
| `zipCode` | string | ✅ | Postal/ZIP code |

### `sender.paymentMethod` — Card

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | ✅ | `"CARD"` |
| `cardTokenId` | string | ✅ | Token UUID from the tokenizer |
| `previousPaymentId` | string | ❌ | For recurring tokens: `paymentId` from the initial authorization |

### `sender.paymentMethod` — Bank Account (ACH)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | ✅ | `"BANK_DEPOSIT"` |
| `accountNumber` | string | ✅ | Bank account number (6–20 digits) |
| `routingNumber` | string | ✅ | ABA routing number (9 digits) |
| `accountType` | string | ✅ | `"CHECKING"`, `"SAVINGS"`, `"BUSINESS_CHECKING"`, or `"BUSINESS_SAVINGS"` |

## Card Payment Lifecycle

```
Tokenize → Authorize → (3DS Challenge?) → Capture → (Refund?)
                                              ↘ Void
```

For card payments:

1. [**Authorize**](cards/authorizing/) — Create the payment (`"capture": false` for pre-auth)
2. [**Handle 3DS**](cards/authorizing/handling-3d-secure.md) — If `status` = `CHALLENGE`, redirect to `redirectAcsUrl`
3. [**Capture**](cards/capture.md) — Settle the authorized payment (within 7 days)
4. [**Void**](cards/void.md) — Cancel before capture
5. [**Refund**](cards/refund.md) — Return funds after capture (full or partial)

## ACH Payments

ACH payments are always captured immediately (`"capture": true`). The pre-auth/capture lifecycle does not apply.

See [ACH (Bank Account)](ach-bank-account.md) for a complete example.

## What's Next

| Guide | Description |
|---|---|
| [Card Authorization](cards/authorizing/) | Full card payment flow with examples |
| [ACH Payment](ach-bank-account.md) | Bank account pull with example payload |
| [3D Secure](cards/authorizing/handling-3d-secure.md) | Challenge redirect handling |
| [AVS / CVC](cards/authorizing/handling-avs-cvc.md) | Address and security code verification |
| [Capture](cards/capture.md) | Settle a pre-authorized payment |
| [Void](cards/void.md) | Cancel before settlement |
| [Refund](cards/refund.md) | Return funds after capture |