Buyer wallet management

A wallet allows a buyer to store multiple payment cards and choose which one to use at the time of purchase, without having to enter a card number. The buyer can request the deletion of a card stored in his wallet at any time.

The banking details are stored by the payment gateway according to the rules imposed by the GDPR (= General Data Protection Regulation).

Operating principle

When the form is displayed, the buyer has several possibilities:

Pay without registering the payment method.
Pay and register the payment method.

If the buyer chooses to save the payment method data, the payment gateway stores it and associates it with their buyer reference (buyer wallet).
Upon their next purchase, the buyer will have several options:

Pay using a payment method that was previously registered in their buyer wallet.
Pay with a new payment method and add it to their buyer wallet.
Pay with a new payment method without adding it to their buyer wallet.
Delete a payment method that was previously registered in their buyer wallet.

The expired payment methods are not offered.

Eligible payment methods

AMEX
CB
Meal Voucher (Titre-Restaurant) cards
VISA
VISA ELECTRON
MASTERCARD
MAESTRO

Implementation

The merchant website must associate a unique reference with each buyer (for example, the customer account ID on the merchant website). The merchant website must make sure this reference is unique.
To offer the use of a wallet during payment, the merchant website must:

Call the Charge/CreatePayment Web Service.
Send the buyer reference via the customer.reference field.
Transmit the formAction field with the CUSTOMER_WALLET value.

Use cases

Using a buyer wallet when making a payment

This use case requires the creation of a formToken via a call to the Charge/CreatePayment Web Service.

To indicate the intention to use a buyer wallet, the merchant website must transmit:

The buyer reference in the customer.reference field.
The formAction field with the CUSTOMER_WALLET value.

An error will return:

If the store's offer does not have the "Payment by token" option.
If the formAction field is set to CUSTOMER_WALLET but the customer.reference field is not transmitted.

Note on the buyer's data associated with the buyer wallet

The billing information (object billingDetails ) transmitted during the payment method registration is automatically applied during transactions made with the buyer wallet.

However, if the merchant transmits new data in the Charge/CreatePayment request, the request data will be used for the transaction. In this case, the buyer's data associated with the payment method is not updated.

If the merchant wants to update the buyer's data for all the tokens associated with the buyer reference, he or she must call the CustomerWallet/Update Web Service.

Example of a POST Charge/CreatePayment request

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

https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44

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

{
    "amount": 40000,
    "currency": "EUR",
    "orderId": "myOrderId-999999",
    "formAction": "CUSTOMER_WALLET", 
    "customer": {
      "email": "sample@example.com",
      "reference": "cust-001"
    }
}

The response contains a formToken that will be used for displaying the form.

