Pull Transaction

Inyo Gateway facilitates pull transactions, a type of financial operation where the payment gateway initiates a request to withdraw funds from a customer's account.

Supports multiple payment methods, including:

• Credit/Debit Cards

• ACH Transfers

Fields Definition

Root Object

Field	Type	Required	Description
externalPaymentId	String	✅	Client external identifier for the payment.
amount	Object	✅	Contains the payment amount information.
ipAddress	String	✅	IPv4 address of the request origin.
paymentType	String	✅	Must be "PULL".
sender	Object	✅	Sender information.

---

amount Object

Field	Type	Required	Constraints	Description
total	Number	✅	>= 1	Payment amount
currency	String	✅	Must be "USD"	Currency of the transaction

---

sender Object

customer

Field	Type	Required	Description
firstName	String	✅	Customer's first name.
lastName	String	✅	Customer's last name.
phoneNumber	String	✅	Digits only, 7–15 characters.
documentNumber	String	✅	Digits only, 5–20 characters.
documentType	String	✅	One of: NATIONAL_ID, PASSPORT, DRIVER_LICENSE
email	String	✅	Must be a valid email address.
countryCodeAlpha3	String	✅	3-letter uppercase country code (e.g., USA).

customerAddress

Field	Type	Required	Description
stateCode	String	✅	US state abbreviation (e.g., MA).
city	String	✅	City name.
line1	String	✅	Street address line 1.
line2	String	❌	Street address line 2 (optional).
state	String	✅	Full state name (e.g., Massachusetts).
zipCode	String	✅	Postal code.

---

source Object

Field	Type	Required	Description
type	String	✅	Must be CARD or BANK_ACCOUNT.

🟢 If type = CARD

Field	Type	Required	Description
token	String	✅	Must be a valid UUID.

🟢 If type = BANK_ACCOUNT

Field	Type	Required	Description
accountType	String	✅	One of: savings, checking, loan, business_checking, business_savings
accountNumber	String	✅	6–20 digits.
routingNumber	String	✅	Must be 9 digits.
accountHolder	Object	✅	Information about the account holder.

accountHolder Object

Field	Type	Required	Description
type	String	✅	Either personal or business.
firstName	String	✅	First name of the account holder.
lastName	String	✅	Last name of the account holder.

---

✅ Example - CARD request

{
  "externalPaymentId": "123456",
  "amount": {
    "total": 10.5,
    "currency": "USD"
  },
  "ipAddress": "192.168.0.1",
  "paymentType": "PULL",
  "sender": {
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "1234567890",
      "documentNumber": "987654321",
      "documentType": "NATIONAL_ID",
      "email": "[e-mail]",
      "countryCodeAlpha3": "USA"
    },
    "customerAddress": {
      "stateCode": "CA",
      "city": "San Francisco",
      "line1": "123 Market St",
      "state": "California",
      "zipCode": "00000"
    },
    "source": {
      "type": "CARD",
      "card": {
        "token": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  }
}

CARD response:

{
  "status": 200,
  "data": {
    "paymentId": 'dce568c6-98ec-456c-bb33-4a6809c4fff8',
    "parentPaymentId": 'dce568c6-98ec-456c-bb33-4a6809c4fff8',
    "externalPaymentId": 'c6bfd9ac-906f-4218-b9ec-aabf0f83fd0c',
    "redirectAcsUrl": 'https://sandbox-gw.simpleps.com/secure-code/start-challenge?token=dce568c6-98ec-456c-bb33-4a6809c4fff8',
    "amount": 10.25,
    "created": '2025-03-31 03:49:05',
    "approved": false,
    "message": 'Payment awaiting 3DS challenge verification',
    "automaticReversed": false,
    "status": 'CHALLENGE',
    "captured": false,
    "voided": false,
    "responseCode": '00',
    "issuerName": 'BANK ISSUER',
    "issuerCountry": 'ITALY',
    "cvcResult": 'N/A',
    "avsResult": 'N/A',
    "avsCardholderNameResult": 'N/A',
    "avsTelephoneResult": 'N/A'
  }
}

Field Name	Description	Example Value
status	HTTP response status code 200 if success 400 if validation error 500 if error	200
paymentId	Unique identifier for the payment	dce568c6-98ec-456c-bb33-4a6809c4fff8
parentPaymentId	Identifier linked to a parent payment if applicable	dce568c6-98ec-456c-bb33-4a6809c4fff8
externalPaymentId	Identifier for the external payment source sent	c6bfd9ac-906f-4218-b9ec-aabf0f83fd0c
redirectAcsUrl	URL for 3D Secure challenge verification, if status = 'CHALLENGE'	https://sandbox-gw.simpleps.com/secure-code/start-challenge?token=dce568c6-98ec-456c-bb33-4a6809c4fff8
amount	Total amount of the payment	10.25
created	Timestamp of when the payment was created (EST)	2025-03-31 03:49:05
approved	Status indicating if the payment is approved. true or false	false
message	Status message for the payment process	Payment awaiting 3DS challenge verification
automaticReversed	Indicates if payment was automatically reversed	false
status	Current status of the payment. CHALLENGE - if the transaction requires 3ds step up. AUTHORIZED - if the transaction was automatically authorized. DECLINED - if the transaction was declined by the network or internal rules.	CHALLENGE
captured	Indicates if the payment was captured. true - for automatic capture false - if pre-auth was requested	false
voided	Indicates if the payment was voided	false
responseCode	Response code from the issuer	00
issuerName	Name of the issuing bank	BANK SA
issuerCountry	Country of the issuer	UNITED STATES
cvcResult	Result of CVC verification APPROVED FAILED (verification failed) NOT_SENT (acquirer or issuer doesn't support) N/A (if challenge)	N/A
avsResult	Result of AVS verification APPROVED FAILED (verification failed) NOT_SENT (acquirer or issuer doesn't support) N/A (if challenge)	N/A

✅ Example – BANK_ACCOUNT request

{
  "externalPaymentId": "7891011",
  "amount": {
    "total": 50.75,
    "currency": "USD"
  },
  "ipAddress": "10.0.0.1",
  "paymentType": "PULL",
  "sender": {
    "customer": {
      "firstName": "Jane",
      "lastName": "Smith",
      "phoneNumber": "61992935445",
      "documentNumber": "12345678909",
      "documentType": "NATIONAL_ID",
      "email": "[e-mail]",
      "countryCodeAlpha3": "USA"
    },
    "customerAddress": {
      "stateCode": "TX",
      "city": "Austin",
      "line1": "456 Congress Ave",
      "line2": "Suite 800",
      "state": "Texas",
      "zipCode": "00000"
    },
    "source": {
      "type": "BANK_ACCOUNT",
      "bankAccount": {
        "accountType": "checking",
        "accountNumber": "111122223333",
        "routingNumber": "021000021",
        "accountHolder": {
          "type": "personal",
          "firstName": "Jane",
          "lastName": "Smith"
        }
      }
    }
  }
}