Quick start

This page describes a quick 3-step integration process.

Check out this link for a complete guide: Payment form integration.

Visualize the operating mode: Kinematics .

I. Create the formToken

Authenticate with the REST API keys (more information: Step 2: Authenticate ).
Use the Charge/CreatePayment Web Service with the payment data (amount, currency, order number, buyer details, etc.).

Sample query

PayPal

Alma (payment in installments)

Apple Pay

SEPA Credit Transfer

Payconiq

UPI

/en-EN/rest/V4.0/api/kb/authentication.html

https://api.lyra.com/api-payment/V4/Charge/CreatePayment

{
  "amount": 10000,
  "currency": "EUR",
  "paymentMethods": [
    "PAYPAL", 
    "PAYPAL_BNPL",
    "CARDS"
  ],
  "customer": {
    "email": "sample@example.com"
  },
  "orderId": "myOrderId-1234"
}

/en-EN/rest/V4.0/api/kb/authentication.html

https://api.lyra.com/api-payment/V4/Charge/CreatePayment

{
  "amount": 10000,
  "currency": "EUR",
  "paymentMethods": [
    "ALMA_2X",
    "ALMA_3X", 
    "ALMA_4X", 
    "ALMA_10X", 
    "ALMA_12X", 
    "CARDS"
  ],
  "customer": {
    "email": "sample@example.com"
  },
  "orderId": "myOrderId-1234"
}

/en-EN/rest/V4.0/api/kb/authentication.html

https://api.lyra.com/api-payment/V4/Charge/CreatePayment

{
  "amount": 10000,
  "currency": "EUR",
  "paymentMethods": [
    "APPLE_PAY", 
    "CARDS"
  ],
  "customer": {
    "email": "sample@example.com"
  },
  "orderId": "myOrderId-1234"
}

/en-EN/rest/V4.0/api/kb/authentication.html

https://api.lyra.com/api-payment/V4/Charge/CreatePayment

{
  "amount": 10000,
  "currency": "EUR",
  "paymentMethods": [
    "IP_WIRE", 
    "CARDS"
  ],
  "customer": {
    "email": "sample@example.com"
  },
  "orderId": "myOrderId-1234"
}

<!-- <pre data-language="json" data-market="es-PE">&#010;{&#010;    &quot;amount&quot;: 200050,&#010;    &quot;currency&quot;: &quot;PEN&quot;,&#010;    &quot;orderId&quot;: &quot;myOrderId-999999&quot;,    &#010;    &quot;channelOptions&quot;: {&#010;      &quot;channelType&quot;: &quot;MAIL&quot;,&#010;      &quot;mailOptions&quot;: {&#010;        &quot;recipient&quot;: &quot;sample@example.com&quot;&#010;      }&#010;    },&#010;    &quot;paymentReceiptEmail&quot;: &quot;sample@example.com&quot;,&#010;    &quot;expirationDate&quot;: &quot;2020-04-20T20:13:26+02:00&quot;,&#010;    &quot;locale&quot;: &quot;es_PE&quot;,&#010;    &quot;dataCollectionForm&quot;: &quot;false&quot;&#010;}&#010;</pre>

{
    "amount": 200050,
    "currency": "ARS",
    "orderId": "myOrderId-999999",    
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient": "sample@example.com"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "locale": "es_AR",
    "dataCollectionForm": "false"
}

{
    "amount": 200050,
    "currency": "COP",
    "orderId": "myOrderId-999999",   
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient": "sample@example.com"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "locale": "es_CO",
    "dataCollectionForm": "false"
}

{
    "amount": 200050,
    "currency": "BRL",
    "orderId": "myOrderId-999999",   
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient": "sample@example.com"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "locale": "pt_BR",
    "dataCollectionForm": "false"
}

-->

