SDK PHP

Nuestro SDK te permite integrarte rapidamente con Culqi

Nuestro SDK oficial PHP, es compatible con la V2.0 del Culqi API, con el cual tendrás la posibilidad de integrarte con el API de tokens, cargos, devoluciones, clientes, tarjetas, planes, suscripciones y órdenes

El SDK te da la posibilidad de capturar el status_code de la solicitud HTTP que se realiza al API de Culqi, así como el response.

Requisitos

  • Nuestro SDK es compatible con PHP 7.0+.
  • Debes tener tus llaves de producción o integración.
  • Si aun no te afilias a Culqi, lo puedes hacer desde aquí.
  • Para encriptar el payload debes generar un id y llave RSA ingresando a tu CulqiPanel > Desarrollo > RSA Keys.

Recuerda que para obtener tu llave pública, debes ingresar a la sección “Desarrollo” y luego a “API Keys” en tu CulqiPanel, para generar tu id y llave RSA debes ingresar a “RSA Keys”.

Repositorio

Puedes descargar el código fuente del SDK desde:

Repositorio

Culqi PHP

repositorio

Repositorio de paquetes

Puedes revisar las versiones disponibles desde el repositorio de paquetes de PHP e instalarlo en tu aplicativo como una dependencia:

Repositorio

Culqi PHP

repositorio

Instalación

a. Vía Composer

Agregar la dependecia en el archivo composer.json de tu aplicativo. Selecciona siempre la versión mas reciente del repositorio de paquetes.

{
  "require": {
    "culqi/culqi-php": "2.0.4"
  }
}

Luego ejecuta composer install en una terminal

composer install

Y cargar todo usando el autoloader de Composer.

require 'vendor/autoload.php';

b. Manualmente

Usa está opción si vas a integrar el código fuente del SDK en tu aplicativo, debes descargarlo desde su repositorio.

git clone git@github.com:culqi/culqi-php.git

Ahora, incluye en la cabecera a culqi-php y también la dependencia Requests. Debes hacer el llamado correctamente a la carpeta y/o archivo dependiendo de tu estructura.

<?php
// Cargamos Requests y Culqi PHP
include_once dirname(__FILE__).'/libraries/Requests/library/Requests.php';
Requests::register_autoloader();
include_once dirname(__FILE__).'/libraries/culqi-php/lib/culqi.php';

Luego ejecuta composer install

composer install

Configuración

1. Configurar llaves

Para empezar a enviar peticiones al API de Culqi debes configurar tu llave pública (pk), llave privada (sk), luego crear una instancia de la clases Culqi.

// Configurar tu API Key y autenticación
$PUBLIC_KEY = "{PUBLIC KEY}";
$SECRET_KEY = "{SECRET KEY}";
$culqi = new Culqi\Culqi(array('api_key' => $SECRET_KEY));

Recuerda que las llaves de integración se identifican como “test” y las de producción como “live”.

2. Encriptar payload

Para encriptar el payload necesitas crear un id RSA y llave RSA, luego declara tus variables y enviar el objeto $encryption_params en las funciones de la librería.

Ejemplo

$encryption_params = array(
  "rsa_public_key" => "la llave pública RSA",
  "rsa_id" => "el id de tu llave"
);
 $req_body = array(
    "card_number" => "4111111111111111",
    "cvv" => "123",
    "email" => "culqi".uniqid()."@culqi.com", //email must not repeated
    "expiration_month" => "7",
    "expiration_year" => $futureDate,
    "fingerprint" => uniqid(),
    "metadata" => array("dni" => "71702935")
);
$token = $culqi->Tokens->create(
    $req_body,
    $encryption_params
);

Servicios

Crear token

Para no poner en riesgo los datos sensibles de la tarjeta de crédito/débito es recomendable es generar los ‘tokens’ con el Custom Checkout debido a que es muy importante que los datos de la tarjeta sean enviados directamente desde el dispositivo de tus clientes a los servidores de Culqi.

Recuerda que cuando interactúas directamente con el API Token necesitas cumplir la normativa de PCI DSS 3.2. Por ello, te pedimos que llenes el formulario SAQ-D y lo envíes al buzón de riesgos Culqi.

 
$req_body = array(
  "card_number" => "4111111111111111",
  "cvv" => "123",
  "email" => "culqi".uniqid()."@culqi.com", //email must not repeated
  "expiration_month" => "7",
  "expiration_year" => $futureDate,
  "fingerprint" => uniqid(),
  "metadata" => array("dni" => "71702935")
);
// Creando token 
$token = $culqi->Tokens->create(
  $req_body
);
//Respuesta
print_r($token);

