{"id":19510639,"url":"https://github.com/culqi/culqi-ruby","last_synced_at":"2025-04-13T11:08:34.554Z","repository":{"id":62556543,"uuid":"79504638","full_name":"culqi/culqi-ruby","owner":"culqi","description":"Biblioteca de Culqi en Ruby","archived":false,"fork":false,"pushed_at":"2024-12-06T22:52:35.000Z","size":127,"stargazers_count":7,"open_issues_count":3,"forks_count":14,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-13T11:08:29.808Z","etag":null,"topics":["payment","ruby","sdk"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","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","contributing":null,"funding":null,"license":"LICENSE","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":"2017-01-19T23:13:34.000Z","updated_at":"2025-02-27T04:56:07.000Z","dependencies_parsed_at":"2024-01-09T20:27:52.964Z","dependency_job_id":"e71fedfc-a0e7-4076-a5de-753c9f3879b5","html_url":"https://github.com/culqi/culqi-ruby","commit_stats":{"total_commits":42,"total_committers":7,"mean_commits":6.0,"dds":0.2857142857142857,"last_synced_commit":"737f9ca6501e3acc8e81774b3570e3cb3a3a3cbf"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/culqi%2Fculqi-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/culqi%2Fculqi-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/culqi%2Fculqi-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/culqi%2Fculqi-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/culqi","download_url":"https://codeload.github.com/culqi/culqi-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248703198,"owners_count":21148118,"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":["payment","ruby","sdk"],"created_at":"2024-11-10T23:16:37.417Z","updated_at":"2025-04-13T11:08:34.526Z","avatar_url":"https://github.com/culqi.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Culqi-Ruby\n\n[![Gem Version](https://badge.fury.io/rb/culqi-ruby.svg)](https://badge.fury.io/rb/culqi-ruby)\n\nNuestra Biblioteca Culqi-Ruby 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| Versión actual|Culqi API|\n|----|----|\n| [1.0.0](https://rubygems.org/gems/culqi-ruby) (2023-08-11) |[v2](https://culqi.com/api)|\n\n\n## Requisitos\n\n- Ruby 3.0.0+\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://mipanel.culqi.com/#/registro).\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## Instalar Dependencias\n\n```bash\ngem install bundler\nbundle install\n```\n\n## Build\n\n```bash\ngem build culqi-ruby.gemspec\ngem install ./culqi-ruby-{VERSION}.gem\ngem push culqi-ruby-{VERSION}.gem\n```\n\n## Configuracion\n\nPara empezar a enviar peticiones al API de Culqi debes configurar tu llave pública (pk), llave privada (sk).\nPara habilitar encriptación de payload debes configurar tu rsa_id y rsa_public_key.\n\n```ruby\n\nrequire 'minitest/autorun'\nrequire 'culqi-ruby'\n\nCulqi.public_key = 'pk_test_e94078b9b248675d'\nCulqi.secret_key = 'sk_test_c2267b5b262745f0'\nCulqi.rsa_id = 'de35e120-e297-4b96-97ef-10a43423ddec'\nCulqi.rsa_key = \"-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDswQycch0x/7GZ0oFojkWCYv+g\nr5CyfBKXc3Izq+btIEMCrkDrIsz4Lnl5E3FSD7/htFn1oE84SaDKl5DgbNoev3pM\nC7MDDgdCFrHODOp7aXwjG8NaiCbiymyBglXyEN28hLvgHpvZmAn6KFo0lMGuKnz8\nHiuTfpBl6HpD6+02SQIDAQAB\n-----END PUBLIC KEY-----\"\n```\n\n### Encriptar payload\n\nPara encriptar el payload necesitas agregar el siguiente codigo en caso de token.\n\nEjemplo\n\n```ruby\ntoken_string =  CulqiCRUD.createTokenEncrypt\ntoken_json = JSON.parse(JSON.generate(token_string[0]))\nid_value = token_json['object']\nassert_equal 'token', id_value\n```\n\n## Servicios\n\n### Crear 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```ruby\nparams ={\n      :card_number =\u003e '4111111111111111',\n      :cvv =\u003e '111',\n      :currency_code =\u003e 'PEN',\n      :email =\u003e 'test1231@culqi.com',\n      :expiration_month =\u003e 9,\n      :expiration_year =\u003e 2025\n    }\ntoken, statusCode = Culqi::Token.create(params,  rsa_key, rsa_id)\n\njsonToken = JSON.parse(token)\n\nputs jsonToken['id']\n```\n\n### Crear 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```ruby\nparams = {\n      :amount =\u003e 1000,\n      :capture =\u003e false,\n      :currency_code =\u003e 'PEN',\n      :description =\u003e 'Venta de prueba',\n      :email =\u003e 'test'+SecureRandom.uuid+'@culqi.com',\n      :installments =\u003e 0,\n      :metadata =\u003e ({\n        :test =\u003e 'test123'\n      }),\n      :source_id =\u003e token_json['id']\n    }\ncharge, statusCode = Culqi::Charge.create(params)\n\njsonCharge = JSON.parse(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```ruby\nparams = {\n  :amount =\u003e 1000,\n  :capture =\u003e false,\n  :currency_code =\u003e 'PEN',\n  :description =\u003e 'Venta de prueba',\n  :email =\u003e 'test'+SecureRandom.uuid+'@culqi.com',\n  :installments =\u003e 0,\n  :metadata =\u003e ({\n    :test =\u003e 'test123'\n  }),\n  :source_id =\u003e token_json['id']\n}\n\ncustom_headers  = {\n  'X-Charge-Channel' =\u003e 'recurrent',\n}\n\ncharge, statusCode = Culqi::Charge.create(params, '', '', custom_headers)\n\njsonCharge = JSON.parse(charge)\n```\n**Solo habilitado para metodos POST**\n### Crear 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```ruby\nrefund, statusCode = Culqi::Refund.create(\n  :amount =\u003e 500,\n  :charge_id =\u003e jsonCharge['id'],\n  :reason =\u003e 'solicitud_comprador'\n)\n\njsonRefund = JSON.parse(refund)\n```\n\n### Crear 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```ruby\nparams = {\n      :address =\u003e 'Avenida Lima 123213',\n      :address_city =\u003e 'LIMA',\n      :country_code =\u003e 'PE',\n      :email =\u003e 'test'+SecureRandom.uuid+'@culqi.com',\n      :first_name =\u003e 'William',\n      :last_name =\u003e 'Muro',\n      :metadata =\u003e ({\n        :other_number =\u003e '789953655'\n      }),\n      :phone_number =\u003e 998989789\n    }\ncustomer, statusCode = Culqi::Customer.create(params)\n\njsonCustomer = JSON.parse(customer)\n```\n\n### Actualizar Cliente\n\n```ruby\nupdatecustomer, statusCode = Culqi::Customer.update('cus_test_F5voBd1yHsCkjSwF',\n      :address =\u003e 'Av. Lima 123',\n      :first_name =\u003e 'Will')\n```\n\n### Obtener Cliente\n\n```ruby\ngetcustomer = Culqi::Customer.get('cus_test_F5voBd1yHsCkjSwF')\n```\n\n### Crear 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```ruby\ncard, statusCode = Culqi::Card.create(\n  :customer_id =\u003e jsonCustomer['id'],\n  :token_id =\u003e jsonToken['id']\n)\n\njsonCard = JSON.parse(card)\n```\n\n### Crear 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```ruby\nparams = {\n      :amount =\u003e 1000,\n      :currency_code =\u003e 'PEN',\n      :interval =\u003e 'dias',\n      :interval_count =\u003e 2,\n      :limit =\u003e 10,\n      :metadata =\u003e ({\n        :alias =\u003e 'plan_test'\n      }),\n      :name =\u003e 'plan-test-'+SecureRandom.uuid,\n      :trial_days =\u003e 50\n    }\n\nplan, statusCode = Culqi::Plan.create(params)\n\njsonPlan = JSON.parse(plan)\n```\n\n### Crear Suscripción\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```ruby\nsubscription, statusCode = Culqi::Subscription.create(\n  :card_id =\u003e jsonCard['id'],\n  :plan_id =\u003e jsonPlan['id']\n)\n\njsonSubscription = JSON.parse(subscription)\n```\n\n### Crear 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```ruby\nparams = {\n  :amount =\u003e 10000,\n  :currency_code =\u003e 'PEN',\n  :description =\u003e 'Venta de prueba',\n  :order_number =\u003e 'pedido-ruby-'+SecureRandom.random_number(50).to_s,\n  :client_details =\u003e ({\n    :first_name =\u003e 'Richard',\n    :last_name =\u003e 'Hendricks',\n    :email =\u003e 'richar3d@piedpiper.com',\n    :phone_number =\u003e '+51945145280'\n  }),\n  :expiration_date =\u003e (Time.now + (2*7*24*60*60)).to_i,\n  :confirm =\u003e false\n}\norder, statusCode = Culqi::Orden.create(params)\n\njsonSubscription = JSON.parse(order)\n```\n\n\n## Pruebas\n\nEn la carpeta **/test** encontraras ejemplos para crear un token, charge, plan, órdenes, card, suscripciones, etc.\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\nSolo debe ejecutar el siguiente comando\n\n```ruby\nrake test test_culqi-create.rb\n```\n\nSi queremos ejecutar un especifico test método\n\n```ruby\nrake test TEST=test/test_culqi-create.rb\nrake test TEST=test/test_culqi-create.rb TESTOPTS=\"--name=test_create_token -v\"\n```\n\n\n### Ejemplo Prueba Token\n\n```ruby\ntoken_string =  CulqiCRUD.createToken\ntoken_json = JSON.parse(JSON.generate(token_string[0]))\nid_value = token_json['object']\nassert_equal 'token', id_value\n```\n\n### Ejemplo Prueba Cargo\n\n```ruby\ncharge_string =  CulqiCRUD.createCharge\ncharge_json = JSON.parse(JSON.generate(charge_string[0]))\nid_value = charge_json['object']\nassert_equal 'charge',id_value\n```\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-ruby-demo-checkoutv4-culqi3ds)\n- [Wiki](https://github.com/culqi/culqi-ruby/wiki)\n\n\n## Changelog\n\nTodos los cambios en las versiones de esta biblioteca están listados en [CHANGELOG](CHANGELOG).\n\n## Autor\nTeam Culqi\n\n## Licencia\nEl código fuente de culqi-net está distribuido bajo MIT License, revisar el archivo LICENSE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fculqi%2Fculqi-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fculqi%2Fculqi-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fculqi%2Fculqi-ruby/lists"}