/**
 * 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"];

?>

/**
 * 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"];

?>

/en-EN/rest/V4.0/api/kb/authentication.html

https://api.lyra.com/api-payment/V4/Charge/CreatePayment

{
  "amount": 10000,
  "currency": "EUR",
  "customer": {
    "email": "sample@example.com"
  },
  "orderId": "myOrderId-1234",
  "paymentMethods": [
    "PAYCONIQ", 
    "CARDS"
  ],
  "customer": {
    "email": "sample@example.com"
  },
  "orderId": "myOrderId-1234"
}

/en-EN/rest/V4.0/api/kb/authentication.html

https://api.lyra.com/api-payment/V4/Charge/CreatePayment

{
  "amount": 10000,
  "currency": "EUR",
  "paymentMethods": [
    "UPI", 
    "CARDS"
  ],
  "customer": {
    "email": "sample@example.com"
  },
  "orderId": "myOrderId-1234",
}

If you do not use the paymentMethods field then ALL eligible payment methods (currencies, technical constraints, etc.) associated with the store are offered (See: Selecting payment methods ). The description and all fields are available from our playground (menu on the left): Charge/CreatePayment .

Retrieve theformToken(answer.formtokenfield) to display the payment form

{
    "status": "SUCCESS",
    "_type": "V4/WebService/Response",
    "webService": "Charge/CreatePayment",
    "applicationProvider": "LYRA",
    "version": "V4",
    "applicationVersion": "4.1.0",
    "answer": {
        "formToken": "DEMO-TOKEN-TO-BE-REPLACED",
        "_type": "V4/Charge/PaymentForm"
    }
}

II. Displaying the form

Once the formToken has been generated:

In the HEAD,

A. load our JavaScript library : src="https://static.lyra.com/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
B. must include the public key in the kr-public-key parameter ( 3rd key in the REST API key table ).
C. include other initialization parameters , such as the kr-post-url-success parameter in case of successful payment.
D. Choose a theme (more information on Themes ).

Code sample for the TEST shop

<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />

<!--
A. load the JS librairy
B. add the kr-public-key
C. add parameters as kr-post-url-success (optionnal)
-->
<script type="text/javascript"
  src="https://static.lyra.com/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
  kr-public-key="69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5"
  kr-post-url-success="[SUCCESS PAYMENT URL]";>
</script>

<!-- 
D. add a theme néon should be loaded in the HEAD section 
-->
<link rel="stylesheet" href="https://static.lyra.com/static/js/krypton-client/V4.0/ext/neon-reset.min.css">
<script type="text/javascript" src="https://static.lyra.com/static/js/krypton-client/V4.0/ext/neon.js">
</script>
</head>
(...)
</html>

In the BODY,

VALUEthe formTokenin the attributekr-form-token(see:I. Create the formToken)

Choosing the display mode:

List mode (default)

<body> <div class="kr-smart-form" kr-form-token="[GENERATED FORMTOKEN]"></div> (...) </body>
More info: List mode

Pop-in mode

<body> <div class="kr-smart-form" kr-popin kr-form-token="[GENERATED FORMTOKEN]"></div> (...) </body>
More info: Pop-in mode

List mode with embedded card

<body> <div class="kr-smart-form" kr-card-form-expanded kr-form-token="[GENERATED FORMTOKEN]"></div> (...) </body>
More info: List mode with embedded card

Code example for the TEST shop

List mode with embedded card

<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />

<!-- STEP :
1 : load the JS librairy
2 : required public key and the JS parameters as url sucess -->

<script type="text/javascript"
  src="https://static.lyra.com/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
  kr-public-key="69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5"
  kr-post-url-success="[SUCCESS PAYMENT URL]";>
</script>

<!-- 3 : theme néon should be loaded in the HEAD section   -->
<link rel="stylesheet" href="https://static.lyra.com/static/js/krypton-client/V4.0/ext/neon-reset.min.css">
<script type="text/javascript" src="https://static.lyra.com/static/js/krypton-client/V4.0/ext/neon.js">
</script>
</head>

<body>

<!-- 4 : display the form payment -->
<div class="kr-smart-form" kr-card-form-expanded kr-form-token="[GENERATED FORMTOKEN]">

</div>
</body>
</html>

You also have the choice :

III. Analyzing the payment result

Analyze the payment result from the IPN or from the browser return.

A la fin du paiement, vous pouvez analyser le résultat du paiement depuis :

instant payment notification: IPN: Analysis of the IPN (Notification URL) .
.

A security mechanism checks the authenticity of the transmitted information, with the kr-hash.

In the object ,PAYMENT,, an example of a kr-answer, :

{
  "shopId": "69876357",
  "orderCycle": "CLOSED",
  "orderStatus": "PAID",
  "serverDate": "2022-01-21T09:28:17+00:00",
  "orderDetails": {
    "orderTotalAmount": 990,
    "orderEffectiveAmount": 990,
    "orderCurrency": "EUR",
    "mode": "TEST",
    "orderId": "myOrderId-475882",
    "metadata": null,
    "_type": "V4/OrderDetails"
  },
  "customer": {
    "billingDetails": {
      "address": null,
      "category": null,
      "cellPhoneNumber": null,
      "city": null,
      "country": null,
      "district": null,
      "firstName": null,
      "identityCode": null,
      "language": "FR",
      "lastName": null,
      "phoneNumber": null,
      "state": null,
      "streetNumber": null,
      "title": null,
      "zipCode": null,
      "legalName": null,
      "_type": "V4/Customer/BillingDetails"
    },
    "email": "sample@example.com",
    "reference": null,
    "shippingDetails": {
      "address": null,
      "address2": null,
      "category": null,
      "city": null,
      "country": null,
      "deliveryCompanyName": null,
      "district": null,
      "firstName": null,
      "identityCode": null,
      "lastName": null,
      "legalName": null,
      "phoneNumber": null,
      "shippingMethod": null,
      "shippingSpeed": null,
      "state": null,
      "streetNumber": null,
      "zipCode": null,
      "_type": "V4/Customer/ShippingDetails"
    },
    "extraDetails": {
      "browserAccept": null,
      "fingerPrintId": null,
      "ipAddress": "185.244.73.2",
      "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.71 Safari/537.36",
      "_type": "V4/Customer/ExtraDetails"
    },
    "shoppingCart": {
      "insuranceAmount": null,
      "shippingAmount": null,
      "taxAmount": null,
      "cartItemInfo": null,
      "_type": "V4/Customer/ShoppingCart"
    },
    "_type": "V4/Customer/Customer"
  },
  "transactions": [
    {
      "shopId": "69876357",
      "uuid": "1c8356b0e24442b2acc579cf1ae4d814",
      "amount": 990,
      "currency": "EUR",
      "paymentMethodType": "CARD",
      "paymentMethodToken": null,
      "status": "PAID",
      "detailedStatus": "AUTHORISED",
      "operationType": "DEBIT",
      "effectiveStrongAuthentication": "ENABLED",
      "creationDate": "2022-01-21T09:28:16+00:00",
      "errorCode": null,
      "errorMessage": null,
      "detailedErrorCode": null,
      "detailedErrorMessage": null,
      "metadata": null,
      "transactionDetails": {
        "liabilityShift": "YES",
        "effectiveAmount": 990,
        "effectiveCurrency": "EUR",
        "creationContext": "CHARGE",
        "cardDetails": {
          "paymentSource": "EC",
          "manualValidation": "NO",
          "expectedCaptureDate": "2022-01-27T09:38:10+00:00",
          "effectiveBrand": "VISA",
          "pan": "497011XXXXXX1003",
          "expiryMonth": 12,
          "expiryYear": 2025,
          "country": "FR",
          "issuerCode": 17807,
          "issuerName": "Banque Populaire Occitane",
          "effectiveProductCode": null,
          "legacyTransId": "929936",
          "legacyTransDate": "2022-01-21T09:28:16+00:00",
          "paymentMethodSource": "NEW",
          "authorizationResponse": {
            "amount": 990,
            "currency": "EUR",
            "authorizationDate": "2022-01-21T09:28:16+00:00",
            "authorizationNumber": "3fe205",
            "authorizationResult": "0",
            "authorizationMode": "FULL",
            "_type": "V4/PaymentMethod/Details/Cards/CardAuthorizationResponse"
          },
          "captureResponse": {
            "refundAmount": null,
            "refundCurrency": null,
            "captureDate": null,
            "captureFileNumber": null,
            "effectiveRefundAmount": null,
            "effectiveRefundCurrency": null,
            "_type": "V4/PaymentMethod/Details/Cards/CardCaptureResponse"
          },
          "threeDSResponse": {
            "authenticationResultData": {
              "transactionCondition": null,
              "enrolled": null,
              "status": null,
              "eci": null,
              "xid": null,
              "cavvAlgorithm": null,
              "cavv": null,
              "signValid": null,
              "brand": null,
              "_type": "V4/PaymentMethod/Details/Cards/CardAuthenticationResponse"
            },
            "_type": "V4/PaymentMethod/Details/Cards/ThreeDSResponse"
          },
          "authenticationResponse": {
            "id": "30eaa40d-dd76-4617-b527-4bed6240b81c",
            "operationSessionId": "ae6f2ad3ffea41bb8faf1aefabad87b9",
            "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": "bafdb21f-e3d6-4d1c-b4f6-d1668b7f7f21",
                "_type": "V4/Charge/Authenticate/AuthenticationId"
              },
              "authenticationValue": {
                "authenticationValueType": "CAVV",
                "value": "BqLgDBHYRaCBpip3Fn3+erKT9vg=",
                "_type": "V4/Charge/Authenticate/AuthenticationValue"
              },
              "status": "SUCCESS",
              "commerceIndicator": "05",
              "extension": {
                "authenticationType": "THREEDS_V2",
                "threeDSServerTransID": "30eaa40d-dd76-4617-b527-4bed6240b81c",
                "dsTransID": "bafdb21f-e3d6-4d1c-b4f6-d1668b7f7f21",
                "acsTransID": "bd6e58b4-6f37-4993-b428-9096766d83a6",
                "_type": "V4/Charge/Authenticate/AuthenticationResultExtensionThreedsV2"
              },
              "reason": {
                "_type": "V4/Charge/Authenticate/AuthenticationResultReason"
              },
              "_type": "V4/Charge/Authenticate/AuthenticationResult"
            },
            "_type": "V4/AuthenticationResponseData"
          },
          "installmentNumber": null,
          "installmentCode": null,
          "markAuthorizationResponse": {
            "amount": null,
            "currency": null,
            "authorizationDate": null,
            "authorizationNumber": null,
            "authorizationResult": null,
            "_type": "V4/PaymentMethod/Details/Cards/MarkAuthorizationResponse"
          },
          "cardHolderName": null,
          "identityDocumentNumber": null,
          "identityDocumentType": null,
          "_type": "V4/PaymentMethod/Details/CardDetails"
        },
        "fraudManagement": {
          "_type": "V4/PaymentMethod/Details/FraudManagement"
        },
        "subscriptionDetails": {
          "subscriptionId": null,
          "_type": "V4/PaymentMethod/Details/SubscriptionDetails"
        },
        "parentTransactionUuid": null,
        "mid": "9999999",
        "sequenceNumber": 1,
        "taxAmount": null,
        "preTaxAmount": null,
        "taxRate": null,
        "externalTransactionId": null,
        "nsu": null,
        "tid": "001",
        "acquirerNetwork": "CB",
        "taxRefundAmount": null,
        "userInfo": "JS Client",
        "paymentMethodTokenPreviouslyRegistered": null,
        "occurrenceType": "UNITAIRE",
        "_type": "V4/TransactionDetails"
      },
      "_type": "V4/PaymentTransaction"
    }
  ],
  "subMerchantDetails": null,
  "_type": "V4/Payment"
}

For more details, Step 5: Analyze the payment result.

Categories

Tags

Quick start

I. Create the formToken

Sample query

II. Displaying the form

Code sample for the TEST shop

Code example for the TEST shop

List mode with embedded card

III. Analyzing the payment result