PayZen REST API

https://payzen.io/fr-FR/rest/V4.0/api/
Admin
PayZen REST API allows merchants to securely process online payments, manage transactions, handle...
Tokens:477,572
Snippets:3,002
Trust Score:8.2
Update:3 days ago
Show doc for...
Tokens:
Raw
### POST /api-payment/V4/Charge/CreateQRCode

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb/create_qr_flow.html

Creates a QR code for the Instore mode, displaying a payment method on a terminal. This example uses Alma in 4 installments.

```APIDOC
## POST /api-payment/V4/Charge/CreateQRCode

### Description
Creates a QR code for the Instore mode, displaying a payment method on a terminal. This example uses Alma in 4 installments.

### Method
POST

### Endpoint
https://api.payzen.eu/api-payment/V4/Charge/CreateQRCode

### Headers
- **Authorization**: Njk4NzYzNTc6dGVzdHBhc3N3b3JkX0RFTU9QUklWQVRFS0VZMjNHNDQ3NXpYWlEyVUE1eDdN
- **Content-Type**: application/json

### Request Body
- **amount** (integer) - Required - The amount in the smallest currency unit (e.g., cents).
- **currency** (string) - Required - The currency code (e.g., EUR).
- **customer.email** (string) - Recommended - The buyer's email address.
- **paymentMethodType** (string) - Required - The payment method name (e.g., ALMA_4X).
- **transactionOptions.paymentMethodOptions.paymentSource** (string) - Required - The payment origin, must be INSTORE.
- **transactionOptions.paymentMethodOptions.deviceSerialNumber** (string) - Recommended - The serial number of the terminal.

### Request Example
```json
{
  "amount": 10000,
  "currency": "EUR",
  "customer": {
    "email": "sample@example.com"
  },
  "paymentMethodType": "ALMA_4X",
  "transactionOptions": {
    "paymentMethodOptions": {
      "paymentSource": "INSTORE",
      "deviceSerialNumber": "123456"
    }
  }
}
```

### Response
No response schema is provided in the source documentation.
```

--------------------------------

### PCI/Charge/Authenticate Response Example

Source: https://payzen.io/fr-FR/rest/V4.0/api/authenticate/integration_guide.html

A sample JSON response from the PCI/Charge/Authenticate service indicating a failed authentication result.

```json
{
 "webService":"PCI/Charge/Authenticate",
 "version":"V4",
 "applicationVersion":"5.23.0",
 "serverDate":"2021-05-05T12:03:24+00:00",
 "ticket":"9dbbe165313c49fb8fd000498a2dfa7c",
 "applicationProvider":"PAYZEN",
 "metadata":null,
 "status":"SUCCESS",
 "mode":"TEST",
 "serverUrl":"https://api.payzen.eu",
 "_type":"V4/WebService/Response",
 "answer":{
  "id":"3b25e3ed-5d48-4f99-af61-0d5db9e3b18e",
  "protocol":{
   "name":"THREEDS",
   "version":"2.1.0",
   "network":"VISA",
   "challengePreference":"NO_PREFERENCE",
   "simulation":true,
   "_type":"V4/Charge/Authenticate/Protocol"
  },
  "value":{
   "authenticationType":"CHALLENGE",
   "authenticationId":{
    "authenticationIdType":"dsTransId",
    "value":"e8286d62-006e-413e-ad3b-328503b14e71",
    "_type":"V4/Charge/Authenticate/AuthenticationId"
   },
   "status":"FAILED",
   "extension":{
    "authenticationType":"THREEDS_V2",
    "threeDSServerTransID":"3b25e3ed-5d48-4f99-af61-0d5db9e3b18e",
    "dsTransID":"e8286d62-006e-413e-ad3b-328503b14e71",
    "acsTransID":"54feb2ac-9666-4ce3-86e5-d8f947cebd87",
    "transStatus": "NOT_AUTHENTICATED",
    "transStatusReason":"01",
    "_type":"V4/Charge/Authenticate/AuthenticationResultExtensionThreedsV2"
   },
   "reason":{
    "code":"CARD_AUTHENTICATION_FAILED",
    "_type":"V4/Charge/Authenticate/AuthenticationResultReason"
   },
   "_type":"V4/Charge/Authenticate/AuthenticationResult"
  },
  "_type":"V4/AuthenticationResponseData"
 }
}
```

