包简介

A sdk for mercury api

README 文档

README

E-Commerce API SDK

Introdução

Este documento explica como realizar a integração com a API de E-Commerce utilizando nosso SDK em PHP para começar a realizar transações.

Requerimentos

PHP 7.0+

Instalação com Composer

composer require soulpay/soulpay-sdk

Vamos Começar

A API é capaz de realizar transações de cartão de crédito, geração de boletos e recorrências diárias, semanais, mensais ou outras escolhas de período.

Ambientes

Para utilizar este SDK em ambiente de teste é necessario colocar o ultimo parametro do construtor de uma request como false, como demonstrado abaixo.

// Request para o ambiente de desenvolvimento
$request = new CreditCardRequest('Sua chave JWT aqui', false);

// Request para o ambiente de produção
$request = new CreditCardRequest('Sua chave JWT aqui', true);

Realizar Login

Para realizar o login é necessário criar um objeto Login, preenche-lo com Email e Password. Logo após, é necessário instanciar a classe LoginRequest e passar o objeto Login (previamente criado) ao método send.

Vejamos um exemplo abaixo

$login = new Login();

$login->setEmail('testedev@dev.com');
$login->setPassword('testeDev');

$loginRequest = new LoginRequest(false);

$response = $loginRequest->send(json_encode($login));

Criando uma Transação

Para criar uma transação é necessário preencher as informações obrigatórias descritas na documentação.

Seguindo a mesma ideia de login, é necessário instanciar os models da transação, sendo esses Customer, Billing, Shipping, CreditCard, CreditInstallment, Payment, CreditCardTransaction.
Para enviar a transação é necessário instanciar CreditCardTransaction onde o token JWT deve ser passado como parâmetro.

$customer = new Customer();

$customer->setName('cliente');
$customer->setEmail('cliente@cliente.com');
$customer->setDob('1997-10-03');
$customer->setTaxId('1234134141');

$billing = new Billing();

$billing->setName('Soulpay');
$billing->setAddress('Avenida Paulista');
$billing->setAddress2('124');
$billing->setDistrict('Bela vista');
$billing->setCity('São Paulo');
$billing->setState('SP');
$billing->setPostalCode('01311000');
$billing->setCountry('BR');
$billing->setPhone('111112222233333');
$billing->setEmail('billing@soulpay.com.br');

$shipping = new Shipping();

$shipping->setName('Soulpay');
$shipping->setAddress('Avenida Paulista');
$shipping->setAddress2('124');
$shipping->setDistrict('Bela vista');
$shipping->setCity('São Paulo');
$shipping->setState('SP');
$shipping->setPostalCode('01311000');
$shipping->setCountry('BR');
$shipping->setPhone('12345678');
$shipping->setEmail('shipping@soulpay.com.br');

$creditCard = new CreditCard();

$creditCard->setCardHolderName('Soulpay');
$creditCard->setNumber('4620685100802685');
$creditCard->setExpDate('12/2022');
$creditCard->setCvvNumber('420');

$creditInstallment = new CreditInstallment();

$creditInstallment->setNumberOfInstallments(1);
$creditInstallment->setChargeInterest('N');

$payment = new Payment();

$payment->setChargeTotal(10.5);
$payment->setCurrencyCode('BRL');
$payment->setCreditInstallment($creditInstallment);

$creditCardTransaction = new CreditCardTransaction();

$creditCardTransaction->setReferenceNum('123456');
$creditCardTransaction->setCustomer($customer);
$creditCardTransaction->setBilling($billing);
$creditCardTransaction->setShipping($shipping);
$creditCardTransaction->setCreditCard($creditCard);
$creditCardTransaction->setPayment($payment);

// Passar o token JWT aqui.
$request = new CreditCardRequest('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjEsImlhdCI6MTU3NTkwMzEyOSwiZXhwIjoxNTc4NDk1MTI5fQ.c0g6ynTtZHFSU3qh4bJWy-jea0VnKE4hGBTAs_uhNjY', false);

