culqi/culqi-php

Culqi API PHP 客户端

维护者

详细信息

github.com/culqi/culqi-php

主页

源代码

问题

安装次数: 302,906

依赖项: 2

建议者: 0

安全: 0

星级: 34

关注者: 17

分支: 36

开放问题: 14

v2.0.3 2024-04-01 16:45 UTC

Requires

Requires (Dev)

MIT 5e89959ed02693ad9a15e1ca96aff5dc18d61a56

phpapiclientpaymentspagosculqiperu

This package is auto-updated.

Last update: 2024-09-25 05:59:36 UTC

README

Latest Stable Version Total Downloads License

我们的官方 PHP 库，兼容 Culqi API V2.0，通过简单配置即可实现使用借记卡和信用卡、Yape、PagoEfectivo、移动钱包和 Cuotéalo 进行收费。

我们的库允许您捕获向 Culqi API 发送 HTTP 请求时的 status_code，以及包含响应体的 response。

要求

  • PHP 5.6+
  • 在此处注册。
  • 如果您要进行测试，请从此处获取您的密钥，如果您要进行真实交易，请从此处获取您的密钥（1）。

请记住，要获取密钥，您需要进入 CulqiPanel > 开发 > API 密钥。

alt tag

请记住，凭证将通过您在注册过程中提供的电子邮件发送。

  • 要加密 payload，您需要通过进入 CulqiPanel > 开发 > RSA 密钥生成一个 id 和 RSA 密钥。

安装

1. 通过 Composer

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

使用 Composer 的自动加载器加载所有内容。

require 'vendor/autoload.php';

2. 手动安装

克隆存储库或下载源代码

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

现在，在头部包含 culqi-php，以及依赖项 Requests。您需要根据您的结构正确调用文件夹和/或文件。

<?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';

然后执行 composer install

composer install

配置

第一步是配置 $API_KEY 凭证。

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

请记住，集成密钥标识为 "test"，而生产密钥标识为 "live"。

加密 payload

要加密 payload，您需要创建一个 RSA id 和 RSA 密钥，为此，您需要进入您的面板，并在左侧导航栏中点击 "开发 / RSA 密钥" 部分。

然后，在您的后端声明 RSA id 和 RSA 密钥变量，并在库的函数中发送它们。

示例

$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
  );

服务

创建一个 token

在创建一个 Charge 或 Card 之前，需要创建一个 token 卡。建议使用 Culqi Checkout v4 或 Culqi JS v4 生成 'tokens'，因为将卡数据直接从客户设备发送到 Culqi 服务器非常重要，这样可以避免泄露信用卡/借记卡的敏感数据。

请记住，当您直接与 API Token 交互时，您需要遵守 PCI DSS 3.2 规范。因此，我们要求您填写 SAQ-D 表格 并将其发送到 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 a una tarjeta sin encriptar
$token = $culqi->Tokens->create(
  $req_body
);

//Respuesta
print_r($charge);

创建一个 charge

创建一个收费项目意味着对一张卡收取一笔销售款项。为了做到这一点，你首先需要生成一个 token 并将其作为参数 source_id 发送。

可以通过 收费 API 来创建收费项目。

$charge = $culqi->Charges->create(
    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}"
    )
);

//Respuesta
print_r($charge);

创建带附加设置的收费项目

附加设置是如何工作的？

你可以在 custom_headers 部分添加可配置的字段来定制收费请求。请注意，不允许使用值 false、null 或空字符串 ('') 的字段。

说明

  • params：包含创建收费项目所需的信息，例如金额、货币和客户邮箱。
  • custom_headers：定义请求的自定义头部。请记住，只允许使用有效的值。
  • 头部过滤：在执行请求之前，会删除包含不允许的值（false、null 或空字符串）的头部，以确保请求被 API 接受。

你想在特定的时间和金额下对一家商家的列表进行收费吗？

为了进行周期性收费，你可以使用以下代码（附加设置 -> 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);

仅支持 POST 方法

创建退款

通过 API 和 CulqiPanel，你可以免费请求客户（部分或全部）购买的退款。

可以通过 退款 API 来创建退款。

$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);

创建客户

客户 是一个服务，允许你保存客户的详细信息。这是生成一个 一键式卡片 的必要步骤。

可以通过 客户 API 来创建客户。

$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);

创建卡片

卡片 是一个服务，允许你保存客户的信用卡或借记卡信息，以便随后进行一键式或周期性（后续收费无需客户再次输入卡信息）的收费。

可以通过 卡片 API 来创建卡片。

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

创建计划

计划是一个服务，允许你定义你希望多久对客户进行一次收费。

计划定义了订阅的行为。计划可以通过 计划 API 或从 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);

创建计划订阅

订阅是一个服务，它将客户的卡片与商家设置的计划关联起来。

可以通过 订阅 API 来创建订阅。

// 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);

创建订单

这是一个服务，允许你为潜在购买生成一个支付订单。订单包含销售所需的信息，并由 PagoEfectivo 系统用于进行延迟支付。

可以通过 订单 API 来创建订单。

查看完整示例

// 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);

测试

在将你的商店投入生产之前，我们建议你进行集成测试。这样可以确保正确部署。

如果您打算开始从您的虚拟商店销售，您需要选择生产环境并输入您的密钥。

请记住，如果您想测试您的集成，可以使用我们的测试卡。

从以下位置下载示例

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

测试令牌示例

$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
);

测试收费示例

$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);

测试

composer install
phpunit --verbose --tap tests/*

示例执行

要执行我们SDK中的可用示例，请按照以下步骤操作

  1. 打开您的终端并导航到项目的"examples"文件夹。

  2. 执行相应的命令以进行您要测试的操作

   # 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

在执行示例之前，请确保您已满足所有先决条件和必要的配置。请注意，要执行的文件名可能会根据您正在测试的操作而变化。

文档

变更日志

该库所有版本的更改都在CHANGELOG.md中列出。

作者

Culqi团队

许可

MIT许可。请参阅LICENSE.md。