--------------------------------

### Exemple PHP avec SDK Lyra pour créer un paiement

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb/cancel_payment_order.html

Exemple PHP utilisant le SDK Lyra pour initialiser le client, créer un paiement avec V4/Charge/CreatePayment et extraire le formToken. Ce code est présenté comme exemple pour la page d'annulation, bien qu'il crée un paiement.

```PHP
/**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * I create a formToken
 */
$store = array("amount" => 250, 
"currency" => "EUR", 
"orderId" => uniqid("MyOrderId"),
"customer" => array(
  "email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];

?>
```

--------------------------------

### Initialisation du SDK PHP et création de paiement

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb_n_fois/whatsapp_payment_order.html

Exemple PHP pour initialiser le SDK Lyra, créer un paiement via V4/Charge/CreatePayment et récupérer le formToken. Nécessite les fichiers vendor/autoload.php, keys.php et helpers.php.

```php
/**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * I create a formToken
 */
$store = array("amount" => 250, 
"currency" => "EUR", 
"orderId" => uniqid("MyOrderId"),
"customer" => array(
  "email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];

?>

```

--------------------------------

### POST /api-payment/V4/Charge/CreatePaymentFlow

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb/create_qr_flow.html

Creates a payment flow for the Instore mode, displaying a QR code on a payment terminal. This example uses Alma in 3 installments.

```APIDOC
## POST /api-payment/V4/Charge/CreatePaymentFlow

### Description
Creates a payment flow for the Instore mode, displaying a QR code on a payment terminal. This example uses Alma in 3 installments.

### Method
POST

### Endpoint
https://api.payzen.eu/api-payment/V4/Charge/CreatePaymentFlow

### Headers
- **Authorization**: Njk4NzYzNTc6dGVzdHBhc3N3b3JkX0RFTU9QUklWQVRFS0VZMjNHNDQ3NXpYWlEyVUE1eDdN
- **Content-Type**: application/json

### Request Body
- **amount** (integer) - Required - The amount in the smallest currency unit (e.g., cents).
- **currency** (string) - Required - The currency code (e.g., EUR).
- **paymentMethodType** (string) - Required - The payment method name (e.g., ALMA_3X).
- **customer.email** (string) - Recommended - The buyer's email address.
- **transactionOptions.paymentMethodOptions.paymentSource** (string) - Required - The payment origin, must be INSTORE.
- **transactionOptions.paymentMethodOptions.deviceSerialNumber** (string) - Recommended - The serial number of the terminal.

### Request Example
```json
{
  "amount": 10000,
  "currency": "EUR",
  "paymentMethodType": "ALMA_3X",
  "customer": {
    "email": "sample@example.com"
  },
  "transactionOptions": {
    "paymentMethodOptions": {
      "paymentSource": "INSTORE",
      "deviceSerialNumber": "123456"
    }
  }
}
```

### Response
No response schema is provided in the source documentation.
```

--------------------------------

### JSON example for restrictedInstallments

Source: https://payzen.io/fr-FR/rest/V4.0/api/playground/Charge/CreateSubscription

Shows a JSON payment request with restrictedInstallments set to [2, 4, 5, 9] to restrict the installment options offered to the buyer. This field is specific to Latin America.

```JSON
{
  "amount": 10000,
  "currency": "EUR",
  "transactionOptions": {
    "cardOptions": {
      "restrictedInstallments": [
        2,
        4,
        5,
        9
      ]
    }
  },
  "customer": {
    "email": "sample@example.com"
  },
  "orderId": "myOrderId-1234"
}
```

--------------------------------

### PHP SDK: CreatePayment

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb_n_fois/url_payment_order.html

Example of using the PHP SDK to create a payment and retrieve a form token. It initializes the SDK, posts a payment request, and handles errors.

