Skip to content

Improve documentation and add Redsys InSite payment method documentation #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

Improve documentation and add Redsys InSite payment method documentation #18

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
217237c
Initial plan
Copilot Oct 5, 2025
3a2ee08
Add comprehensive documentation with InSite payment method
Copilot Oct 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
282 changes: 265 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,64 @@
# Redsys

A PHP package to platform Redsys
A PHP package for Redsys payment gateway integration

[![tests](https://github.com/descom-es/redsys/actions/workflows/test.yml/badge.svg)](https://github.com/descom-es/redsys/actions/workflows/test.yml)
[![analyse](https://github.com/descom-es/redsys/actions/workflows/analyse.yml/badge.svg)](https://github.com/descom-es/redsys/actions/workflows/analyse.yml)
[![Fix Styles](https://github.com/descom-es/redsys/actions/workflows/fix_style.yml/badge.svg)](https://github.com/descom-es/redsys/actions/workflows/fix_style.yml)

## Install
## Table of Contents

Via Composer
- [Installation](#installation)
- [Configuration](#configuration)
- [Payment Methods](#payment-methods)
- [Redirect Payment](#redirect-payment)
- [InSite Payment (EMV 3DS)](#insite-payment-emv-3ds)
- [Response Object](#response-object)
- [Testing](#testing)

## Installation

Install via Composer:

```bash
composer require descom/redsys
```

## Usage
## Configuration

The package supports both sandbox and production environments:

### Sandbox Environment

```php
use Descom\Redsys\Redsys;

$redsys = Redsys::sandbox([
'code' => 999008881,
'terminal' => 1,
'signatureKey' => 'sq7HjrUOBfKmC576ILgskD5srU870gJ7',
]);
```

### Production Environment

### Generate Redirect From to payment
```php
use Descom\Redsys\Redsys;

$redsys = Redsys::production([
'code' => YOUR_MERCHANT_CODE,
'terminal' => YOUR_TERMINAL,
'signatureKey' => 'YOUR_SIGNATURE_KEY',
]);
```

## Payment Methods

### Redirect Payment

Traditional payment flow where the user is redirected to Redsys payment page.

#### Generate Redirect Payment

```php
use Descom\Redsys\Redsys;
Expand All @@ -30,18 +72,28 @@ $redsys = Redsys::sandbox([
$orderId = '123456';
$amount = 12.05;


echo $redsys
->redirect()
->generateRedirectPayment($orderId, $amount, 'http://localhost:8000')
// ->description('description about the order products') optional DS_MERCHANT_PRODUCTDESCRIPTION
// ->merchantName('rename merchant name') optional DS_MERCHANT_MERCHANTNAME
// ->data('internal data, to read in response') optional DS_MERCHANT_MERCHANTDATA
// ->merchantPaymethods('z') // optional payment with Bizum
->generateRedirectPayment($orderId, $amount, 'http://localhost:8000/payment-notification')
->description('Order #123456 - Product description') // optional
->merchantName('My Store') // optional
->data('internal-order-reference') // optional
->merchantPaymethods('z') // optional - 'z' for Bizum
->redirect();
```

### Capture payment notification
#### Optional Parameters

- `description($text)` - Product or order description (DS_MERCHANT_PRODUCTDESCRIPTION)
- `merchantName($name)` - Custom merchant name (DS_MERCHANT_MERCHANTNAME)
- `data($data)` - Internal data to be returned in the response (DS_MERCHANT_MERCHANTDATA)
- `merchantPaymethods($methods)` - Payment method filter (e.g., 'z' for Bizum)
- `urlSuccessful($url)` - Custom success URL (DS_MERCHANT_URLOK)
- `urlDenied($url)` - Custom denied URL (DS_MERCHANT_URLKO)

#### Capture Payment Notification

Process the payment notification received from Redsys:

```php
use Descom\Redsys\Redsys;
Expand All @@ -54,24 +106,220 @@ $redsys = Redsys::sandbox([

$response = $redsys->redirect()->capturePaymentNotification($_POST);

if (! $response->successful()) {
if (!$response->successful()) {
$orderId = $response->orderId;
$errorCode = $response->errorCode;
$responseCode = $response->responseCode;
// $responseData = $response->toArray();

throw new \Exception("Error processing payment [$orderId] [$errorCode]", $responseCode);
throw new \Exception("Error processing payment [$orderId] [$errorCode]", $responseCode);
}

// Payment successful
$orderId = $response->orderId;
$authorizationCode = $response->authorizationCode;
$amount = $response->amount;
$data = $response->data; // Internal data sent in the request
```

### InSite Payment (EMV 3DS)

//
InSite payment allows processing payments directly on your website with EMV 3-D Secure authentication.

The InSite payment flow consists of three steps:

1. **Card Configuration** - Initialize 3DS authentication
2. **Process Payment** - Send authentication data and process the payment
3. **Capture Payment** - Complete the payment if challenge is required

#### Step 1: Card Configuration

Obtain the 3DS configuration for the card:

```php
use Descom\Redsys\Redsys;

$redsys = Redsys::sandbox([
'code' => 999008881,
'terminal' => 1,
'signatureKey' => 'sq7HjrUOBfKmC576ILgskD5srU870gJ7',
]);

$orderId = '123456';
$amount = 12.05;
$cardToken = 'CARD_TOKEN_FROM_REDSYS'; // Token obtained from Redsys card tokenization
$urlNotification = 'https://yoursite.com/payment-notification';

$config = $redsys->inSite()->cardConfiguration($orderId, $amount, $cardToken, $urlNotification);

// Response contains:
// $config['em3dSecure']['version'] - Protocol version
// $config['em3dSecure']['transId'] - Transaction ID
// $config['em3dSecure']['url'] - 3DS Method URL (optional)
// $config['iframe']['src'] - iframe HTML to embed (optional, if url exists)
```

If `$config['iframe']` exists, render the iframe in your page to complete the 3DS method data collection.

#### Step 2: Process Payment

Process the payment with authentication data:

```php
use Descom\Redsys\Redsys;
use Illuminate\Http\Request; // Optional, for browser data collection

$redsys = Redsys::sandbox([
'code' => 999008881,
'terminal' => 1,
'signatureKey' => 'sq7HjrUOBfKmC576ILgskD5srU870gJ7',
]);

$orderId = '123456';
$amount = 12.05;
$cardToken = 'CARD_TOKEN_FROM_REDSYS';
$urlNotification = 'https://yoursite.com/payment-notification';

// Browser screen information (collect from JavaScript)
$screen = [
'width' => 1920,
'height' => 1080,
'colorDepth' => 24,
];

// 3DS configuration from step 1
$em3dSecure = [
'version' => $config['em3dSecure']['version'],
'transId' => $config['em3dSecure']['transId'],
'url' => $config['em3dSecure']['url'] ?? null,
];

$request = Request::capture(); // Optional Laravel request for browser headers

$response = $redsys->inSite()->process(
$orderId,
$amount,
$cardToken,
$urlNotification,
$screen,
$em3dSecure,
$request // optional
);

if ($response->required3DsChallenger()) {
// Challenge required - proceed to step 3
$emv3ds = $response->emv3ds;

// Render challenge iframe:
// <iframe name="challengeIframe"
// src="{$emv3ds['acsURL']}"
// width="100%"
// height="400">
// </iframe>
//
// <form id="challengeForm" method="POST" action="{$emv3ds['acsURL']}" target="challengeIframe">
// <input type="hidden" name="creq" value="{$emv3ds['creq']}" />
// </form>

} elseif ($response->successful()) {
// Payment completed successfully
$orderId = $response->orderId;
$authorizationCode = $response->authorizationCode;
$amount = $response->amount;
} else {
// Payment failed
$errorCode = $response->errorCode;
$responseCode = $response->responseCode;
}
```

#### Step 3: Capture Payment (if challenge required)

If the payment requires a challenge, capture the payment after the user completes it:

```php
use Descom\Redsys\Redsys;

$redsys = Redsys::sandbox([
'code' => 999008881,
'terminal' => 1,
'signatureKey' => 'sq7HjrUOBfKmC576ILgskD5srU870gJ7',
]);

$orderId = '123456';
$amount = 12.05;
$cardToken = 'CARD_TOKEN_FROM_REDSYS';
$version = $emv3ds['protocolVersion']; // From step 2 response
$cres = $_POST['cres']; // Challenge response from the iframe form submission

$response = $redsys->inSite()->capture($orderId, $amount, $cardToken, $version, $cres);

if ($response->successful()) {
// Payment completed successfully
$orderId = $response->orderId;
$authorizationCode = $response->authorizationCode;
$amount = $response->amount;
} else {
// Payment failed
$errorCode = $response->errorCode;
$responseCode = $response->responseCode;
}
```

## Response Object

The `Response` object provides convenient access to payment information:

### Properties

- `$response->orderId` - Order identifier
- `$response->amount` - Payment amount (as float)
- `$response->authorizationCode` - Authorization code (if successful)
- `$response->errorCode` - Error code (if failed)
- `$response->responseCode` - Response code from Redsys
- `$response->data` - Custom data sent in the request
- `$response->emv3ds` - EMV 3DS information (for InSite payments)

### Methods

- `$response->successful()` - Check if payment was successful
- `$response->required3DsChallenger()` - Check if 3DS challenge is required (InSite payments)
- `$response->secure()` - Check if payment was processed with secure payment
- `$response->toArray()` - Get all response parameters as an array

### Example

```php
$response = $redsys->redirect()->capturePaymentNotification($_POST);

if ($response->successful()) {
echo "Payment successful!";
echo "Order: " . $response->orderId;
echo "Amount: " . $response->amount;
echo "Authorization: " . $response->authorizationCode;
echo "Secure payment: " . ($response->secure() ? 'Yes' : 'No');
} else {
echo "Payment failed!";
echo "Error: " . $response->errorCode;
echo "Response code: " . $response->responseCode;
}
```

## Testing

``` bash
Run the test suite:

```bash
composer test
```

Run static analysis:

```bash
composer analyse
```

Fix code style:

```bash
composer style
```