{"openapi":"3.0.3","info":{"title":"API de dispersión de pagos para comercios","version":"1.5.0","description":"API para que cualquier comercio con cuenta de pagos en Orbital Wallet disperse pagos desde sus sistemas. Documento publicado para homologación en staging: la URL base, la credencial de servicio, el ID de la cuenta de pagos y la clave de firma de callbacks se entregan por un canal seguro y no forman parte de este archivo."},"security":[{"orbitalPayServiceBearer":[]}],"paths":{"/integrations/orbital-pay/v1/account":{"get":{"operationId":"getOrbitalPayAccount","summary":"Consultar saldo operativo","description":"Requiere scope account:read. Aislamiento por principal y ambiente resuelto desde la credencial.","responses":{"200":{"description":"Cuenta virtual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"},"example":{"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"}}}},"401":{"description":"Credencial ausente, inválida, revocada o de otro ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope o mandato insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de frecuencia; respetar Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Segundos antes de reintentar","schema":{"type":"integer","minimum":1}}}},"500":{"description":"Fallo interno; ante resultado incierto recuperar por externalId o repetir la misma clave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Servicio o elegibilidad no disponibles; no asumir saldo cero ni cliente no elegible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"sourceAccountId","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SourceAccountId"},"description":"ID de la cuenta de pagos de tu empresa. Requiere autorizacion de cuenta ademas de account:read."}]}},"/integrations/orbital-pay/v1/disbursements":{"post":{"operationId":"createOrbitalPayDisbursement","summary":"Aceptar una dispersión","description":"Requiere scope disbursements:write. Aislamiento por principal y ambiente resuelto desde la credencial. sourceAccountId debe estar en sourceAccountIds de la credencial. El callback se entrega asincronicamente al confirmar liquidacion; fallos de entrega no vuelven a ejecutar pagos.","responses":{"200":{"description":"Mismo recurso, con estado actual, sin nueva reserva ni envío","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Disbursement"}}},"headers":{"Idempotency-Replayed":{"schema":{"type":"boolean","enum":[true]}}}},"202":{"description":"Lote y reserva persistidos; no implica liquidación bancaria","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Disbursement"},"example":{"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"}}},"headers":{"Location":{"description":"Ruta del recurso aceptado","schema":{"type":"string"}},"Idempotency-Replayed":{"schema":{"type":"boolean","enum":[false]}}}},"400":{"description":"Solicitud inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Credencial ausente, inválida, revocada o de otro ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope o mandato insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"SOURCE_ACCOUNT_NOT_FOUND: cuenta virtual no disponible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicto de idempotencia, referencia, cuenta bloqueada, límite de mandato o revisión","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Cuerpo mayor a 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Saldo operativo insuficiente; no se acepta ni reserva el lote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de frecuencia; respetar Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Segundos antes de reintentar","schema":{"type":"integer","minimum":1}}}},"500":{"description":"Fallo interno; ante resultado incierto recuperar por externalId o repetir la misma clave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Servicio o elegibilidad no disponibles; no asumir saldo cero ni cliente no elegible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},"description":"Única por principal, ambiente y operación. Mismo contenido normalizado repite el recurso; otro contenido produce 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDisbursement"},"example":{"externalId":"payroll-2026-11-001","sourceAccountId":"22222222-2222-4222-8222-222222222222","callbackUrl":"https://tu-dominio.example.com/callback","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"}]}}}},"callbacks":{"transferSettled":{"{$request.body#/callbackUrl}":{"post":{"summary":"Transferencia liquidada","security":[],"description":"Solo cuando se envio callbackUrl. Verificar HMAC-SHA256(signingKey, timestamp + punto + body crudo), cabecera X-Orbital-Signature: v1=<hex>. Validar ventana de tiempo y deduplicar X-Orbital-Event-Id. La firma usa un secreto independiente del bearer de API.","parameters":[{"in":"header","name":"X-Orbital-Event-Id","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-Orbital-Timestamp","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-Orbital-Key-Id","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-Orbital-Signature","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferSettledCallback"}}}},"responses":{"200":{"description":"Evento recibido; tambien para duplicados ya procesados"},"204":{"description":"Evento recibido sin cuerpo"}}}}}}},"get":{"operationId":"findOrbitalPayDisbursement","summary":"Recuperar por referencia externa exacta","description":"Requiere scope disbursements:read. Aislamiento por principal y ambiente resuelto desde la credencial.","responses":{"200":{"description":"Lote encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Disbursement"}}}},"400":{"description":"Solicitud inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Credencial ausente, inválida, revocada o de otro ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope o mandato insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso no encontrado dentro del principal autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de frecuencia; respetar Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Segundos antes de reintentar","schema":{"type":"integer","minimum":1}}}},"500":{"description":"Fallo interno; ante resultado incierto recuperar por externalId o repetir la misma clave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Servicio o elegibilidad no disponibles; no asumir saldo cero ni cliente no elegible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"externalId","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"}}]}},"/integrations/orbital-pay/v1/disbursements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getOrbitalPayDisbursement","summary":"Consultar resultado de dispersión","description":"Requiere scope disbursements:read. Aislamiento por principal y ambiente resuelto desde la credencial.","responses":{"200":{"description":"Estado y totales","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Disbursement"}}}},"400":{"description":"Solicitud inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Credencial ausente, inválida, revocada o de otro ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope o mandato insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso no encontrado dentro del principal autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de frecuencia; respetar Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Segundos antes de reintentar","schema":{"type":"integer","minimum":1}}}},"500":{"description":"Fallo interno; ante resultado incierto recuperar por externalId o repetir la misma clave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Servicio o elegibilidad no disponibles; no asumir saldo cero ni cliente no elegible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/integrations/orbital-pay/v1/disbursements/{id}/payments":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listOrbitalPayDisbursementPayments","summary":"Consultar principales y bonos","description":"Requiere scope disbursements:read. Aislamiento por principal y ambiente resuelto desde la credencial.","responses":{"200":{"description":"Página de pagos de una revisión consistente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPage"},"example":{"disbursementId":"11111111-1111-4111-8111-111111111111","revision":1,"items":[{"externalId":"payment-2026-11-001","principal":{"amount":100000,"status":"PENDIENTE","bankReference":null},"bonus":{"eligible":true,"rateBps":500,"amount":5000,"status":"PENDING","bankReference":null}}],"nextCursor":null}}}},"400":{"description":"Solicitud inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Credencial ausente, inválida, revocada o de otro ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope o mandato insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso no encontrado dentro del principal autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicto de idempotencia, referencia, cuenta bloqueada, límite de mandato o revisión","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de frecuencia; respetar Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Segundos antes de reintentar","schema":{"type":"integer","minimum":1}}}},"500":{"description":"Fallo interno; ante resultado incierto recuperar por externalId o repetir la misma clave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Servicio o elegibilidad no disponibles; no asumir saldo cero ni cliente no elegible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1,"maxLength":4096},"description":"Cursor opaco ligado al lote, principal y revisión. Si cambia la revisión, 409 SNAPSHOT_CHANGED; reiniciar desde primera página."}]}},"/integrations/orbital-pay/v1/aliases/types":{"get":{"operationId":"getOrbitalPayAliasTypes","summary":"Listar tipos de alias consultables","description":"Requiere aliases:read. Solo lectura; no consulta al banco.","responses":{"200":{"description":"Tipos admitidos","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["types"],"properties":{"types":{"type":"array","items":{"type":"string","enum":["CI","RUC","MOBILE","EMAIL"]}}}}}}},"401":{"description":"Credencial ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Falta scope aliases:read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Configuracion, transporte o respuesta bancaria no disponibles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/integrations/orbital-pay/v1/aliases/lookup":{"post":{"operationId":"lookupOrbitalPayAlias","summary":"Consultar un alias por tipo y valor","description":"Requiere aliases:read. No requiere Idempotency-Key ni reserva saldo o crea pagos. No registra, borra ni bloquea alias. Maximo 4 KiB de JSON sin compresion. Un rechazo del banco no prueba inexistencia ni disponibilidad; identidad ausente se devuelve como null.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AliasLookupRequest"},"examples":{"CI":{"value":{"type":"CI","value":"0012345"}},"RUC":{"value":{"type":"RUC","value":"80000000-1"}},"MOBILE":{"value":{"type":"MOBILE","value":"+595981000000"}},"EMAIL":{"value":{"type":"EMAIL","value":"prueba@example.com"}}}}}},"responses":{"200":{"description":"Alias resuelto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AliasLookupResponse"}}}},"400":{"description":"Tipo, valor, JSON o encoding invalidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Credencial ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Falta scope aliases:read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Cuerpo supera 4 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"ALIAS_LOOKUP_REJECTED: el banco no pudo resolver la consulta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Configuracion, transporte o respuesta bancaria no disponibles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/integrations/orbital-pay/v1/cash-ins":{"post":{"operationId":"createCashIn","summary":"Declarar un cash in","description":"Requiere cash-ins:write y una credencial de comercio. Declara una transferencia que tu cliente va a hacer a la cuenta recaudadora de Orbital. Cuando el banco notifica una transferencia recibida cuyo banco emisor, últimos cuatro dígitos de la cuenta emisora, CI o RUC del titular y monto coinciden con un cash in pendiente declarado antes de recibirla, el ingreso se acepta y se acredita en la cuenta de pagos de tu empresa. Si dos empresas declararon los mismos datos, Orbital concilia manualmente. Mientras tu empresa tenga un cash in pendiente con esos cuatro datos, otro con distinto externalId devuelve 409 CASH_IN_ALREADY_PENDING; podés declararlo cuando el anterior quede CREDITED o REJECTED. No requiere Idempotency-Key: la idempotencia es por externalId. Ante un timeout repetí el mismo body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashInInput"},"example":{"externalId":"cashin-2026-11-001","amount":150000,"bank":"BANCO ITAU PARAGUAY S.A.","accountLast4":"3456","document":"1234567","callbackUrl":"https://comercio.example.com/orbital/cash-ins"}}}},"responses":{"200":{"description":"Mismo externalId y mismos datos: devuelve el cash in existente con su estado actual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashIn"}}},"headers":{"Location":{"description":"Ruta del cash in","schema":{"type":"string"}},"Idempotency-Replayed":{"schema":{"type":"boolean","enum":[true]}}}},"201":{"description":"Cash in registrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashIn"}}},"headers":{"Location":{"description":"Ruta del cash in","schema":{"type":"string"}},"Idempotency-Replayed":{"schema":{"type":"boolean","enum":[false]}}}},"400":{"description":"Body invalido, banco no admitido, fecha fuera de rango o callbackUrl no autorizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bearer ausente o invalido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Falta el scope o la credencial no es de un comercio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_EXTERNAL_ID: el externalId ya se usó con otros datos; CASH_IN_ALREADY_PENDING: ya hay un cash in pendiente con el mismo banco, últimos cuatro dígitos, CI o RUC y monto; ACCOUNT_BLOCKED: la empresa o su cuenta de pagos no esta activa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Cuerpo supera 4 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Servicio o callbacks no disponibles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"findCashIn","summary":"Buscar un cash in por referencia externa","description":"Requiere cash-ins:read. Solo devuelve cash in de tu empresa.","parameters":[{"name":"externalId","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"}}],"responses":{"200":{"description":"Cash in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashIn"}}}},"400":{"description":"externalId invalido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bearer ausente o invalido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Falta el scope o la credencial no es de un comercio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe para tu credencial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/integrations/orbital-pay/v1/cash-ins/{id}":{"get":{"operationId":"getCashIn","summary":"Consultar el estado de un cash in","description":"Requiere cash-ins:read. Solo devuelve cash in de tu empresa.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","maxLength":100,"pattern":"^\\d{4}-\\d{2}-\\d{2}T[0-9:.]+Z_[a-f0-9-]{36}$"}}],"responses":{"200":{"description":"Cash in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashIn"}}}},"400":{"description":"id invalido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bearer ausente o invalido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Falta el scope o la credencial no es de un comercio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe para tu credencial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/integrations/orbital-pay/v1/cash-ins/banks":{"get":{"operationId":"listCashInBanks","summary":"Bancos emisores admitidos","description":"Requiere cash-ins:write. Nombres canónicos aceptados en bank al declarar un cash in.","responses":{"200":{"description":"Bancos admitidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashInBanks"}}}},"401":{"description":"Bearer ausente o invalido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Falta el scope o la credencial no es de un comercio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"orbitalPayServiceBearer":{"type":"http","scheme":"bearer","description":"Credencial de servicio de tu empresa, exclusiva por ambiente, con scopes, cuentas autorizadas y límites configurados en servidor. Se entrega por un canal seguro."}},"schemas":{"Beneficiary":{"type":"object","additionalProperties":false,"required":["documentType","documentNumber","fullName"],"properties":{"documentType":{"type":"string","minLength":1,"maxLength":16},"documentNumber":{"type":"string","minLength":1,"maxLength":64},"fullName":{"type":"string","minLength":1,"maxLength":160}}},"Destination":{"type":"object","additionalProperties":false,"required":["entityBic","accountNumber","beneficiary"],"properties":{"entityBic":{"type":"string","minLength":1,"maxLength":11,"pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$"},"accountNumber":{"type":"string","minLength":1,"maxLength":64},"beneficiary":{"$ref":"#/components/schemas/Beneficiary"}}},"PaymentInput":{"type":"object","additionalProperties":false,"required":["externalId","amount","destination","concept"],"properties":{"externalId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},"amount":{"type":"integer","minimum":1,"maximum":9007199254740991},"destination":{"$ref":"#/components/schemas/Destination"},"concept":{"type":"string","minLength":1,"maxLength":140}},"description":"amount es principal, sin descontar bonificaciones. Normalizar texto NFKC, trim y espacios; documento y cuenta siguen siendo texto y conservan ceros. BIC y tipo de documento se normalizan a mayúsculas. Rechazar controles y valores vacíos tras normalizar."},"CreateDisbursement":{"type":"object","additionalProperties":false,"required":["externalId","payments"],"properties":{"externalId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},"payments":{"type":"array","minItems":1,"maxItems":25,"items":{"$ref":"#/components/schemas/PaymentInput"}},"sourceAccountId":{"$ref":"#/components/schemas/SourceAccountId"},"callbackUrl":{"$ref":"#/components/schemas/CallbackUrl"}},"description":"Maximo 25 pagos y cuerpo de 1 MiB. sourceAccountId selecciona la cuenta virtual autorizada a reservar/debitar; si se omite se usa orbital-pay por compatibilidad. callbackUrl es opcional y se notifica solo al liquidar cada transferencia (principal y bono por separado). Cuenta y callback quedan congelados para idempotencia; cambiar cualquiera requiere una nueva solicitud."},"Account":{"type":"object","additionalProperties":false,"required":["id","name","currency","status","postedBalance","reservedBalance","availableBalance","observedAt"],"properties":{"id":{"$ref":"#/components/schemas/SourceAccountId"},"name":{"type":"string"},"currency":{"type":"string","enum":["PYG"]},"status":{"type":"string","enum":["ACTIVE","BLOCKED"]},"postedBalance":{"type":"integer","minimum":0,"maximum":9007199254740991},"reservedBalance":{"type":"integer","minimum":0,"maximum":9007199254740991},"availableBalance":{"type":"integer","minimum":0,"maximum":9007199254740991},"observedAt":{"type":"string","format":"date-time"}},"description":"Saldo virtual propio. availableBalance=postedBalance-reservedBalance. No representa una reserva nueva ni el saldo bancario. Sin configuración o lectura válida devolver 503, nunca saldo cero inventado."},"Totals":{"type":"object","additionalProperties":false,"required":["paymentCount","principalAmount","bonusAmount","requiredBalance","reservedRemaining"],"properties":{"paymentCount":{"type":"integer","minimum":1,"maximum":25},"principalAmount":{"type":"integer","minimum":1,"maximum":9007199254740991},"bonusAmount":{"type":"integer","minimum":0,"maximum":9007199254740991},"requiredBalance":{"type":"integer","minimum":1,"maximum":9007199254740991},"reservedRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991}},"description":"principalAmount, bonusAmount y requiredBalance son los importes aceptados, inmutables. requiredBalance=principalAmount+bonusAmount. reservedRemaining disminuye por liquidación o liberación confirmada y nunca supera requiredBalance."},"Disbursement":{"type":"object","additionalProperties":false,"required":["id","externalId","sourceAccountId","currency","status","revision","totals","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"externalId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},"sourceAccountId":{"$ref":"#/components/schemas/SourceAccountId"},"currency":{"type":"string","enum":["PYG"]},"status":{"type":"string","enum":["QUEUED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","FAILED","BLOCKED","REQUIRES_REVIEW"]},"revision":{"type":"integer","minimum":1},"totals":{"$ref":"#/components/schemas/Totals"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"callbackUrl":{"$ref":"#/components/schemas/CallbackUrl"},"retryOf":{"type":"object","additionalProperties":false,"required":["batchId","rowNumber"],"properties":{"batchId":{"type":"string","format":"uuid"},"rowNumber":{"type":"integer","minimum":1}},"description":"Transferencia original cuyo reintento fue autorizado. No implica que la original haya sido rechazada."}},"description":"Estado agregado de principales y bonos. COMPLETED requiere todos los principales y bonos aplicables liquidados. Un principal liquidado con bono rechazado es PARTIALLY_COMPLETED al terminar los demás componentes. Incertidumbre o devoluciones por conciliar prevalecen como REQUIRES_REVIEW."},"Principal":{"type":"object","additionalProperties":false,"required":["amount","status","bankReference"],"properties":{"amount":{"type":"integer","minimum":1,"maximum":9007199254740991},"status":{"type":"string","enum":["NO_EJECUTADO","PENDIENTE","ENVIANDO","ENVIADO","ACEPTADO","LIQUIDADO","RECHAZADO","DEVUELTO","INCIERTO","REQUIERE_INTERVENCION"]},"bankReference":{"type":"string","nullable":true,"maxLength":128}}},"Bonus":{"type":"object","additionalProperties":false,"required":["eligible","rateBps","amount","status","bankReference"],"properties":{"eligible":{"type":"boolean"},"rateBps":{"type":"integer","enum":[0,500]},"amount":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["NOT_APPLICABLE","ZERO_AMOUNT","PENDING","PROCESSING","SETTLED","FAILED","CANCELED","REQUIRES_REVIEW"]},"bankReference":{"type":"string","nullable":true,"maxLength":128}},"description":"Tasa 500 bps si es elegible; de lo contrario 0. amount=floor(principal.amount/20) si es elegible; de lo contrario 0 y NOT_APPLICABLE. Si el ambiente tiene el bono deshabilitado: eligible=false, rateBps=0, amount=0 y NOT_APPLICABLE. Elegible con monto 0 usa ZERO_AMOUNT. SETTLED exige liquidación del principal y acreditación confirmada del bono. La elegibilidad se congela al aceptar y los lotes previos conservan su bono."},"Payment":{"type":"object","additionalProperties":false,"required":["externalId","principal","bonus"],"properties":{"externalId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},"principal":{"$ref":"#/components/schemas/Principal"},"bonus":{"$ref":"#/components/schemas/Bonus"}}},"PaymentPage":{"type":"object","additionalProperties":false,"required":["disbursementId","revision","items","nextCursor"],"properties":{"disbursementId":{"type":"string","format":"uuid"},"revision":{"type":"integer","minimum":1},"items":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/Payment"}},"nextCursor":{"type":"string","nullable":true,"maxLength":4096}}},"Error":{"type":"object","additionalProperties":false,"required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","IDEMPOTENCY_CONFLICT","DUPLICATE_EXTERNAL_ID","CASH_IN_ALREADY_PENDING","DUPLICATE_PAYMENT_REFERENCE","ACCOUNT_BLOCKED","MANDATE_LIMIT_EXCEEDED","SNAPSHOT_CHANGED","INSUFFICIENT_OPERATING_BALANCE","PAYLOAD_TOO_LARGE","RATE_LIMITED","ELIGIBILITY_UNAVAILABLE","SERVICE_UNAVAILABLE","INTERNAL_ERROR","ALIAS_LOOKUP_REJECTED","ALIAS_LOOKUP_UNAVAILABLE","SOURCE_ACCOUNT_FORBIDDEN","SOURCE_ACCOUNT_NOT_FOUND","CALLBACK_NOT_ALLOWED","CALLBACK_UNAVAILABLE"]},"message":{"type":"string","minLength":1,"maxLength":280},"requestId":{"type":"string","format":"uuid"}}},"AliasLookupRequest":{"type":"object","additionalProperties":false,"required":["type","value"],"properties":{"type":{"type":"string","enum":["CI","RUC","MOBILE","EMAIL"]},"value":{"type":"string","minLength":1,"maxLength":254,"description":"Texto sin controles; se eliminan espacios de los extremos. Conservar ceros iniciales y formato registrado del alias."}}},"AliasLookupResponse":{"type":"object","additionalProperties":false,"required":["type","entityBic","accountNumber","beneficiary"],"properties":{"type":{"type":"string","enum":["CI","RUC","MOBILE","EMAIL"]},"entityBic":{"type":"string","description":"Código de entidad informado por el banco, sin truncar ni sustituir patrocinadores. Consultarlo no garantiza compatibilidad con la validacion de dispersiones."},"accountNumber":{"type":"string"},"beneficiary":{"type":"object","additionalProperties":false,"required":["documentType","documentNumber","firstName","lastName"],"properties":{"documentType":{"type":"string","nullable":true},"documentNumber":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true}}}}},"SourceAccountId":{"oneOf":[{"type":"string","enum":["orbital-pay"]},{"type":"string","format":"uuid"}],"description":"ID de la cuenta de pagos de tu empresa, autorizada para tu credencial. Enviarlo siempre; orbital-pay identifica una cuenta heredada y se usa solo si se omite."},"CallbackUrl":{"type":"string","format":"uri","maxLength":2048,"description":"URL HTTPS exacta autorizada por Orbital para tu integración. Sin credenciales, fragmento, IP literal ni puerto distinto de 443. No se siguen redirecciones."},"TransferSettledCallback":{"type":"object","additionalProperties":false,"required":["id","type","occurredAt","stage","disbursementId","externalId","paymentExternalId","sourceAccountId","component","amount","currency","status","bankReference"],"properties":{"id":{"type":"string","pattern":"^[a-f0-9]{64}$"},"type":{"type":"string","enum":["transfer.settled"]},"occurredAt":{"type":"string","format":"date-time"},"stage":{"type":"string","enum":["stg","prod"]},"disbursementId":{"type":"string","format":"uuid"},"externalId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},"paymentExternalId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},"sourceAccountId":{"$ref":"#/components/schemas/SourceAccountId"},"component":{"type":"string","enum":["PRINCIPAL","BONUS"]},"amount":{"type":"integer","minimum":1,"maximum":9007199254740991},"currency":{"type":"string","enum":["PYG"]},"status":{"type":"string","enum":["LIQUIDADO"]},"bankReference":{"type":"string","minLength":1,"maxLength":128},"retryOf":{"type":"object","additionalProperties":false,"required":["batchId","rowNumber"],"properties":{"batchId":{"type":"string","format":"uuid"},"rowNumber":{"type":"integer","minimum":1}},"description":"Transferencia original cuyo reintento fue autorizado. No implica que la original haya sido rechazada."}},"description":"Evento por transferencia liquidada, incluido el bono. Entrega al menos una vez; deduplicar por id. El orden de entrega no esta garantizado."},"CashInInput":{"type":"object","additionalProperties":false,"required":["externalId","amount","bank","accountLast4","document"],"properties":{"externalId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$","description":"Tu referencia única del cash in. Es la clave de idempotencia: repetirla con los mismos datos devuelve el original."},"amount":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Monto entero exacto en guaraníes que va a transferir el cliente."},"bank":{"type":"string","minLength":2,"maxLength":160,"description":"Banco emisor. Debe ser uno de GET /cash-ins/banks; se ignoran mayúsculas, tildes y puntuación."},"accountLast4":{"type":"string","pattern":"^\\d{4}$","description":"Últimos cuatro dígitos de la cuenta emisora."},"document":{"type":"string","minLength":3,"maxLength":30,"pattern":"^[A-Za-z0-9. -]{3,30}$","description":"CI o RUC del titular de la cuenta emisora. Se ignoran puntos, guiones y espacios; el dígito verificador del RUC cuenta."},"date":{"type":"string","format":"date","description":"Fecha prevista de la transferencia, entre hoy y los últimos 30 días. Por defecto, hoy."},"callbackUrl":{"$ref":"#/components/schemas/CallbackUrl"}},"description":"Un cash in por solicitud."},"CashIn":{"type":"object","additionalProperties":false,"required":["id","externalId","amount","currency","bank","accountLast4","date","status","createdAt","autoMatchUntil","resolvedAt","rejectionReason"],"properties":{"id":{"type":"string","maxLength":100,"pattern":"^\\d{4}-\\d{2}-\\d{2}T[0-9:.]+Z_[a-f0-9-]{36}$"},"externalId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},"amount":{"type":"integer","minimum":1,"maximum":9007199254740991},"currency":{"type":"string","enum":["PYG"]},"bank":{"type":"string"},"accountLast4":{"type":"string","pattern":"^\\d{4}$"},"date":{"type":"string","format":"date"},"status":{"type":"string","enum":["PENDING","CREDITED","REJECTED"]},"createdAt":{"type":"string","format":"date-time"},"autoMatchUntil":{"type":"string","format":"date-time","description":"Hasta cuándo una transferencia recibida se acepta automáticamente. Después la concilia Orbital."},"resolvedAt":{"type":"string","format":"date-time","nullable":true},"rejectionReason":{"type":"string","nullable":true},"callbackUrl":{"$ref":"#/components/schemas/CallbackUrl"}},"description":"El documento del titular nunca se devuelve."},"CashInBanks":{"type":"object","additionalProperties":false,"required":["banks"],"properties":{"banks":{"type":"array","items":{"type":"string"}}}},"CashInCallback":{"type":"object","additionalProperties":false,"required":["id","type","occurredAt","stage","cashInId","externalId","sourceAccountId","amount","currency","status"],"properties":{"id":{"type":"string","pattern":"^[a-f0-9]{64}$"},"type":{"type":"string","enum":["cash_in.credited","cash_in.rejected"]},"occurredAt":{"type":"string","format":"date-time"},"stage":{"type":"string","enum":["stg","prod"]},"cashInId":{"type":"string","maxLength":100,"pattern":"^\\d{4}-\\d{2}-\\d{2}T[0-9:.]+Z_[a-f0-9-]{36}$"},"externalId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},"sourceAccountId":{"$ref":"#/components/schemas/SourceAccountId"},"amount":{"type":"integer","minimum":1,"maximum":9007199254740991},"currency":{"type":"string","enum":["PYG"]},"status":{"type":"string","enum":["CREDITED","REJECTED"]},"bankReference":{"type":"string","minLength":1,"maxLength":128,"description":"Solo en cash_in.credited."}},"description":"Evento al acreditarse o rechazarse un cash in declarado con callbackUrl. Entrega al menos una vez; deduplicar por id."}}},"servers":[{"url":"{baseUrl}","description":"Staging (homologación). Reemplazá baseUrl por la URL que recibiste junto con tu credencial.","variables":{"baseUrl":{"default":"https://staging.example.com","description":"URL base de staging entregada por Orbital"}}}]}