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] )
  • 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

FieldTypeDescription
orderReferenceStringOrder Merchant ID
startDateYYYY-MM-DDThe date of the travel / check-in or event
endDateYYYY-MM-DDThe date of the check-out date (where applicable)
descriptionStringDescription of the travel
paymentTypeEnum"deposit" , "balance" , "full"
insuranceTypeEnum"full" , "partial" , "none"
refundeTypeEnum"full" , "partial" , "none"
paxIntegerNumber of people travelling
paxDetailsObject - see dedicated data model below for more infoAny extensions properties that are required for the type (e.g.: givenNames)
transportationsObject - see dedicated data model below for more infoAny extensions properties that are required for the type (e.g.: type)
rentalsObject - see dedicated data model below for more infoAny extensions properties that are required for the type (e.g.: type)
accomodationsObject - see dedicated data model below for more infoAny extensions properties that are required for the type (e.g.: type)
experiencesObject - see dedicated data model below for more infoAny extensions properties that are required for the type (e.g.: type)

paxDetails

FieldTypeDescription
givenNamesStringFirst names of the traveler/s
surnameStringLast name of the traveler/s
dateOfBirthYYYY-MM-DDBirth date of the traveler/s

transpostations

FieldTypeDescription
typeEnum"flight" , "ferry" , "bus"
carrierStringName of the carrier
classEnum"economy" , "premium" , "business" , "first" , "smart" , "other"
departureObjectSee below the data model
arrivalObjectSee below the data model

departure

arrival

rentals

FieldTypeDescription
typeEnum"car" , "bike" , "bicycle"
nameStringRental company name
pickupCityStringCity name
dropoffCityStringCity name

accomodations

FieldTypeDescription
typeEnum"hotel" , "hostel" , "B&B"
nameStringHotel name
groupStringHotel group name
cityStringCity name
postalCodeStringPlease add the city postal code
countryCodeStringPlease use https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2this list as reference
berthString-
classString-

experiences

FieldTypeDescription
typeEnum"concert" , "tour"
nameStringExperience name
cityStringCity name
countryCodeStringPlease use https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2this list as reference
ticketTypeEnum"one-entry" , "season-pass" , "none"

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"
    },
    "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"
    },
    "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": {
        "orderReference": "ASLKJ9320JD09J2",
        "startDate": "2020-01-01",
        "endDate": "2020-01-03",
        "description": "Travel Package",
        "paymentType": "deposit",
        "insuranceType": "full",
        "refundType": "full",
        "pax": 2,
        "paxDetails": [
          {
            "givenNames": "John",
            "surname": "Doe",
            "dateOfBirth": "2000-01-01" 
          },
          {
            "givenNames": "Jane Francisca",
            "surname": "Binay",
            "dateOfBirth": "2002-01-01" 
          }
        ],
        "transportations": [
          {
            "type": "flight", 
            "carrier": "Cebu Pacific",
            "class": "Economy",
            "departure": {
              "portCode": "MNL", 
              "countryCode": "PH" 
            },
            "arrival": {
              "portCode": "CEB", 
              "countryCode": "PH" 
            }
          },
          {
            "type": "ferry", ***  ENUM TBD?
            "carrier": "2GO",
            "class": "Economy",
            "departure": {
              "portCode": "20123", 
              "countryCode": "IT" 
            },
            "arrival": {
              "portCode": "PHBOH", 
              "countryCode": "PH" 
            }
          }
        ],
        "rentals": [
          {
            "type": "car",
            "company": "Avis",
            "pickupCity": "Manila"
            "dropoffCity": "Bohol"  
          }
        ],
        "accommodations": [
          {
            "type": "hotel", 
            "name": "Shangri-La Makati",
            "group": "Shangri-La hotels and resorts",
            "city": "Milan", 
            "postalCode": "20123",
            "countryCode": "IT",
            "berth": "double",
            "class": "5-star"
          }
        ],
        "experiences": [
          {
            "type": "tour"
            "name": "Bohol Countryside Tour",
            "city": "Bohol"
            "countryCode": "IT"
            "ticketType": "one-entry"
          }
        ]
      }
    }
  }
}

❷ 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