```APIDOC
## PHP SDK: CreatePayment

### Description
Example of using the PHP SDK to create a payment and retrieve a form token. It initializes the SDK, posts a payment request, and handles errors.

### Method
POST

### Endpoint
V4/Charge/CreatePayment

### Parameters
#### Request Body
- **amount** (integer) - Required - Amount in the smallest currency unit.
- **currency** (string) - Required - Currency code.
- **orderId** (string) - Required - Unique order identifier.
- **customer** (object) - Optional - Customer information.
  - **email** (string) - Required - Customer email.

### Request Example
{
  "amount": 250,
  "currency": "EUR",
  "orderId": "MyOrderId...",
  "customer": {
    "email": "sample@example.com"
  }
}

### Response
#### Success Response (200)
- **status** (string) - Status of the response (e.g., SUCCESS).
- **answer** (object) - Response data.
  - **formToken** (string) - Token for the payment form.

#### Response Example
{
  "status": "SUCCESS",
  "answer": {
    "formToken": "..."
  }
}

### Error Handling
- **errorCode** (string) - Error code.
- **errorMessage** (string) - Error message.

```

--------------------------------

### AuthenticationResponseData Example

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb/result_3DS_by_id.html

Example JSON response for the 3DS authentication result, showing the structure of the AuthenticationResponseData object.

```APIDOC
## AuthenticationResponseData

### Description
Object containing the result of a 3DS authentication, including identifiers, authentication values, status, protocol details, and reason codes.

### Fields
- **id** (string) - Unique authentication identifier (UUID).
- **operationSessionId** (string) - Unique authentication session identifier.
- **value.authenticationType** (string) - Type of authentication performed.
- **value.authenticationId.authenticationIdType** (string) - Field from dsTransId of 3DS V2 protocol.
- **value.authenticationId.value** (string) - Authentication transaction identifier known by the banking network.
- **value.authenticationValue.authenticationValueType** (string) - Type of authentication value.
- **value.authenticationValue.value** (string) - Final authentication value (CAVV, AEVV, or AAV), base64 encoded, 28 characters.
- **value.status** (string) - Authentication status (positive/negative result).
- **value.commerceIndicator** (string) - Commerce Indicator (ECI) returned by ACS.
- **value.reason.code** (string) - Additional code explaining the result origin (e.g., DS_TIMEOUT).
- **value.reason.message** (string) - Additional message explaining the result origin.
- **protocol.name** (string) - Cardholder authentication protocol name.
- **protocol.version** (string) - Protocol version.
- **protocol.network** (string) - Network on which the payment method was authenticated.
- **protocol.challengePreference** (string) - Indicates if merchant requests a challenge.
- **protocol.simulation** (boolean) - Indicates if authentication is in simulation mode.

### Example Response
```json
{
  "webService": "PCI/Authentication/GetResult",
  "applicationProvider": "PAYZEN",
  "metadata": null,
  "status": "SUCCESS",
  "mode": "TEST",
  "serverUrl": "https://api.payzen.eu",
  "_type": "V4/WebService/Response",
  "answer": {
    "id": "e1180f84-ed34-4511-b160-bd2a79c5823a",
    "protocol": {
      "name": "THREEDS",
      "version": "2.2.0",
      "network": "VISA",
      "challengePreference": "NO_PREFERENCE",
      "simulation": true,
      "_type": "V4/Charge/Authenticate/Protocol"
    },
    "value": {
      "authenticationType": "CHALLENGE",
      "authenticationId": {
        "authenticationIdType": "dsTransId",
        "value": "64305551-aaf8-4ed8-87f0-93edc79298fc",
        "_type": "V4/Charge/Authenticate/AuthenticationId"
      },
      "authenticationValue": {
        "authenticationValueType": "CAVV",
        "value": "u**************************=",
        "_type": "V4/Charge/Authenticate/AuthenticationValue"
      },
      "status": "SUCCESS",
      "commerceIndicator": "05",
      "extension": {
        "authenticationType": "THREEDS_V2",
        "threeDSServerTransID": "e1180f84-ed34-4511-b160-bd2a79c5823a",
        "dsTransID": "64305551-aaf8-4ed8-87f0-93edc79298fc",
        "acsTransID": "06729a8f-083e-4e77-8167-b9781797f778",
        "requestorName": "Company name",
        "_type": "V4/Charge/Authenticate/AuthenticationResultExtensionThreedsV2"
      },
      "reason": {
        "_type": "V4/Charge/Authenticate/AuthenticationResultReason"
      },
      "_type": "V4/Charge/Authenticate/AuthenticationResult"
    },
    "_type": "V4/AuthenticationResponseData"
  }
}
```
```