{
  "webService": "Charge/CreatePayment",
  "version": "V4",
  "applicationVersion": "5.13.0",
  "status": "SUCCESS",
  "answer": {
    "formToken": "10n5J2yTR-Sb6jnXXOohmfsw209eyJhbW91bnQiOjQwMDAwLCJjdXJyZW5jeSI6IkVVUiIsIm1vZGUiOiJURVNUIiwidmVyc2lvbiI6Mywib3JkZXJJZCI6Im15T3JkZXJJZC05OTk5OSIsInNob3BOYW1lIjoiRGVtbyBzaG9wIiwiYnJhbmRQcmlvcml0eSI6WyJCQU5DT05UQUNUIiwiTUFFU1RSTyJdLCJjYXRlZ29yaWVzIjp7ImRlYml0Q3JlZGl0Q2FyZHMiOnsiYXBwSWQiOiJjYXJkcyIsInBhcmFtIjpbIkVERU5SRUQiLCJBTUVYIiwiQ09ORUNTIiwiTUFTVEVSQ0FSRF9ERUJJVCIsIkRJU0NPVkVSIiwiVklTQSIsIlZJU0FfREVCSVQiLCJTT0RFWE8iLCJESU5FUlMiLCJNQUVTVFJPIiwiRS1DQVJURUJMRVVFIiwiQ0hRX0RFSiIsIk1BU1RFUkNBUkQiLCJCQU5DT05UQUNUIiwiQVBFVElaIiwiVklTQV9FTEVDVFJPTiIsIkNCIl19fSwiY2FyZHMiOnsiQ09ORUNTIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJBTUVYIjp7ImZpZWxkcyI6eyJzZWN1cml0eUNvZGUiOnsibWF4TGVuZ3RoIjo0fX0sImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJFREVOUkVEIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJNQVNURVJDQVJEX0RFQklUIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJESVNDT1ZFUiI6eyJjb3B5RnJvbSI6ImNhcmRzLkRFRkFVTFQifSwiVklTQSI6eyJjb3B5RnJvbSI6ImNhcmRzLkRFRkFVTFQifSwiRElORVJTIjp7ImZpZWxkcyI6eyJzZWN1cml0eUNvZGUiOnsicmVxdWlyZWQiOmZhbHNlfX0sImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJTT0RFWE8iOnsiY29weUZyb20iOiJjYXJkcy5ERUZBVUxUIn0sIlZJU0FfREVCSVQiOnsiY29weUZyb20iOiJjYXJkcy5ERUZBVUxUIn0sIk1BRVNUUk8iOnsiZmllbGRzIjp7InNlY3VyaXR5Q29kZSI6eyJyZXF1aXJlZCI6ZmFsc2V9LCJkb1JlZ2lzdGVyIjp7ImhpZGRlbiI6dHJ1ZX19LCJjb3B5RnJvbSI6ImNhcmRzLkRFRkFVTFQifSwiRS1DQVJURUJMRVVFIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJDSFFfREVKIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJNQVNURVJDQVJEIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJCQU5DT05UQUNUIjp7ImZpZWxkcyI6eyJzZWN1cml0eUNvZGUiOnsicmVxdWlyZWQiOmZhbHNlLCJoaWRkZW4iOnRydWV9LCJkb1JlZ2lzdGVyIjp7ImhpZGRlbiI6dHJ1ZX19LCJjb3B5RnJvbSI6ImNhcmRzLkRFRkFVTFQifSwiVklTQV9FTEVDVFJPTiI6eyJmaWVsZHMiOnsic2VjdXJpdHlDb2RlIjp7InJlcXVpcmVkIjpmYWxzZX19LCJjb3B5RnJvbSI6ImNhcmRzLkRFRkFVTFQifSwiQVBFVElaIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJERUZBVUxUIjp7ImZpZWxkcyI6eyJwYW4iOnsibWluTGVuZ3RoIjoxMCwibWF4TGVuZ3RoIjoxOSwidmFsaWRhdG9ycyI6WyJOVU1FUklDIiwiTFVITiJdLCJyZXF1aXJlZCI6dHJ1ZSwic2Vuc2l0aXZlIjp0cnVlLCJoaWRkZW4iOmZhbHNlLCJjbGVhck9uRXJyb3IiOmZhbHNlfSwiZXhwaXJ5RGF0ZSI6eyJyZXF1aXJlZCI6dHJ1ZSwic2Vuc2l0aXZlIjp0cnVlLCJoaWRkZW4iOmZhbHNlLCJjbGVhck9uRXJyb3IiOmZhbHNlfSwic2VjdXJpdHlDb2RlIjp7Im1pbkxlbmd0aCI6MywibWF4TGVuZ3RoIjo0LCJ2YWxpZGF0b3JzIjpbIk5VTUVSSUMiXSwicmVxdWlyZWQiOnRydWUsInNlbnNpdGl2ZSI6dHJ1ZSwiaGlkZGVuIjpmYWxzZSwiY2xlYXJPbkVycm9yIjp0cnVlfSwiZG9SZWdpc3RlciI6eyJ2YWx1ZSI6ImZhbHNlIiwidmFsaWRhdG9ycyI6WyJCT09MRUFOIl0sInJlcXVpcmVkIjpmYWxzZSwic2Vuc2l0aXZlIjpmYWxzZSwiaGlkZGVuIjpmYWxzZSwiY2xlYXJPbkVycm9yIjpmYWxzZX19fSwiQ0IiOnsiY29weUZyb20iOiJjYXJkcy5ERUZBVUxUIn19LCJwYXNzQWN0aXZhdGVkIjp0cnVlLCJhcGlSZXN0VmVyc2lvbiI6IjQuMCJ96902",
    "_type": "V4/Charge/PaymentForm"
  },
  "ticket": null,
  "serverDate": "2020-09-25T10:09:36+00:00",
  "applicationProvider": "PAYZEN",
  "metadata": null,
  "_type": "V4/WebService/Response"
}

