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
amount
required
currency
required
effectDate
required
paymentMethodToken
required
rrule
required
orderId
recommended
general transaction options
comment
description
initialAmount
initialAmountNumber
metadata
[1]
:
card related options
transactionOptions
cardOptions
paymentSource
mid
manualValidation
captureDelay
firstInstallmentDelay
installmentNumber
retry
debitCreditSelector
Try me
Documentation

Charge/CreateSubscription Web Service

POSThttps://api.lyra.com/api-payment/V4/Charge/CreateSubscription

The Charge/CreateSubscription REST Web Service allows to make recurring payments using an existing and valid token.

A token is also referred to as payment token.

When the Charge/CreateSubscription REST Web Service is called, the payment gateway starts automatically creating and capturing transactions.

Frequent errors when creating recurring payments:

  • The provided token does not exist, is disabled or terminated.
  • The effective date of the recurring payment has passed.

This web service also allows you to create recurring SEPA direct debits.

To do this, you must transmit the unique mandate reference (UMR) in the paymentMethodToken field.

Make sure the effective date is 14 days or more.

Request parameters

amount

Payment amount in its smallest currency unit (cent for euro).

Example: 30050 for EUR 300.50.

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

comment

Public comment.

Format

description

Description associated with the subscription.

Format

effectDate

Recurring payment start date in ISO 8601 format defined by W3C.

Format

initialAmount

Amount of the first installments. Its value must be a positive integer (e.g.: 1234 for 12.34 EUR).

Format

initialAmountNumber

Number of installments for applying the amount specified in initalAmount.

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

paymentMethodToken

Token associated with a payment method.

Only tokens associated with a credit card are supported.

Format

orderId

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

Format

rrule

Description of the recurring payment rule in the form of a rrule (RFC-5545).

For more information on how to generate a RRULE:

  • RRULE specification
  • RRULE generator
  • Examples of recurrence rules

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".

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

manualValidation

Path: transactionOptions.cardOptions.manualValidation

Transaction validation mode.

Format

Possible values

The possible values are:

Value DESCRIPTION
NO Automatic validation by the payment gateway.
YES Manual validation by the Merchant.
null Default configuration of the selected shop (configurable in the Lyra Collect Back Office).

captureDelay

Path: transactionOptions.cardOptions.captureDelay

Delay to be applied to the capture date.

DESCRIPTION

Indicates the delay (in days) before the capture.

If this parameter is not passed, then the default value set in the Expert Back Office will be used.

It can be set in the Expert Back Office by all authorized persons.

If the capture delay is higher than 365 days in the payment request, it will be automatically reset to 365 days.

Format

firstInstallmentDelay

Path: transactionOptions.cardOptions.firstInstallmentDelay

Number of deferred months to be applied to the first installment of payment in installments. Field specific to acquirers in Latin America.

Format

installmentNumber

Path: transactionOptions.cardOptions.installmentNumber

Number of installments.

Format

retry

Path: transactionOptions.cardOptions.retry

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

Format

debitCreditSelector

Path: transactionOptions.cardOptions.debitCreditSelector

This field is specific to Brazil for multiplo card management .

"Multiplo" cards are payment cards (Elo, Visa or MasterCard) that allow to pay using:

  • Either immediate debit: the amount is debited immediately, and the merchant is credited on D+1.
  • Or credit: the debit is deferred and the amount can be debited in one or more installments. The merchant is later credited with the entirety or a portion of the total amount.

This field allows you to force the use of the card in debit or credit mode.

Possible values

values DESCRIPTION
DEBIT Using the "debit" function of the card.
CREDIT Using the "credit" function of the card.

Format

Response reference

The web service returns the following object:

Response Context
SubscriptionCreated Object containing details of the created recurring payment.

See response reference for more information.