Request |
Introduction
The doWebPayment function initialises a web payment before Payline begins payment flow. This allows immediate or deferred full payments, instalments payments, and subscription payments to be made.
Full payments allow you to carry out an authorisation+validation or a simple authorisation. If using simple authorisation, validation (or capture) takes place either automatically by the Payline payment solution, or by the merchant, using webservice calls or via our back office Payline administration centre. This can also be programmed from the authorisation request, always within 7 days, using the batch interface function or the doCapture web service by entering the date of action.
NOTE : With a debit authorization, you have up to 7 days to validate the payment request. Outside of those 7 days, your authorization expires and is no longer valid.
The notifications
To be informed that your customer has paid once the authorization request has been accepted, even if the customer does not return to your site, fill in the notificationURL field in your point-of-sale settings or when you make a web payment initialisation request. Payline will then contact a page from your site and send back the token linked to the payment in the GET parameter of the HTTP request. This page must be accessible by Internet using the HTTP/S protocol.
When a notification is received, your site must carry out a result request for the notified web payment.
NOTE : If your site cannot be accessed, Payline tries every minute during 2 hours. After this, notification is deactivated. You can find your payments in the Merchant Administration Centre web interface.
Instalments or subscription payment is possible using a virtual wallet.
Payline takes charge of the creation of a virtual wallet after the validation of data collected at first payment. When the customers make a second purchase on your online store, Payline suggests that they use their virtual wallet. In this case, “one click” payment is used and the customer does not need to enter any payment information.
Payline can manage instalment payments. When payment is carried out, you can be advised by email by activating the “send an email to merchant” option in the Merchant Administration Centre. If there is a problem with payment, Payline tries the transaction 3 times during one week. Each time an attempt fails, you are informed.
Alternative payment method : this feature allows the merchant, in case of bank refusal, to offer his customers to pay with another means of payment.
This function only applies: for the same order, at the time of the first payment and in the event of a bank refusal. A list of alternative payment methods must have been provided in doWebPayment (secondSelectedContractList).
Request
The doWebPaymentRequest request must have the following structure:
Element | Description | Required | Type | Example | Condition |
| version | Payline web services version. To be valued with the latest version: see the table of versions. | Yes | N2 | 18 | |
| payment | Information regarding payment. see the items below | Yes | Object payment | Possible values of payment.action = 100, 101, 108, 110, 120, 121. | |
returnURL | URL on which the shopper's browser is redirected in case of acceptance or refusal of payment on Payline. | Yes | AN255 | http: // ... or https: // ... | |
cancelURL | URL on which the shopper's browser is redirected in case of abandonment of the user, Payline or merchant. | Yes | AN255 | http: // ... or https: // ... | |
order | Order Information : see the items below | Yes | |||
notificationURL | URL on which Payline will ask the merchant site to retrieve the result of the transaction. | no | AN255 | http: // ... or https: // ... | |
selectedContractList | The list of contract you wish to use for this payment. Payline displays the list of payment methods according to the list order: see the items below | Yes | Mandatory from version 4 | ||
secondSelectedContractList | The list of contract numbers that you want to be able to resubmit when the first transaction attempt fails. If this field is not filled in, Payline will not resubmit a payment method when the first transaction attempt fails. | no | |||
privateDataList | Your own personal information : see the items below | no | |||
languageCode | Fill in this field with the ISO code of the language in which you want to display the Payline payment web pages. By default, the web browser of your shopper asks Payline for the page in the desired language : cf. complete list language code | no | AN6 | fr | |
customPaymentPageCode | The personalization identifier of the merchant's customization web pages | no | AN50 | 1fd51s2dfs51 | |
buyer | Shopper information : see the items below | no | Object buyer | ||
owner | Cardholder Information : see the items below | no | Applicable only for AMEX | ||
securityMode | Selecting the security mode to use for the payment transaction | Yes | AN | SSL | |
recurring | Recurring payment information : see the items below | no | |||
customPaymentTemplateURL | Dynamic template URL | no | AN255 | https: // .... only | |
contractNumberWalletList | A chart of the contract numbers of the wallet. The Widget mode uses the multi-PDV Wallet and multi-contract.see the items below | no | Not used in Widget mode. RELEASE 4.53 | ||
| merchantName | Name displayed on the ACS authentication page | no | AN25 | Your name of signboard | |
| subMerchant | Payment Facilitator Information : see below | no | object subMerchant | version 18 or later RELEASE 4.53 | |
| miscData | Additional data , without character limit and transmitted to the partners. Consult the payment method for each use : see below | no | AN | version 18 or later RELEASE 4.53 | |
| asynchronousRetryTimeout | For the Asynchronous Retry function , this is a numeric that specifies the period in minutes. It must be between 5 and 10080 (7 days). | no | AN | 10080 | RELEASE 4.56 |
The reference elements
Object payment
Field Description Mandatory Format Example amount Transaction amount in the smallest currency unit. The value 100 corresponds to 1 € N12 100 currency Payment currency code N3 978 action Payment function code : see the table N3 100 mode Payment mode full or deferred : see the table AN3 CPT contractNumber The e-commerce contract code or number which gives the payment method you wish to use AN20 1234567 differedActionDate Date of the action. It must be earlier than today + 7 days. Format : dd/mm/yy AN8 07/04/2016 If the mode = DIF field, then the DifferedActionDate date is required otherwise this field must be empty. method Name of card issuer : see the table values AN20 CB version 10 or higher. Information displayed on the account statement of the buyer, limited with certain means of payment. This information will be displayed on the payment ticket. version 13 or higher version 15 or higher registrationToken version 18 or higher RELEASE 4.53 In case of installment or recurring payment this parameter specifies the amount paid up to now. The amount does not include this last payment. The amount is expressed in the smallest currency unit. version 21 or higher RELEASE 4.58Condition Yes Yes Yes Yes Conditionnal No No
Ex : CB, PAYSAFECARDsoftDescriptor
Special characters (not A..Z and 1..9) are specific to each acquirer / payment method.No AN64 www.boutique.fr 
Not supported by all banks. Please check Soft Descriptor (DSD)cardBrand No AN 15 Token used in response in services.
It allows the partner to return a token to identify a consumer and finds this data when making a payment request.No AN cumulatedAmount No N12
Object order
Field Description Mandatory Type Example ref Order reference. AN50 12345678 origin Type of order with the values : No AN country Code of the country in which the order is done, see the list No AN2 FR taxes The amount of tax added to the order in the smallest currency unit. No N12 100 amount The amount of order in smallest unit of currency. Yes N12 6000 currency Currency code used for order. The ISO code : 978: euros See complete list in List of currencies Yes N3 date The merchant order date. Format : dd/mm/yyyy HH24:MI Yes AN16 details Information about the ordered items. The order details is limited to 100 items. No deliveryTime Delivery time : Values for deliveryTime No N 1 deliveryMode Delivery method : Values for deliveryMode No N 4 Expected delivery date must be greater than the current date. Format: dd/mm/yyyy version 21 or higher version 21 or higher version 21 or higher version 21 or higher version 21 or higher Additionnal information about the order. In JSON format AN in JSON format version 21 or higher (3DSV2) Online Travel Agency information. AN in JSON format See Object OrderOTA version 21 or higher Condition
This reference must be unique since it is used in duplicate request check.
The back slash character ("\") is forbidden.Yes
An amount of 1 € corresponds to 100.
An amount of 60 € corresponds to 6000. From version 28 of the API, this field must contain the amount to be authenticated (3DSV2)
840: US dollars978 07/04/2016 11:00 deliveryCharge Amount of delivery charges in smallest unit of currency, example 250 for 2.50 euros No N version 18 ou higher deliveryExpectedDate No datetime 07/04/2016 Posted to Limonetik deliveryExpectedDelay Expected delivery time (in days) No N2 10 Posted to Limonetik discountAmount Amount of the discount for this order (in the same currency than the order) No N12 OTAPackageType Type of package (flight only, journey+accomodation, …). See the table of values Codes - OTAPackageType No N2 OTADestinationCountry Country code of the destination, in ISO 3166-1 format. See the table of values Codes - country No AN2 bookingReference Booking reference or Id of the travel file No AN100 orderDetail Used only for origin = MO or TO. No AN4 orderExtended No orderOTA No
Object orderDetail
Field Description Required Format Example ref Item reference No AN50 price Item price, in the smallest currency unit No N12 quantity Number of Items No N5 comment Comment No AN255 category Category of item No AN50 brand Product brand No AN50 HERMES subcategory1 Rank 1 subcategory No AN50 Watches & Jewellery subcategory2 Rank 2 subcategory No AN50 Jewellery additionalData List of specifications required for some payment methods No AN255 LegalAge=18;Discount=0105 taxRate Item tax rate (expressed in hundredths). Format : 1580 for 15.8% No N4 1580 Type of seller. Values : 1: ProfessionalCondition See table values seller Name or id of the final seller No AN100 Release 4.58 - version 21 or higher merchant.com sellerType
2: Private sellerNo N2 Release 4.58 - version 21 or higher 1
Object selectedContractList
Field Description Mandatory Type Condition selectedContract The contract numbers list you want to use for this payment. Payline displays the payment methods in which the list has been filled. If this field is not filled in, Payline displays all of your payment methods actived for the point of sale. Number of occurrences: 1 to 99. No AN50 Filed required as following :
Object privateDataList
Field Description Mandatory Format Example privateData List containing privateData Number of items 0 to 100 Yes
Object privateData
Field Description Mandatory Format Example key Key name of value Yes AN50 user value Value associated to the key Yes AN50 Martin
Object buyer
Field Description Mandatory Type Example lastName Buyer's surname No AN50 firstName Buyer's first name No AN50 email Buyer's email address No AN150 shippingAdress Delivery address. No billingAddress Billing address No accountCreateDate The date of creation of the buyer's account. Format : dd/mm/yy No AN10 01/04/16 accountAverageAmount The average amount of this buyer's purchases No N10 accountOrderCount The number of orders placed by this buyer No N10 walletId The virtual wallet identifier of your client. No AN50 walletDisplayed Management of the display of the means of payment of your customer. To not display the customer payment data, enter the value "none". To display the customer payment data, the tag must be empty or absent. No AN5 walletSecured Nature of the control added to the payment kinematics WEB. No AN12 walletCardInd Specifies the index of the card to use. No AN2 1 ip Buyer's IP address. Format : IPv4 or IPv6 Conditionnal AN50 mobilePhone The mobile number of the buyer No N15 0033691666666 customerId Customer ID No AN50 894492568 2016-04-27 0 : No program from version 21 or higher (3DSV2) RELEASE 4.58 from version 21 or higher (3DSV2) RELEASE 4.58 from version 21 or higher (3DSV2) RELEASE 4.58Condition title Title of civility, See the table of values No AN1 Do not put more than 12 consecutive digits (eg test123456789101@test.test ) Object Address Mandatory for wallet payment
See the table of valuesThe index, default value "1" Mandatory in a verifyEnrollmentRequest for browser based authentication. Clearsale: This data can be an identifier or an email legalStatus Legal status of the customer: person or company No N1 1 Clearsale: see the table of value. legalDocumentType Type of document : See the table of values No N1 1 legalDocument Identification number of the official document No AN100 X5446119U birthDate Birth date. Format: yyyy-mm-dd No AN10 fingerprintID ID Device fingerprint No AN50 deviceFingerprint DeviceFingerPrint information. No AN from version 15 isBot DeviceFingerPrint information. Possible value: Y or N No AN1 from version 15 isIncognito DeviceFingerPrint information. Possible value: Y or N No AN1 from version 15 isBehindProxy DeviceFingerPrint information. Possible value: Y or N No AN1 from version 15 isFromTor DeviceFingerPrint information. Possible value: Y or N No AN1 from version 15 isEmulator DeviceFingerPrint information. Possible value: Y or N No AN1 from version 15 isRooted DeviceFingerPrint information. Possible value: Y or N No AN1 from version 15 hasTimezoneMismatch DeviceFingerPrint information. Possible value: Y or N No AN1 from version 15 loyaltyMemberType Values :
1 : Standard/Normal
2 : Silver
3 : Gold/Premium
4 : Platinium
9 : Subscription in progress
99 : Special or OtherNo N2 0 buyerExtended Past events about buyer. See below for more information about buyerExtendedHistory No AN { "loyaltyMemberId": "buyerExtLoyMemId", "buyerExtendedHistory": {...}}merchantAuthentication Information about cardholder to authenticate to the merchant No Object merchantAuthentication
Object owner
Field Description Mandatory Type Example lastName Owner lastname No AN30 Pierre firstName Owner firstname No AN15 Paul billingAddress No issueCardDate Issue card date. Format : mmyy No AN4 0118Condition Applicable only for AMEX Applicable only for AMEX Billing adress Applicable only for AMEX Applicable only for AMEX
Object addressOwner
Field Description Required Format Example street Street name No AN20 cityName City No AN40 zipCode Postal code No AN9 country Country, the list of values. No AN2 FR phone Phone No AN15
Object address
Field Description Required Format title Title, see table values No AN2 Name Name or building number No AN100 firstName First name No AN100 lastName Last name No AN100 street1 Street name No AN100 street2 Complement of street name No AN100 cityName City No AN40 zipCode Postal code No AN12 country Country, see table values No AN2 phone Phone No AN15 state No AN100 Specificity of ShippingAdress: For electronic delivery, the email address to which the merchandise is delivered. version 21 or higher (3DSV2) RELEASE 4.58 version 21 or higher (3DSV2) RELEASE 4.58Condition streetNumber Street number No N State county Région No AN15 phoneType Phone category, see table values No N1 email No AN150 addressCreateDate Creation date of the address in the merchant's system No AN10
Object recurring
firstAmount The amount of the first amount to be made. It must be formulated in the smallest unit of the currency. No N12 10000 amount The amount of a maturity. It must be formulated in the smallest unit of the currency. Yes N12 500 billingCycle The code of the frequency of payments. Values : 40: Monthly cf. complete list in annex table " Frequency list " Yes N2 40 Rank of the installment (from 1 to n, where n is the total number of installments ie the value of 'billingLeft') This value has to be set when used in the doAuthorization web service startDate The date of the first expiry (only in REC mode). If this field is not filled in, Payline assigns the current date. No AN10 01/01/2018 31/12/2018 12:00 06/06/2018 12:00 Example : Payment in = REC mode with the following values: The first transaction is made on the current date and then every month, at the end of the month for 2 years until the endDate. For the even months and the month of February, the day selected when creating the deadlines is 30 for even months and 28 or 29 for February.Field Description Required Format Example Condition
For an amount of 100 €, you must set the value 10000value mandatory REC and NX
For an amount of 5 €, you must put the value 500value mandatory REC and NX
60: QuarterlybillingLeft Number total of due dates (only for NX) No N3 3 value mandatory NX billingRank No N2 1 Version 22 or higher (3DSV2) billingDay Day when the deadlines must be processed. Format : dd No AN2 20
Format : dd/mm/yyyyendDate The date of the end of payment deadlines. Format : dd/mm/yyyy HH24:MI No AN16 newAmount New amount changed. For an amount of 60 €, you must put the value 6000 No N12 6000 amountModificationDate The date of the modification of the amount. Format : dd/mm/yyyy HH24:MI No AN16
Object contractNumberWalletList
Field Description Required Format Example contractNumberWallet List containing the contract numbers of portfolio. Number of elements 0 to 10. The Widget mode uses the multi-PDV and multi-contract wallet: the wallet is linked to merchant level. No Not used in Widget mode. RELEASE 4.53Condition
Object subMerchant
Object available in version 18 or higher of web services Field Description Type Amex subMerchantId Identifier of the sub-market (final beneficiary) defined by the payment provider (Payment Facilitator). M AN15 subMerchantName Sub-merchant's name : see Payment Facilitator. M AN15 subMerchantMCC MCC Code M N4 subMerchantSIRET SIRET (French merchants) O AN14 subMerchantTaxCode Tax code (US and Canadian merchants) AN subMerchantStreet Street name M AN30 subMerchantCity City M AN15 subMerchantZipCode Postal code M AN15 subMerchantCountry Country code M AN2 subMerchantState O AN3 Phone numberPresence (Mandatory/Optional/Conditional) Conditions and notes CB MSC VISA iDEAL M M M M Limited to 15 char from version 26 or higher (was 25 char in version 18-25) M M M O O C C Mandatory for countries USA and CAN.
It is up to the Payment Facilitator to determine whether that information should be provided or not.O O O M see the list of values State O subMerchantEmailAddress Email M ANS40 subMerchantPhoneNumber M AN20
Additional Private Data (example)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | <impl:miscData> <![CDATA[ { "ContratVAD": "{'optionalTravelDetails': {'class':'First', 'departureDate':'2014-10-05T08:43:00', 'destinationCountry':'GN', 'insurance':'SIMPLE', 'mainDepartureCompany':'Luftansa', 'ownTicket':false, 'ticketCount':1, 'travellerCount':2, 'travellerPassportList':[{'expirationDate':'2018-12-31T08:45:00','issuanceCountry':'FR'}, {'expirationDate':'2019-01-01T08:45:00','issuanceCountry':'DE'}], 'type':'TwoWay' }, 'additionalNumericFieldList':[{'index':'1', 'value':'10'}, {'index':'2', 'value':'20'}], 'additionalTextFieldList':[{'index':'11', 'value':'val11'}, {'index':'22', 'value':'val22'}] }" } ]]></impl:miscData> |