{"id":15025461,"url":"https://github.com/culqi/culqi-php","last_synced_at":"2025-10-05T01:04:48.689Z","repository":{"id":36421961,"uuid":"40726943","full_name":"culqi/culqi-php","owner":"culqi","description":"Biblioteca que permite integrar la pasarela de pagos CULQI. ","archived":false,"fork":false,"pushed_at":"2024-12-03T21:06:57.000Z","size":672,"stargazers_count":36,"open_issues_count":14,"forks_count":37,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-05-15T08:12:07.680Z","etag":null,"topics":["api-client","cliente","culqi","payment-integration","php","php-7","sdk"],"latest_commit_sha":null,"homepage":"https://www.culqi.com/docs","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/culqi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2015-08-14T17:14:20.000Z","updated_at":"2025-04-23T21:46:06.000Z","dependencies_parsed_at":"2024-04-01T17:52:41.692Z","dependency_job_id":"ce1efa70-4e64-432a-bdbc-a90dd627dfe9","html_url":"https://github.com/culqi/culqi-php","commit_stats":{"total_commits":378,"total_committers":23,"mean_commits":"16.434782608695652","dds":0.6190476190476191,"last_synced_commit":"709ae3d09788916006a3724d6fd01db8c7bcc7c8"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/culqi%2Fculqi-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/culqi%2Fculqi-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/culqi%2Fculqi-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/culqi%2Fculqi-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/culqi","download_url":"https://codeload.github.com/culqi/culqi-php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254564122,"owners_count":22092121,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["api-client","cliente","culqi","payment-integration","php","php-7","sdk"],"created_at":"2024-09-24T20:02:23.370Z","updated_at":"2025-10-05T01:04:43.637Z","avatar_url":"https://github.com/culqi.png","language":"PHP","readme":"# Culqi-HP\n\n[![Latest Stable Version](https://poser.pugx.org/culqi/culqi-php/v/stable)](https://packagist.org/packages/culqi/culqi-php)\n[![Total Downloads](https://poser.pugx.org/culqi/culqi-php/downloads)](https://packagist.org/packages/culqi/culqi-php)\n[![License](https://poser.pugx.org/culqi/culqi-php/license)](https://packagist.org/packages/culqi/culqi-php)\n\nNuestra Biblioteca PHP oficial, es compatible con la V2.0 del Culqi API, con el cual tendrás la posibilidad de realizar cobros con tarjetas de débito y crédito, Yape, PagoEfectivo, billeteras móviles y Cuotéalo con solo unos simples pasos de configuración.\n\nNuestra biblioteca te da la posibilidad de capturar el status_code de la solicitud HTTP que se realiza al API de Culqi, así como el response que contiene el cuerpo de la respuesta obtenida.\n\n\n## Requisitos \n\n* PHP 5.6+.\n* Afiliate [aquí](https://afiliate.culqi.com/).\n* Si vas a realizar pruebas obtén tus llaves desde [aquí](https://integ-panel.culqi.com/#/registro), si vas a realizar transacciones reales obtén tus llaves desde [aquí](https://panel.culqi.com/#/registro) (1).\n\n\u003e Recuerda que para obtener tus llaves debes ingresar a tu CulqiPanel \u003e Desarrollo \u003e ***API Keys***.\n\n![alt tag](http://i.imgur.com/NhE6mS9.png)\n\n\u003e Recuerda que las credenciales son enviadas al correo que registraste en el proceso de afiliación.\n\n* Para encriptar el payload debes generar un id y llave RSA ingresando a CulqiPanel \u003e Desarrollo \u003e RSA Keys.\n\n## Instalación\n\n### 1. Vía Composer\n```json\n{\n  \"require\": {\n    \"culqi/culqi-php\": \"2.0.4\"\n  }\n}\n```\n\nY cargar todo usando el autoloader de Composer.\n\n```php\nrequire 'vendor/autoload.php';\n```\n\n### 2. Manualmente\n\nClonar el repositorio o descargar el código fuente\n\n```bash\ngit clone git@github.com:culqi/culqi-php.git\n```\n\nAhora, incluir en la cabecera a `culqi-php` y también la dependencia [`Requests`](https://github.com/rmccue/requests). Debes hacer el llamado correctamente a la carpeta y/o archivo dependiendo de tu estructura.\n\n```php\n\u003c?php\n// Cargamos Requests y Culqi PHP\ninclude_once dirname(__FILE__).'/libraries/Requests/library/Requests.php';\nRequests::register_autoloader();\ninclude_once dirname(__FILE__).'/libraries/culqi-php/lib/culqi.php';\n```\n\nLuego ejecuta composer install\n\n```bash\ncomposer install\n```\n\n## Configuración\n\nComo primer paso hay que configurar la credencial `$API_KEY `\n\n```php\n// Configurar tu API Key y autenticación\n$PUBLIC_KEY = \"{PUBLIC KEY}\";\n$SECRET_KEY = \"{SECRET KEY}\";\n$culqi = new Culqi\\Culqi(array('api_key' =\u003e $SECRET_KEY));\n```\n\n\u003e Recuerda que las llaves de integración se identifican como \"test\" y las de producción como \"live\".\n\n## Encriptar payload\n\nPara encriptar el payload necesitas crear un id RSA y llave RSA, para esto debes ingresa a tu panel y hacer click en la sección “Desarrollo / RSA Keys” de la barra de navegación a la mano izquierda.\n\nLuego declara en variables el id RSA y llave RSA en tu backend, y envialo en las funciones de la librería.\n\nEjemplo\n\n```php\n$encryption_params = array(\n  \"rsa_public_key\" =\u003e \"la llave pública RSA\",\n  \"rsa_id\" =\u003e \"el id de tu llave\"\n);\n $req_body = array(\n    \"card_number\" =\u003e \"4111111111111111\",\n    \"cvv\" =\u003e \"123\",\n    \"email\" =\u003e \"culqi\".uniqid().\"@culqi.com\", //email must not repeated\n    \"expiration_month\" =\u003e \"7\",\n    \"expiration_year\" =\u003e $futureDate,\n    \"fingerprint\" =\u003e uniqid(),\n    \"metadata\" =\u003e array(\"dni\" =\u003e \"71702935\")\n);\n$token = $culqi-\u003eTokens-\u003ecreate(\n    $req_body,\n    $encryption_params\n  );\n```\n\n## Servicios\n\n### Crear un token\n\nAntes de crear un Cargo o Card es necesario crear un `token` de tarjeta. \nLo recomendable es generar los 'tokens' con [Culqi Checkout v4](https://docs.culqi.com/es/documentacion/checkout/v4/culqi-checkout/) o [Culqi JS v4](https://docs.culqi.com/es/documentacion/culqi-js/v4/culqi-js/) **debido a que es muy importante que los datos de tarjeta sean enviados desde el dispositivo de tus clientes directamente a los servidores de Culqi**, para no poner en riesgo los datos sensibles de la tarjeta de crédito/débito.\n\n\u003e Recuerda que cuando interactúas directamente con el [API Token](https://apidocs.culqi.com/#tag/Tokens/operation/crear-token) necesitas cumplir la normativa de PCI DSS 3.2. Por ello, te pedimos que llenes el [formulario SAQ-D](https://listings.pcisecuritystandards.org/documents/SAQ_D_v3_Merchant.pdf) y lo envíes al buzón de riesgos Culqi.\n\n```php\n$req_body = array(\n  \"card_number\" =\u003e \"4111111111111111\",\n  \"cvv\" =\u003e \"123\",\n  \"email\" =\u003e \"culqi\".uniqid().\"@culqi.com\", //email must not repeated\n  \"expiration_month\" =\u003e \"7\",\n  \"expiration_year\" =\u003e $futureDate,\n  \"fingerprint\" =\u003e uniqid(),\n  \"metadata\" =\u003e array(\"dni\" =\u003e \"71702935\")\n);\n  \n// Creando token a una tarjeta sin encriptar\n$token = $culqi-\u003eTokens-\u003ecreate(\n  $req_body\n);\n\n//Respuesta\nprint_r($charge);\n```\n\n### Crear un cargo\n\nCrear un cargo significa cobrar una venta a una tarjeta. Para esto previamente deberías generar el  `token` y enviarlo en parámetro **source_id**.\n\nLos cargos pueden ser creados vía [API de cargo](https://apidocs.culqi.com/#tag/Cargos/operation/crear-cargo).\n\n```php\n$charge = $culqi-\u003eCharges-\u003ecreate(\n    array(\n      \"amount\" =\u003e 1000,\n      \"capture\" =\u003e true,\n      \"currency_code\" =\u003e \"PEN\",\n      \"description\" =\u003e \"Venta de prueba\",\n      \"email\" =\u003e \"test@culqi.com\",\n      \"installments\" =\u003e 0,\n      \"antifraud_details\" =\u003e array(\n          \"address\" =\u003e \"Av. Lima 123\",\n          \"address_city\" =\u003e \"LIMA\",\n          \"country_code\" =\u003e \"PE\",\n          \"first_name\" =\u003e \"Test_Nombre\",\n          \"last_name\" =\u003e \"Test_apellido\",\n          \"phone_number\" =\u003e \"9889678986\",\n      ),\n      \"source_id\" =\u003e \"{token_id o card_id}\"\n    )\n);\n\n//Respuesta\nprint_r($charge);\n```\n\n### Crear Cargo con Configuración Adicional\n\n**¿Cómo funciona la configuración adicional?**\n\nPuedes agregar campos configurables en la sección **custom_headers** para personalizar las solicitudes de cobro. Es importante tener en cuenta que no se permiten campos con valores **false**, **null**, o cadenas vacías (**''**).\n\n**Explicación:**\n- **params**: Contiene la información necesaria para crear el cargo, como el monto, la moneda, y el correo del cliente.\n- **custom_headers**: Define los encabezados personalizados para la solicitud. Recuerda que solo se permiten valores válidos.\n- **Filtrado de encabezados**: Antes de realizar la solicitud, se eliminan los encabezados con valores no permitidos (**false, null, o vacíos**) para garantizar que la solicitud sea aceptada por la API.\n\n**¿Quieres realizar cobros a una lista de comercios en un tiempo y monto determinado?**\n\nPara realizar un cobro recurrente, puedes utilizar el siguiente código (**Configuración Adicional -\u003e custom_headers**):\n\n```php\n$req_body =  array(\n  \"amount\" =\u003e 1000,\n  \"capture\" =\u003e true,\n  \"currency_code\" =\u003e \"PEN\",\n  \"description\" =\u003e \"Venta de prueba\",\n  \"email\" =\u003e \"test@culqi.com\",\n  \"installments\" =\u003e 0,\n  \"antifraud_details\" =\u003e array(\n      \"address\" =\u003e \"Av. Lima 123\",\n      \"address_city\" =\u003e \"LIMA\",\n      \"country_code\" =\u003e \"PE\",\n      \"first_name\" =\u003e \"Test_Nombre\",\n      \"last_name\" =\u003e \"Test_apellido\",\n      \"phone_number\" =\u003e \"9889678986\",\n  ),\n  \"source_id\" =\u003e \"{token_id o card_id}\"\n);\n\n$custom_headers = array(\n  \"X-Charge-Channel\" =\u003e 'recurrent'\n);\n\n$charge = $culqi-\u003eCharges-\u003ecreate($req_body, [], $custom_headers);\n//Respuesta\nprint_r($charge);\n```\n**Solo habilitado para metodos POST**\n### Crear una devolución\n\nSolicita la devolución de las compras de tus clientes (parcial o total) de forma gratuita a través del API y CulqiPanel. \n\nLas devoluciones pueden ser creados vía [API de devolución](https://apidocs.culqi.com/#tag/Devoluciones/operation/crear-devolucion).\n\n```php\n$req_body = array(\n  \"amount\" =\u003e 500,\n  \"charge_id\" =\u003e \"{charge_id}\",\n  \"reason\" =\u003e \"bought an incorrect product\"\n);\n\n// Creando una devolución sin encriptar\n$refund = $culqi-\u003eRefunds-\u003ecreate(\n  $req_body\n);\n\n//Respuesta\nprint_r($refund);\n```\n\n### Crear un Cliente\n\nEl **cliente** es un servicio que te permite guardar la información de tus clientes. Es un paso necesario para generar una [tarjeta](/es/documentacion/pagos-online/recurrencia/one-click/tarjetas).\n\nLos clientes pueden ser creados vía [API de cliente](https://apidocs.culqi.com/#tag/Clientes/operation/crear-cliente).\n\n```php\n$customer = $culqi-\u003eCustomers-\u003ecreate(\n  array(\n    \"address\" =\u003e \"av lima 123\",\n    \"address_city\" =\u003e \"lima\",\n    \"country_code\" =\u003e \"PE\",\n    \"email\" =\u003e \"www@\".uniqid().\"me.com\",\n    \"first_name\" =\u003e \"Will\",\n    \"last_name\" =\u003e \"Muro\",\n    \"metadata\" =\u003e array(\"test\"=\u003e\"test\"),\n    \"phone_number\" =\u003e 899898999\n  )\n);\nprint_r($customer);\n```\n\n### Crear un Card\n\nLa **tarjeta** es un servicio que te permite guardar la información de las tarjetas de crédito o débito de tus clientes para luego realizarles cargos one click o recurrentes (cargos posteriores sin que tus clientes vuelvan a ingresar los datos de su tarjeta).\n\nLas tarjetas pueden ser creadas vía [API de tarjeta](https://apidocs.culqi.com/#tag/Tarjetas/operation/crear-tarjeta).\n\n```php\n$card = $culqi-\u003eCards-\u003ecreate(\n  array(\n    \"customer_id\" =\u003e \"{customer_id}\",\n    \"token_id\" =\u003e \"{token_id}\"\n  )\n);\nprint_r($card);\n```\n\n### Crear un Plan\n\nEl plan es un servicio que te permite definir con qué frecuencia deseas realizar cobros a tus clientes.\n\nUn plan define el comportamiento de las suscripciones. Los planes pueden ser creados vía el [API de Plan](https://apidocs.culqi.com/#/planes#create) o desde el **CulqiPanel**.\n\n```php\n$plan = $culqi-\u003ePlans-\u003ecreate(\n  array(\n    \"interval_unit_time\" =\u003e 1,\n    \"interval_count\" =\u003e 1,\n    \"amount\" =\u003e 300,\n    \"name\" =\u003e \"Plan mensual\" . uniqid(),\n    \"description\" =\u003e \"Plan-mock\" . uniqid(),\n    \"short_name\" =\u003e \"pln-\" . uniqid(),\n    \"currency\" =\u003e \"PEN\",\n    \"metadata\" =\u003e json_decode('{}'),\n    \"initial_cycles\" =\u003e array(\n      \"count\" =\u003e 0,\n      \"amount\" =\u003e 0,\n      \"has_initial_charge\" =\u003e false,\n      \"interval_unit_time\" =\u003e 1\n    ),\n  )\n);\n\n//Respuesta\nprint_r($plan);\n```\n\n### Crear un Suscripción a un plan\n\nLa suscripción es un servicio que asocia la tarjeta de un cliente con un plan establecido por el comercio.\n\nLas suscripciones pueden ser creadas vía [API de suscripción](https://apidocs.culqi.com/#tag/Suscripciones/operation/crear-suscripcion).\n\n```php\n// Creando Suscriptor a un plan\n$subscription = $culqi-\u003eSubscriptions-\u003ecreate(\n  array(\n    \"card_id\" =\u003e \"crd_live_tjHaW6x5Dj2oKhrS\",\n    \"plan_id\" =\u003e \"pln_live_0HzG8Edqy0aUIusL\",\n    \"tyc\" =\u003e true,\n    \"metadata\" =\u003e array(\"envtest\" =\u003e \"SDK-JAVA\"),\n  )\n);\n\n//Respuesta\nprint_r($subscription);\n```\n\n### Crear una Orden \n\nEs un servicio que te permite generar una orden de pago para una compra potencial.\nLa orden contiene la información necesaria para la venta y es usado por el sistema de **PagoEfectivo** para realizar los pagos diferidos.\n\nLas órdenes pueden ser creadas vía [API de orden](https://apidocs.culqi.com/#tag/Ordenes/operation/crear-orden).\n\n[Ver ejemplo completo](/examples/08-create-order.php)\n\n```php\n// Creando orden (con 1 dia de duracion)\n$order = $culqi-\u003eOrders-\u003ecreate(\n      array(\n        \"amount\" =\u003e 1000,\n        \"currency_code\" =\u003e \"PEN\",\n        \"description\" =\u003e 'Venta de prueba',        \n        \"order_number\" =\u003e 'pedido-9999',  \n        \"client_details\" =\u003e array( \n            \"first_name\"=\u003e \"Brayan\", \n            \"last_name\" =\u003e \"Cruces\",\n            \"email\" =\u003e \"micorreo@gmail.com\", \n            \"phone_number\" =\u003e \"51945145222\"\n         ),\n        \"expiration_date\" =\u003e time() + 24*60*60   // Orden con un dia de validez\n      )\n);\nprint_r($order);\n```\n\n\n## Pruebas\n\nAntes de activar tu tienda en producción, te recomendamos realizar pruebas de integración. Así garantizarás un correcto despliegue.\n\nSi vas a empezar a vender desde tu tienda virtual, deberás seleccionar el ambiente de producción e ingresar tus llaves.\n\n\u003e Recuerda que si quieres probar tu integración, puedes utilizar nuestras [tarjetas de prueba.](https://docs.culqi.com/es/documentacion/pagos-online/tarjetas-de-prueba/)\n\nDescarga los ejemplos desde:\n\n```bash\ngit clone https://github.com/culqi/culqi-php.git\ncomposer install\ncd culqi-php/examples\nphp -S 0.0.0.0:8000\n```\n\n### Ejemplo Prueba Token\n\n```php\n$PUBLIC_KEY = \"{PUBLIC KEY}\";\n$culqi = new Culqi\\Culqi(array('api_key' =\u003e $PUBLIC_KEY));\n$futureDate = date('Y', strtotime('+1 year'));\n$encryption_params = array(\n  \"rsa_public_key\" =\u003e \"\",\n  \"rsa_id\" =\u003e \"\"\n);\n\n$req_body = array(\n  \"card_number\" =\u003e \"4111111111111111\",\n  \"cvv\" =\u003e \"123\",\n  \"email\" =\u003e \"culqi\".uniqid().\"@culqi.com\", //email must not repeated\n  \"expiration_month\" =\u003e \"7\",\n  \"expiration_year\" =\u003e $futureDate,\n  \"fingerprint\" =\u003e uniqid(),\n  \"metadata\" =\u003e array(\"dni\" =\u003e \"71702935\")\n);\n  \n// Creando token a una tarjeta sin encriptar\n$token = $culqi-\u003eTokens-\u003ecreate(\n  $req_body\n);\n\n```\n\n### Ejemplo Prueba Cargo\n\n```php\n$SECRET_KEY = \"{SECRET KEY}\";\n$culqi = new Culqi\\Culqi(array('api_key' =\u003e $SECRET_KEY));\n\n//Datos para encriptar\n$encryption_params = array(\n  \"rsa_public_key\" =\u003e \"\",\n  \"rsa_id\" =\u003e \"\"\n);\n\n//3ds object, la primera vez que se consume el servicio no se debe enviar los parámetros 3ds\n$tds_xid = $_POST[\"xid\"];\n$tds = array(\"authentication_3DS\" =\u003e array(\n  \"eci\" =\u003e $_POST[\"eci\"],\n  \"xid\" =\u003e $tds_xid,\n  \"cavv\" =\u003e $_POST[\"cavv\"],\n  \"protocolVersion\" =\u003e $_POST[\"protocolVersion\"],\n  \"directoryServerTransactionId\" =\u003e $_POST[\"directoryServerTransactionId\"]\n));\n\n$req_body = array(\n  \"amount\" =\u003e 10000,\n  \"capture\" =\u003e true,\n  \"currency_code\" =\u003e \"PEN\",\n  \"description\" =\u003e \"Venta de prueba\",\n  \"installments\" =\u003e 0,\n  \"email\" =\u003e \"test@culqi.com\",\n  \"metadata\" =\u003e array(\"test\"=\u003e\"test\"),\n  \"source_id\" =\u003e \"\" // previamente generado usando create token\n);\n\n\n$with_tds = ($req_body) + (isset($tds_xid) ? $tds : array());\n\n// Creando Cargo sin encriptar a una tarjeta\n$charge = $culqi-\u003eCharges-\u003ecreate($with_tds);\n// Respuesta\necho \"\u003cb\u003eCargo sin encriptar payload:\u003c/b\u003e \".\"\u003cbr\u003e\".json_encode($charge).\"\u003cbr\u003e\";\n\n// Creando Cargo con encriptación a una tarjeta\n$charge = $culqi-\u003eCharges-\u003ecreate($with_tds, $encryption_params);\n```\n\n## Tests\n\n```bash\ncomposer install\nphpunit --verbose --tap tests/*\n```\n\n## Ejecución de Ejemplos\n\nPara ejecutar los ejemplos disponibles en nuestro SDK, sigue estos pasos:\n\n1. Abre tu terminal y navega a la carpeta \"examples\" del proyecto.\n\n2. Ejecuta el comando correspondiente para la operación que deseas probar:\n\n```bash\n   # Ejecutar el ejemplo de creación de planes\n   php examples/plan/02-create-plan.php\n\n   # Ejecutar el ejemplo de creación de suscripciones\n   php examples/subscription/01-create-subscription.php\n```\nAsegúrate de tener todos los requisitos previos y configuraciones necesarias antes de ejecutar los ejemplos. \nTen en cuenta que el nombre del archivo a ejecutar puede variar según la operación que estés probando.\n\n## Documentación\n\n- [Referencia de Documentación](https://docs.culqi.com/)\n- [Referencia de API](https://apidocs.culqi.com/)\n- [Demo Checkout V4 + Culqi 3DS](https://github.com/culqi/culqi-php-demo-checkoutv4-culqi3ds)\n- [Wiki](https://github.com/culqi/culqi-php/wiki)\n\n## Changelog\n\nTodos los cambios en las versiones de esta biblioteca están listados en\n[CHANGELOG.md](CHANGELOG.md).\n\n## Autor\nTeam Culqi\n\n## Licencia\nLicencia MIT. Revisar el LICENSE.md.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fculqi%2Fculqi-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fculqi%2Fculqi-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fculqi%2Fculqi-php/lists"}