{"openapi":"3.0.3","info":{"title":"TipTap Go API","version":"1.0.0","description":"API de cobros de TipTap Go: links de pago, clientes con tarjeta guardada, historial de pagos y liquidaciones. Autenticación con API key (Bearer). Todos los montos van en la moneda de la cuenta (USD en Panamá)."},"servers":[{"url":"https://go.paytiptap.com/api/v1"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Cuenta"},{"name":"Links de pago"},{"name":"Pagos"},{"name":"Clientes"},{"name":"Liquidaciones"}],"paths":{"/me":{"get":{"tags":["Cuenta"],"summary":"Datos de la cuenta","description":"Devuelve la cuenta detrás de la API key. Sirve para verificar la llave.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/balance":{"get":{"tags":["Liquidaciones"],"summary":"Saldo del comercio","description":"Cuánto dinero cobrado tiene TipTap Go y en qué etapa: `available` (sin liquidar), `in_transit` (liquidación generada) y `paid_out` (ya transferido).","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment_links":{"get":{"tags":["Links de pago"],"summary":"Listar links de pago","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Cuántos objetos devolver (máximo 100)."},{"name":"starting_after","in":"query","schema":{"type":"string"},"description":"Cursor: el `next_cursor` de la página anterior."},{"name":"created_after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"created_before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","COMPLETED","CANCELLED"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentLink"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Links de pago"],"summary":"Crear un link de pago","description":"Devuelve la `url` a la que mandas al cliente. Requiere la cuenta con cobros activados.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","amount"],"properties":{"title":{"type":"string","minLength":2,"maxLength":120,"example":"Mensualidad julio"},"description":{"type":"string","maxLength":300},"amount":{"type":"number","format":"double","example":25},"max_uses":{"type":"integer","nullable":true,"description":"Omitido = un solo uso. `null` = usos ilimitados."},"expires_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment_links/{id}":{"get":{"tags":["Links de pago"],"summary":"Ver un link de pago","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment_links/{id}/cancel":{"post":{"tags":["Links de pago"],"summary":"Cancelar un link de pago","description":"Cierra el link para nuevos pagos. Los pagos ya cobrados no se tocan.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"El link ya estaba completo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments":{"get":{"tags":["Pagos"],"summary":"Listar pagos","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Cuántos objetos devolver (máximo 100)."},{"name":"starting_after","in":"query","schema":{"type":"string"},"description":"Cursor: el `next_cursor` de la página anterior."},{"name":"created_after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"created_before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","schema":{"type":"string","enum":["PENDING","APPROVED","FAILED","VOIDED","TIMEOUT"]}},{"name":"payment_link_id","in":"query","schema":{"type":"string"}},{"name":"customer_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments/{id}":{"get":{"tags":["Pagos"],"summary":"Ver un pago","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers":{"get":{"tags":["Clientes"],"summary":"Listar clientes","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Cuántos objetos devolver (máximo 100)."},{"name":"starting_after","in":"query","schema":{"type":"string"},"description":"Cursor: el `next_cursor` de la página anterior."},{"name":"phone","in":"query","schema":{"type":"string"},"description":"Busca por celular."},{"name":"email","in":"query","schema":{"type":"string"},"description":"Busca por email (único por cuenta)."},{"name":"external_ref","in":"query","schema":{"type":"string"},"description":"Busca por el id que el cliente tiene en tu sistema."},{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","ARCHIVED"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Clientes"],"summary":"Crear un cliente","description":"El celular es la identidad del cliente y no se puede repetir en la cuenta.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","phone"],"properties":{"name":{"type":"string","example":"María Pérez"},"phone":{"type":"string","example":"+507 6000-0000"},"email":{"type":"string","format":"email"},"notes":{"type":"string","maxLength":500},"external_ref":{"type":"string","maxLength":120,"description":"Id de este cliente en TU sistema, para casar ambos lados sin adivinar."}}}}}},"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Ya existe un cliente con ese celular","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}":{"get":{"tags":["Clientes"],"summary":"Ver un cliente","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Clientes"],"summary":"Actualizar un cliente","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}/charges":{"post":{"tags":["Clientes"],"summary":"Cobrar a un cliente","description":"Con `use_saved_card: true` cobra al instante la tarjeta tokenizada del cliente. Sin ella devuelve el link para que el cliente pague. Manda el header `Idempotency-Key` para que un reintento devuelva el mismo cobro en vez de cobrar otra vez; la respuesta repetida trae `Idempotent-Replay: true`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Cadena única tuya (por ejemplo un UUID). El reintento con la misma llave devuelve el mismo resultado. Reusarla con otro cuerpo responde 422."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","format":"double","example":25},"description":{"type":"string","maxLength":120},"use_saved_card":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Cobro creado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"400":{"description":"Parámetros inválidos o Idempotency-Key mal formada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"La tarjeta fue rechazada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"El cliente no tiene tarjeta guardada; el resultado del cobro quedó sin confirmar (charge_unresolved); o una petición con esa Idempotency-Key sigue en curso o quedó sin resolver","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reusada con otro cuerpo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/settlements":{"get":{"tags":["Liquidaciones"],"summary":"Listar liquidaciones","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Cuántos objetos devolver (máximo 100)."},{"name":"starting_after","in":"query","schema":{"type":"string"},"description":"Cursor: el `next_cursor` de la página anterior."},{"name":"status","in":"query","schema":{"type":"string","enum":["PENDING","PAID","DEBT"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Settlement"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/settlements/{id}":{"get":{"tags":["Liquidaciones"],"summary":"Ver una liquidación con su detalle","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settlement"}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key ausente o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta sin cobros activados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite de peticiones superado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"API key del comercio: `Authorization: Bearer tiptap_sk_…`"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","permission_error","invalid_request_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string","example":"invalid_parameters"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}},"Account":{"type":"object","properties":{"object":{"type":"string","enum":["account"]},"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"legal_name":{"type":"string","nullable":true},"tax_id":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"enum":["NATURAL_PERSON","BUSINESS",null]},"status":{"type":"string","enum":["TRIAL","ACTIVE","SUSPENDED","CLOSED"]},"activation_status":{"type":"string"},"charges_enabled":{"type":"boolean"},"contact_email":{"type":"string"},"contact_phone":{"type":"string","nullable":true},"currency":{"type":"string","example":"USD"},"timezone":{"type":"string","example":"America/Panama"},"created_at":{"type":"string","format":"date-time"}}},"PaymentLink":{"type":"object","properties":{"object":{"type":"string","enum":["payment_link"]},"id":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"amount":{"type":"number","format":"double","example":25},"currency":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","COMPLETED","CANCELLED"]},"max_uses":{"type":"integer","nullable":true},"paid_count":{"type":"integer"},"expires_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"Payment":{"type":"object","properties":{"object":{"type":"string","enum":["payment"]},"id":{"type":"string"},"amount":{"type":"number","format":"double","example":25},"currency":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","FAILED","VOIDED","TIMEOUT"],"description":"APPROVED = cobrado · VOIDED = autorizado y anulado (sin cargo) · TIMEOUT = expiró."},"payer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"}}},"customer_id":{"type":"string","nullable":true},"payment_link":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"}}},"authorization_code":{"type":"string","nullable":true},"processor_reference":{"type":"string","nullable":true},"settlement_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"Customer":{"type":"object","properties":{"object":{"type":"string","enum":["customer"]},"id":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"source":{"type":"string","enum":["MERCHANT","SELF"]},"notes":{"type":"string","nullable":true},"external_ref":{"type":"string","nullable":true,"description":"Id del cliente en el sistema del comercio."},"card":{"type":"object","nullable":true,"description":"Tarjeta tokenizada del cliente, si registró una.","properties":{"brand":{"type":"string","nullable":true},"last4":{"type":"string","nullable":true},"expiry":{"type":"string","nullable":true}}},"created_at":{"type":"string","format":"date-time"}}},"Charge":{"type":"object","properties":{"object":{"type":"string","enum":["charge"]},"customer_id":{"type":"string"},"amount":{"type":"number","format":"double","example":25},"currency":{"type":"string"},"paid":{"type":"boolean","description":"true si ya se cobró la tarjeta guardada."},"payment_id":{"type":"string","nullable":true},"payment_url":{"type":"string","nullable":true},"payment_link":{"$ref":"#/components/schemas/PaymentLink","nullable":true}}},"Settlement":{"type":"object","properties":{"object":{"type":"string","enum":["settlement"]},"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","PAID","DEBT"],"description":"PENDING = transferencia en camino · PAID = ya transferida · DEBT = neto <= 0, sin transferencia (deuda del comercio)."},"currency":{"type":"string"},"gross_amount":{"type":"number","format":"double","example":25},"fee_amount":{"type":"number","format":"double","example":25},"net_amount":{"type":"number","format":"double","example":25},"payment_count":{"type":"integer"},"period_start":{"type":"string","format":"date-time"},"period_end":{"type":"string","format":"date-time"},"bank_account":{"type":"object","nullable":true,"properties":{"bank_name":{"type":"string","nullable":true},"account_last4":{"type":"string"}}},"reference":{"type":"string","nullable":true},"paid_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"payments":{"type":"array","description":"Solo en el detalle (GET /settlements/{id}).","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number","format":"double","example":25},"payer_name":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}},"Balance":{"type":"object","properties":{"object":{"type":"string","enum":["balance"]},"currency":{"type":"string"},"available":{"type":"object","properties":{"payment_count":{"type":"integer"},"gross_amount":{"type":"number","format":"double","example":25},"fee_amount":{"type":"number","format":"double","example":25},"net_amount":{"type":"number","format":"double","example":25}}},"in_transit":{"type":"number","format":"double","example":25},"paid_out":{"type":"number","format":"double","example":25},"fee_schedule":{"type":"object","properties":{"percent":{"type":"number"},"fixed":{"type":"number"}}}}}}},"x-webhook-events":["payment.succeeded","payment.failed","payment_link.completed","customer.created","customer.card_saved","settlement.created","settlement.paid"]}