support
Back to documentation
Search
Categories
Tags
Charge/CreatePayment
webService
Charge/CreatePaymentOrder
webService
Charge/CreateSubscription
webService
Charge/CreateToken
webService
Charge/CreateTokenFromTransaction
webService
Charge/PaymentOrder/Get
webService
Charge/PaymentOrder/Update
webService
Charge/SDKTest
webService
Order/Get
webService
Subscription/Cancel
webService
Subscription/Get
webService
Subscription/Update
webService
Token/Cancel
webService
Token/Get
webService
Token/Reactivate
webService
Token/Update
webService
Transaction/CancelOrRefund
webService
CustomerWallet/Get
webService
CustomerWallet/Update
webService
Transaction/Capture
webService
Transaction/Duplicate
webService
Transaction/Get
webService
Transaction/Update
webService
Transaction/Validate
webService
Risk/AddToGreyList
webService
PCI/Charge/Authenticate (PCI)
PCI
webService
PCI/Charge/CreatePayment (PCI)
PCI
webService
PCI/Charge/CreateToken (PCI)
PCI
webService
Token/Update (PCI)
PCI
webService
PCI/Charge/VerifyPaymentMethod
PCI
webService
AuthenticationResponseData
answer
Charge/PaymentForm
answer
OrderTransactions
answer
Payment
answer
PaymentOrder
answer
Common/ResponseCodeAnswer
answer
Subscription
answer
SubscriptionCreated
answer
Transaction
answer
Token
answer
CustomerWallet
answer
GreyList
answer
Transaction informationexpand all
amount
currency
transactionCategory
productType
merchant
mid
required
tid
name
recurring
expiryDate
required
frequency
value
required
unit
required
Payment Method
paymentForm
networkPreference
required
accountType
pan
required
expiryMonth
required
expiryYear
required
cardHolderName
installmentNumber
issuerInstallment
information about your customer
customer
reference
email
recommended
billingDetails
title
category
firstName
lastName
phoneNumber
streetNumber
address
address2
district
zipCode
city
state
country
language
cellPhoneNumber
identityCode
shippingDetails
category
firstName
lastName
phoneNumber
streetNumber
address
address2
district
zipCode
city
state
country
deliveryCompanyName
shippingSpeed
shippingMethod
legalName
identityCode
shoppingCart
insuranceAmount
shippingAmount
taxAmount
cartItemInfo
[1]
productLabel
productType
productRef
productQty
productAmount
productVat
Protocol information
protocolRequest
name
required
version
challengePreference
Device information
device
required
3DS response parameters
id
instructionResult
name
required
value
required
protocol
name
required
version
required
network
challengePreference
required
simulation
required
Try me
Documentation

PCI/Charge/Authenticate (PCI)

POSThttps://api.lyra.com/api-payment/V4/PCI/Charge/Authenticate

The activation of these features is subject to prior approval by company_name.

You can find the reference documentation on its integration here: Cardholder authentication service

Request parameters

amount

Amount of the transaction to authenticate. Its value must be positive and in the smallest currency unit (cent for euro). E.g.: 1234 for 12.34 EUR

Format

currency

Currency of the transaction to authenticate. Alphabetic code in uppercase in accordance with the ISO 4217 standard (e.g.: “EUR” for euro).

Format

transactionCategory

Transaction category. Is usually set to PAYMENT for a regular payment.

Format

Possible values

values DESCRIPTION
ADD_CARD Addition of a card to a wallet.
PAYMENT Regular payment (includes recurring or installment payments).

productType

Product type for which the transaction is made This field is required .

Possible values

values DESCRIPTION
ACCOUNT_FUNDING Wire transfer to an account.
CHECK_ACCEPTANCE Acceptance testing.
GOODS_OR_SERVICE_PURCHASE Purchase of an item or a service.
PREPAID_ACTIVATION_AND_LOAD Activation and loading of a prepaid card.
QUASI_CASH_TRANSACTION Transactions in cash equivalents (e.g.: holiday coupons, lottery tickets, etc.).

Format

merchant.mid

Merchant ID number.

Format

merchant.tid

Terminal ID POS identifier defined within the acceptance contract.

This field is only used in Colombia for choosing between REDEBAN and CREDIBANCO.

Format

networkPreference

Path: paymentForm.networkPreference

Name of the network recommended by the Merchant in case of multi-brand cards (e.g.: CB and VISA within the same card).