--------------------------------

### PHP SDK - Initialize and Create Payment Form Token

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb_n_fois/whatsapp_payment_order.html

Example of initializing the Lyra PHP SDK and creating a payment form token using the V4/Charge/CreatePayment endpoint.

```APIDOC
## PHP SDK - Initialize and Create Payment Form Token

### Description
Example of initializing the Lyra PHP SDK and creating a payment form token using the V4/Charge/CreatePayment endpoint.

### Method
POST

### Endpoint
V4/Charge/CreatePayment

### Parameters
#### Request Body
- **amount** (integer) - Required - The amount in the smallest currency unit.
- **currency** (string) - Required - The currency code.
- **orderId** (string) - Required - The unique order identifier.
- **customer** (object) - Optional - Customer information.
  - **email** (string) - Optional - Customer email.

### Request Example
$store = array("amount" => 250, 
"currency" => "EUR", 
"orderId" => uniqid("MyOrderId"),
"customer" => array(
  "email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);

### Response
#### Success Response (200)
- **status** (string) - The status of the response (e.g., SUCCESS).
- **answer** (object) - The response data.
  - **formToken** (string) - The form token used for payment.

#### Response Example
{
  "status": "SUCCESS",
  "answer": {
    "formToken": "abc123"
  }
}
```

--------------------------------

### POST /rest/V4.0/api/kb/authentication.html

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb_n_fois/mail_payment_order.html

Creates a payment order with a custom installment schedule using exact dates for each installment. The request must include the total amount, currency, order ID, channel type MAIL, recipient email, and installment schedules with dates and amounts.

```APIDOC
## POST /rest/V4.0/api/kb/authentication.html

### Description
Creates a payment order with a custom installment schedule using exact dates for each installment. The request must include the total amount, currency, order ID, channel type MAIL, recipient email, and installment schedules with dates and amounts.

### Method
POST

### Endpoint
https://api.payzen.eu/api-payment/V4/Charge/CreatePaymentOrder

### Parameters
#### Request Body
- **amount** (integer) - Required - Total amount in minor units (e.g., 10000 for 100.00 EUR)
- **currency** (string) - Required - Currency code (e.g., EUR)
- **orderId** (string) - Required - Order reference (e.g., myOrderId-1234)
- **channelOptions.channelType** (string) - Required - Channel type, must be MAIL
- **channelOptions.mailOptions.recipient** (string) - Required - Buyer email address
- **transactionOptions.installmentOptions.schedules** (array) - Required - List of installment schedules
  - **date** (string) - Required - Date of the installment in ISO 8601 format (e.g., 2023-04-01T23:59:59+00:00)
  - **amount** (integer) - Required - Amount of the installment in minor units

### Request Example
{
  "amount": 10000,
  "currency": "EUR",
  "orderId": "myOrderId-1234",
  "channelOptions": {
    "channelType": "MAIL",
    "mailOptions": {
      "recipient": "customer@example.com"
    }
  },
  "transactionOptions": {
    "installmentOptions": {
      "schedules": [
        {
          "date": "2023-04-01T23:59:59+00:00",
          "amount": 5000
        },
        {
          "date": "2023-05-01T23:59:59+00:00",
          "amount": 3000
        },
        {
          "date": "2023-06-01T23:59:59+00:00",
          "amount": 2000
        }
      ]
    }
  }
}

### Response
#### Success Response (200)
No response schema provided in the source.

### Error Handling
- The sum of all installment amounts must equal the total amount.
- The last installment date cannot be more than 12 months from the submission date.
- If the last installment date exceeds the card validity date, no installments will be recorded and the buyer will be notified.
```