Following the basic principles of JavaScript client usage, you use the , formToken ,, generated when calling the Web Service , Charge/CreatePayment ,, to specify the form identifier to be displayed in the , kr-form-token , attribute of your <div>.

The form appears:

The buyer enters their card data, checks the Save my card box and clicks “Pay”.

If the buyer has already registered a card in their buyer wallet, the input fields are pre-filled with the data of their payment method:

If they do not want to pay with this card, the "New card" tab allows them to enter a new payment method and to register it, if they wish to do so:

If the buyer has registered several payment methods in their buyer wallet, they will have to choose the card to be used or enter a new card in the "New card" tab:

Once the payment is complete, a notification is sent to the merchant's site on the URL defined in the merchant back office. The same information is returned to the browser by the JavaScript client to the URL declared in the kr-post-url-success parameter when the form is displayed.

Among the transmitted information, the kr-answer object contains the Payment object that contains the details of the transaction as well as the details of the used payment method.

Registering a card in a wallet without payment

This use case requires the creation of a formToken via a call to the Charge/CreateToken Web Service.

To indicate the intention to use a buyer wallet, the merchant website must pass the buyer reference in the customer.reference field.

If the buyer reference is not transmitted, the card will be registered and a token will be created, but the card will not be added to the wallet.

During the next payment, if the merchant website transmits the buyer reference (using the buyer wallet), this card will not be suggested in the list of registered cards.

Example of a POST Charge/CreateToken request

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

https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44

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

{
    "currency": "EUR",
    "orderId": "myOrderId-999999",    
    "customer": {
      "email": "sample@example.com",
      "reference": "cust-001"
    }       
}

The response contains a formToken that will be used for displaying the form.

{
  "webService": "Charge/CreateToken",
  "version": "V4",
  "applicationVersion": "5.13.0",
  "status": "SUCCESS",
  "answer": {
    "formToken": "10hIV6-LQ9TGeZIRI9C_zENg209eyJhbW91bnQiOjAsImN1cnJlbmN5IjoiRVVSIiwibW9kZSI6IlRFU1QiLCJ2ZXJzaW9uIjozLCJvcmRlcklkIjoibXlPcmRlcklkLTk5OTk5Iiwic2hvcE5hbWUiOiJEZW1vIHNob3AiLCJjYXRlZ29yaWVzIjp7ImRlYml0Q3JlZGl0Q2FyZHMiOnsiYXBwSWQiOiJjYXJkcyIsInBhcmFtIjpbIkFNRVgiLCJFLUNBUlRFQkxFVUUiLCJNQVNURVJDQVJEX0RFQklUIiwiTUFTVEVSQ0FSRCIsIkRJU0NPVkVSIiwiVklTQSIsIlZJU0FfRUxFQ1RST04iLCJWSVNBX0RFQklUIiwiQ0IiLCJESU5FUlMiXX19LCJjYXJkcyI6eyJBTUVYIjp7ImZpZWxkcyI6eyJzZWN1cml0eUNvZGUiOnsibWF4TGVuZ3RoIjo0fX0sImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJFLUNBUlRFQkxFVUUiOnsiY29weUZyb20iOiJjYXJkcy5ERUZBVUxUIn0sIk1BU1RFUkNBUkRfREVCSVQiOnsiY29weUZyb20iOiJjYXJkcy5ERUZBVUxUIn0sIkRJU0NPVkVSIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJNQVNURVJDQVJEIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJWSVNBIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJWSVNBX0VMRUNUUk9OIjp7ImZpZWxkcyI6eyJzZWN1cml0eUNvZGUiOnsicmVxdWlyZWQiOmZhbHNlfX0sImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJERUZBVUxUIjp7ImZpZWxkcyI6eyJwYW4iOnsibWluTGVuZ3RoIjoxMCwibWF4TGVuZ3RoIjoxOSwidmFsaWRhdG9ycyI6WyJOVU1FUklDIiwiTFVITiJdLCJyZXF1aXJlZCI6dHJ1ZSwic2Vuc2l0aXZlIjp0cnVlLCJoaWRkZW4iOmZhbHNlLCJjbGVhck9uRXJyb3IiOmZhbHNlfSwiZXhwaXJ5RGF0ZSI6eyJyZXF1aXJlZCI6dHJ1ZSwic2Vuc2l0aXZlIjp0cnVlLCJoaWRkZW4iOmZhbHNlLCJjbGVhck9uRXJyb3IiOmZhbHNlfSwic2VjdXJpdHlDb2RlIjp7Im1pbkxlbmd0aCI6MywibWF4TGVuZ3RoIjo0LCJ2YWxpZGF0b3JzIjpbIk5VTUVSSUMiXSwicmVxdWlyZWQiOnRydWUsInNlbnNpdGl2ZSI6dHJ1ZSwiaGlkZGVuIjpmYWxzZSwiY2xlYXJPbkVycm9yIjp0cnVlfX19LCJESU5FUlMiOnsiZmllbGRzIjp7InNlY3VyaXR5Q29kZSI6eyJyZXF1aXJlZCI6ZmFsc2V9fSwiY29weUZyb20iOiJjYXJkcy5ERUZBVUxUIn0sIkNCIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJWSVNBX0RFQklUIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9fSwicGFzc0FjdGl2YXRlZCI6dHJ1ZSwiYXBpUmVzdFZlcnNpb24iOiI0LjAifQ4a02",
    "_type": "V4/Charge/PaymentForm"
  },
  "ticket": null,
  "serverDate": "2020-09-25T10:15:37+00:00",
  "applicationProvider": "PAYZEN",
  "metadata": null,
  "_type": "V4/WebService/Response"
}

