{"id":24660000,"url":"https://github.com/moiseshp/culqi-react-nextjs-integration","last_synced_at":"2026-03-03T17:33:12.420Z","repository":{"id":258944875,"uuid":"875476667","full_name":"moiseshp/culqi-react-nextjs-integration","owner":"moiseshp","description":"A quick and easy solution to integrate secure payments with Culqi in React and Next.js applications.","archived":false,"fork":false,"pushed_at":"2024-12-06T02:16:10.000Z","size":607,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-27T03:52:14.283Z","etag":null,"topics":["culqi","nextjs","reactjs","tailwindcss"],"latest_commit_sha":null,"homepage":"https://culqi-react-nextjs.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moiseshp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-20T04:43:06.000Z","updated_at":"2025-07-15T16:01:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"f3dda84b-eed7-4c98-8ec8-ff8b5b1c13df","html_url":"https://github.com/moiseshp/culqi-react-nextjs-integration","commit_stats":null,"previous_names":["moiseshp/culqi-react-nextjs-integration"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/moiseshp/culqi-react-nextjs-integration","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moiseshp%2Fculqi-react-nextjs-integration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moiseshp%2Fculqi-react-nextjs-integration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moiseshp%2Fculqi-react-nextjs-integration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moiseshp%2Fculqi-react-nextjs-integration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moiseshp","download_url":"https://codeload.github.com/moiseshp/culqi-react-nextjs-integration/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moiseshp%2Fculqi-react-nextjs-integration/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30052493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T15:26:47.567Z","status":"ssl_error","status_checked_at":"2026-03-03T15:26:17.132Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["culqi","nextjs","reactjs","tailwindcss"],"created_at":"2025-01-26T03:16:02.562Z","updated_at":"2026-03-03T17:33:12.384Z","avatar_url":"https://github.com/moiseshp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Culqi React \u0026 Next.js Integration\n\n![Culqi Vercel Page](https://culqi-react-nextjs.vercel.app/screenshot-1.png)\n\nPuedes revisar esta integración en [Culqi React NextJS Integration](https://culqi-react-nextjs.vercel.app/) gracias a [Vercel](https://vercel.com)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n## Descripción\n\nEste proyecto proporciona una integración rápida y sencilla del sistema de pagos de [Culqi](https://culqi.com) en aplicaciones construidas con **React** o **NextJS**. No es necesario instalar ninguna librería adicional. La integración utiliza el script oficial de Culqi: [https://js.culqi.com/checkout-js](https://js.culqi.com/checkout-js) que permite implementar la versión de [Culqi Checkout Custom](https://docs.culqi.com/es/documentacion/checkout/v4/culqi-checkout-custom/).\n\nLa pasarela de **Culqi Checkout Custom** te permite habilitar los siguientes formas de pago:\n\n- [x] Tarjetas de Crédito\n- [x] Tarjetas de Débito\n- [x] Yape\n- [ ] PLIN y otras billeteras - WIP 🚧\n- [ ] Transferencias bancarias - WIP 🚧\n- [ ] Agente - WIP 🚧\n- [ ] Cuotealo - WIP 🚧\n\n## Integración Culqi (Quickstart)\n\nSigue los siguientes pasos para integrar **Culqi Checkout Custom** en tu aplicación **React** o **NextJS**.\n\n\u003e ⚠️ **Importante:** Debes tener acceso a tus llaves pública y privada los cuales los puedes encontrar en la sección [desarrollo](https://mipanel.culqi.com/development/apikeys) del panel de tu comercio. Si no tienes un comercio registrado en [Culqi](https://afiliate.culqi.com/) primero [Afiliáte aquí](https://afiliate.culqi.com/online/step1).\n\n### Paso 1. Configura tus credenciales\n\nEstablece tus llaves pública y privada en una variable de entorno.\n\n```env\n# .env.local\nNEXT_PUBLIC_API_PUBLIC_KEY=tu_public_key\nAPI_PRIVATE_KEY=tu_secret_key\n```\n\n### Paso 2. Copia la carpeta ./culqi-checkout-custom a tu proyecto\n\nEsta es la estructura y descripción de los archivos:\n\n```bash\n/your-project\n├── culqi-checkout-custom\n│   ├── __tests__           # Pruebas unitarias del módulo\n│   ├── config.ts           # Configuración de Culqi y comercio\n│   ├── load-script.ts      # Función para cargar el script de Culqi\n│   ├── payment-button.tsx  # Componente de botón de pago 😍\n│   └── types.ts            # Definición de interfaces y tipos\n```\n\nDetalle de la estructura de archivos:\n\n- **`config.ts`**: Configuración por defecto para la integración de Culqi y los datos de tu comercio.\n- **`load-script.ts`**: Función que carga dinámicamente el script de Culqi en el frontend.\n- **`payment-button.tsx`**: Componente botón de pago configurado para utilizar el script de Culqi.\n- **`types.ts`**: Contiene las interfaces y tipos para tipar los datos de manera segura.\n\n### Paso 3. Agrega el componente de Botón de Pago a tu vista\n\nImporta el componente `\u003cPaymentButton /\u003e`. Es necesario pasarle los siguientes `props`:\n\n| Props           | Description                                                                                                                                                                                                       |\n| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| onPaymentAction | Callback para gestionar el proceso del pago.                                                                                                                                                                      |\n| config          | Objeto de tipo `CulqiConfig`. Revisa la documentación de [Culqi](https://docs.culqi.com/es/documentacion/checkout/v4/culqi-checkout-custom/#paso-2-configura-el-custom-culqi-checkout-para-tokenizar-la-tarjeta). |\n\nCódigo de ejemplo en un componente **React** que importa el **Botón de Pago**:\n\n```jsx\nimport { PaymentButton } from './culqi-checkout-custom/payment-button';\nimport { type CulqiConfig } from './culqi-checkout-custom/types';\n\nexport default function Checkout() {\n  const totalPrice = 184.47;\n  const config: Partial\u003cCulqiConfig\u003e = {\n    settings: {\n      amount: totalPrice * 100,\n    },\n  };\n\n  const handlePaymentAction = () =\u003e {};\n\n  return (\n    \u003c\u003e\n      \u003cPaymentButton onPaymentAction={handlePaymentAction} config={config}\u003e\n        Pagar S/ {totalPrice}\n      \u003c/PaymentButton\u003e\n    \u003c/\u003e\n  );\n}\n```\n\nScreenshot del Checkout de Culqi:\n\n![Culqi Checkout](https://culqi-react-nextjs.vercel.app/screenshot-3.png)\n\n### Paso 4. Gestiona la respuesta de Culqi\n\nGestiona la respuesta del modal de Culqi hacia tu backend para procesar el cargo. Culqi devuelve un `string` que es un **ID Tokenizado** `token` el cual debes procesar únicamente de servidor a servidor mediante el API de Culqi.\n\nPuedes consultas la [documentación oficial](https://apidocs.culqi.com/#tag/Cargos/Objeto-cargo) para más información sobre cómo estructurar los cargos entre Culqi y tu backend:\n\n```jsx\nconst handlePaymentAction = async (token: string) =\u003e {\n  /**\n   * Aquí puedes implementar una request hacia tu backend enviado la siguiente información:\n   * amount: number\n   * currency_code: string ISO\n   * source_id: ID tokenizado (token que devuelve el modal de Culqi)\n   */\n};\n```\n\nEl siguiente código es un ejemplo con **NextJS + Server Actions** (versión 13 o superior)\n\n```jsx\n// page.tsx\nconst handlePaymentAction = async (token: string) =\u003e {\n  const response = await processPaymentAction({\n    amount: config.settings?.amount as number,\n    currencyCode: config.settings?.currency as string,\n    sourceId: token,\n  });\n};\n```\n\n```js\n// actions.ts\n'use server';\nconst API_URL = 'https://api.culqi.com/v2/charges';\n\ninterface PaymentCharge {\n  amount: number;\n  currencyCode: string;\n  sourceId: string;\n}\n\nexport async function processPaymentAction(data: PaymentCharge) {\n  try {\n    await fetch(API_URL, {\n      method: 'POST',\n      headers: {\n        Authorization: `Bearer ${process.env.API_PRIVATE_KEY}`,\n        'Content-Type': 'application/json',\n      },\n      body: JSON.stringify({\n        ...data,\n        currency_code: data.currencyCode,\n        source_id: data.sourceId,\n      }),\n    });\n    return {\n      message: 'Success payment',\n    };\n  } catch {\n    throw new Error('error to process paymento with processPaymentAction');\n  }\n}\n```\n\nSegún la respuesta recibida desde processPaymentAction o el servicio externo que decidas implementar puedes personalizar los mensajes de éxito o error para notificar al usuario sobre el estado de la transacción. Esto permite una mejor experiencia de usuario, adaptando la respuesta de la API de Culqi a tu flujo de negocio.\n\n## Prueba este proyecto\n\n### Requisitos\n\n- Node.js 18.17 o superior.\n- macOS, Windows (including WSL), y Linux están soportados.\n- Llaves pública y privada de Culqi.\n\n1. Clona este repositorio:\n\n```bash\ngit clone https://github.com/moiseshp/culqi-react-nextjs-integration.git\n```\n\n2. Instala las dependencias:\n\n```bash\nnpm install\n```\n\n3. Establece tus llaves pública y privada en una variable de entorno.\n\n```env\n# .env.local\nNEXT_PUBLIC_API_PUBLIC_KEY=tu_public_key\nAPI_PRIVATE_KEY=tu_secret_key\n```\n\n4. Ejecuta el proyecto:\n\n```bash\nnpm run dev\n```\n\n## Contribuciones son Bienvenidas 🎉\n\n¡Gracias por tu interés en colaborar con este proyecto! Me encataría contar con tu ayuda para mejorar y expandir este proyecto para la comunidad. Aceptamos contribuciones de todo tipo, desde mejoras en la documentación hasta nuevas funcionalidades y correcciones de errores.\n\nPor otro lado, si te parece que este proyecto te es útil, ¡deja una estrella en GitHub! Esto ayuda a aumentar la visibilidad y a fomentar la colaboración. Gracias por tu apoyo.\n\n[![Star](https://img.shields.io/github/stars/moiseshp/culqi-react-nextjs-integration?style=social)](https://github.com/moiseshp/culqi-react-nextjs-integration)\n\n## Licencia\n\nEste proyecto está bajo la Licencia MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoiseshp%2Fculqi-react-nextjs-integration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoiseshp%2Fculqi-react-nextjs-integration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoiseshp%2Fculqi-react-nextjs-integration/lists"}