Primeiros Passos

Visão Geral

O Inyo Payment Gateway permite que você:

• Faça pull de fundos — Cobre clientes via cartões de crédito/débito ou transferências bancárias ACH
• Faça push de fundos — Envie payouts domésticos (ACH) ou internacionais (cartões, PIX, carteiras, contas bancárias)
• Pull + Push — Colete e desembolse em uma única chamada de API

Todas as operações seguem um padrão consistente de API REST com autenticação OAuth 2.0.

Pré-requisitos

Antes de começar a integração, você precisará de três credenciais da equipe Inyo:

Para obter as credenciais, entre em contato com a equipe comercial da Inyo. Durante o onboarding, você também fornecerá a(s) URL(s) de origem para a whitelist de CORS.

Fluxo de Integração

Este é o caminho de integração típico para um pagamento com cartão:

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 pagamentos ACH e push, pule a etapa 2 (tokenização) e forneça os dados bancários/de destino diretamente no payload do pagamento.

Exemplo Rápido: Autorizar um Pagamento com Cartão

Etapa 1 — Obtenha um token de acesso

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

Resposta:

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

Etapa 2 — Tokenize um cartão (lado do cliente)

Carregue a biblioteca do tokenizador e crie um token a partir dos dados do portador do cartão. Veja Tokenizando Cartões para o guia completo.

<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 contém o token do cartão
    submitPayment(response.additionalData.token);
  },
  errorCallback: (error) => {
    console.error('Tokenization failed:', error.code);
  }
});

// Chame quando o usuário clicar em "Pagar"
tokenizer.tokenizeCard();

Etapa 3 — Crie o pagamento

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

Resposta (Challenge 3DS necessário):

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

Resposta (Autorizado diretamente):

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

Etapa 4 — Capture quando estiver pronto

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

Ciclo de Vida do Pagamento

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

• CHALLENGE → O portador do cartão deve completar a verificação 3DS
• AUTHORIZED → Fundos reservados; você pode capturar ou cancelar (void)
• CAPTURED → Fundos liquidados; você pode reembolsar (total ou parcial)
• VOIDED → Autorização cancelada antes da captura
• DECLINED → Pagamento rejeitado pelo emissor ou por regras de fraude

Ambientes

O Que Vem a Seguir