Save addresses & customer details
The cart stores the invoice and delivery address as well as additional customer information like email, phone etc
This method will automatically separate order and customer information based on the fields available in those models.
Attention: The available fields can vary depending on the configuration of your Hublify system.
Tipp: Provided fields will be merged with already saved other cart-data, so depending on your checkout setup, you can provide all data at once or in multiple calls.
Request
Request URL
https://{your hublify url}/api/eos_10/cart_setAddressesRequest parameter
{
"filter": {
"cart_id": 123
},
"fields": {
"invoice_company": "",
"invoice_gender": "male",
"invoice_firstname": "Max",
"invoice_lastname": "Muster",
"invoice_addrextra": "",
"invoice_street": "Sample Street",
"invoice_housenr": "1b",
"invoice_zip": "22222",
"invoice_town": "Hamburg",
"invoice_country": "DE",
"invoice_email": "max.muster.de",
"deliver_company": "",
"deliver_gender": "male",
"deliver_firstname": "Max",
"deliver_lastname": "Muster",
"deliver_addrextra": "",
"deliver_street": "Sample Street",
"deliver_housenr": "1b",
"deliver_zip": "22222",
"deliver_town": "Hamburg",
"deliver_country": "DE",
"telephone": "+4940123456", // customer detail phone number
"telephone_mobile": "+491601234567", // customer detail mobile number
"email": "max@muster.de", // customer details email
"bday": "2020-12-31" // customer birthday
}
}Response
You get a status acknowledging the success of your request.
{ "status": true}
Get shipping options and costs
If you configured multiple shipping options in your Hublify system, you can get the list of options that are valid for your current cart.
If already set, this will filter the shipping options based on
- invoice and delivery country
- weight and total amount
- selected payment method (optional)
Request
Request URL
https://{your hublify url}/api/eos_10/cart_getShippingOptionsRequest parameter
{
"filter": {
"cart_id": 123
},
"payment_filter_enable": true // optional (default: false) also check against current payment-selection
}Response
You receive a list of possible shipping options
{
"status": true,
"data": [
{
"st_id": "1", // Hublify internal ID for the shipping type
"st_grp_name": "Standardlieferung",
"st_label": "Standard", // Label for the shipping type
"st_desc": null,
"st_deliver_category": "delivery", // delivery|pickup
"st_xcost_value_abs": "3.0000", // absolute costs for this type
"st_xcost_value_rel": null, // relative costs for this type in %
"st_xcost_value_min": null, // min costs for this type
"st_xcost_value_max": "10000.0000", // max costs for this type
"oo_default": "0",
"oo_settings": null,
"drvd_xcost_brutto": 3, // absolute and relative costs combined based on your current cart total (incl.vat)
"drvd_xcost_netto": 2.52, // absolute and relative costs combined based on your current cart total (without vat)
"drvd_xcost_total": 3
},
{
"st_id": "2",
"st_grp_name": "Expressversand",
"st_label": "Express",
"st_desc": null,
"st_deliver_category": "delivery",
"st_xcost_value_abs": "4.5000",
"st_xcost_value_rel": "1.0000",
"st_xcost_value_min": null,
"st_xcost_value_max": "10000.0000",
"st_xcost_xdata": {
"weight_scale": {
"1000": "6.40",
"2000": "10.35",
"5000": "11.30",
"10000": "12.10",
"15000": "13.75",
"20000": "19.10",
"30000": "20.90",
"50000": "32.80",
"100000": "52.15",
"200000": "93.80"
}
},
"oo_default": "0",
"oo_settings": null,
"drvd_xcost_brutto": 4.65,
"drvd_xcost_netto": 3.91,
"drvd_xcost_total": 4.65
}
]
}Save shipping details
If you configured multiple shipping options in your Hublify system, you can override the default shipping type with the customer selection.
Request
Request URL
https://{your hublify url}/api/eos_10/cart_setShippingRequest parameter
{
"filter": {
"cart_id": 123
},
"fields": {
"fk_o_stid": 2, // The Hublify internal ID for the shipping type
"shipping": [] // additional data specific for the shipping type if needed
}
}Response
You get a status acknowledging the success of your request.
{ "status": true}
Get payment options and costs
If you configured multiple payment options, you can get the list of options that are vald for your current cart.
If already set, this will filter the payment options based on
- invoice and delivery country
- total amount
- selected shipping method (optional)
- customer specific restrictions (e..g. number of previous orders)
Request
Request URL
https://{your hublify url}/api/eos_10/cart_getPaymentOptionsRequest parameter
{
"filter": {
"cart_id": 123
},
"shipping_filter_enable": true // optional (default: false) also check against current shipping-selection
}Response
You receive a list of available payment options
{
"status": true,
"data": [
{
"pys_id": "1", // The Hublify internal ID for the payment method
"pys_method": "Remittance", // Hublify internal label for the payment method
"pys_desc": "Vorkasse", // Human readable name
"pys_xcost_value_abs": "0.0000", // absolute costs for this type
"pys_xcost_value_rel": "0.0000", // relative costs for this type in %
"pys_xcost_value_min": "0.0000", // min costs for this type
"pys_xcost_value_max": "10000.0000", // max costs for this type
"pys_pos": "0",
"pyp_id": "1",, // The Hublify internal ID for the payment provider
"pyp_label": "ecs_intern", // Hublify internal label for the payment provider
"pyp_classname": "ecsself",
"oo_default": "1",
"drvd_xcost_brutto": 0, // absolute and relative costs combined based on your current cart total (incl.vat)
"drvd_xcost_netto": 0, // absolute and relative costs combined based on your current cart total (without vat)
"drvd_xcost_total": 0
},
{
"pys_id": "7",
"pys_method": "PaypalEC",
"pys_desc": "PayPal Express",
"pys_xcost_value_abs": "0.0000",
"pys_xcost_value_rel": "0.0000",
"pys_xcost_value_min": "0.0000",
"pys_xcost_value_max": "10000.0000",
"pys_pos": "0",
"pyp_id": "5",
"pyp_label": "paypal",
"pyp_classname": "paypal",
"oo_default": "0",
"drvd_xcost_brutto": 0,
"drvd_xcost_netto": 0,
"drvd_xcost_total": 0
}
]
}Save payment details
If your system offers multiple payment options, you can override the default payment method with the customer selection.
Depending on the selected payment method, addtional data might be required.
Request
Request URL
https://{your hublify url}/api/eos_10/cart_setPaymentRequest parameter
{
"filter": {
"cart_id": 123
},
"fields": {
"pys_id": 1, // The Hublify internal ID for the payment method
"payment": [] // additional data needed for this payment type
}
}Response
You get a status acknowledging the success of your request.
{
"status": true
}Finalize the purchase
Once you collected all relevant data, you can finalize the purchase and create an order from your cart.
Request
Request URL
https://{your hublify url}/api/eos_10/cart_purchaseRequest parameter
{
"filter": {
"cart_id": 123
}
}Response
If your request was successful, you get the data for your newly created order
{
"status": true,
"data": {
"oid": 12345, // Hublify internal primary id for the order
"orderid": "A00012345", // Hublify internal order-id created.
"persid": 1234, // Hublify internal primary id for the customer
"payment": {
"amount": "14.56", // Total amount of the created payment-transaction
"currency": "EUR", // Currency the transaction was created in
"transid": 2539 // Hublify internal primary id for the created payment-transaction
}
},
"msg": null,
}On default, the cart-record would be deleted after a successful purchase.
If you want to preserve it for future use, add Parameter "skip_cart_delete" to your purchase request.
Request URL
https://{your hublify url}/api/eos_10/cart_purchaseRequest parameter
{
"skip_cart_delete": true,
"filter": {
"cart_id": 123
}
}Final checks
Before the purchase is finalized, all items in the cart will be checked one last time and invalid items will be removed or updated.
If an item was changed or removed on this final check, the purchase will not be finalized just yet.
You receive an error status in this and a message explaining what happened.
In this case you should show the customer a cart overview once again to give him a chance to review the changes.
You also receive the flag "can_purchase" if the adjusted cart can be purchased without the need for active changes.
In this case the can customer can trigger "cart_purchase" once again.
Response examples
Quantity in stock is lower than the requested quantity of an item. The quantity of the product was reduced to match the available stock.
{
"status": false,
"data": null,
"msg": [
{
"type": "ERROR",
"i18n": {
"string": "ecs.CARTITEM.storage_counter_too_low",
"params": {
"name": "Demo Product",
"pcode": "HFY1234"
}
}
}
],
"can_purchase": true // indicates that the purchase can be triggered again once the customer reviewed the change
}Product is no longer in stock. Item was removed from the cart.
{
"status": false,
"data": null,
"msg": [
{
"type": "ERROR",
"i18n": {
"string": "ecs.CARTITEM.storage_counter_empty",
"params": {
"name": "Demo Product",
"pcode": "HFY1234"
}
}
}
],
"can_purchase": true // indicates that the purchase can be triggered again once the customer reviewed the change
}Coupon is not valid and was removed.
{
"status": false,
"data": null,
"msg": [
{
"type": "WARNING",
"i18n": {
"string": "ecs_plugin_coupon.COUPON.deleted_from_cart",
"params": {
"coupon_code": "DemoCoupon"
}
}
}
],
"can_purchase": true // indicates that the purchase can be triggered again once the customer reviewed the change
}Execute the payment transaction
Depending on the selected payment method, additional user interaction might be required once the order was created.
This would typically require you to direct the user to an external url (via iframe or redirect).
If your payment method was configured accordingly, you would already receive the "redirectURL" as part of the payment-data in the cart_purchase result.
Response
{
"status": true,
"data": {
"oid": 12345, // Hublify internal primary id for the order
"orderid": "A00012345", // Hublify internal order-id created.
"persid": 1234, // Hublify internal primary id for the customer
"payment": {
"amount": "14.56", // Total amount of the created payment-transaction
"currency": "EUR", // Currency the transaction was created in
"transid": 2539, // Hublify internal primary id for the created payment-transaction
"redirectURL": "https:\/\/www.example.com" // An external URL specific to this transaction and the selected payment method
}
},
"msg": null,
}Alternatively you can start the process yourself.
You have the option to update some transaction parameters before the execution.
Which ones depends on the selected payment method.
Request
Request URL
https://{your hublify url}/api/eos_10/transaction_executeRequest parameter
{
"filter": {
"transid": 2539 // this is the transaction ID you received with your order
},
"fields": {
"transparams": {
"returnURLsuccess": "https:\/\/back.example.com/success", // A URL on your system the user should be redirected to after a successful payment
"returnURLerror": "https:\/\/back.example.com/failed" // A URL on your system the user should be redirected to after a failed/aborted payment
}
},
}Response
If your request was successful, you get the details for this transaction. You have to redirect the user to the URL returned in "redirectURL".
{
"status": true,
"data": {
"amount": "14.56", // Total amount of the created payment-transaction
"currency": "EUR", // Currency the transaction was created in
"transid": 2539, // Hublify internal primary id for the created payment-transaction
"redirectURL": "https:\/\/www.example.com" // An external URL specific to this transaction and the selected payment method
},
"msg": null,
}On return the user will be redirected to the provided success or error URL.
We will automatically add the "transid" and "oid" to the provided URLs to help you identify the returning transaction.
On success, the user would be redirected to
"https://back.example.com/success?transid=2539&oid=12345"
On error, the user would be redirected to
"https://back.example.com/failed?transid=2539&oid=12345"
Retry executing the payment
If the user does not complete the payment transaction successfully on the first try, you can retry it with the same Endpoint as before.
E.g. if the user was redirected back to your "returnURLerror".
The order stays available, so you only have to repeat the payment execution.
If the payment method and your provided additional parameters stay the same for another try, you don't have to provide them again.
All you need is the "transid" in that case.
Request
Request URL
https://{your hublify url}/api/eos_10/transaction_executeRequest parameter
{
"filter": {
"transid": 2539 // this is the transaction ID you received with your order
}
}Response
If your request was successful, you get the details for this transaction. You have to redirect the user to the URL returned in "redirectURL".
{
"status": true,
"data": {
"amount": "14.56", // Total amount of the created payment-transaction
"currency": "EUR", // Currency the transaction was created in
"transid": 2539, // Hublify internal primary id for the created payment-transaction
"redirectURL": "https:\/\/www.example.com" // An external URL specific to this transaction and the selected payment method
},
"msg": null,
}On return the user will be redirected to the previously provided success or error URL.
We will automatically add the "transid" and "oid" to the provided URLs to help you identify the returning transaction.
On success, the user would be redirected to
"https://back.example.com/success?transid=2539&oid=12345"
On error, the user would be redirected to
"https://back.example.com/failed?transid=2539&oid=12345"
Alternative Filter
If you don't have the "transid" available, you can also call "transaction_execute" with "oid" or "orderid" as Filter.
Request
Request URL
https://{your hublify url}/api/eos_10/transaction_executeRequest parameter
{
"filter": {
"orderid": "A00012345" // this is the orderid the transaction was created for
},
"fields": {
"transparams": {
"returnURLsuccess": "https:\/\/back.example.com/success", // A URL on your system the user should be redirected to after a successful payment
"returnURLerror": "https:\/\/back.example.com/failed" // A URL on your system the user should be redirected to after a failed/aborted payment
}
},
}