Possible values

Value DESCRIPTION
AMEX American Express network (SafeKey)
CB Bank Card Network
MASTERCARD MasterCard network
VISA Visa network
ELO Elo network (Brazil)
DINERS Diners network
DISCOVER Discover network
OSB Network OSB

Format

accountType

Path: paymentForm.accountType

Card type. This field is mandatory in Brazil.

Possible values

values DESCRIPTION
DEBIT Debit card
CREDIT Credit card

Format

paymentForm.pan

PAN (Primary Account Number) is the primary card number usually consisting of 16 digits.

Format

expiryMonth

Path: paymentForm.expiryMonth

Expiry month.

Format

expiryYear

Path: paymentForm.expiryYear

Expiry year.

Format

cardHolderName

Path: paymentForm.cardHolderName

Cardholder's first and last names.

Format

installmentNumber

Path: paymentForm.installmentNumber

Number of installments.

Format

customer.reference

Buyer ID on the merchant side.

Format

customer.email

Buyer's e-mail address.

Format

address

Path: customer.billingDetails.address

Billing address.

Warning: the characters > and < are not authorized.

Format

address2

Path: customer.billingDetails.address2

Second line of the billing address.

Warning: the characters > and < are not authorized.

Format

category

Path: customer.billingDetails.category

Buyer type.

Format

Possible values

values DESCRIPTION
PRIVATE Individual buyer type.
COMPANY Company buyer type.

cellPhoneNumber

Path: customer.billingDetails.cellPhoneNumber

Buyer's cell phone number.

Accepts all formats:

Examples:

  • 0623456789
  • +33623456789
  • 0033623456789
  • (+34) 824 65 43 21
  • 87 77 12 34

Format

city

Path: customer.billingDetails.city

City of the billing address.

Format

country

Path: customer.billingDetails.country

Buyer's country (in uppercase, in accordance with the ISO 3166-1 alpha-2 country codes).

Format

Possible values

Examples of possible values:

Country Code
AUSTRIA AT
BRAZIL BR
CORSICA FR
IVORY COAST CI
FRANCE FR
GUADELOUPE GP
INDIA IN
MARTINIQUE MQ
NEW CALEDONIA NC
ST-PIERRE-ET-MIQUELON PM
FRENCH POLYNESIA PF

district

Path: customer.billingDetails.district

District of the billing address.

Format

firstName

Path: customer.billingDetails.firstName

Buyer's first name.

Format

identityCode

Path: customer.billingDetails.identityCode

National identifier. Allows to identify each citizen within a country.

Format

language

Path: customer.billingDetails.language

Buyer's language code, according to ISO 639-1.

Specify the language in which payment confirmation e-mails are sent.

Format

Possible values

Examples of possible values:

Language Code
German (Germany) DE
English (United Kingdom) EN
English (United States) EN
Chinese (Traditional) ZH
Spanish (Spain) ES
Spanish (Chile) ES
French (France) FR
Italian (Italy) IT
Japanese (Japan) JP
Dutch (the Netherlands) NL
Polish (Poland) PL
Portuguese (Brazil) PT
Portuguese (Portugal) PT
Russian (Russia) RU

lastName

Path: customer.billingDetails.lastName

Buyer's last name.

Format

legalName

Path: customer.billingDetails.legalName

Legal name.

Format

phoneNumber

Path: customer.billingDetails.phoneNumber

Buyer's phone number.

Accepts all formats:

Examples:

  • 0123456789
  • +33123456789
  • 0033123456789
  • (00.571) 638.14.00
  • 40 41 42 42

Format

state

Path: customer.billingDetails.state

Region (state) of the billing address. It is recommended, but not mandatory, to pass the value in ISO-3166-2.

Format

streetNumber

Path: customer.billingDetails.streetNumber

Street number of the billing address.

Accepted characters:

  • Alphabetical characters (from "A" to "Z" and from "a" to "z")
  • Space

Format

title

Path: customer.billingDetails.title

Buyer's title.

Examples:

  • Mr
  • Ms
  • Mrs

Format

zipCode

Path: customer.billingDetails.zipCode

Zip code of the billing address.

Format

address

Path: customer.shippingDetails.address

Shipping address.

Warning: the characters > and < are not authorized.

Format

address2

Path: customer.shippingDetails.address2

Second line of the shipping address.

Warning: the characters > and < are not authorized.

Format