Crear cargo

Crear un cargo significa cobrar una venta a una tarjeta. Para esto previamente deberías generar el token y enviarlo en el parámetro source_id.

Los cargos son creados a través del API de cargo.

$charge = $culqi->Charges->create(
    array(
      "amount" => 1000,
      "source_id" => "{token_id o card_id}"
      "capture" => true,
      "currency_code" => "PEN",
      "description" => "Venta de prueba",
      "email" => "test@culqi.com",
      "installments" => 0,
      "antifraud_details" => array(
          "address" => "Av. Lima 123",
          "address_city" => "LIMA",
          "country_code" => "PE",
          "first_name" => "Test_Nombre",
          "last_name" => "Test_apellido",
          "phone_number" => "9889678986",
      )
    )
);
//Respuesta
print_r($charge);

Crear Cargo con Configuración Adicional

¿Cómo funciona la configuración adicional?

Puedes 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 (”). Solo habilitado para métodos POST.

Explicación:

  • params: Contiene la información necesaria para crear el cargo, como el monto, la moneda, y el correo del cliente.
  • custom_headers: Define los encabezados personalizados para la solicitud. Recuerda que solo se permiten valores válidos.
  • 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.

¿Quieres realizar cobros a una lista de comercios en un tiempo y monto determinado?

Para realizar un cobro recurrente, puedes utilizar el siguiente código (Configuración Adicional -> custom_headers):

$req_body =  array(
  "amount" => 1000,
  "capture" => true,
  "currency_code" => "PEN",
  "description" => "Venta de prueba",
  "email" => "test@culqi.com",
  "installments" => 0,
  "antifraud_details" => array(
      "address" => "Av. Lima 123",
      "address_city" => "LIMA",
      "country_code" => "PE",
      "first_name" => "Test_Nombre",
      "last_name" => "Test_apellido",
      "phone_number" => "9889678986",
  ),
  "source_id" => "{token_id o card_id}"
);
$custom_headers = array(
  "X-Charge-Channel" => 'recurrent'
);
$charge = $culqi->Charges->create($req_body, [], $custom_headers);
//Respuesta
print_r($charge);

Crear devolución

Solicita la devolución de las compras de tus clientes (parcial o total) a través del API y CulqiPanel.

Las devoluciones son creadas a través del API de devolución.

$req_body = array(
  "amount" => 500,
  "charge_id" => "{charge_id}",
  "reason" => "bought an incorrect product"
);
// Creando una devolución sin encriptar
$refund = $culqi->Refunds->create(
  $req_body
);
//Respuesta
print_r($refund);

Crear Cliente

El cliente es un servicio que te permite guardar la información de tus clientes. Es un paso necesario para generar una tarjeta.

Los clientes son creados a través del API de cliente.

$customer = $culqi->Customers->create(
  array(
    "address" => "av lima 123",
    "address_city" => "lima",
    "country_code" => "PE",
    "email" => "www@".uniqid()."me.com",
    "first_name" => "Will",
    "last_name" => "Muro",
    "metadata" => array("test"=>"test"),
    "phone_number" => 899898999
  )
);
print_r($customer);

Crear Card

La 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).

Las tarjetas son creadas a través del API de tarjeta.

$card = $culqi->Cards->create(
  array(
    "customer_id" => "{customer_id}",
    "token_id" => "{token_id}"
  )
);
print_r($card);

Crear Plan

El plan es un servicio que te permite definir con qué frecuencia deseas realizar cobros a tus clientes.

Un plan define el comportamiento de las suscripciones. Los planes son creados a través del API de Plan o desde el CulqiPanel.

$plan = $culqi->Plans->create(
  array(
    "interval_unit_time" => 1,
    "interval_count" => 1,
    "amount" => 300,
    "name" => "Plan mensual" . uniqid(),
    "description" => "Plan-mock" . uniqid(),
    "short_name" => "pln-" . uniqid(),
    "currency" => "PEN",
    "metadata" => json_decode('{}'),
    "initial_cycles" => array(
      "count" => 0,
      "amount" => 0,
      "has_initial_charge" => false,
      "interval_unit_time" => 1
    ),
  )
);
//Respuesta
print_r($plan);

Crear Suscripción a un plan

La suscripción es un servicio que asocia la tarjeta de un cliente con un plan establecido por el comercio.

Las suscripciones son creadas a través del API de suscripción.

