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
Field Type Description orderReference String Order Merchant ID startDate YYYY-MM-DD The date of the travel / check-in or event endDate YYYY-MM-DD The date of the check-out date (where applicable) description String Description of the travel paymentType Enum "deposit" , "balance" , "full" insuranceType Enum "full" , "partial" , "none" refundeType Enum "full" , "partial" , "none" pax Integer Number of people travelling paxDetails Object - see dedicated data model below for more info Any extensions properties that are required for the type (e.g.: givenNames) transportations Object - see dedicated data model below for more info Any extensions properties that are required for the type (e.g.: type) rentals Object - see dedicated data model below for more info Any extensions properties that are required for the type (e.g.: type) accomodations Object - see dedicated data model below for more info Any extensions properties that are required for the type (e.g.: type) experiences Object - see dedicated data model below for more info Any extensions properties that are required for the type (e.g.: type) paxDetails
Field Type Description givenNames String First names of the traveler/s surname String Last name of the traveler/s dateOfBirth YYYY-MM-DD Birth date of the traveler/s transpostations
Field Type Description type Enum "flight" , "ferry" , "bus" carrier String Name of the carrier class Enum "economy" , "premium" , "business" , "first" , "smart" , "other" departure Object See below the data model arrival Object See below the data model departure
Field Type Description portCode String Please use these lists as reference:
- https://en.wikipedia.org/wiki/List_of_airports_by_IATA_airport_code:_Aflights
- https://freightanchor.com/resources-sea-ports-codesmaritime routescountryCode String Please use https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2this list as reference arrival
Field Type Description portCode String Please use these lists as reference:
- https://en.wikipedia.org/wiki/List_of_airports_by_IATA_airport_code:_Aflights
- https://freightanchor.com/resources-sea-ports-codesmaritime routescountryCode String Please use https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2this list as reference rentals
Field Type Description type Enum "car" , "bike" , "bicycle" name String Rental company name pickupCity String City name dropoffCity String City name accomodations
Field Type Description type Enum "hotel" , "hostel" , "B&B" name String Hotel name group String Hotel group name city String City name postalCode String Please add the city postal code countryCode String Please use https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2this list as reference berth String - class String - experiences
Field Type Description type Enum "concert" , "tour" name String Experience name city String City name countryCode String Please use https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2this list as reference ticketType Enum "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.
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 9 months ago