Orbital WalletDesarrolladores

API de pagos para comercios · v1

Integrá tus pagos en minutos.

Conectá el ERP, el sistema de nómina o la plataforma de tu comercio y pagá a proveedores, empleados o clientes en cualquier cuenta bancaria de Paraguay, con el saldo de la cuenta de pagos de tu empresa. Esta guía te conecta al ambiente de staging para homologar tu integración.

Primeros pasos

Inicio rápido

Cinco pasos para pasar de cero a tu primera dispersión en staging.

  1. Habilitá tu empresa para integrar

    Tu empresa necesita una cuenta de pagos en el portal empresarial de Orbital. Pedí a tu contacto de Orbital que active el canal Integración API en staging: por un canal seguro te enviamos la URL base de staging, la credencial de servicio de tu empresa, el ID de tu cuenta de pagos y, si vas a recibir notificaciones, la clave de firma de callbacks. Contanos también la URL HTTPS de tu receptor.

  2. Configurá tus variables de entorno

    Todos los ejemplos de esta guía leen estos tres valores. Guardalos en tu gestor de secretos o en un archivo local fuera de Git.

    .env
    # Te enviamos estos valores por un canal seguro. No los subas a tu repositorio.
    ORBITAL_API_BASE_URL=<URL base de staging que recibiste>
    ORBITAL_API_TOKEN=<credencial de staging de tu empresa>
    ORBITAL_SOURCE_ACCOUNT_ID=<ID de la cuenta de pagos de tu empresa>
  3. Verificá la conexión

    Consultá el saldo de la cuenta de pagos de tu empresa. Si recibís 200 con los saldos, tu credencial y tu cuenta están listas.

    curl "$ORBITAL_API_BASE_URL/integrations/orbital-pay/v1/account?sourceAccountId=$ORBITAL_SOURCE_ACCOUNT_ID" \
      -H "Authorization: Bearer $ORBITAL_API_TOKEN"
  4. Enviá tu primera dispersión

    Usá los datos de prueba que te indicó Orbital. En cURL, reemplazá sourceAccountId por el ID de tu cuenta. Un 202 significa que el lote quedó aceptado y el saldo reservado.

    curl -X POST "$ORBITAL_API_BASE_URL/integrations/orbital-pay/v1/disbursements" \
      -H "Authorization: Bearer $ORBITAL_API_TOKEN"
      -H "Content-Type: application/json"
      -H "Idempotency-Key: payroll-2026-11-001"
      --data '{
      "externalId": "payroll-2026-11-001",
      "sourceAccountId": "22222222-2222-4222-8222-222222222222",
      "payments": [
        {
          "externalId": "payment-2026-11-001",
          "amount": 100000,
          "destination": {
            "entityBic": "TESTPYPX",
            "accountNumber": "000123456",
            "beneficiary": {
              "documentType": "CI",
              "documentNumber": "1234567",
              "fullName": "Persona de prueba"
            }
          },
          "concept": "Pago de servicios"
        }
      ]
    }'
  5. Seguí el resultado

    Consultá GET /disbursements/{id} cada 5 segundos hasta un estado final, o recibí el evento transfer.settled cuando cada pago se liquide. También lo ves en el portal empresarial, en Desembolsos API.

Seguridad

Autenticación y ambiente

Cada request lleva tu credencial de servicio en la cabecera Authorization.

Cabeceras
Authorization: Bearer <tu credencial de staging>
Content-Type: application/json      # en POST
Idempotency-Key: <referencia única> # solo al crear dispersiones

Solo servidor a servidor

Nunca incluyas la credencial en una app móvil, un frontend web, logs ni repositorios. Si se expone, avisanos para revocarla.

Un ambiente, una credencial

Staging y producción usan URL base, credencial y clave de firma independientes. Una credencial de staging no funciona en producción.

Scopes

Tu credencial trae habilitados los scopes que acordaste con Orbital. Si un endpoint responde 403 FORBIDDEN, falta su scope.

ScopePermite
account:readConsultar saldo.
disbursements:writeCrear dispersiones.
disbursements:readConsultar lotes y pagos.
aliases:readConsultar alias de destinatarios.
cash-ins:writeDeclarar cash in y consultar bancos admitidos.
cash-ins:readConsultar cash in declarados.

Antes de codificar

Conceptos clave

Seis reglas que evitan la mayoría de los problemas de integración.

Montos enteros en guaraníes

amount es un entero en PYG, sin decimales ni separadores: 100000 equivale a Gs. 100.000.

202 no es dinero acreditado

El 202 confirma que el lote se aceptó y el saldo se reservó. La acreditación se confirma cuando el pago llega a LIQUIDADO.

Idempotencia

