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
Field Type Description Required persons_count Integer Number of passengers / guests / ticket holders / ... Y startDate YYY-MM-DD The date of the travel / check-in or event Y endDate YYY-MM-DD The number of nights or the date of the check-out date (where applicable) Y insurance Boolean Whether the user has opted for insurance Y transportationReservationDetails Object - see dedicated data model below for more info Any extensions properties that are required for the type (e.g.: transportation) N hotelReservationDetails Objet - see dedicated data model below for more info Any extensions properties that are required for the type (e.g.: hotel bookings) N events Object - see dedicated data model below for more info Any extensions properties that are required for the type (e.g.: event bookings) N transportationReservationDetails
Field Type Description Required type Enum type of travel ( air | train | bus | ferry ) Y departure Enum Departure location (IATA code or port code) Y arrival String Destination location (IATA code or port code) Y ticketClass String Class of ticket booked ( economy | premium_economy | business | first | other ) Y ticketType Enum Type of journey booked ( one_way | return | other) N loyaltyProgramme Boolean Whether the user has supplied a loyalty programme N hotelReservationDetails
Field Type Description Required nights Integer Number of nights the reservation is for Y hotelCountry String Name of hotel Y hotelCountry String Country code (ISO 3166-1 alpha-2) Y hotelStars Integer Number of stars that the hotel has N insurance Boolean Whether the user has opted for insurance N loyaltyProgramme Boolean Whether the user has supplied a loyalty programme N events
Field Type Description Required eventName String Name of the event Y eventCountry String Country of the event Y category Enum Category of the event ( concert | club | festival | experience ) Y ticketType Enum Type 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.
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
Updated about 2 months ago