{ "info": { "_postman_id": "00000000-0000-0000-0000-helppiupay01", "name": "Helppiu Pay API", "description": "API REST de **Helppiu Pay**. Permite tokenizar tarjetas, crear cobros directos,\nsesiones de Checkout, gestionar payouts Bre-B (cash-out), bolsillo recargable,\nwebhooks firmados HMAC-SHA256 y catálogos.\n\n## Autenticación\nTodas las llamadas usan **Bearer** con el formato `key_id:secret`:\n```\nAuthorization: Bearer hp_pk_xxx:sk_yyy\n```\n- `hp_pk_*` (publishable): solo `POST /v1/tokens`.\n- `hp_sk_*` (secret): todos los endpoints server-to-server.\n\n## Entornos\n- **Test (sandbox)**: usa keys `hp_*_test_*`. Las llamadas no impactan proveedores reales.\n- **Live (producción)**: usa keys `hp_*_live_*`.\n\n## Idempotencia\nEnvía el header `Idempotency-Key: ` en cualquier `POST` mutativo. Las\nrespuestas se cachean 24 h por par `(merchant, key)`. Un replay incluye el header\n`X-Idempotency-Replayed: true`.\n\n## Webhooks\nCada entrega lleva el header `X-Helppiu-Signature: t=,v1=`\ndonde `v1 = HMAC_SHA256(secret, \"{t}.{raw_body}\")`. Verifica siempre antes de\nprocesar el evento.\n", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_key_id}}:{{api_key_secret}}", "type": "string" } ] }, "event": [], "variable": [ { "key": "baseUrl", "value": "https://helppiupay.com" }, { "key": "api_key_id", "value": "hp_sk_test_xxx", "type": "string" }, { "key": "api_key_secret", "value": "sk_yyy", "type": "string" } ], "item": [ { "name": "Tokens", "description": "Tokenización PCI-safe de tarjetas (uso desde el navegador con publishable key).", "item": [ { "name": "Tokenizar tarjeta", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/tokens", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "tokens" ] }, "description": "Crea un token de un solo uso (`tok_*`) válido **30 minutos**. Los datos\nde tarjeta nunca se persisten en BD; se almacenan cifrados en cache.\nAcepta publishable o secret key.\n", "body": { "mode": "raw", "raw": "{\n \"card_number\": \"4111111111111111\",\n \"card_cvv\": \"123\",\n \"card_exp_month\": \"12\",\n \"card_exp_year\": \"30\",\n \"card_holder_name\": \"JUAN PEREZ\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] } ] }, { "name": "Charges", "description": "Cobros server-to-server (Direct Charges API).", "item": [ { "name": "Listar cobros directos", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/charges", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "charges" ] }, "description": null }, "response": [] }, { "name": "Crear cobro directo", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "UUID opcional para idempotencia" } ], "url": { "raw": "{{baseUrl}}/api/v1/charges", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "charges" ] }, "description": "Procesa un pago server-to-server sin Checkout hospedado. Requiere **secret key**.\nSoporta `card` (con token), `pse`, `nequi`, `daviplata`, `crypto`.\n", "body": { "mode": "raw", "raw": "{\n \"reference\": \"ORDER-1001\",\n \"amount\": 50000,\n \"currency\": \"COP\",\n \"description\": \"Suscripción Pro\",\n \"customer\": {\n \"name\": \"María Gómez\",\n \"email\": \"maria@example.com\",\n \"document\": \"1020304050\",\n \"phone\": \"3001234567\"\n },\n \"payment_method\": {\n \"type\": \"card\",\n \"token\": \"tok_abc123def456\",\n \"installments\": 1\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Recuperar un cobro", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/charges/{{uuid}}", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "charges", "{{uuid}}" ] }, "description": null }, "response": [] } ] }, { "name": "Checkout Sessions", "description": "Sesiones de Checkout hospedado por Helppiu Pay.", "item": [ { "name": "Crear sesión de Checkout", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "UUID opcional para idempotencia" } ], "url": { "raw": "{{baseUrl}}/api/v1/checkout-sessions", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "checkout-sessions" ] }, "description": null, "body": { "mode": "raw", "raw": "{\n \"reference\": \"ORDER-2002\",\n \"amount\": 75000,\n \"currency\": \"COP\",\n \"description\": \"Compra ecommerce\",\n \"payment_method_types\": [\n \"card\",\n \"pse\",\n \"nequi\"\n ],\n \"customer_name\": \"Laura Vargas\",\n \"customer_email\": \"laura@example.com\",\n \"success_url\": \"https://tienda.com/ok\",\n \"cancel_url\": \"https://tienda.com/cancel\",\n \"metadata\": {\n \"order_id\": \"2002\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Recuperar sesión", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/checkout-sessions/{{uuid}}", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "checkout-sessions", "{{uuid}}" ] }, "description": null }, "response": [] }, { "name": "Expirar sesión", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/checkout-sessions/{{uuid}}/expire", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "checkout-sessions", "{{uuid}}", "expire" ] }, "description": null }, "response": [] } ] }, { "name": "Payouts", "description": "Cash-out Bre-B desde el bolsillo del comercio.", "item": [ { "name": "Listar payouts", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/payouts", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "payouts" ] }, "description": null }, "response": [] }, { "name": "Crear payout Bre-B", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "UUID opcional para idempotencia" } ], "url": { "raw": "{{baseUrl}}/api/v1/payouts", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "payouts" ] }, "description": "Crea un cash-out hacia una llave Bre-B previamente registrada en la whitelist.\nSi el monto requiere OTP, la primera llamada responde `202` con `requires_otp:true`\ny debes reintentar con `otp_code`.\nOpcional: `doc_number`/`doc_type` para pisar, solo en este payout, el documento\nguardado en la whitelist (ej. el destinatario no es el titular de enrollment).\n", "body": { "mode": "raw", "raw": "{\n \"amount\": 50000,\n \"brev_key\": \"@maria\",\n \"notes\": \"Pago a proveedor\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Verificar código OTP", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/payouts/verify-otp", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "payouts", "verify-otp" ] }, "description": null, "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Recuperar payout", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/payouts/{{uuid}}", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "payouts", "{{uuid}}" ] }, "description": null }, "response": [] } ] }, { "name": "Wallet", "description": "Bolsillo Bre-B, topups PSE y whitelist de llaves.", "item": [ { "name": "Saldo del bolsillo", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/wallet/balance", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "wallet", "balance" ] }, "description": null }, "response": [] }, { "name": "Listar topups", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/wallet/topups", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "wallet", "topups" ] }, "description": null }, "response": [] }, { "name": "Crear topup PSE", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "UUID opcional para idempotencia" } ], "url": { "raw": "{{baseUrl}}/api/v1/wallet/topups", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "wallet", "topups" ] }, "description": null, "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Listar llaves whitelisted", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/wallet/whitelist", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "wallet", "whitelist" ] }, "description": null }, "response": [] }, { "name": "Agregar llave Bre-B a la whitelist", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/wallet/whitelist", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "wallet", "whitelist" ] }, "description": "Antes de guardarla, la llave se consulta contra la red Bre-B. Si no existe NO se registra:\nen un payout la llave es el unico dato del destinatario, asi que un digito equivocado\nenviaria el dinero a un tercero real.\n\n201 -> incluye holder_name (enmascarado), bank_name y verified_at.\n409 -> la llave ya estaba registrada.\n422 -> la llave no existe.\n503 -> no se pudo verificar ahora; reintenta mas tarde.", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Consultar el titular de una llave Bre-B", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\"brev_key\": \"@maria\", \"doc_number\": \"1020304050\"}" }, "url": { "raw": "{{baseUrl}}/api/v1/wallet/whitelist/verify", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "wallet", "whitelist", "verify" ] }, "description": "Devuelve a nombre de quien esta una llave Bre-B y en que entidad, SIN registrarla.\ndoc_number es el documento del TITULAR de la llave (no el tuyo como comercio) y es recomendado: sin el, el proveedor puede comparar contra tu propio NIT y responder que no coincide aunque la llave sea valida.\nSegun el proveedor que resuelva la consulta, el nombre puede llegar enmascarado o completo.\n\nfound=true -> {\"holder_name\":\"DAN***** BAL***** DEL*****\",\"bank_name\":\"Daviplata\"}\nfound=false -> la llave no existe, o no se pudo consultar (mira el codigo HTTP: 200 vs 503)." }, "response": [] }, { "name": "Eliminar llave", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/wallet/whitelist/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "wallet", "whitelist", "{{id}}" ] }, "description": null }, "response": [] } ] }, { "name": "Transactions", "description": "Consulta de transacciones.", "item": [ { "name": "Listar transacciones", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/transactions", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "transactions" ] }, "description": null }, "response": [] }, { "name": "Recuperar transacción", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/transactions/{{uuid}}", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "transactions", "{{uuid}}" ] }, "description": null }, "response": [] } ] }, { "name": "Webhook Endpoints", "description": "Gestión de URLs y eventos suscritos.", "item": [ { "name": "Listar endpoints", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/webhook-endpoints", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhook-endpoints" ] }, "description": null }, "response": [] }, { "name": "Crear endpoint", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/webhook-endpoints", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhook-endpoints" ] }, "description": null, "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Eliminar endpoint", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/webhook-endpoints/{{id}}", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "webhook-endpoints", "{{id}}" ] }, "description": null }, "response": [] } ] }, { "name": "Catalogs", "description": "Bancos PSE y tasas de cambio.", "item": [ { "name": "Listar bancos PSE", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/banks/pse", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "banks", "pse" ] }, "description": "Cacheado 1 hora." }, "response": [] }, { "name": "Tasas de cambio FX", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/v1/exchange-rates", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "exchange-rates" ] }, "description": "Tasas COP base con markup aplicado del comercio." }, "response": [] } ] } ] }