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
main parametersexpand all
currency
required
orderId
recommended
information about your customer
customer
reference
recommended
email
required
billingDetails
title
category
firstName
lastName
phoneNumber
streetNumber
address
address2
district
zipCode
city
state
country
language
cellPhoneNumber
identityCode
identityType
legalName
shoppingCart
insuranceAmount
shippingAmount
taxAmount
cartItemInfo
[1]
productLabel
productType
productRef
productQty
productAmount
productVat
ipAddress
general transaction options
contrib
ipnTargetUrl
fingerPrintId
metadata
[1]
:
strongAuthentication
card related options
transactionOptions
cardOptions
paymentSource
mid
retry
information about the sub-merchant
subMerchantDetails
companyType
legalNumber
name
required
url
phoneNumber
address1
address2
zip
city
country
mcc
mid
softDescriptor
new properties
payload
type
required
data
[1]
:
Try me
Documentation

Charge/CreateToken Web Service

Method:
POST
Entry point:
https://api.lyra.com/api-payment/V4/Charge/CreateToken

The Charge/CreateToken operation is a REST API Web Service.

It allows you to create a token from a payment method.

Only credit cards are supported. This method does not allow you to create a token from an IBAN.

Creating a token using a new card

You can create tokens using a card with an embedded form.

In this case, the Charge/CreateToken Web Service will return a formToken which must be used with our JavaScript form.

For more information, go to: Getting started: Creating a token .

A verification transaction is created at the same time as the token. The token will be inside the Transaction object, in the paymentMethodToken parameter. To see the response reference documentation that contains the formToken , go to: Charge/PaymentForm

If you are PCI-DSS certified

If you are PCI-DSS certified, you can directly transmit sensitive information to the Web Service (such as the card number). For more information, visit our page dedicated to using the PCI/Charge/CreateToken REST Web Service in PCI DSS mode .

Note on the buyer's data associated with the token

The billing information ( billingDetails object) registered when the token is created is automatically used for the transactions performed with this token.

However, if the merchant transmits new data in the Charge/CreatePayment request, then the data in the request is used for the transaction. In this case, the token is not updated.

If the merchant wants to update the buyer's data, they must call the Token/Update Web Service.

Request parameters

The Charge/CreateToken REST Web Service supports the following parameters:

contrib

Name of the e-commerce solution used on the merchant website and its version number.

Format

currency

Payment currency. Alphabetic code in uppercase according to alpha-3 (ISO 4217).

Eg: "EUR" for the euro.

Format

Possible values

The possible values are:

Currency ISO 4217 ENCODING Fractional unit
Australian dollar (036) AUD 2
Canadian dollar (124) CAD 2
Danish crown (208) DKK 2
Japanese yen (392) JPY 0
Norwegian crown (578) NOK 2
Swedish krona (752) SEK 2
Swiss franc (756) CHF 2
Pound Sterling (826) GBP 2
US dollar (840) USD 2
Euro (978) EUR 2

ipnTargetUrl

You can override the Instant Payment Notification (also called IPN) in the payment form in case you use one shop for various sales channels, payment types, languages, etc.

Format

orderId

Order reference defined by the Merchant. Does not support UTF-8 characters.

Format

metadata

Custom values linked to the transaction, in JSON format.

Example of a call

For example, to pass a custom value, such as the Buyer's eye color, add the following to your query:

{
    "metadata": {
        "eyesColor": "blue"
    }
}

This value will be returned in the newly created transaction object.

You can also use the metadata “ orderInfo1 ”, “ orderInfo2 ” and “ orderInfo3 ” to send complementary information about the order

This data can be found later in the Extra tab of the transaction details via your Expert Back Office.

Format

fingerPrintId

Disable the requested authentication Allows the session ID (or fingerPrint Id) to be transmitted to the payment gateway for completing the risk analysis.

The supported analyzers are:

  • NOTO
  • Cybersource
  • MonitorPlus
  • ClearSale

Can contain uppercase and lowercase characters, numbers or hyphens ([A-Z] [a-z], 0-9, _, -).

Format

strongAuthentication

strongAuthentication is used to indicate the Merchant's preference for strong buyer authentication.

With 3DS2, it is no longer possible to disable 3DS. However, the Merchant can request an exemption in his or her payment request (this is called "merchant preference").

In this case, if the request is accepted by the issuer, the Buyer will not have to authenticate him/herself (no challenge) but the Merchant will assume the responsibility in case of chargeback (no liability shift to the issuer).

In any case, the issuing bank itself determines whether interaction with the Buyer (challenge) is necessary.

Under PSD2, strong authentication is required when registering a card, regardless of the merchant's preference.