category

Path: customer.shippingDetails.category

Buyer type.

Format

Possible values

values DESCRIPTION
PRIVATE Individual buyer type.
COMPANY Company buyer type.

city

Path: customer.shippingDetails.city

Shipping city.

Format

country

Path: customer.shippingDetails.country

Shipping country (in uppercase, in accordance with the ISO 3166-1 alpha-2 country codes).

Format

Possible values

Examples of possible values:

Country Code
AUSTRIA AT
BRAZIL BR
CORSICA FR
IVORY COAST CI
FRANCE FR
GUADELOUPE GP
INDIA IN
MARTINIQUE MQ
NEW CALEDONIA NC
ST-PIERRE-ET-MIQUELON PM
FRENCH POLYNESIA PF

deliveryCompanyName

Path: customer.shippingDetails.deliveryCompanyName

Name of the delivery company.

Format

district

Path: customer.shippingDetails.district

District of the billing address.

Format

firstName

Path: customer.shippingDetails.firstName

First name of the recipient.

Format

identityCode

Path: customer.shippingDetails.identityCode

National identifier. Allows to identify each citizen within a country.

Format

lastName

Path: customer.shippingDetails.lastName

Buyer's last name.

Format

legalName

Path: customer.shippingDetails.legalName

Legal name in case of shipping to a company.

Format

phoneNumber

Path: customer.shippingDetails.phoneNumber

Buyer's phone number.

Accepts all formats:

Examples:

  • 0123456789
  • +33123456789
  • 0033123456789
  • (00.571) 638.14.00
  • 40 41 42 42

Format

shippingMethod

Path: customer.shippingDetails.shippingMethod

Shipping mode.

Format

Possible values

Value DESCRIPTION
RECLAIM_IN_SHOP Item pickup at the shop.
RELAY_POINT Use of a third-party pickup network (Kiala, Alveol, etc.).
RECLAIM_IN_STATION Pickup at an airport, a train station or a travel agency.
PACKAGE_DELIVERY_COMPANY Shipping by the transporter (Colissimo, UPS, etc.).
ETICKET Issue of an electronic ticket, online download of the product.
CARD_HOLDER_ADDRESS Delivery to the buyer. Reserved for future use.
VERIFIED_ADDRESS Delivery to a verified address. Reserved for future use.
NOT_VERIFIED_ADDRESS Delivery to a non-verified address. Reserved for future use.
SHIP_TO_STORE In-store pickup. Reserved for future use.
DIGITAL_GOOD Digital delivery. Reserved for future use.
ETRAVEL_OR_ETICKET E-ticket. Reserved for future use.
OTHER Other: Reserved for future use.
PICKUP_POINT Pickup point delivery. Reserved for future use.
AUTOMATED_PICKUP_POINT Pickup at an automatic pickup point. Reserved for future use.

shippingSpeed

Path: customer.shippingDetails.shippingSpeed

Shipping delay.

Format

Possible values

Examples of possible values:

Value DESCRIPTION
STANDARD Standard shipping.
EXPRESS Express shipping (in less than 24h).
PRIORITY Priority shipping (Click & Collect).

state

Path: customer.shippingDetails.state

Region of the billing address.

Format

streetNumber

Path: customer.shippingDetails.streetNumber

Street number of the delivery address.

Accepted characters:

  • Alphabetical characters (from "A" to "Z" and from "a" to "z")
  • Space

Format

zipCode

Path: customer.shippingDetails.zipCode

Zip code of the billing address.

Format

insuranceAmount

Path: customer.shoppingCart.insuranceAmount

Insurance amount for the entire order, expressed in the smallest monetary unit (cent for euro).

Example: 30050 for EUR 300.50.

Format

shippingAmount

Path: customer.shoppingCart.shippingAmount

Amount of delivery fees for the entire order, expressed in its smallest monetary unit (cent for euro).

Example: 30050 for EUR 300.50.

Format

taxAmount

Path: customer.shoppingCart.taxAmount

Amount of taxes for the entire order expressed in the smallest monetary unit (cent for euro).

Example: 30050 for EUR 300.50.

Format

cartItemInfo

Path: customer.shoppingCart.cartItemInfo

cardItemInfo is a list that contains Customer/ShoppingCartItemInfo objects.

See the customer.shoppingCart.* properties for more information.

Format

productAmount

Path: customer.shoppingCart.cartItemInfo.productAmount