Ante un timeout, repetí el mismo body con la misma Idempotency-Key. Nunca cambies referencias para “destrabar” un reintento.

Todo o nada al aceptar

Si el saldo disponible no cubre el lote completo, se rechaza con 422 y no se reserva nada.

Tu cuenta de pagos

Los fondos salen de la cuenta de tu empresa, la misma del portal empresarial. Enviá su ID en sourceAccountId en cada request: tu credencial solo opera cuentas autorizadas.

Bonificaciones

Si el ambiente las tiene habilitadas, un pago a una cuenta Orbital Wallet elegible suma un componente BONUS debitado de la misma cuenta. Usá siempre los importes que informa la API.

Límites

Pagos por solicitud
1 a 25
Cash in por solicitud
1
Moneda
PYG, montos enteros
Tamaño del body
Hasta 1 MiB
Referencias
1 a 128 caracteres: letras, números y . _ : -
Página de pagos
Hasta 100 por página

Reintentos seguros

Reintentá solo caídas de red, 429 y 5xx, con espera creciente. Si se agotan los intentos, buscá el lote por externalId antes de decidir.

// Reintentar sin duplicar: misma clave y mismo body, siempre.
async function createDisbursement(batch) {
  const headers = {
    Authorization: `Bearer ${process.env.ORBITAL_API_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": batch.externalId,
  };
  const url = `${process.env.ORBITAL_API_BASE_URL}/integrations/orbital-pay/v1/disbursements`;
  for (let attempt = 1; attempt <= 5; attempt++) {
    const response = await fetch(url, { method: "POST", headers, body: JSON.stringify(batch) }).catch(() => null);
    if (response?.status === 200 || response?.status === 202) return response.json();
    if (response && response.status < 500 && response.status !== 429) {
      throw new Error(`API de pagos ${response.status}: ${await response.text()}`); // Error de negocio: no reintentar.
    }
    await new Promise(resolve => setTimeout(resolve, 2 ** attempt * 1000));
  }
  // Resultado incierto: consultá por referencia antes de decidir.
  const found = await fetch(`${url}?externalId=${encodeURIComponent(batch.externalId)}`, { headers });
  return found.ok ? found.json() : null;
}

Endpoints

Referencia de API

Todas las rutas cuelgan de tu URL base de staging seguida de /integrations/orbital-pay/v1.

MétodoRutaPara qué sirve
GET/accountConsultar saldo
POST/disbursementsCrear una dispersión
GET/disbursements?externalId={externalId}Buscar por referencia externa
GET/disbursements/{id}Consultar estado de un lote
GET/disbursements/{id}/paymentsConsultar pagos de un lote
GET/aliases/typesTipos de alias
POST/aliases/lookupConsultar un alias
GET/cash-ins/banksBancos para cash in
POST/cash-insDeclarar un cash in
GET/cash-ins?externalId={externalId}Buscar un cash in por referencia
GET/cash-ins/{id}Consultar estado de un cash in
GET/integrations/orbital-pay/v1/account

Consultar saldo

Devuelve el saldo contable, reservado y disponible de la cuenta de pagos de tu empresa. Es la mejor primera llamada para verificar tu credencial.

Scope requerido account:read

Parámetros

Authorizationheaderobligatorio
Bearer seguido de tu credencial de staging.
sourceAccountIdqueryopcional
ID de la cuenta de pagos de tu empresa. Enviálo siempre.

Errores frecuentes

curl "$ORBITAL_API_BASE_URL/integrations/orbital-pay/v1/account?sourceAccountId=$ORBITAL_SOURCE_ACCOUNT_ID" \
  -H "Authorization: Bearer $ORBITAL_API_TOKEN"
Respuesta 200
{
  "id": "22222222-2222-4222-8222-222222222222",
  "name": "Comercio de prueba S.A.",
  "currency": "PYG",
  "status": "ACTIVE",
  "postedBalance": 200000,
  "reservedBalance": 105000,
  "availableBalance": 95000,
  "observedAt": "2026-11-02T15:00:00Z"
}

availableBalance = postedBalance − reservedBalance.

POST/integrations/orbital-pay/v1/disbursements

Crear una dispersión

Acepta un lote de 1 a 25 pagos y reserva el saldo necesario. Un 202 confirma que el lote quedó registrado y reservado, no que el dinero ya llegó.

Scope requerido disbursements:write

Parámetros

Authorizationheaderobligatorio
Bearer seguido de tu credencial de staging.
Idempotency-Keyheaderobligatorio
Única por operación. Recomendamos usar el mismo externalId del lote.
Content-Typeheaderobligatorio
application/json

Campos del body

externalIdobligatorio
Tu referencia única del lote. Recomendado: usarla también como Idempotency-Key.
sourceAccountIdopcional
ID de la cuenta de pagos de tu empresa, de la que salen los fondos. Es opcional por compatibilidad, pero enviálo siempre.
callbackUrlopcional
URL HTTPS registrada con Orbital para recibir las liquidaciones. Sin este campo no se envían callbacks.
payments[]obligatorio
Entre 1 y 25 pagos.
payments[].externalIdobligatorio
Referencia única del pago, incluso entre lotes distintos.
payments[].amountobligatorio
Monto entero en guaraníes, mayor a cero. 100000 equivale a Gs. 100.000.
payments[].destination.entityBicobligatorio
BIC de la entidad destino, por ejemplo el que devuelve la consulta de alias.
payments[].destination.accountNumberobligatorio
Número de cuenta como texto. Conservá los ceros iniciales.
payments[].destination.beneficiary.documentTypeobligatorio
Tipo de documento, por ejemplo CI o RUC.
payments[].destination.beneficiary.documentNumberobligatorio
Número de documento como texto.
payments[].destination.beneficiary.fullNameobligatorio
Nombre del titular, hasta 160 caracteres.
payments[].conceptobligatorio
Concepto visible del pago, hasta 140 caracteres.

Errores frecuentes

curl -X POST "$ORBITAL_API_BASE_URL/integrations/orbital-pay/v1/disbursements" \
  -H "Authorization: Bearer $ORBITAL_API_TOKEN"
  -H "Content-Type: application/json"
  -H "Idempotency-Key: payroll-2026-11-001"
  --data '{
  "externalId": "payroll-2026-11-001",
  "sourceAccountId": "22222222-2222-4222-8222-222222222222",
  "payments": [
    {
      "externalId": "payment-2026-11-001",
      "amount": 100000,
      "destination": {
        "entityBic": "TESTPYPX",
        "accountNumber": "000123456",
        "beneficiary": {
          "documentType": "CI",
          "documentNumber": "1234567",
          "fullName": "Persona de prueba"
        }
      },
      "concept": "Pago de servicios"
    }
  ]
}'
Respuesta 202
{
  "id": "11111111-1111-4111-8111-111111111111",
  "externalId": "payroll-2026-11-001",
  "sourceAccountId": "22222222-2222-4222-8222-222222222222",
  "currency": "PYG",
  "status": "QUEUED",
  "revision": 1,
  "totals": {
    "paymentCount": 1,
    "principalAmount": 100000,
    "bonusAmount": 5000,
    "requiredBalance": 105000,
    "reservedRemaining": 105000
  },
  "createdAt": "2026-11-02T15:00:00Z",
  "updatedAt": "2026-11-02T15:00:00Z"
}

Si repetís el mismo request con la misma clave, recibís 200, el mismo id y la cabecera Idempotency-Replayed: true.

GET/integrations/orbital-pay/v1/disbursements?externalId={externalId}

Buscar por referencia externa

Recupera un lote por tu externalId exacto. Usalo cuando no sabés si un POST llegó (timeout, caída de red) antes de reintentar.

Scope requerido disbursements:read

Parámetros

Authorizationheaderobligatorio
Bearer seguido de tu credencial de staging.
externalIdqueryobligatorio
Referencia del lote que enviaste al crearlo.

Errores frecuentes

curl "$ORBITAL_API_BASE_URL/integrations/orbital-pay/v1/disbursements?externalId=payroll-2026-11-001" \
  -H "Authorization: Bearer $ORBITAL_API_TOKEN"
Respuesta 200
{
  "id": "11111111-1111-4111-8111-111111111111",
  "externalId": "payroll-2026-11-001",
  "sourceAccountId": "22222222-2222-4222-8222-222222222222",
  "currency": "PYG",
  "status": "PROCESSING",
  "revision": 1,
  "totals": {
    "paymentCount": 1,
    "principalAmount": 100000,
    "bonusAmount": 5000,
    "requiredBalance": 105000,
    "reservedRemaining": 105000
  },
  "createdAt": "2026-11-02T15:00:00Z",
  "updatedAt": "2026-11-02T15:00:00Z"
}
GET/integrations/orbital-pay/v1/disbursements/{id}

Consultar estado de un lote

Estado agregado y totales del lote. Consultalo cada 5 segundos mientras esté en QUEUED o PROCESSING, o esperá el callback.

Scope requerido disbursements:read

Parámetros

Authorizationheaderobligatorio
Bearer seguido de tu credencial de staging.
idpathobligatorio
UUID devuelto al crear el lote.

Errores frecuentes

curl "$ORBITAL_API_BASE_URL/integrations/orbital-pay/v1/disbursements/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer $ORBITAL_API_TOKEN"
Respuesta 200
{
  "id": "11111111-1111-4111-8111-111111111111",
  "externalId": "payroll-2026-11-001",
  "sourceAccountId": "22222222-2222-4222-8222-222222222222",
  "currency": "PYG",
  "status": "COMPLETED",
  "revision": 4,
  "totals": {
    "paymentCount": 1,
    "principalAmount": 100000,
    "bonusAmount": 5000,
    "requiredBalance": 105000,
    "reservedRemaining": 0
  },
  "createdAt": "2026-11-02T15:00:00Z",
  "updatedAt": "2026-11-02T15:00:42Z"
}
GET/integrations/orbital-pay/v1/disbursements/{id}/payments

Consultar pagos de un lote

Detalle paginado de cada pago: principal, bonificación, estado y referencia bancaria.

Scope requerido disbursements:read

Parámetros

Authorizationheaderobligatorio
Bearer seguido de tu credencial de staging.
idpathobligatorio
UUID del lote.
limitqueryopcional
Entre 1 y 100. Por defecto 100.
cursorqueryopcional
Valor de nextCursor de la página anterior. Omitilo en la primera página.

Errores frecuentes

curl "$ORBITAL_API_BASE_URL/integrations/orbital-pay/v1/disbursements/11111111-1111-4111-8111-111111111111/payments?limit=100" \
  -H "Authorization: Bearer $ORBITAL_API_TOKEN"
Respuesta 200
{
  "disbursementId": "11111111-1111-4111-8111-111111111111",
  "revision": 4,
  "items": [
    {
      "externalId": "payment-2026-11-001",
      "principal": {
        "amount": 100000,
        "status": "LIQUIDADO",
        "bankReference": "REFERENCIA-SINTETICA-001"
      },
      "bonus": {
        "eligible": true,
        "rateBps": 500,
        "amount": 5000,
        "status": "SETTLED",
        "bankReference": "REFERENCIA-SINTETICA-002"
      }
    }
  ],
  "nextCursor": null
}

Si el lote cambia mientras paginás, recibís 409 SNAPSHOT_CHANGED: volvé a pedir la primera página.

GET/integrations/orbital-pay/v1/aliases/types

Tipos de alias

Lista los tipos de alias que podés consultar para encontrar la cuenta de un destinatario.

Scope requerido aliases:read

Parámetros

Authorizationheaderobligatorio
Bearer seguido de tu credencial de staging.

Errores frecuentes

curl "$ORBITAL_API_BASE_URL/integrations/orbital-pay/v1/aliases/types" \
  -H "Authorization: Bearer $ORBITAL_API_TOKEN"
Respuesta 200
{
  "types": [
    "CI",
    "RUC",
    "MOBILE",
    "EMAIL"
  ]
}
POST/integrations/orbital-pay/v1/aliases/lookup

Consultar un alias

Resuelve un alias (CI, RUC, celular o correo) a banco, cuenta y titular. Solo consulta: no reserva saldo ni crea pagos.

Scope requerido aliases:read

Parámetros

Authorizationheaderobligatorio
Bearer seguido de tu credencial de staging.
Content-Typeheaderobligatorio
application/json

Errores frecuentes

curl -X POST "$ORBITAL_API_BASE_URL/integrations/orbital-pay/v1/aliases/lookup" \
  -H "Authorization: Bearer $ORBITAL_API_TOKEN"
  -H "Content-Type: application/json"
  --data '{
  "type": "CI",
  "value": "0012345"
}'
Respuesta 200
{
  "type": "CI",
  "entityBic": "TESTPYPX",
  "accountNumber": "000123456",
  "beneficiary": {
    "documentType": "CI",
    "documentNumber": "0012345",
    "firstName": "Persona",
    "lastName": "de prueba"
  }
}

Los datos de identidad que el banco no informa llegan como null. Conservá los ceros iniciales del valor.

GET/integrations/orbital-pay/v1/cash-ins/banks

Bancos para cash in

Lista los nombres de banco emisor que acepta la declaración de cash in.

Scope requerido cash-ins:write

Parámetros

Authorizationheaderobligatorio
Bearer seguido de tu credencial de staging.

Errores frecuentes

curl "$ORBITAL_API_BASE_URL/integrations/orbital-pay/v1/cash-ins/banks" \
  -H "Authorization: Bearer $ORBITAL_API_TOKEN"
Respuesta 200
{
  "banks": [
    "BANCO DE PRUEBA S.A.",
    "OTRO BANCO DE PRUEBA S.A."
  ]
}
POST/integrations/orbital-pay/v1/cash-ins

Declarar un cash in

Registra una transferencia que tu cliente va a hacer a la cuenta recaudadora de Orbital. Cuando llega una transferencia con el mismo banco, últimos cuatro dígitos, CI o RUC y monto, el ingreso se acredita solo en tu cuenta de pagos.

Scope requerido cash-ins:write

Parámetros

Authorizationheaderobligatorio
Bearer seguido de tu credencial de staging.
Content-Typeheaderobligatorio
application/json

Campos del body

externalIdobligatorio
Tu referencia única del cash in. Repetirla con los mismos datos devuelve el original.
amountobligatorio
Monto entero exacto en guaraníes que va a transferir tu cliente.
bankobligatorio
Banco emisor, tal como lo devuelve GET /cash-ins/banks.
accountLast4obligatorio
Últimos cuatro dígitos de la cuenta desde la que transfiere tu cliente.
documentobligatorio
CI o RUC del titular de esa cuenta. Puntos, guiones y espacios se ignoran.
dateopcional
Fecha prevista de la transferencia, de hoy hasta 30 días atrás. Por defecto, hoy.
callbackUrlopcional
URL HTTPS registrada con Orbital para recibir cash_in.credited y cash_in.rejected.

Errores frecuentes

curl -X POST "$ORBITAL_API_BASE_URL/integrations/orbital-pay/v1/cash-ins" \
  -H "Authorization: Bearer $ORBITAL_API_TOKEN"
  -H "Content-Type: application/json"
  --data '{
  "externalId": "cashin-2026-11-001",
  "amount": 150000,
  "bank": "BANCO DE PRUEBA S.A.",
  "accountLast4": "3456",
  "document": "1234567"
}'
Respuesta 201
{
  "id": "2026-11-12T13:00:00.000Z_33333333-3333-4333-8333-333333333333",
  "externalId": "cashin-2026-11-001",
  "amount": 150000,
  "currency": "PYG",
  "bank": "BANCO DE PRUEBA S.A.",
  "accountLast4": "3456",
  "date": "2026-11-12",
  "status": "PENDING",
  "createdAt": "2026-11-12T13:00:00.000Z",
  "autoMatchUntil": "2026-12-12T13:00:00.000Z",
  "resolvedAt": null,
  "rejectionReason": null
}

El externalId es la clave de idempotencia. Si repetís el mismo body recibís 200, el mismo id y la cabecera Idempotency-Replayed: true; con otros datos, 409 DUPLICATE_EXTERNAL_ID. Solo puede haber un cash in pendiente con el mismo banco, últimos cuatro dígitos, CI o RUC y monto: otro con distinto externalId devuelve 409 CASH_IN_ALREADY_PENDING hasta que el anterior quede CREDITED o REJECTED.

GET/integrations/orbital-pay/v1/cash-ins?externalId={externalId}

Buscar un cash in por referencia

Recupera un cash in por tu externalId exacto, por ejemplo después de un timeout.

Scope requerido cash-ins:read

Parámetros

Authorizationheaderobligatorio
Bearer seguido de tu credencial de staging.
externalIdqueryobligatorio
Referencia que enviaste al declararlo.

Errores frecuentes

curl "$ORBITAL_API_BASE_URL/integrations/orbital-pay/v1/cash-ins?externalId=cashin-2026-11-001" \
  -H "Authorization: Bearer $ORBITAL_API_TOKEN"
Respuesta 200
{
  "id": "2026-11-12T13:00:00.000Z_33333333-3333-4333-8333-333333333333",
  "externalId": "cashin-2026-11-001",
  "amount": 150000,
  "currency": "PYG",
  "bank": "BANCO DE PRUEBA S.A.",
  "accountLast4": "3456",
  "date": "2026-11-12",
  "status": "PENDING",
  "createdAt": "2026-11-12T13:00:00.000Z",
  "autoMatchUntil": "2026-12-12T13:00:00.000Z",
  "resolvedAt": null,
  "rejectionReason": null
}
GET/integrations/orbital-pay/v1/cash-ins/{id}

Consultar estado de un cash in

Estado del ingreso declarado. Pasa a CREDITED cuando se acredita o a REJECTED si Orbital lo rechaza.

Scope requerido cash-ins:read

Parámetros

Authorizationheaderobligatorio
Bearer seguido de tu credencial de staging.
idpathobligatorio
id devuelto al declararlo.

Errores frecuentes

curl "$ORBITAL_API_BASE_URL/integrations/orbital-pay/v1/cash-ins/2026-11-12T13:00:00.000Z_33333333-3333-4333-8333-333333333333" \
  -H "Authorization: Bearer $ORBITAL_API_TOKEN"
Respuesta 200
{
  "id": "2026-11-12T13:00:00.000Z_33333333-3333-4333-8333-333333333333",
  "externalId": "cashin-2026-11-001",
  "amount": 150000,
  "currency": "PYG",
  "bank": "BANCO DE PRUEBA S.A.",
  "accountLast4": "3456",
  "date": "2026-11-12",
  "status": "CREDITED",
  "createdAt": "2026-11-12T13:00:00.000Z",
  "autoMatchUntil": "2026-12-12T13:00:00.000Z",
  "resolvedAt": "2026-11-12T14:05:10.120Z",
  "rejectionReason": null
}

Ciclo de vida

Estados

El lote tiene un estado agregado y cada pago informa el estado de su principal y su bonificación.

Lote

EstadoQué significaFinal
QUEUEDLote aceptado y saldo reservado. Todavía no se envió al banco.No
PROCESSINGHay pagos o bonificaciones en curso.No
COMPLETEDTodos los pagos aplicables quedaron liquidados.Sí
PARTIALLY_COMPLETEDAl menos un pago se liquidó y otro terminó rechazado.Sí
FAILEDNingún pago se liquidó y no queda nada en curso. La reserva se libera.Sí
BLOCKEDUn bloqueo operativo detiene nuevos envíos. Orbital lo gestiona; no reenvíes el lote.No
REQUIRES_REVIEWResultado incierto o devolución en revisión por Orbital. No reenvíes el lote.No

Pago (principal)

EstadoQué significaFinal
PENDIENTEEsperando envío.No
ENVIANDO / ENVIADO / ACEPTADOEn proceso bancario.No
LIQUIDADOAcreditado al destinatario, con referencia bancaria.Sí
RECHAZADOEl banco rechazó la transferencia; la reserva se libera.Sí
NO_EJECUTADONo se envió al banco.Sí
DEVUELTO / INCIERTOEn revisión por Orbital antes de liberar fondos.No

La bonificación informa NOT_APPLICABLE, ZERO_AMOUNT, PENDING, PROCESSING, SETTLED, FAILED, CANCELED o REQUIRES_REVIEW.

Cash in

EstadoQué significaFinal
PENDINGDeclarado. Se acredita solo si llega una transferencia que coincide antes de autoMatchUntil.No
CREDITEDLa transferencia llegó y el monto se acreditó en tu cuenta de pagos.Sí
REJECTEDOrbital lo rechazó; rejectionReason explica el motivo.Sí

Solo se acredita automáticamente una transferencia recibida después de declararla. Si llegó antes, o si otra empresa declaró los mismos datos, Orbital la concilia manualmente.

Notificaciones

Callbacks de liquidación

Si enviás callbackUrl al crear el lote, te avisamos con un POST firmado cada vez que una transferencia queda liquidada.

Un evento por transferencia

Se emite transfer.settled solo al confirmar LIQUIDADO. Un pago con bonificación genera dos eventos: PRINCIPAL y BONUS.

Al menos una vez

Puede llegar repetido o fuera de orden. Deduplicá por id, nunca solo por paymentExternalId.

Respondé 2xx rápido

Tenés 8 segundos. Sin respuesta, 408, 429 o 5xx se reintentan 3 veces durante 5 minutos; un 4xx es un rechazo final y no se reintenta. Un reintento nunca vuelve a ejecutar el pago.

Habilitación

Compartí con Orbital la URL exacta de tu receptor: HTTPS en el puerto 443, DNS público, certificado válido y sin redirecciones. Recibís la clave de firma por un canal seguro y hacemos juntos una liquidación de prueba.

Cabeceras

X-Orbital-Event-Id
Identificador estable del evento (64 hex). Usalo para deduplicar.
X-Orbital-Timestamp
Segundos Unix del intento. Se renueva en cada reintento.
X-Orbital-Key-Id
Versión de la clave de firma. Elegí la clave local con este valor.
X-Orbital-Signature
v1=<hex de HMAC-SHA256(clave, timestamp + "." + body crudo)>

Evento

transfer.settled
{
  "id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "type": "transfer.settled",
  "occurredAt": "2026-11-05T19:17:22.341Z",
  "stage": "stg",
  "disbursementId": "11111111-1111-4111-8111-111111111111",
  "externalId": "payroll-2026-11-001",
  "paymentExternalId": "payment-2026-11-001",
  "sourceAccountId": "22222222-2222-4222-8222-222222222222",
  "component": "PRINCIPAL",
  "amount": 100000,
  "currency": "PYG",
  "status": "LIQUIDADO",
  "bankReference": "REFERENCIA-SINTETICA-001"
}

Si declarás cash in con callbackUrl, recibís cash_in.credited al acreditarse o cash_in.rejected si se rechaza, con las mismas cabeceras y firma.

cash_in.credited
{
  "id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "type": "cash_in.credited",
  "occurredAt": "2026-11-12T14:05:10.120Z",
  "stage": "stg",
  "cashInId": "2026-11-12T13:00:00.000Z_33333333-3333-4333-8333-333333333333",
  "externalId": "cashin-2026-11-001",
  "sourceAccountId": "22222222-2222-4222-8222-222222222222",
  "amount": 150000,
  "currency": "PYG",
  "status": "CREDITED",
  "bankReference": "REFERENCIA-SINTETICA-003"
}

Verificar la firma

Calculá el HMAC sobre los bytes crudos del body antes de parsear el JSON, compará en tiempo constante, validá una ventana de 5 minutos y fijá stg como ambiente esperado desde tu configuración.

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const EVENT_STATUS = new Map([["transfer.settled", "LIQUIDADO"], ["cash_in.credited", "CREDITED"], ["cash_in.rejected", "REJECTED"]]);

// keys: Map<keyId, signingKey> cargado desde tu almacén de secretos.
export function verifyCallback(rawBody, headers, keys, expectedStage, nowMs = Date.now()) {
  const timestamp = headers["x-orbital-timestamp"];
  const keyId = headers["x-orbital-key-id"];
  const signature = headers["x-orbital-signature"];
  const eventId = headers["x-orbital-event-id"];
  if (!Buffer.isBuffer(rawBody) || !/^\d{1,12}$/.test(timestamp ?? "") ||
      !/^v1=[a-f0-9]{64}$/.test(signature ?? "") || !/^[a-f0-9]{64}$/.test(eventId ?? "")) {
    throw new Error("INVALID_CALLBACK_HEADERS");
  }
  const secret = keys.get(keyId);
  if (typeof secret !== "string" || secret.length < 32) throw new Error("UNKNOWN_CALLBACK_KEY");
  const expected = createHmac("sha256", secret).update(timestamp + ".", "utf8").update(rawBody).digest();
  if (!timingSafeEqual(expected, Buffer.from(signature.slice(3), "hex"))) {
    throw new Error("INVALID_CALLBACK_SIGNATURE");
  }
  if (Math.abs(Math.floor(nowMs / 1000) - Number(timestamp)) > 300) {
    throw new Error("CALLBACK_TIMESTAMP_OUTSIDE_WINDOW");
  }
  const event = JSON.parse(rawBody.toString("utf8"));
  if (event.id !== eventId || event.stage !== expectedStage ||
      !EVENT_STATUS.has(event.type) || EVENT_STATUS.get(event.type) !== event.status) {
    throw new Error("INVALID_CALLBACK_EVENT");
  }
  return event;
}

const app = express();
const signingKeys = await loadSigningKeys(); // Tu función: Map<keyId, signingKey>.
// Capturá el body crudo: la firma se calcula sobre los bytes exactos.
app.post("/callbacks/orbital", express.raw({ type: "application/json", limit: "64kb" }), async (req, res) => {
  let event;
  try {
    event = verifyCallback(req.body, req.headers, signingKeys, "stg");
  } catch {
    return res.sendStatus(401);
  }
  await saveEventOnce(event); // Tu función: restricción única por (stage, id) y efecto en la misma transacción.
  res.sendStatus(204);
});
Resultado en tu receptorRespondéQué hacemos
Evento guardado de forma durable200 · 202 · 204Lo damos por entregado.
Duplicado ya procesado200 · 204Lo damos por entregado.
Firma, clave o timestamp inválidos401Reintentamos.
Payload que no coincide con tus datos400 · 422Reintentamos; revisalo sin aplicar efectos.
Falla temporal de tu base de datos503Reintentamos.

Diagnóstico

Errores

Todos los errores comparten el mismo formato. Guardá el requestId: es lo que necesitamos para ayudarte.

Error
{
  "code": "INSUFFICIENT_OPERATING_BALANCE",
  "message": "Saldo operativo insuficiente",
  "requestId": "33333333-3333-4333-8333-333333333333"
}
CódigoHTTPQué significaQué hacerReintentar
INVALID_REQUEST400El body, un parámetro o una cabecera no cumplen el contrato.Corregí el request; el campo afectado se describe en message.No
CALLBACK_NOT_ALLOWED400La callbackUrl no está habilitada para tu integración.Usá la URL exacta que registraste con Orbital, u omití el campo.No
UNAUTHORIZED401Credencial ausente, inválida, revocada o de otro ambiente.Verificá la cabecera Authorization y que uses la credencial de staging.No
FORBIDDEN403Tu credencial no tiene el scope que exige el endpoint.Pedí a Orbital que habilite el scope necesario.No
SOURCE_ACCOUNT_FORBIDDEN403La cuenta de origen no está autorizada para tu credencial.Enviá el ID de la cuenta de tu empresa que recibiste con tu credencial.No
NOT_FOUND404El lote o cash in no existe para tu credencial.Revisá el id o externalId consultado.No
SOURCE_ACCOUNT_NOT_FOUND404La cuenta de origen no está disponible.Confirmá el ID de tu cuenta con Orbital.No
IDEMPOTENCY_CONFLICT409Reutilizaste una Idempotency-Key con un body distinto.Para reintentar, enviá exactamente el mismo body. Para un lote nuevo, usá una clave nueva.No
DUPLICATE_EXTERNAL_ID409Ese externalId ya fue usado: en un lote, con otra clave; en un cash in, con otros datos.Consultá el existente con GET /disbursements?externalId=… o GET /cash-ins?externalId=…No
CASH_IN_ALREADY_PENDING409Ya tenés un cash in pendiente con el mismo banco, últimos cuatro dígitos, CI o RUC y monto. message indica su externalId.Esperá a que ese cash in quede CREDITED o REJECTED antes de declarar otro igual, o consultalo con GET /cash-ins?externalId=…No
DUPLICATE_PAYMENT_REFERENCE409El externalId de un pago ya existe, incluso en otro lote.Asigná referencias de pago únicas.No
ACCOUNT_BLOCKED409La cuenta de tu empresa está bloqueada para nuevos lotes y cash in.Contactá a Orbital.No
MANDATE_LIMIT_EXCEEDED409El lote supera el monto máximo acordado para tu integración.Dividí los pagos en lotes más chicos.No
SNAPSHOT_CHANGED409El lote cambió mientras paginabas sus pagos.Volvé a pedir la primera página sin cursor.Sí
PAYLOAD_TOO_LARGE413El body supera 1 MiB (4 KiB en consulta de alias y cash in).Reducí el tamaño o la cantidad de pagos.No
INSUFFICIENT_OPERATING_BALANCE422El saldo disponible no cubre el lote completo. No se reservó nada.Consultá /account y cargá saldo desde el portal empresarial antes de reintentar.No
ALIAS_LOOKUP_REJECTED422El banco no pudo resolver el alias.No implica que el alias no exista; verificá el valor con el destinatario.No
RATE_LIMITED429Demasiadas solicitudes.Esperá lo indicado en Retry-After.Sí
INTERNAL_ERROR500Fallo interno con resultado incierto.Buscá el lote por externalId o repetí el mismo request con la misma clave.Sí
SERVICE_UNAVAILABLE503Servicio no disponible temporalmente.Reintentá con espera creciente. No asumas saldo cero.Sí
ELIGIBILITY_UNAVAILABLE503No se pudo verificar la elegibilidad del destinatario. No se reservó nada.Reintentá con espera creciente y el mismo request.Sí
CALLBACK_UNAVAILABLE503Los callbacks todavía no están habilitados para tu integración.Coordiná la habilitación con Orbital u omití callbackUrl.No
ALIAS_LOOKUP_UNAVAILABLE503La consulta de alias no está disponible temporalmente.Reintentá más tarde.Sí

Antes de producción

Checklist de homologación

Cuando tu integración cumpla estos puntos en staging, está lista para coordinar el pase a producción.

  • GET /account responde 200 con tu credencial de staging.
  • Creaste un lote de un pago y recibiste 202 con su id.
  • Repetiste el mismo POST y recibiste 200, el mismo id e Idempotency-Replayed: true.
  • La misma Idempotency-Key con otro body devuelve 409 IDEMPOTENCY_CONFLICT y lo manejás sin reintentar.
  • Seguís el lote por id o externalId hasta un estado final, con espera creciente ante fallos.
  • Paginás los pagos y reiniciás desde la primera página ante 409 SNAPSHOT_CHANGED.
  • Tu receptor de callbacks acepta una firma válida y rechaza body alterado, clave desconocida y timestamp vencido.
  • Un callback repetido o simultáneo produce un solo efecto, y principal y bono se registran aunque lleguen fuera de orden.
  • Si declarás cash in, seguís cada uno por id o externalId hasta CREDITED o REJECTED y aplicás cada callback una sola vez.
  • Ante 401, 403 y 422 tu sistema no reintenta a ciegas.
  • Tus logs nunca contienen la credencial, la clave de firma ni las cabeceras de firma completas.
Pase a producción
Coordiná la habilitación con tu contacto de Orbital. Producción tiene URL base, credencial y clave de firma propias, y mueve dinero real: nunca reutilices valores de staging.

Herramientas

Recursos