--------------------------------

### Fonction createInstructionIframe JavaScript

Source: https://payzen.io/fr-FR/rest/V4.0/api/authenticate/integration_guide.html

Cette fonction initialise un conteneur, crée un iframe pour l'instruction, gère un timeout optionnel via postMessage, et soumet un formulaire masqué vers l'iframe.

```javascript
        function createInstructionIframe(instruction) {
    // Get instruction container element
    container = document.getElementById('instructionContainer');

    // Clean instruction container
    container.innerHTML = '';

    // Create iframe element
    var iframe = document.createElement('iframe');
    iframe.id = 'instructionIframe';
    iframe.name = 'instructionIframe';
    iframe.src = 'about:blank';
    iframe.style.width = instruction.value.target.width+"px";
    iframe.style.height = instruction.value.target.height+"px";
    iframe.style.visibility = instruction.value.target.visible ? 'visible' : 'hidden';

    // Handle timeout
    if(instruction.value.timeout){
        setTimeout(() => {
            const instructionResultTimeout = {
                eventName: 'LYRA_AUTH_INSTRUCTION_RESULT',
                value: {
                    name: instruction.value.name,
                    value: 'TIMEOUT',
                    protocol: {
                        name: instruction.protocol.name,
                        version: instruction.protocol.version,
                        network: instruction.protocol.network,
                        challengePreference: instruction.protocol.challengePreference,
                        simulation: instruction.protocol.simulation
                    },
                },
            };
            window.postMessage(JSON.stringify(instructionResultTimeout), '*');
        }, instruction.value.timeout * 1000);
    }

    // Add iframe to container
    container.appendChild(iframe);

    // Create form to post
    var form = document.createElement('form');
    form.id = 'instructionForm';
    form.name = 'instructionForm';
    form.target = 'instructionIframe';
    form.method = instruction.value.http.method;
    form.action = instruction.value.http.url;
    form.style = 'visibility: hidden';

    // Create form body
    Object.keys(instruction.value.http.body).forEach(function (name) {
        form.innerHTML += '<input name="' + name + '" value="' + instruction.value.http.body[name] + '">';
    });
    var body = document.createElement('form');

    // Add form to container
    container.appendChild(form);

    // Triger form submit
    form.submit();
}
```

```javascript
function createInstructionIframe(instruction) {
    // Get instruction container element
    container = document.getElementById('instructionContainer');

    // Clean instruction container
    container.innerHTML = '';

    // Create iframe element
    var iframe = document.createElement('iframe');
    iframe.id = 'instructionIframe';
    iframe.name = 'instructionIframe';
    iframe.src = 'about:blank';
    iframe.style.width = instruction.value.target.width+"px";
    iframe.style.height = instruction.value.target.height+"px";
    iframe.style.visibility = instruction.value.target.visible ? 'visible' : 'hidden';

    // Handle timeout
    if(instruction.value.timeout){
        setTimeout(() => {
            const instructionResultTimeout = {
                eventName: 'LYRA_AUTH_INSTRUCTION_RESULT',
                value: {
                    name: instruction.value.name,
                    value: 'TIMEOUT',
                    protocol: {
                        name: instruction.protocol.name,
                        version: instruction.protocol.version,
                        network: instruction.protocol.network,
                        challengePreference: instruction.protocol.challengePreference,
                        simulation: instruction.protocol.simulation
                    },
                },
            };
            window.postMessage(JSON.stringify(instructionResultTimeout), '*');
        }, instruction.value.timeout * 1000);
    }

    // Add iframe to container
    container.appendChild(iframe);

    // Create form to post
    var form = document.createElement('form');
    form.id = 'instructionForm';
    form.name = 'instructionForm';
    form.target = 'instructionIframe';
    form.method = instruction.value.http.method;
    form.action = instruction.value.http.url;
    form.style = 'visibility: hidden';

    // Create form body
    Object.keys(instruction.value.http.body).forEach(function (name) {
        form.innerHTML += '<input name="' + name + '" value="' + instruction.value.http.body[name] + '">';
    });
    var body = document.createElement('form');

    // Add form to container
    container.appendChild(form);

    // Triger form submit
    form.submit();
}
```