Amount of the product expressed in the smallest currency unit (cent for euro).

Example: 30050 for EUR 300.50.

Format

productLabel

Path: customer.shoppingCart.cartItemInfo.productLabel

Product name.

Format

productQty

Path: customer.shoppingCart.cartItemInfo.productQty

Product quantity.

Format

productRef

Path: customer.shoppingCart.cartItemInfo.productRef

Product reference.

Format

productType

Path: customer.shoppingCart.cartItemInfo.productType

Product type.

Format

Possible values

Value DESCRIPTION
FOOD_AND_GROCERY Food and grocery
AUTOMOTIVE Cars / Moto
ENTERTAINMENT Entertainment / Culture
HOME_AND_GARDEN Home and gardening
HOME_APPLIANCE Household appliances
AUCTION_AND_GROUP_BUYING Auctions and group purchasing
FLOWERS_AND_GIFTS Flowers and presents
COMPUTER_AND_SOFTWARE Computers and software
HEALTH_AND_BEAUTY Health and beauty
SERVICE_FOR_INDIVIDUAL Services for individuals
SERVICE_FOR_BUSINESS Services for companies
SPORTS Sports
CLOTHING_AND_ACCESSORIES Clothes and accessories
TRAVEL Travel
HOME_AUDIO_PHOTO_VIDEO Sound, image and video
TELEPHONY Telephony

productVat

Path: customer.shoppingCart.cartItemInfo.productVat

Product type.

Tax fee amount (expressed in the smallest currency unit).

Possible values

Value DESCRIPTION
Integer Transaction amount. Its value must be a positive integer (e.g.: 1234 for 12.34 EUR).
Decimal number, lower than 100 Percentage applied to the amount. Examples: 20.0 or 19.6532

To display a percentage applied to the payment amount for the product in question, the value should have maximum 4 digits after the decimal point. The decimal separator is mandatory for displaying a percentage. The decimal separator is represented by the "." symbol.

device.deviceType

Type of device on which the authentication takes place.

Several methods can be used to identify the device type (screen size, user-agent, etc.).

Example of JavaScript code based on the screen size:

    var isMobile = "";
    var testMobile = window.matchMedia("only screen and (max-width: 760px)");
	if (testMobile.matches){
		isMobile="MOBILE";		
	}
	else{
		isMobile="BROWSER"
	}  

Possible values

Value DESCRIPTION
BROWSER Authentication in a browser.
MOBILE Authentication by phone.

Format

device.acceptHeader

Exact content of the Accept HTTP header as it is sent by the Buyer’s browser.

Format

device.userAgent

Exact content of the HTTP "user-agent" header sent by the browser. Must be truncated if the value exceeds 2048 characters.

Obtained from the client’s browser via the “navigator.userAgent” property.

JavaScript code allowing to retrieve the value:

const language = navigator.userAgent;

Format

device.ip

Browser’s IP address as returned in HTTP headers by the client. IPV4 format (e.g.: 1.12.123.255) or IPV6 (e.g.: 2011:0db8:85a3:0101:0101:8a2e:0370:7334). Variable length, maximum 45 characters.

Format

device.javaEnabled

Boolean that represents the browser's capacity to execute Java. The value is the one returned by the “navigator.javaEnabled()” function, it can be true or false.

JavaScript code allowing to retrieve the value:

const javaEnabled = navigator.javaEnabled();

Format

device.language

String indicating the language of the browser.

Obtained from the client browser via the "navigator.language" property.

Examples: “en”, “en-US”, “de”, “fr”, etc.

JavaScript code allowing to retrieve the value:

const language = navigator.language;

Format

device.colorDepth

Value representing the depth of the color palette used to display images, in bits per pixel.

Obtained from the client’s browser via the “screen.colorDepth” property.

JavaScript code allowing to retrieve the value:

const colorDepth = screen.colorDepth;

Format

device.screenHeight

Total height of the client's screen in pixels. La valeur est celle retournée par la propriété "screen height".De 1 à 6 caractères

JavaScript code allowing to retrieve the value:

const screenHeight = screen.height;

Format

device.screenWidth

The total width of the client’s screen in pixels. La valeur est celle retournée par la propriété "screen width".De 1 à 6 caractères

JavaScript code allowing to retrieve the value:

const screenWidth = screen.width;

Format

timeZoneOffset

Path: device.timeZoneOffset

