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:

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

curl -X POST https://{FQDN}/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "secretId": "YOUR_CLIENT_SECRET"
  }'

Response:

{
  "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 for the full guide.

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

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

curl -X POST https://{FQDN}/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):

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

Response (Authorized directly):

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

curl -X POST https://{FQDN}/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

What's Next