PHP

SDK oficial PHP para o gateway de pagamento Cost+. Simplifica o fluxo de redirecionamento HPP (Página de Pagamento Alojada), assinatura de payloads HMAC e verificação de webhooks.

Funcionalidades

Zero dependências externas — utiliza apenas extensões PHP nativas (curl, json, hash)
PHP 8.1+ com propriedades readonly, argumentos nomeados e tipos estritos
Geração de assinaturas HMAC-SHA256 e verificação em tempo constante via hash_equals
Mapeamento automático snake_case/camelCase entre a API e o SDK
Análise de webhooks + verificação de encomendas baseada na API
Testado com PHP 8.1, 8.2 e 8.3

Requisitos

PHP 8.1 ou superior
Extensões: curl, json (ambas incluídas no PHP padrão)
Uma conta de comerciante Cost+ — dashboard.costplus.io

Instalação

composer require nopayn/sdk

Início Rápido

1. Inicializar o Cliente

use NoPayn\NoPaynClient;

$nopayn = new NoPaynClient([
    'apiKey'     => 'your-api-key',
    'merchantId' => 'your-project',
]);

2. Criar um Pagamento e Redirecionar para o HPP

$result = $nopayn->generatePaymentUrl([
    'amount'           => 1295,            // €12.95 in cents
    'currency'         => 'EUR',
    'merchantOrderId'  => 'ORDER-001',
    'description'      => 'Premium Widget',
    'returnUrl'        => 'https://shop.example.com/success',
    'failureUrl'       => 'https://shop.example.com/failure',
    'webhookUrl'       => 'https://shop.example.com/webhook',
    'locale'           => 'en-GB',
    'expirationPeriod' => 'PT30M',
]);

// Redirect the customer
// $result['orderUrl']   → HPP (customer picks payment method)
// $result['paymentUrl'] → direct link to the first transaction's payment method
// $result['signature']  → HMAC-SHA256 for verification
// $result['orderId']    → NoPayn order UUID
header('Location: ' . ($result['paymentUrl'] ?? $result['orderUrl']));

3. Tratar o Webhook

$rawBody  = file_get_contents('php://input');
$verified = $nopayn->verifyWebhook($rawBody);

echo $verified['order']['status']; // 'completed', 'cancelled', etc.
echo $verified['isFinal'];        // true when the order won't change

if ($verified['order']['status'] === 'completed') {
    // Fulfil the order
}

http_response_code(200);

Referência da API

`new NoPaynClient(array $config)`

Parâmetro	Tipo	Obrigatório	Predefinição
`apiKey`	`string`	Sim	—
`merchantId`	`string`	Sim	—
`baseUrl`	`string`	Não	`https://api.nopayn.co.uk`

`$client->createOrder(array $params): array`

Cria uma encomenda via POST /v1/orders/.

Parâmetro	Tipo	Obrigatório	Descrição
`amount`	`int`	Sim	Montante na menor unidade monetária (cêntimos)
`currency`	`string`	Sim	Código ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`string`	Não	A sua referência interna da encomenda
`description`	`string`	Não	Descrição da encomenda
`returnUrl`	`string`	Não	Redirecionamento após pagamento bem-sucedido
`failureUrl`	`string`	Não	Redirecionamento em cancelamento/expiração/erro
`webhookUrl`	`string`	Não	Notificações assíncronas de alteração de estado
`locale`	`string`	Não	Idioma do HPP (`en-GB`, `de-DE`, `nl-NL`, etc.)
`paymentMethods`	`string[]`	Não	Filtrar métodos do HPP
`expirationPeriod`	`string`	Não	Duração ISO 8601 (`PT30M`)

Métodos de pagamento disponíveis: credit-card, apple-pay, google-pay, vipps-mobilepay

`$client->getOrder(string $orderId): array`

Obtém detalhes da encomenda via GET /v1/orders/{id}/.

`$client->createRefund(string $orderId, int $amount, ?string $description = null): array`

Emite um reembolso total ou parcial via POST /v1/orders/{id}/refunds/.

`$client->generatePaymentUrl(array $params): array`

Método de conveniência que cria uma encomenda e devolve:

[
    'orderId'    => string,   // NoPayn order UUID
    'orderUrl'   => string,   // HPP URL
    'paymentUrl' => ?string,  // Direct payment URL (first transaction)
    'signature'  => string,   // HMAC-SHA256 of amount:currency:orderId
    'order'      => array,    // Full order object
]

`$client->generateSignature(int $amount, string $currency, string $orderId): string`

Gera uma assinatura HMAC-SHA256 em hexadecimal.

`$client->verifySignature(int $amount, string $currency, string $orderId, string $signature): bool`

Verificação em tempo constante de uma assinatura HMAC-SHA256.

`$client->verifyWebhook(string $rawBody): array`

Analisa o corpo do webhook, depois chama GET /v1/orders/{id}/ para verificar o estado real.

Utilitários HMAC Autónomos

use NoPayn\Signature;

$sig = Signature::generate('your-api-key', 1295, 'EUR', 'order-uuid');
$ok  = Signature::verify('your-api-key', 1295, 'EUR', 'order-uuid', $sig);

Tratamento de Erros

use NoPayn\Exceptions\ApiException;
use NoPayn\Exceptions\NoPaynException;
use NoPayn\Exceptions\WebhookException;

try {
    $nopayn->createOrder(['amount' => 100, 'currency' => 'EUR']);
} catch (ApiException $e) {
    echo $e->getStatusCode(); // 401, 400, etc.
    print_r($e->getErrorBody()); // Raw API error response
} catch (NoPaynException $e) {
    echo $e->getMessage(); // Network or parsing error
}

Estados da Encomenda

Estado	Final?	Descrição
`new`	Não	Encomenda criada
`processing`	Não	Pagamento em curso
`completed`	Sim	Pagamento bem-sucedido — entregue a mercadoria
`cancelled`	Sim	Pagamento cancelado pelo cliente
`expired`	Sim	Link de pagamento expirou
`error`	Sim	Falha técnica

Boas Práticas para Webhooks

Verifique sempre através da API — o payload do webhook contém apenas o ID da encomenda, nunca o estado. O verifyWebhook() do SDK faz isto automaticamente.
Devolva HTTP 200 para confirmar a receção. Qualquer outro código desencadeia até 10 tentativas (com 2 minutos de intervalo).
Implemente um poller de backup — para encomendas com mais de 10 minutos que não atingiram um estado final, consulte getOrder() como rede de segurança.
Seja idempotente — pode receber o mesmo webhook várias vezes.

Cartões de Teste

Utilize estes cartões no modo de teste da Cost+ (website sandbox):

Cartão	Número	Notas
Visa (sucesso)	`4111 1111 1111 1111`	Qualquer CVV
Mastercard (sucesso)	`5544 3300 0003 7`	Qualquer CVV
Visa (recusado)	`4111 1111 1111 1105`	Do Not Honor
Visa (fundos insuficientes)	`4111 1111 1111 1151`	Insufficient Funds

Utilize qualquer data de validade futura e qualquer CVC de 3 dígitos.

Aplicação de Demonstração

Uma aplicação de demonstração baseada em Docker está incluída no repositório GitHub para testar o fluxo completo de pagamento.

Suporte

Precisa de ajuda? Contacte a nossa equipa de suporte em support@costplus.io.

On this page