Inyo Global is a licensed money movement infrastructure provider (50-state MTL holder, FinCEN MSB: 31000231163732). The platform operates under Golden Money Transfer, Inc. dba Inyo.

When designing an integration, always refer to the documentation at Inyo Developer Portal or the LLM-optimized docs.

Authentication

All API calls require OAuth 2.0 Bearer tokens. Obtain tokens via POST /oauth/token with your Client ID and Client Secret. Tokens expire — always handle token refresh. Never hardcode tokens; store them securely and refresh before expiry.

Refer to the Authentication Guide for details.

Card tokenization uses a separate client-side library (inyo.js) with a Public Key. Never mix server-side OAuth credentials with client-side tokenization keys.

Environments

Always develop and test against the Sandbox environment first. Never use production credentials in development or testing.

Payment Gateway Integration

Card Payments — Recommended Flow

The standard integration path for card payments is:

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

Refer to the Getting Started Guide for the full walkthrough.

Card Tokenization

Always use the inyo.js client-side library for card tokenization. Never send raw card numbers (PANs) to your server — this violates PCI compliance.

The tokenizer supports two 3DS integration modes:

• URL Redirect (successUrl/failUrl) — for server-rendered apps
• PostMessage (enablePostMessage: true) — for SPAs using iframes

Refer to the Tokenizing Cards Guide for complete examples.

Pre-Authorization vs Direct Capture

Use pre-authorization (two-step: authorize then capture) when:

• You need to verify funds before fulfilling an order
• You want to review transactions for fraud before capturing
• The final amount may differ from the initial authorization

Use direct capture (one-step) when:

• Payment and fulfillment happen simultaneously
• The amount is final at the time of payment

ACH Payments

For ACH bank account payments, skip tokenization — provide bank/destination details directly in the payment payload using paymentMethod.type: "BANK_DEPOSIT".

Refer to the ACH Guide.

Push Transactions (Payouts)

To send money (domestic or international), use POST /v2/payment with paymentType: "PUSH". Push transactions support:

• Domestic payouts via ACH
• International payouts to cards, bank accounts, PIX, and wallets in 165+ countries
• China local wallets via Visa Direct Wallets

Refer to the Push Transaction Guide.

Pull and Push Combined

For collect-and-disburse in a single API call, use paymentType: "PULLPUSH". The sender uses PULL-style source fields, and the recipient uses PUSH-style destination fields.

Refer to the Pull and Push Guide.

Payload Structure

Be aware of the intentional payload structure differences:

• PULL transactions: Flat sender structure — sender.firstName, sender.address, sender.paymentMethod
• PUSH transactions: Nested sender structure — sender.customer.firstName, sender.customerAddress, recipient.destination
• PULLPUSH transactions: Sender uses PULL-style source, recipient uses PUSH-style destination

3D Secure Handling

When a payment returns status: "CHALLENGE", the cardholder must complete 3DS verification. Two integration options:

1. URL Redirect: Redirect the user to redirectUrl. After verification, they return to your successUrl or failUrl.
2. PostMessage: Load redirectUrl in an iframe and listen for window.postMessage events for SPA-friendly handling.

Never skip 3DS handling — payments in CHALLENGE status will not proceed without cardholder verification.

AVS / CVC Responses

Always check avsResult and cvcResult in authorization responses. These are advisory — Inyo does not auto-decline based on AVS/CVC. Your application must implement its own risk rules based on these values.

Refer to the AVS/CVC Guide.

Response Codes

Internal response codes must never be exposed to end users. Map them to customer-facing messages using the 11 categories defined in the Response Code Reference.

Webhooks

Register webhook endpoints to receive real-time payment status notifications. Always:

• Verify webhook signatures
• Handle duplicate deliveries idempotently
• Respond with HTTP 200 quickly; process asynchronously

Refer to the Webhooks Guide.

Fraud Prevention

• Use pre-authorization to review high-risk transactions before capture
• Implement velocity checks (transaction count/amount per time window)
• Monitor AVS/CVC mismatches
• Consider proactive refunds over chargebacks — refunds are cheaper
• Never expose internal error codes or system details to end users

Refer to the Fraud Mitigation Guide.

Remittance Integration

For cross-border money transfers, the flow is:

1. Authenticate → OAuth token
2. Create Sender → KYC registration with trust levels
3. Get FX Quote → POST /foreign-exchange for rate locking
4. Create Recipient → With country-specific schema
5. Create Recipient Account → Bank account or wallet
6. Fund Sender Account → Link funding source
7. Create Transaction → Execute the transfer

Always check country-specific schemas via the Data Population endpoints before creating recipients or accounts.

Refer to the Remittance Getting Started Guide.

Testing

Use the sandbox environment with test card numbers:

• 4000 0000 0000 0002 — Successful authorization
• 4000 0000 0000 0069 — Declined
• 4000 0000 0000 3220 — 3DS Challenge required

Refer to the Test Data Guide for the full list.

Common Mistakes to Avoid

1. Never send raw card data server-side — always tokenize client-side with inyo.js
2. Never expose internal response codes to customers — map to friendly messages
3. Never skip 3DS handling — CHALLENGE payments require cardholder verification
4. Never hardcode OAuth tokens — they expire; implement refresh logic
5. Never use production credentials in sandbox or vice versa
6. Never auto-decline based on AVS alone — use it as one signal among many
7. Never ignore webhooks — polling is unreliable for payment status updates