Timezone difference between UTC and the local time of the Buyer’s browser in minutes. Its value is -120 for a user in the UTC+2 time zone and 570 for the UTC-09:30 time zone.

JavaScript code allowing to retrieve the value:

const timeZoneOffset = new Date().getTimezoneOffset();

Format

id

Unique identifier of the authentication, in UUID format.

Null upon the first call.

When several calls to the PCI/Charge/Authenticate Web Service are required to perform buyer authentication, the value of the transmitted ID must be the same for each call within the same authentication. Then, the ID provided in the previous response must be used.

Format

name

Path: instructionResult.name

Instruction name.

Possible values

Value DESCRIPTION
CHALLENGE Challenge Instruction that allows interactive user authentication via the ACS.
FINGERPRINT Fingerprint Instruction that allows to identify the user via the ACS.

Format

value

Path: instructionResult.value

Result in the form of JWT string, or an error code in plain text format in case of error ( timeout for example).

Format

challengePreference

Path: instructionResult.protocol.challengePreference

Indicates whether or not the Merchant has requested a challenge.

Possible values

Value 3DS1 card 3DS2 card
NO_PREFERENCE Forced 3DS1 authentication. The choice of preference is delegated to the card issuer.
NO_CHALLENGE_REQUESTED Disabled 3DS1 authentication. Allows you to request authentication without interaction (frictionless).
CHALLENGE_REQUESTED Forced 3DS1 authentication. Allows you to request strong authentication for the transaction.
CHALLENGE_MANDATED Forced 3DS1 authentication. Allows to indicate that, for regulatory reasons, strong authentication is required for the transaction.

Format

name

Path: instructionResult.protocol.name

Name of the protocol used by the cardholder authentication services.

Possible values

Value DESCRIPTION
THREEDS 3D Secure protocol
PROCESOS_DINERS Procesos Diners OTP protocol
OSB Protocol OTP OSB

Format

network

Path: instructionResult.protocol.network

Name of the network recommended by the Merchant in case of multi-brand cards (e.g.: CB and VISA within the same card).

Possible values

Value DESCRIPTION
AMEX American Express network (SafeKey)
CB Bank Card Network
MASTERCARD MasterCard network
VISA Visa network
ELO Elo network (Brazil)
DINERS Diners network
DISCOVER Discover network
OSB Network OSB

Format

simulation

Path: instructionResult.protocol.simulation

Boolean indicating if the authentication must be carried out in simulation mode. Simulation mode allows to perform merchant integration without being in production or using a real card.

Format

version

Path: instructionResult.protocol.version

Version of the protocol used by the cardholder authentication services.

Currently supported versions

Value DESCRIPTION
1.0.2 Version 1.0.2
2.1.0 Version 2.1.0

Format

protocolRequest.name

Name of the protocol used by the cardholder authentication services.

Possible values

Value DESCRIPTION
THREEDS 3D Secure protocol
PROCESOS_DINERS Procesos Diners OTP protocol
OSB Protocol OTP OSB

Format

version

Path: protocolRequest.version

Allows you to force the version of the authentication protocol to be used.

Currently supported versions

Value DESCRIPTION
1 3D Secure 1
2 3D Secure 2

Format

challengePreference

Path: protocolRequest.challengePreference

Indicates whether or not the Merchant has requested a challenge.

Possible values

Value 3DS1 card 3DS2 card
NO_PREFERENCE Forced 3DS1 authentication. The choice of preference is delegated to the card issuer.
NO_CHALLENGE_REQUESTED Disabled 3DS1 authentication. Allows you to request authentication without interaction (frictionless).
CHALLENGE_REQUESTED Forced 3DS1 authentication. Allows you to request strong authentication for the transaction.
CHALLENGE_MANDATED Forced 3DS1 authentication. Allows to indicate that, for regulatory reasons, strong authentication is required for the transaction.

Format

recurring.expiryDate

Date d'expiration de la récurrence. Exemple: 2019-12-24

Format

unit

Path: recurring.frequency.unit

Recurring payment frequency.

Possible values

values DESCRIPTION
DAY In days
MONTH In months
YEAR In years

Format

value

Path: recurring.frequency.value

Value of the recurring payment frequency, expressed in unit of frequency. Example: 12.

Format

Response reference

Several responses are possible, depending on the context:

Response Context
AuthenticationResponseData Object containing the authentication result.

See the reference of each response for more information.