This is the integration mode to choose if you want to send a payment link directly to the customer's device. For an order from a point of sale for exemple.
In Pay By Link integration, the payment page is hosted by Floa.
Requirements :
- A dedicated and not shared IP
- Your IP must have a good reputation on this website : https://www.brightcloud.com/tools/url-ip-lookup.php . If not, you can request a change using the form.
- Calls to FLOA services must be made on the server side, the authentication token being provided for each call to our services must not be on the client side
This integration offers the following advantages :
- Allows the client to use FLOA's splitted payment solutions inside a physical store thanks to his mobile device
- You do not have to develop your own payment page
- Does not require PCI-DSS certification on your part
- Calls to payment services are simplified
Disadvantages of this integration :
- You don't have any control over the graphic design of the payment page, only the logo of your company can be added (amendment to be requested to the Floa team)
- You don't have any control over the content of the email or SMS sent
Workflow
Services to call
Authentication
Example in the integration environment
GET https://paymentgateway.integration-cb4x.fr/v1/auth/token
Headers
authorization : login:password (in base 64)
Body
Empty
PreEligibility
Subject to customer information and consent (workshop to be conducted with your account manager)
PreEligibility
For a 1XD payment, specify the number of days of deferment in reportDelayInDays
Example in the integration environment
POST https://eligibility.integration-cb4x.fr/api/v1/pre-eligibilities?merchantId=38&merchantSiteIds=7017
Headers
Content-type : application/json
authToken : the token retrieved via the call to the authentication service
Body
{
"presaleFolder": {
"shoppingCarts": [
{
"reference": "order reference",
"rawAmount": amount of the order in cents,
"productsCount": 1,
"products": [
{
"name": "Product A",
"rawAmount": amount of the product in cents,
"shipping": {
"method": "UPS"
}
}
]
}
],
"customer": {
"reference": "customer reference",
"civility": "Mr",
"firstName": "fTest",
"lastName": "lTest",
"email": "[email protected]",
"homePhoneNumber": "0512345678",
"homeAddress": {
"line1": "route de bordeaux",
"zipCode": "33000",
"city": "Bordeaux",
"countryCode": "FR"
}
},
"saleChannel": "Desktop"
}
}
Eligibility
Eligibility
For better tracking of the orders, we recommend you put the same value in presaleFolder/shoppingCarts/reference for the PreEligibility and the Eligibility
In the case of a 1XD payment, indicate the number of deferred days in reportDelayInDays
In the case of a 1XC payment, birthDate, birthZipCode, maidenName are not mandatory
Example in the integration environment
POST https://eligibility.integration-cb4x.fr/api/v1/eligibilities?merchantId=38&merchantSiteIds=7017
If a pre-eligibility is made, link the pre-eligibility to the eligibility via the pre-eligibility requested in the URL :
POST https://eligibility.integration-cb4x.fr/api/v1/eligibilities?merchantId=38&merchantSiteIds=7017&requestId=123456
Headers
Content-type : application/json
authToken : the token retrieved via the call to the authentication service
Body
{
"presaleFolder": {
"shoppingCarts": [
{
"reference": "order reference",
"rawAmount": amount of the order in cents,
"productsCount": 1,
"products": [
{
"name": "Product A",
"rawAmount": amount of the product in cents,
"shipping": {
"method": "UPS"
}
}
]
}
],
"customer": {
"reference": "60128411000001321",
"firstName": "fTest",
"lastName": "lTest",
"email": "[email protected]",
"birthDate": "1986-07-16T00:00:00.0000000+00:00",
"birthZipCode": "33",
"civility": "Mr",
"homePhoneNumber": "0512345678",
"cellPhoneNumber": "0612345678",
"homeAddress": {
"line1": "route de bordeaux",
"zipCode": "33000",
"city": "Bordeaux",
"countryCode": "FR"
}
},
"saleChannel": "Desktop"
}
}
Create a payment link
Get the payment link by eligibility token.
For better orders’ follow-up, we recommend you set the same value in orderReference as presaleFolder/shoppingCarts/reference
Send the value returned by the Eligibility service in the token field in the path for eligibilityToken
You have to send a value for sendingTypes. The variable sendingTypes can take the following values :
- "Sms" : send a SMS with the payment link to the number sent in presaleFolder/customer/cellPhoneNumber in the eligibility call
- "Email" : send an email with the payment link to the email sent in presaleFolder/customer/email in the eligibility call
- "Web" : returns a payment link without sending any SMS or email
If you use orderRowsAmount to display the amount of the order without fees on the payment page, you will have to sent the same value than sent in presaleFolder/shoppingCarts/rawAmount in the eligibility call.
Example in the integration environment
Headers
Content-type : application/json
authToken : the token retrieved via the call to the authentication service
Body
{
"orderReference": "FLOA_20220222001",
"invoiceId": "0",
"paymentUrls": {
"merchantBackUrl": "back to cart URL",
"merchantNotifyUrl": "URL to which the payment notification will be sent",
"merchantReturnUrl": "URL to which the customer will be redirected after the payment"
},
"culture": "fr-FR",
"freeText": "free",
"orderRowsAmount": value sent in presaleFolder/shoppingCarts/rawAmount in the eligibility call,
"orderFeesAmount": 2000,
"orderDiscountAmount": 3000,
"orderShippingCost": 4000
}
Response
If sendingTypes is set to Email or SMS, the service returns a 204 no content if successfull
If sendindTypes is set to Web, the service returns a 201 with the payment link as content :
{
"paymentLinkUrl": "https://payment.integration-cb4x.fr/Generic/CardPayment/Initialization?requestId=eb8bed5d-f756-45b6-a907-717553b25935&hmacPay=C3A388FC96324B79FEB3C8C578DB7611AFFCFBA5"
}
- Error 400 : bad request, see details in the errors object
{
"errors": [
"An error occured while creating payment session for merchantId='38' and merchantSiteId='7017': statusCode='BadRequest', content='{\"operationSucceeded\":false,\"paymentSessionId\":null,\"paymentSessionUrl\":null,\"complementaryCode\":null,\"responseMessage\":\"The merchant back url must be defined and must be a valid URL, unless you use iframe form type\"}'."
],
"links": null
}
- Error 401 : your authToken is invalid
- Error 403 : invalid rights, see details in the errors object
- Error 404 : eligibilityToken not found
- Error 500 : technical error, see details in the errors object
Get order result
Get the order result by eligibility token.
Order results allows you to be aware of the result of a payment for a given eligibilityToken.
Send the value returned by the Eligibility service in the token field in the path for eligibilityToken
Example in the integration environment
Headers
Content-type : application/json
authToken : the token retrieved via the call to the authentication service
Body
Empty
Response
- OK 200, Payment state :
- Payed : payment is completed
- Refused : payment is refused
- Undetermined : payment is not completed
{
"paymentState": "Payed"
}
- Error 400 : bad request, see details in the errors object
{
"errors": [
"eligibilityToken: The value 'aaa' is not valid."
],
"links": null
}
- Error 401 : your authToken is invalid
- Error 403 : invalid rights, see details in the errors object
- Error 404 : eligibilityToken not found
- Error 404 : payment has not been processed by the customer
{
"errors": [
"Awaiting: the payment needs to be processed by the customer."
]
}
- Error 500 : technical error, see details in the errors object
Overview of the email sent
Overview of the SMS sent
Overview of the payment page
Display of specific information
BACK TO BASKET
This link is only displayed if the paymentUrls/merchantBackUrl data is completed
Items
Corresponds to the amount indicated in orderRowsAmount (displays 0 if not filled)
Delivery
Corresponds to the amount indicated in orderShippingAmount (displays 0 if not filled)
Voucher / promo code
Corresponds to the amount indicated in orderDiscountAmount (not displayed if not completed)
Management fees
Corresponds to the amount indicated in orderFeesAmount (not displayed if not completed)
Total amount
Corresponds to the amount of the order (Floa fees included)
ATTENTION
No calculations of the amounts are made automatically. The amounts displayed are those sent in the service. It is up to the merchant to make sure that the values are consistent.