// Creando Suscriptor a un plan
$subscription = $culqi->Subscriptions->create(
  array(
    "card_id" => "crd_live_tjHaW6x5Dj2oKhrS",
    "plan_id" => "pln_live_0HzG8Edqy0aUIusL",
    "tyc" => true,
    "metadata" => array("envtest" => "SDK-JAVA"),
  )
);
//Respuesta
print_r($subscription);

Crear Orden

Es un servicio que te permite generar una orden de pago para una compra potencial. La orden contiene la información necesaria para la venta y es usado por el sistema de PagoEfectivo para realizar los pagos diferidos.

Las órdenes son creadas a través del API de orden.

// Creando orden (con 1 dia de duracion)
$order = $culqi->Orders->create(
      array(
        "amount" => 1000,
        "currency_code" => "PEN",
        "description" => 'Venta de prueba',        
        "order_number" => 'pedido-9999',  
        "client_details" => array( 
            "first_name"=> "Brayan", 
            "last_name" => "Cruces",
            "email" => "micorreo@gmail.com", 
            "phone_number" => "51945145222"
         ),
        "expiration_date" => time() + 24*60*60   // Orden con un dia de validez
      )
);
print_r($order);

Pruebas

Antes de activar tu tienda en producción, te recomendamos realizar pruebas de integración. Así garantizarás un correcto despliegue.

Si vas a empezar a vender desde tu tienda virtual, deberás seleccionar el ambiente de producción e ingresar tus llaves.

Recuerda que si quieres probar tu integración, puedes utilizar nuestras tarjetas de prueba.

Descarga los ejemplos desde:

git clone https://github.com/culqi/culqi-php.git
composer install
cd culqi-php/examples
php -S 0.0.0.0:8000

Ejemplo Prueba Token

$PUBLIC_KEY = "{PUBLIC KEY}";
$culqi = new Culqi\Culqi(array('api_key' => $PUBLIC_KEY));
$futureDate = date('Y', strtotime('+1 year'));
$encryption_params = array(
  "rsa_public_key" => "",
  "rsa_id" => ""
);

$req_body = array(
  "card_number" => "4111111111111111",
  "cvv" => "123",
  "email" => "culqi".uniqid()."@culqi.com", //email must not repeated
  "expiration_month" => "7",
  "expiration_year" => $futureDate,
  "fingerprint" => uniqid(),
  "metadata" => array("dni" => "71702935")
);
  
// Creando token a una tarjeta sin encriptar
$token = $culqi->Tokens->create(
  $req_body
);

Ejemplo Prueba Cargo

$SECRET_KEY = "{SECRET KEY}";
$culqi = new Culqi\Culqi(array('api_key' => $SECRET_KEY));

//Datos para encriptar
$encryption_params = array(
  "rsa_public_key" => "",
  "rsa_id" => ""
);

//3ds object, la primera vez que se consume el servicio no se debe enviar los parámetros 3ds
$tds_xid = $_POST["xid"];
$tds = array("authentication_3DS" => array(
  "eci" => $_POST["eci"],
  "xid" => $tds_xid,
  "cavv" => $_POST["cavv"],
  "protocolVersion" => $_POST["protocolVersion"],
  "directoryServerTransactionId" => $_POST["directoryServerTransactionId"]
));

$req_body = array(
  "amount" => 10000,
  "capture" => true,
  "currency_code" => "PEN",
  "description" => "Venta de prueba",
  "installments" => 0,
  "email" => "test@culqi.com",
  "metadata" => array("test"=>"test"),
  "source_id" => "" // previamente generado usando create token
);


$with_tds = ($req_body) + (isset($tds_xid) ? $tds : array());

// Creando Cargo sin encriptar a una tarjeta
$charge = $culqi->Charges->create($with_tds);
// Respuesta
echo "<b>Cargo sin encriptar payload:</b> "."<br>".json_encode($charge)."<br>";

// Creando Cargo con encriptación a una tarjeta
$charge = $culqi->Charges->create($with_tds, $encryption_params);

Ejecución de Ejemplos

Abre una terminal y navega a la carpeta “examples” del proyecto, allí encontraras varios ejemplos de prueba.

Ejemplo

   # Ejecutar el ejemplo de creación de planes
   php examples/plan/02-create-plan.php

   # Ejecutar el ejemplo de creación de suscripciones
   php examples/subscription/01-create-subscription.php

Asegúrate de tener todos los requisitos previos y configuraciones necesarias antes de ejecutar los ejemplos. Ten en cuenta que el nombre del archivo a ejecutar puede variar según la operación que estés probando.

Anterior Librerias
Siguiente SDK Net Core