Dynamic API flow

🚧

When should I use the dynamic API flow

You should set the Scalapay dynamic API flow when your agrement with the Scalapay Sales referent includes product dynamicity (pay in 3 or pay in 4) according to determined parameters, that are travelDate and/or price of the reservation.

To correctly set up the Dynamic custom integration, you need to implement the following 3 API calls:

create order
This POST call is mandatory to create the order.

In this call, all the useful order information are sent from the merchant website to our server. Upon successful call, an order is created in Scalapay database: Scalapay answers with a checkout URL where to redirect the customer.

As a Travel merchant, it is mandatory to note the following details regarding the create order call:

  • in the consumer parameter, the field email is mandatory and must be valid (no spaces before or after the address, format username+symbol+mail server+domain - ex. [email protected] )
  • shipping must be sent, but empty
  • billing should be sent, if available
  • please make sure the type field is set to online for e-commerce purchases
  • please make sure the product field is configured as indicated below
    "product":"pay-in-3",
    "frequency":{
        "number": 1,
        "frequencyType":"monthly"
    }
  • extensions field must be added and populated, as indicated below
    "extensions": {
        "industry":{
            "travel":{
                "startDate": "2023-11-30",
                "endDate": "2023-12-18"
            }

👍

How to boost your conversion?

To enhance the approval rate and therefore exploit at its best the power of Scalapay, please add the following data in the extensions parameter

travel

FieldTypeDescriptionRequired
persons_countIntegerNumber of passengers / guests / ticket holders / ...Y
startDateYYY-MM-DDThe date of the travel / check-in or eventY
endDateYYY-MM-DDThe number of nights or the date of the check-out date (where applicable)Y
insuranceBooleanWhether the user has opted for insuranceY
transportationReservationDetailsObject - see dedicated data model below for more infoAny extensions properties that are required for the type (e.g.: transportation)N
hotelReservationDetailsObjet - see dedicated data model below for more infoAny extensions properties that are required for the type (e.g.: hotel bookings)N
eventsObject - see dedicated data model below for more infoAny extensions properties that are required for the type (e.g.: event bookings)N

transportationReservationDetails

FieldTypeDescriptionRequired
typeEnumtype of travel ( air | train | bus | ferry )Y
departureEnumDeparture location (IATA code or port code)Y
arrivalStringDestination location (IATA code or port code)Y
ticketClassStringClass of ticket booked ( economy | premium_economy | business | first | other )Y
ticketTypeEnumType of journey booked ( one_way | return | other)N
loyaltyProgrammeBooleanWhether the user has supplied a loyalty programmeN

hotelReservationDetails

FieldTypeDescriptionRequired
nightsIntegerNumber of nights the reservation is forY
hotelCountryStringName of hotelY
hotelCountryStringCountry code (ISO 3166-1 alpha-2)Y
hotelStarsIntegerNumber of stars that the hotel hasN
insuranceBooleanWhether the user has opted for insuranceN
loyaltyProgrammeBooleanWhether the user has supplied a loyalty programmeN

events

FieldTypeDescriptionRequired
eventNameStringName of the eventY
eventCountryStringCountry of the eventY
categoryEnumCategory of the event ( concert | club | festival | experience )Y
ticketTypeEnumType of ticket ( singleuse | subscription )N

Please find below a full example of the create order API for Travel merchants

{  
    "totalAmount": {  
        "amount": "1500.00",
        "currency": "EUR"
    },
    "consumer": {  
        "phoneNumber": "0400000001",
        "givenNames": "Joe",
        "surname": "Consumer",
        "email": "[email protected]"
    },
    "billing": {  
        "name": "Joe Consumer",
        "line1": "Via della Rosa, 58",
        "suburb": "Montelupo Fiorentino",
        "postcode": "50056",
        "countryCode": "IT",
        "phoneNumber": "0400000000"
    },
    "shipping": {  
    },
    "items":[  
         {
             "name": "Tours Islands",
             "category": "Honeymoon Trips",
             "brand": "Tour Operator Name",
             "sku": "12341234",
             "quantity": 1,
             "price": {
                 "amount": "1500.00",
                 "currency": "EUR"
             }
         },
    ],
    "discounts": [
        {
            "displayName": "10% Off",
            "amount": {
                "amount": "150.00",
                "currency": "EUR"
            }
        }
    ],
    "merchant": {
        "redirectConfirmUrl": "https://scalapay.com",
        "redirectCancelUrl": "https://scalapay.com"
    },
    "merchantReference": "merchantOrder-1234",
     "taxAmount": {  
        "amount": "3.70",
        "currency": "EUR"
     },
     "shippingAmount": {  
         "amount": "10.00",
         "currency": "EUR"
    },
    "orderExpiryMilliseconds": 6000000,
    "channel": "scalapay.com",
    "type":"online",
    "product":"pay-in-3",
    "frequency":{
        "number": 1,
        "frequencyType":"monthly"
    },
    "extensions": {
        "industry":{
            "travel":{
                "startDate": "2023-11-30",
                "endDate": "2023-12-18"
            }
        },    
  }
{  
    "totalAmount": {  
        "amount": "1500.00",
        "currency": "EUR"
    },
    "consumer": {  
        "phoneNumber": "0400000001",
        "givenNames": "Joe",
        "surname": "Consumer",
        "email": "[email protected]"
    },
    "billing": {  
        "name": "Joe Consumer",
        "line1": "Via della Rosa, 58",
        "suburb": "Montelupo Fiorentino",
        "postcode": "50056",
        "countryCode": "IT",
        "phoneNumber": "0400000000"
    },
    "shipping": {  
    },
    "items":[  
         {
             "name": "Tours Islands",
             "category": "Honeymoon Trips",
             "brand": "Tour Operator Name",
             "sku": "12341234",
             "quantity": 1,
             "price": {
                 "amount": "1500.00",
                 "currency": "EUR"
             }
         },
    ],
    "discounts": [
        {
            "displayName": "10% Off",
            "amount": {
                "amount": "150.00",
                "currency": "EUR"
            }
        }
    ],
    "merchant": {
        "redirectConfirmUrl": "https://scalapay.com",
        "redirectCancelUrl": "https://scalapay.com"
    },
    "merchantReference": "merchantOrder-1234",
     "taxAmount": {  
        "amount": "3.70",
        "currency": "EUR"
     },
     "shippingAmount": {  
         "amount": "10.00",
         "currency": "EUR"
    },
    "orderExpiryMilliseconds": 6000000,
    "channel": "scalapay.com",
    "type":"online",
    "product":"pay-in-3",
    "frequency":{
        "number": 1,
        "frequencyType":"monthly"
    },
    "extensions": {
        "industry":{
            "travel": {
                "startDate": "2023-11-30",
                "endDate": "2023-12-18",
                "date": "2023-06-01",
                "refundable": true|false,
                "transportationReservationDetails": [
                    {
                        "type": "air|train|bus|ferry",
                        "departure": "BCN",
                        "arrival": "MXP",
                        "ticketClass": "economy|premium_economy|business|first|other",
                        "ticketType": "one_way|return|other",
                        "loyaltyProgramme": true|false
                    }
                ],
                "hotelReservationDetails": {
                    "nights": 4,
                    "hotelName": "Best Western",
                    "hotelCountry": "IT",
                    "hotelStars": 4,
                    "insurance": true|false,
                    "loyaltyProgramme": true|false
                },
                "events": {
                    "eventName": "Muse Concert in Rome",
                    "eventCountry": "IT",
                    "category": "concert|club|festival|experience|...",
                    "ticketType": "singleuse|subscription"
                }
            }
        },    
  }

get order details
This GET call checks the status of order.

It is not mandatory, but highly recommended in order to check the status of the order before sending the capture call. Please note that only authorized orders can be captured.

capture order
This POST call is the final one and is mandatory to correctly finalize the order.

Once capture call is made, the first installment is deducted from the user card and the order status is updated to charged.

Scalapay will respond with a success or a failure.

1440

📘

API Simulator

In this section, you can find the API Simulator that allows you to test the API calls and to know for each API call, how Scalapay will respond