---
description: >-
  Everything you need to accept payments, send payouts, and manage the full
  transaction lifecycle with the Inyo Payment Gateway.
---

# Getting Started

## Overview

The Inyo Payment Gateway enables you to:

- **Pull funds** — Charge customers via credit/debit cards or ACH bank transfers
- **Push funds** — Send payouts domestically (ACH) or internationally (cards, PIX, wallets, bank accounts)
- **Pull + Push** — Collect and disburse in a single API call

All operations follow a consistent REST API pattern with OAuth 2.0 authentication.

## Prerequisites

Before you begin integrating, you'll need three credentials from the Inyo team:

| Credential | Format | Purpose |
|---|---|---|
| **Public Key** | `a23271e1-c1c0-44d3-...` | Card tokenization via the JavaScript library |
| **Client ID** | `MY_CLIENT_ID` | OAuth authentication (`/oauth/token`) |
| **Client Secret** | `4efa3460-a121-1ca9-...` | OAuth authentication (`/oauth/token`) |

> **To obtain credentials**, contact the Inyo commercial team. During onboarding, you'll also provide your origin URL(s) for CORS whitelisting.

## Integration Flow

Here's the typical integration path for a card payment:

```
1. Authenticate       →  POST /oauth/token
2. Tokenize card      →  Client-side via inyo.js
3. Create payment     →  POST /v2/payment
4. Handle 3DS         →  Redirect to redirectAcsUrl (if CHALLENGE)
5. Capture payment    →  POST /payments/{id}/capture
6. (Optional) Void    →  POST /payments/{id}/void
7. (Optional) Refund  →  POST /payments/{id}/refund
```

For ACH and push payments, skip step 2 (tokenization) and provide bank/destination details directly in the payment payload.

## Quick Example: Authorize a Card Payment

### Step 1 — Get an access token

```bash
curl -X POST https://sandbox-gw.simpleps.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "secretId": "YOUR_CLIENT_SECRET"
  }'
```

**Response:**

```json
{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}
```

### Step 2 — Tokenize a card (client-side)

Load the tokenizer library and create a token from the cardholder's data. See [Tokenizing Cards](apis/tokenizing-cards.md) for the full guide.

```html
<script src="https://cdn.simpleps.com/sandbox/inyo.js"></script>
```

```javascript
const tokenizer = new InyoTokenizer({
  targetId: '#payment-form',
  publicKey: 'YOUR_PUBLIC_KEY',
  storeLaterUse: false,
  successCallback: (response) => {
    // response.additionalData.token contains the card token
    submitPayment(response.additionalData.token);
  },
  errorCallback: (error) => {
    console.error('Tokenization failed:', error.code);
  }
});

// Call when user clicks "Pay"
tokenizer.tokenizeCard();
```

### Step 3 — Create the payment

```bash
curl -X POST https://sandbox-gw.simpleps.com/v2/payment \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "order-12345",
    "ipAddress": "203.0.113.42",
    "paymentType": "PULL",
    "capture": false,
    "amount": {
      "total": 99.99,
      "currency": "USD"
    },
    "sender": {
      "firstName": "John",
      "lastName": "Smith",
      "address": {
        "countryCode": "US",
        "stateCode": "NY",
        "city": "New York",
        "line1": "123 Main Street",
        "zipCode": "10001"
      },
      "paymentMethod": {
        "type": "CARD",
        "cardTokenId": "ab5fc589-8b48-4531-94c0-68b0629c13fe"
      }
    }
  }'
```

**Response (3DS Challenge required):**

```json
{
  "status": 200,
  "data": {
    "paymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8",
    "externalPaymentId": "order-12345",
    "amount": 99.99,
    "status": "CHALLENGE",
    "redirectAcsUrl": "https://sandbox-gw.simpleps.com/secure-code/start-challenge?token=dce568c6-...",
    "approved": false,
    "captured": false,
    "message": "Payment awaiting 3DS challenge verification"
  }
}
```

**Response (Authorized directly):**

```json
{
  "status": 200,
  "data": {
    "paymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8",
    "externalPaymentId": "order-12345",
    "amount": 99.99,
    "status": "AUTHORIZED",
    "approved": true,
    "captured": false,
    "message": "Payment Approved",
    "responseCode": "00",
    "cvcResult": "APPROVED",
    "avsResult": "APPROVED"
  }
}
```

### Step 4 — Capture when ready

```bash
curl -X POST https://sandbox-gw.simpleps.com/payments/order-12345/capture \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
```

## Payment Lifecycle

```
                    ┌──────────┐
                    │ CHALLENGE│ ──(3DS fail)──→ DECLINED
                    └────┬─────┘
                         │ (3DS success)
                         ▼
┌─────────┐     ┌────────────┐     ┌─────────┐
│ Payment │────→│ AUTHORIZED │────→│ CAPTURED │────→ REFUNDED
│ Created │     └──────┬─────┘     └─────────┘    (full/partial)
└─────────┘            │
                       ▼
                    VOIDED
```

- **CHALLENGE** → Cardholder must complete 3DS verification
- **AUTHORIZED** → Funds reserved; you can capture or void
- **CAPTURED** → Funds settled; you can refund (full or partial)
- **VOIDED** → Authorization cancelled before capture
- **DECLINED** → Payment rejected by issuer or fraud rules

## Environments

| Environment | API Base URL | Tokenizer URL |
|---|---|---|
| **Sandbox** | `https://sandbox-gw.simpleps.com` | `https://cdn.simpleps.com/sandbox/inyo.js` |
| **Production** | `https://gw.simpleps.com` | `https://cdn.simpleps.com/production/inyo.js` |

## What's Next

| Topic | Description |
|---|---|
| [Authentication](authentication-methods.md) | OAuth 2.0 token details and best practices |
| [Tokenizing Cards](apis/tokenizing-cards.md) | Client-side card tokenization with `inyo.js` |
| [Pulling Funds](apis/payment/pulling-funds/) | Card and ACH payment collection |
| [Push Transactions](apis/payment/push-transaction.md) | Domestic and international payouts |
| [3D Secure](apis/payment/pulling-funds/cards/authorizing/handling-3d-secure.md) | Challenge flow and redirect handling |
| [Webhooks](apis/webhooks.md) | Real-time transaction status notifications |
| [Test Data](apis/test-data/cards.md) | Sandbox test cards and simulation codes |
| [Technical Resources](technical-resources.md) | API keys, URLs, rate limits, and OpenAPI spec |