--------------------------------

### POST /api-payment/V4/Charge/CreatePayment (Multiple Installment Options)

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb/create_n_fois.html

Creates a payment with multiple installment options, allowing the buyer to choose between different payment plans (e.g., 2 or 3 times). The request body includes the total amount, currency, order ID, and an array of installment options.

```APIDOC
## POST /api-payment/V4/Charge/CreatePayment

### Description
Creates a payment with multiple installment options, allowing the buyer to choose between different payment plans (e.g., 2 or 3 times). The request body includes the total amount, currency, order ID, and an array of installment options.

### Method
POST

### Endpoint
https://api.payzen.eu/api-payment/V4/Charge/CreatePayment

### Headers
- **Authorization** (string) - Required - Authentication token.
- **Content-Type** (string) - Required - application/json

### Request Body
- **amount** (integer) - Required - Total amount in minor units (e.g., 10000 for 100.00 EUR).
- **currency** (string) - Required - Currency code (e.g., EUR).
- **orderId** (string) - Recommended - Order reference.
- **transactionOptions** (object) - Optional - Contains installment options.
  - **installmentOptions** (array) - Optional - List of installment plans.
    - **firstAmount** (integer) - Recommended - Amount of the first payment in minor units.
    - **count** (integer) - Required - Number of installments.
    - **period** (integer) - Required - Number of days between each installment.

### Request Example
{
  "amount": 10000,
  "currency": "EUR",
  "orderId": "myOrderId-1234",
  "transactionOptions": {
    "installmentOptions": [
      {
        "firstAmount": 5000,
        "count": 2,
        "period": 7
      },
      {
        "firstAmount": 5000,
        "count": 3,
        "period": 10
      }
    ]
  }
}

### Response
No response schema is provided in the source documentation.

```

--------------------------------

### Initialisation du SDK PHP

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb_n_fois/invoice_payment_order.html

Exemple d'initialisation du client SDK PHP et de création d'un formToken.

```php
/**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * I create a formToken
 */
$store = array("amount" => 250, 
"currency" => "EUR", 
"orderId" => uniqid("MyOrderId"),
"customer" => array(
  "email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];

?>
```

```php
/**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * I create a formToken
 */
$store = array("amount" => 250, 
"currency" => "EUR", 
"orderId" => uniqid("MyOrderId"),
"customer" => array(
  "email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];

?>
```

--------------------------------

### Initialisation et envoi de données avec le SDK PHP

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb/webservice_usage.html

Utilisation du client Lyra pour initialiser la connexion et envoyer des données de test vers le service V4/Charge/SDKTest.

```php
/** 
 * Initialize the SDK 
 * Please update your keys in keys.php
 */
$client = new Lyra\Client();  

/**
 * I send test data
 */
$store = array("value" => "my testing value");
$response = $client->post("V4/Charge/SDKTest", $store);
```

--------------------------------

### Create Shipment Transaction Response Example

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb/create_shipment.html

Example JSON response for a successful Charge/CreateShipmentTransaction request. The status PAID indicates the transaction was accepted.

```json
           
      {
        "webService": "Charge/CreateShipmentTransaction",
        "version": "V4",
        "applicationVersion": "6.12.0",
        "status": "SUCCESS",
        "answer": {
          "shopId": "12345678",
          "uuid": "7b8179b7845e4576868d624039b754c5",
          "paymentMethodType": "CARD",
          "paymentMethodToken": null,
          "detailedStatus": "AUTHORISED",
          "status": "PAID",
          "amount": 3500,
          "currency": "EUR",
              (...)   
    "_type": "V4/WebService/Response" 
}

}
```

```json
   
      {
        "webService": "Charge/CreateShipmentTransaction",
        "version": "V4",
        "applicationVersion": "6.12.0",
        "status": "SUCCESS",
        "answer": {
          "shopId": "12345678",
          "uuid": "7b8179b7845e4576868d624039b754c5",
          "paymentMethodType": "CARD",
          "paymentMethodToken": null,
          "detailedStatus": "AUTHORISED",
          "status": "PAID",
          "amount": 3500,
          "currency": "EUR",
              (...)   
    "_type": "V4/WebService/Response" 
}

}
```

