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)
- ACH Bank Transfers — Via bank account and routing number
All pull transactions use the same endpoint:
POST https://{FQDN}/v2/payment
Request Structure
Root Object
| Field | Type | Required | Description |
|---|
externalPaymentId | string | Yes | Your unique payment identifier (idempotency key) |
ipAddress | string | Yes | Payer's IPv4 or IPv6 address |
paymentType | string | Yes | "PULL" |
capture | boolean | Yes | true = auto-capture; false = pre-auth only (cards only) |
amount | object | Yes | Transaction amount |
sender | object | Yes | Payer information, address, and payment method |
amount Object
| Field | Type | Required | Description |
|---|
total | number | Yes | Payment amount (must be ≥ 1) |
currency | string | Yes | ISO 4217 currency code (e.g., "USD") |
sender Object
| Field | Type | Required | Description |
|---|
firstName | string | Yes | Payer's first name |
lastName | string | Yes | Payer's last name |
address | object | Yes | Billing address |
paymentMethod | object | Yes | Card or bank account details |
sender.address Object
| Field | Type | Required | Description |
|---|
countryCode | string | Yes | ISO Alpha-2 country code (e.g., "US") |
stateCode | string | Yes | State abbreviation (e.g., "NY") |
city | string | Yes | City name |
line1 | string | Yes | Street address line 1 |
line2 | string | No | Street address line 2 |
zipCode | string | Yes | Postal/ZIP code |
sender.paymentMethod — Card
| Field | Type | Required | Description |
|---|
type | string | Yes | "CARD" |
cardTokenId | string | Yes | Token UUID from the tokenizer |
previousPaymentId | string | No | For recurring tokens: paymentId from the initial authorization |
sender.paymentMethod — Bank Account (ACH)
| Field | Type | Required | Description |
|---|
type | string | Yes | "BANK_DEPOSIT" |
accountNumber | string | Yes | Bank account number (6–20 digits) |
routingNumber | string | Yes | ABA routing number (9 digits) |
accountType | string | Yes | "CHECKING", "SAVINGS", "BUSINESS_CHECKING", or "BUSINESS_SAVINGS" |
Card Payment Lifecycle
Tokenize → Authorize → (3DS Challenge?) → Capture → (Refund?)
↘ Void
For card payments:
- Authorize — Create the payment (
"capture": false for pre-auth) - Handle 3DS — If
status = CHALLENGE, redirect to redirectAcsUrl - Capture — Settle the authorized payment (within 7 days)
- Void — Cancel before capture
- Refund — 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) for a complete example.
What's Next