$response = $request->send(json_encode($creditCardTransaction)

Criando uma Recorrência

Para criar uma recorrência é necessário preencher as informações obrigatórias descritas na documentação.

Seguindo a mesma ideia de transação, é necessário instanciar os models da recorrência, sendo esses Customer, Billing, Shipping, CreditCard, Recurring, CreditInstallment, Payment, RecurringTransaction. Para enviar a recorrência é necessário instanciar RecurringRequest onde o token JWT deve ser passado como parâmetro.

$customer = new Customer();

$customer->setName('cliente');
$customer->setEmail('cliente@cliente.com');
$customer->setDob('1997-10-03');
$customer->setTaxId('1234134141');

$billing = new Billing();

$billing->setName('Soulpay');
$billing->setAddress('Avenida Paulista');
$billing->setAddress2('124');
$billing->setDistrict('Bela vista');
$billing->setCity('São Paulo');
$billing->setState('SP');
$billing->setPostalCode('01311000');
$billing->setCountry('BR');
$billing->setPhone('111112222233333');
$billing->setEmail('billing@soulpay.com.br');

$shipping = new Shipping();

$shipping->setName('Soulpay');
$shipping->setAddress('Avenida Paulista');
$shipping->setAddress2('124');
$shipping->setDistrict('Bela vista');
$shipping->setCity('São Paulo');
$shipping->setState('SP');
$shipping->setPostalCode('01311000');
$shipping->setCountry('BR');
$shipping->setPhone('12345678');
$shipping->setEmail('shipping@soulpay.com.br');

$creditCard = new CreditCard();

$creditCard->setCardHolderName('Soulpay');
$creditCard->setNumber('4620685100802685');
$creditCard->setExpDate('12/2022');
$creditCard->setCvvNumber('420');

$creditInstallment = new CreditInstallment();
$creditInstallment->setNumberOfInstallments(1);
$creditInstallment->setChargeInterest('N');

$payment = new Payment();

$payment->setChargeTotal(10.5);
$payment->setCurrencyCode('BRL');
$payment->setCreditInstallment($creditInstallment);

$recurring = new Recurring();

$recurring->setStartDate('2022-01-10');
$recurring->setPeriod('monthly');
$recurring->setFrequency('1');
$recurring->setInstallments('12');
$recurring->setFirstAmount(20.2);
$recurring->setFailureThreshold(15);

$recurringTransaction = new RecurringTransaction();

$recurringTransaction->setReferenceNum('123456');
$recurringTransaction->setCustomer($customer);
$recurringTransaction->setBilling($billing);
$recurringTransaction->setShipping($shipping);
$recurringTransaction->setCreditCard($creditCard);
$recurringTransaction->setPayment($payment);
$recurringTransaction->setRecurring($recurring);

// Passar o token JWT aqui.
$request = new RecurringRequest('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjEsImlhdCI6MTU3NTkwMzEyOSwiZXhwIjoxNTc4NDk1MTI5fQ.c0g6ynTtZHFSU3qh4bJWy-jea0VnKE4hGBTAs_uhNjY', false);

$response = $request->send(json_encode($recurringTransaction))

Ativando/desativando uma Recorrência

Na edição de recorrência é necessário instanciar a model RecurringStatus. Para enviar a requisição é necessário instanciar RecurringRequest, onde o token JWT deve ser passado como parâmetro.

$recurringStatus = new RecurringStatus();

//Passar a ação a ser executada: disable | enable
$recurringStatus->setStatus('disable');

// Passar o token JWT aqui.
$request = new RecurringRequest('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjMsImlhdCI6MTU3NjA3Mzc0MiwiZXhwIjoxNTc4NjY1NzQyfQ.45tr4BlNhzRQQc1nLw9C6kUqMpwS1WxdYptSIBmHtE4', false);

// Order ID
$response = $request->put(10407, json_encode($recurringStatus));

Gerando Boleto Bancario

Para criar um boleto é necessário preencher as informações obrigatorias descritas na documentação.

Seguindo a mesma ideia de transação é necessário instanciar os models de boleto, sendo esses Customer, Billing, BankSlip, Payment, BankSLipTransaction, BankSlipRequest.
Para enviar o boleto bancario é necessário instanciar BankSlipTransaction onde o token JWT deve ser passado como parâmetro.

    $billing = new Billing();
    
    $billing->setName('SoulPay');
    $billing->setAddress('Avenida Paulista');
    $billing->setAddress2('124');
    $billing->setDistrict('Bela vista');
    $billing->setCity('São Paulo');
    $billing->setState('SP');
    $billing->setPostalCode('01311000');
    $billing->setCountry('BR');
    $billing->setPhone('111112222233333');
    $billing->setEmail('billing@soulpay.com.br');

    $customer = new Customer();

    $customer->setName('Cliente');
    $customer->setTaxId('12234554323');

    $bankSlip = new BankSlip();

    $bankSlip->setExpirationDate('2022-12-25');
    $bankSlip->setInstructions('teste API');

    $payment = new Payment();
    
    $payment->setChargeTotal(10.5);
    $payment->setCurrencyCode('BRL');

    $bankSlipTransaction = new BankSlipTransaction();

    $bankSlipTransaction->setReferenceNum('123456');
    $bankSlipTransaction->setCustomer($customer);
    $bankSlipTransaction->setBilling($billing);
    $bankSlipTransaction->setBankSlip($bankSlip);
    $bankSlipTransaction->setPayment($payment);


  // Passar o token JWT aqui.
    $bankSlipRequest = new BankSlipRequest('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjMsImlhdCI6MTU3NjA3Mzc0MiwiZXhwIjoxNTc4NjY1NzQyfQ.45tr4BlNhzRQQc1nLw9C6kUqMpwS1WxdYptSIBmHtE4', false);
    
$response = $bankSlipRequest->send(json_encode($bankSlipTransaction))

Consulta de transações

Para consultar uma transação, é necessário instanciar a classe CreditCardRequest. O Order ID deve ser passado como parâmetro de busca.

// Passar o token JWT aqui.
$request = new CreditCardRequest('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjEsImlhdCI6MTU3NTkwMzEyOSwiZXhwIjoxNTc4NDk1MTI5fQ.c0g6ynTtZHFSU3qh4bJWy-jea0VnKE4hGBTAs_uhNjY', false);

// Order ID
$response = $request->get(253);

Consulta de boletos

Para consultar um boleto, é necessário instanciar a classe BankSlipRequest. O Order ID deve ser passado como parâmetro de busca.

// Passar o token JWT aqui.
$request = new BankSlipRequest('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjMsImlhdCI6MTU3NjA3Mzc0MiwiZXhwIjoxNTc4NjY1NzQyfQ.45tr4BlNhzRQQc1nLw9C6kUqMpwS1WxdYptSIBmHtE4', false);

// Order ID
$response = $request->get(253);

Consulta de recorrências

Para consultar uma recorrência, é necessário instanciar a classe RecurringRequest. O Order ID deve ser passado como parâmetro de busca.

// Passar o token JWT aqui.
$request = new RecurringRequest('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjMsImlhdCI6MTU3NjA3Mzc0MiwiZXhwIjoxNTc4NjY1NzQyfQ.45tr4BlNhzRQQc1nLw9C6kUqMpwS1WxdYptSIBmHtE4', false);

// Order ID
$response = $request->get(253);

Suporte

Utilizar o issues do github

soulpay/soulpay-sdk 适用场景与选型建议

soulpay/soulpay-sdk 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 15 次下载、GitHub Stars 达 0，最近一次更新时间为 2020 年 01 月 07 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「php」「api」「sdk」「php-sdk」「soulpay」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 soulpay/soulpay-sdk 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 soulpay/soulpay-sdk 我们能提供哪些服务？

定制开发 / 二次开发

基于 soulpay/soulpay-sdk 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 soulpay/soulpay-sdk 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

theodorejb/phaster 6

A PSR-7 compatible library for making CRUD API endpoints

foxtes/alfabank-rest 1

Alfabank REST API integration

cboxdk/dns 0

Zero-dependency raw PHP DNS resolver, domain-ownership verification, and intoDNS/MxToolbox-style diagnostics. Queries authoritative nameservers directly over sockets — never trusts the recursive cache for ownership checks.

fredoware/fredobase 0

A lightweight plain-PHP framework for database-backed CRUD APIs.

bughq/bughq 0

bughq error tracking - PHP SDK

absurge/php 0

ABsurge PHP SDK for feature flags and A/B testing

soulpay/soulpay-sdk

包简介

关键字：