Possible values

The possible values are:

Value 3DS1 description 3DS2 description
ENABLED

Enables strong authentication (if possible).

Depreciated. This value will be interpreted as CHALLENGE_REQUESTED.

DISABLED

Disables strong authentication (if possible). Requires the "3DS1 Selective" option.

By using this value, you expose yourself to “Soft decline” refusals.

Deactivation will not be taken into account if the payment method requires strong authentication. This is the case of MAESTRO cards.

Allows to request an authentication without interaction (frictionless). Requires the "Frictionless 3DS2" option.

  • For payments made in euro, if the amount is lower than €30, a request for frictionless is transmitted to the DS. If the request for frictionless is accepted by the issuer, the merchant loses the payment guarantee.

  • For payments made in euros, if the amount is greater than €30, the value transmitted by the merchant is ignored and the handling of cardholder authentication is delegated to the gateway.

  • For payments made in a currency other than euro, a frictionless request is sent to the DS.

If the store does not have the "Frictionless 3DS2" option, the value transmitted by the merchant is ignored and the handling of the cardholder authentication is delegated to the gateway.

CHALLENGE_REQUESTED

Enables strong authentication (if possible).

Allows you to request strong authentication for the transaction.

CHALLENGE_MANDATE

Enables strong authentication (if possible).

Allows you to indicate that for regulatory reasons, strong authentication is required for the transaction.

NO_PREFERENCE

Enables strong authentication (if possible).

Allows you to inform the DS that the Merchant does not have a preference. If the issuer decides to perform frictionless authentication, the payment will be guaranteed.

AUTO

Enables strong authentication (if possible).

The choice of preference is delegated to the card issuer (No Preference).

Format

customer.reference

Buyer ID on the merchant side.

Format

customer.email

Buyer's e-mail address.

Format

customer.ipAddress

Buyer's IP 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

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.

mid

Path: transactionOptions.cardOptions.mid

Merchant ID number. If this field is populated, make sure you use the appropriate MID depending on the card scheme.

Format

paymentSource

Path: transactionOptions.cardOptions.paymentSource

Payment source.

Format

Possible values

The possible values are:

Value DESCRIPTION
EC E-commerce: the payment method details are entered by the Buyer. This value allows to have strong authentication during a payment.
MOTO MAIL OR TELEPHONE ORDER: entry by an operator. The payment information is sent by mail or e-mail. Requires a VAD contract
CC Call Center: payment made via a call center. Requires a VAD type contract.
OTHER Other sales channel. Returned output value for payments made via the Back-Office, payments by file, recurring payments, proximity payments, refunds via the Shopify CMS.
Absent ou null The default value is "EC".

retry

Path: transactionOptions.cardOptions.retry

Number of new attempts available in case the payment is rejected (3 by default).

Format

companyType

Path: subMerchantDetails.companyType

Company type of the sub-merchant. Transmitted by the payment facilitator.

Format

legalNumber

Path: subMerchantDetails.legalNumber

Legal identifier of the sub-merchant. Transmitted by the payment facilitator.

Format

name

Path: subMerchantDetails.name

Business name of the sub-merchant. Transmitted by the payment facilitator.

Format

url

Path: subMerchantDetails.url

URL of the sub-merchant. Transmitted by the payment facilitator.

Format

phoneNumber

Path: subMerchantDetails.phoneNumber

Telephone number of the sub-merchant. Transmitted by the payment facilitator.

Format

address1

Path: subMerchantDetails.address1

Address of the sub-merchant. Transmitted by the payment facilitator.

Format

address2

Path: subMerchantDetails.address2

Address line 2 of the sub-merchant. Transmitted by the payment facilitator.

Format

zip

Path: subMerchantDetails.zip

Zip code of the sub-merchant. Transmitted by the payment facilitator.

Format

city

Path: subMerchantDetails.city

City of the sub-merchant. Transmitted by the payment facilitator.

Format

country

Path: subMerchantDetails.country

Country code of the sub-merchant's address (ISO 3166 alpha-2 standard). Transmitted by the payment facilitator.

Format

mcc

Path: subMerchantDetails.mcc

MCC code of the sub-merchant. Transmitted by the payment facilitator.

Format

mid

Path: subMerchantDetails.mid

Contract number (MID) of the sub-merchant. Transmitted by the payment facilitator.

Format

softDescriptor

Path: subMerchantDetails.softDescriptor

Title (soft descriptor) of the sub-merchant that appears on the buyer's bank statement. Transmitted by the payment facilitator.

Format

Response reference

Response Context
Charge/PaymentForm Object containing a hash that should be used with the embedded form to create a new transaction.

See the reference of each response for more information.