--------------------------------

### POST V4/Charge/CreatePayment (PHP SDK)

Source: https://payzen.io/fr-FR/rest/V4.0/api/authenticate/integration_guide.html

This PHP SDK example demonstrates how to create a payment form token using the Lyra client. It initializes the SDK, sends a request to create a payment, and extracts the form token from the response.

```APIDOC
## POST V4/Charge/CreatePayment (PHP SDK)

### Description
Creates a payment form token using the Lyra PHP SDK.

### Method
POST

### Endpoint
V4/Charge/CreatePayment

### Parameters
#### Request Body
- **amount** (integer) - Required - Transaction amount in minor units.
- **currency** (string) - Required - Currency code (e.g., EUR).
- **orderId** (string) - Required - Unique order identifier.
- **customer** (object) - Required - Customer information.
  - **email** (string) - Required - Customer email.

### Request Example
```php
$store = array(
  "amount" => 250,
  "currency" => "EUR",
  "orderId" => uniqid("MyOrderId"),
  "customer" => array(
    "email" => "sample@example.com"
  )
);
$response = $client->post("V4/Charge/CreatePayment", $store);
```

### Response
#### Success Response (200)
- **status** (string) - Status of the response (e.g., SUCCESS).
- **answer** (object) - Response data.
  - **formToken** (string) - The form token to be used for payment.
  - **errorCode** (string) - Error code if status is not SUCCESS.
  - **errorMessage** (string) - Error message if status is not SUCCESS.

#### Response Example
No explicit response example provided in the source.
```

--------------------------------

### Create Shipment Transaction Response Example 2

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb/create_shipment.html

Example JSON response for a successful shipment transaction with an amount of 2500. The status PAID confirms acceptance.

```json
           
      {
        "webService": "Charge/CreateShipmentTransaction",
        "version": "V4",
        "applicationVersion": "6.12.0",
        "status": "SUCCESS",
        "answer": {
          "shopId": "12345678",
          "uuid": "7b8179b7845e4576868d624039b754c5",
          "paymentMethodType": "CARD",
          "paymentMethodToken": null,
          "detailedStatus": "AUTHORISED",
          "status": "PAID",
          "amount": 2500,
          "currency": "EUR",
              (...)   
    "_type": "V4/WebService/Response" 
}

}
```

```json
   
      {
        "webService": "Charge/CreateShipmentTransaction",
        "version": "V4",
        "applicationVersion": "6.12.0",
        "status": "SUCCESS",
        "answer": {
          "shopId": "12345678",
          "uuid": "7b8179b7845e4576868d624039b754c5",
          "paymentMethodType": "CARD",
          "paymentMethodToken": null,
          "detailedStatus": "AUTHORISED",
          "status": "PAID",
          "amount": 2500,
          "currency": "EUR",
              (...)   
    "_type": "V4/WebService/Response" 
}

}
```

--------------------------------

### POST /api-payment/V4/Charge/CreatePaymentOrder

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb_n_fois/mail_payment_order.html

Creates a payment order with installment options. Supports standard installment rules (first amount, count, period) and custom schedules with specific dates and amounts.

