Pay By Link

📘

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

Authenticate

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

POST https://eligibility.integration-cb4x.fr/api/v4/eligibilities/abc46f0b-4f6b-4e0c-8dfb-2bad36589b70/payment-links/send?merchantId=38&merchantSiteId=7017&sendingTypes=Email

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

POST https://eligibility.integration-cb4x.fr/api/v4/eligibilities/c1cace4b-1421-4da4-8952-8b5fdab48fbb/order-results?merchantId=38&merchantSiteId=7017

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.