telecoms.cart function

Home > telephony > nts > function-reference > func.telecoms.cart

function telecoms.cart

NTS Telephony Shopping Cart Functions

Functions

`telecoms.cart.assign`	(supplier function) - migrate a cart created under a master API account to a customer account so that it can be checked out; this is useful if your customer isn't currently logged in or hasn't yet created an account but you want them to put numbers into their cart before they do as part of the signup process.
`telecoms.cart.checkout`	Complete the purchase of items in the shopping cart; takes payment, raises invoice and adds numbers to your account in one call
`telecoms.cart.create`	create a new empty shopping cart instance
`telecoms.cart.delete`	delete a shopping cart instance
`telecoms.cart.edit`	add, remove or change things in your shopping cart
`telecoms.cart.get`	fetch the detail of a shopping cart instance
`telecoms.cart.list`	fetch a list of all current shopping cart instances

What can I do with these functions?

Use these functions to browse for available numbers and add them to your account. Some numbers incur a setup fee. The cart takes payment, raises an invoice and allocates the numbers when you check out.

You can have multiple separate carts at the same time; simply use the cartID to identify each one. This allows you to have several customers browsing your site and putting numbers into their own carts without them interfering with each other. The cart system manages number reservations automatically, so if one customer puts a number into their cart, it won't be available to anyone else unless they remove it from their cart or they go away and let the reservation time out.

Each time you call telecoms.cart.create, telecoms.cart.edit or telecoms.cart.get the cart system refreshes the reservations for any phone numbers in that cart. If you ensure that you call one of those functions regularly (eg whenever your customer refreshes the page) then it keeps the reservations fresh and prevents them from timing out.

Number reservations time out after 15 minutes, after which time there can be no guarantee that the number(s) will still be available. However, if you regularly update (with telecoms.cart.edit) or fetch (with telecoms.cart.get the contents of the cart, these reservations will be renewed back to the full 15 minutes each time.

How do I use these functions?

The basic technique is this:

use telecoms.num.browse to find some available numbers
use telecoms.cart.create to create a cart instance if you have not already done so; this will return a cartID which you will use to refer to this cart instance later.
use telecoms.cart.edit to add numbers to the cart (or remove some if the customer changes their mind)
use telecoms.cart.get if you just need to query the cart contents
repeat the above steps until the customer is ready to check out
call telecoms.cart.checkout to finish, which will take payment and raise an invoice as necessary, and put the numbers onto the customer's account

Checking out

When you have finished putting numbers into your cart, you need to call telecoms.cart.checkout. If there are non-free items in your cart, some form of payment will need to be taken; telecoms.cart.checkout will do this for you.

There are three payment options:

interactive - the URL of a card entry form will be returned. You should redirect the user to this page. Other arguments will be required. This option is only suitable for our own systems letting our own customers browse and add numbers.
stored_card - make payment with a payment card already stored on the system
after_invoice - no additional payment will be taken at the time; this requires you to have a sufficient account balance to cover the cost of the items in the cart

If you are a reseller adding numbers to your account while your customer is purchasing through your site, there will typically be two separate payments:

your customer's payment to you
your payment to us

You would typically take payment from your customer first* along with any markup and only once this has been successful would you check out yourself. If you wish to pay with a card you already have stored on our system, you would use the stored_card payment method. Alternatively, if you have sufficient balance in your account to cover the cost of the items being checked out, you can use after_invoice.
* you will need to perform this step separately, independently of our API.

after_invoice is the most reliable payment method as it does not rely on an external payment succeeding. For resellers we therefore recommend they maintain a sufficient account balance and use this payment method for checking out to complete an order for a customer who has just paid you. If you instead choose to pay with a stored card but that payment fails, the cart will not check out. If you have a stored card on your account and wish to automate payments to maintain a balance, you can use payment.take to top up your account balance.

Each time the cart is updated or fetched, the returned data will show you the price of each individual item and also the total and VAT that will be charged. You will therefore know the size of payment that will be taken/due when you check out.

How do I create a cart if the customer is not logged in?

When you create a cart, you would normally create it with the custID of the customer. However, if the customer has not yet logged in and is just browsing and choosing numbers, you won't yet know their custID.

In these cases, you can create a cart in your master API account. You will want to ensure that the customer logs in (or creates an account - see cust.create) before they can check out. Once either of these actions has been performed, you will then have their custID. Once you have this, you can call telecoms.cart.assign to assign that cart to that custID. From that point, the customer's account owns the cart and you can call telecoms.cart.checkout using the customer's own API logins.