Once the payment method registration is completed, a notification is sent to the merchant website using the URL defined in the Merchant Back Office.

The same information is returned to the browser by the JavaScript client to the URL declared in the kr-post-url-success parameter when the form is displayed.

The transmitted kr-answer field contains a Payment object describing the verification transaction as well as the details of the created token.

Only the presence of the customer.reference field, populated with the buyer reference transmitted by the merchant, indicates that the card has been added to the buyer wallet.

Deleting a registered card

During the payment process, the buyer can request to remove a card registered in their buyer wallet by clicking the recycle bin icon.

The deletion is called "logical", that is, the alias is terminated, it is no longer possible to use it for payments. But it is still visible in the Merchant Back Office.

In compliance with the privacy and protection regulations for banking data required by PCI DSS, the payment method details are purged after a period of 15 months if the associated token has not been used.

A new setting in the Merchant Back Office allows you to configure if it will be deleted automatically or by the merchant.

Automatic deletion

When you click on the recycle bin, a confirmation message appears:

If the buyer clicks Delete , the card disappears from the list of available cards.

This action triggers notifications based on the token update:

Instant Payment Notification URL at the end of the payment
Confirmation e-mail of token creation sent to the buyer
Confirmation e-mail of token creation sent to the merchant
Confirmation SMS of token creation sent to the merchant
Token creation confirmation SMS sent to the buyer

If the deleted card was the only registered one, the "New card" tab is automatically displayed.

If the card is being used to pay for an automatic subscription, a warning message appears inviting the buyer to contact the merchant:

To enable automatic removal:

In the Merchant Back Office, open the Settings > Company menu and click on the Subscription and alias parameters tab.
In the Buyer wallet parameter section, check the box Logical removal of the alias authorized by the buyer.
Click Save to save your changes.

Manual removal

When you click on the recycle bin, a notification appears inviting the buyer to contact the merchant:

To enable manual deletion:

In the Merchant Back Office, open the Settings > Company menu and click on the Subscription and alias parameters tab.
In the Buyer wallet parameter section, uncheck the box Logical removal of the alias authorized by the buyer.
Click Save to save your changes.

Categories

Tags