Primeros Pasos

Descripción General

El Inyo Payment Gateway le permite:

• Extraer fondos (pull) — Cobrar a clientes mediante tarjetas de crédito/débito o transferencias bancarias ACH
• Enviar fondos (push) — Enviar payouts nacionales (ACH) o internacionales (tarjetas, PIX, billeteras, cuentas bancarias)
• Pull + Push — Cobrar y desembolsar en una sola llamada a la API

Todas las operaciones siguen un patrón de API REST consistente con autenticación OAuth 2.0.

Requisitos Previos

Antes de comenzar la integración, necesitará tres credenciales del equipo de Inyo:

Para obtener credenciales, contacte al equipo comercial de Inyo. Durante el onboarding, también proporcionará su(s) URL(s) de origen para la lista blanca de CORS.

Flujo de Integración

Esta es la ruta de integración típica para un pago con tarjeta:

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

Para pagos ACH y push, omita el paso 2 (tokenización) y proporcione los detalles bancarios o de destino directamente en el payload del pago.

Ejemplo Rápido: Autorizar un Pago con Tarjeta

Paso 1 — Obtenga un token de acceso

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

Respuesta:

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

Paso 2 — Tokenice una tarjeta (del lado del cliente)

Cargue la biblioteca del tokenizador y cree un token con los datos del tarjetahabiente. Vea Tokenización de Tarjetas para la guía completa.

<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 contiene el token de la tarjeta
    submitPayment(response.additionalData.token);
  },
  errorCallback: (error) => {
    console.error('Tokenization failed:', error.code);
  }
});

// Llame cuando el usuario haga clic en "Pagar"
tokenizer.tokenizeCard();

Paso 3 — Cree el pago

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"
      }
    }
  }'

Respuesta (Challenge 3DS requerido):

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

Respuesta (Autorizado directamente):

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

Paso 4 — Capture cuando esté listo

curl -X POST https://{FQDN}/payments/order-12345/capture \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Ciclo de Vida del Pago

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

• CHALLENGE → El tarjetahabiente debe completar la verificación 3DS
• AUTHORIZED → Fondos reservados; puede capturar o anular (void)
• CAPTURED → Fondos liquidados; puede reembolsar (total o parcial)
• VOIDED → Autorización cancelada antes de la captura
• DECLINED → Pago rechazado por el emisor o por las reglas de fraude

Entornos

Qué Sigue