```APIDOC
## POST /api-payment/V4/Charge/CreatePaymentOrder

### Description
Creates a payment order with installment options. Supports standard installment rules (first amount, count, period) and custom schedules with specific dates and amounts.

### Method
POST

### Endpoint
https://api.payzen.eu/api-payment/V4/Charge/CreatePaymentOrder

### Parameters
#### Headers
- **Authorization** (string) - Required - Authentication token.
- **Content-Type** (string) - Required - Must be application/json.

#### Request Body
- **amount** (integer) - Required - Total amount in minor units (e.g., 10000 for 100.00 EUR).
- **currency** (string) - Required - Currency code (e.g., EUR).
- **orderId** (string) - Optional - Order reference.
- **channelOptions** (object) - Required - Channel configuration.
  - **channelType** (string) - Required - Must be MAIL.
  - **mailOptions** (object) - Required - Mail options.
    - **recipient** (string) - Required - Buyer email address.
- **transactionOptions** (object) - Required - Transaction options.
  - **installmentOptions** (object) - Required - Installment configuration.
    - **firstAmount** (integer) - Optional - Amount of first payment in minor units (for standard rule).
    - **count** (integer) - Optional - Number of installments (for standard rule).
    - **period** (integer) - Optional - Days between installments (for standard rule).
    - **schedules** (array) - Optional - Custom schedule list.
      - **date** (string) - Required - Payment date in ISO 8601 format.
      - **amount** (integer) - Required - Payment amount in minor units.

### Request Example
{
  "amount": 10000,
  "currency": "EUR",
  "orderId": "myOrderId-1234",
  "channelOptions": {
    "channelType": "MAIL",
    "mailOptions": {
      "recipient": "customer@example.com"
    }
  },
  "transactionOptions": {
    "installmentOptions": {
      "firstAmount": 5000,
      "count": 3,
      "period": 7
    }
  }
}

### Response
#### Success Response (200)
No response schema provided in the source.

### Notes
- The sum of all installment amounts must equal the total amount.
- The last installment date cannot exceed 12 months from the submission date.
- If the last installment date exceeds the card validity date, no installments will be recorded and the buyer will be notified.

### Custom Schedule Example
{
  "amount": 10000,
  "currency": "EUR",
  "orderId": "myOrderId-1234",
  "channelOptions": {
    "channelType": "MAIL",
    "mailOptions": {
      "recipient": "customer@example.com"
    }
  },
  "transactionOptions": {
    "installmentOptions": {
      "schedules": [
        {
          "date": "2023-04-01T23:59:59+00:00",
          "amount": 5000
        },
        {
          "date": "2023-05-01T23:59:59+00:00",
          "amount": 3000
        },
        {
          "date": "2023-06-01T23:59:59+00:00",
          "amount": 2000
        }
      ]
    }
  }
}
```

--------------------------------

### PHP SDK - Exemple de modification de lien de paiement

Source: https://payzen.io/fr-FR/rest/V4.0/api/kb/update_payment_order.html

Exemple d'utilisation du SDK PHP Lyra pour initialiser le client et créer un paiement, illustrant le pattern d'appel au Web Service. Note : l'exemple fourni utilise Charge/CreatePayment, mais le même pattern s'applique à PaymentOrder/Update.

```APIDOC
## PHP SDK - Exemple de modification de lien de paiement

### Description
Exemple d'utilisation du SDK PHP pour initialiser le client et effectuer un appel au Web Service. L'exemple montre la création d'un paiement avec Charge/CreatePayment, mais le même pattern d'appel s'applique à PaymentOrder/Update.

### Method
POST

### Endpoint
V4/Charge/PaymentOrder/Update (via le SDK)

### Request Example
```php
<?php
/**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * I create a formToken
 */
$store = array("amount" => 250, 
"currency" => "EUR", 
"orderId" => uniqid("MyOrderId"),
"customer" => array(
  "email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];
?>
```
```

--------------------------------

### Appel de la fonction createInstructionIframe en PHP (Second exemple)

Source: https://payzen.io/fr-FR/rest/V4.0/api/authenticate/integration_guide.html

Exemple identique au précédent montrant l'appel de la méthode authenticate et la génération du script d'iframe.

```php
//Call the charge/Authenticate method
$obj = authenticate($data);
if ($obj['answer']['_type']== 'V4/AuthenticationResponseData'){ 
	$response= $obj['answer'];
	
	//Test if anwser contains an instruction
	if($response['value']['_type'] == 'V4/Charge/Authenticate/AuthenticationInstruction'){					
		$_SESSION['RequestParams']= $param_request;
		$_SESSION['requestId'] = $response['id'];
		
		//create an iFrame to proceed to the payer authentication						
		echo '<script>window.onload = function() {
    var instruction = JSON.parse(\''. json_encode($response) .'\');
    createInstructionIframe(instruction);
  }
  </script>';
	}	
}
```
Tokens:
Raw