The steps required to take and verify a payment are as follows.

1. Initiate the card reader with the amount to charge
2. Direct the user to interact with the payment terminal
3. The user pays for their item
4. The amount of money is 'reserved' on the card
5. Your application attempts a vend
6. If the vend is successful the card is charged

API

Hold

You can hold the payment which puts a hold on the card for a specific amount, but waits before taking the money from their account. This means that if the vend fails, for whatever reason, we can instantly refund the user. For purchasing decisions this is the best way to initiate a payment as it allows for a failed vend to happen in the meantime.

This method is used in conjunction with OS.Payment.charge.confirm(), which ratifies the charge with some or all of the money held.

OS.Payment.charge.hold({
  amount: 21.00,
  reference: 'Some reference'
}).then(res => {
  // Successful hold placed
  console.log(res)
}).catch(err => {
  // Payment declined or the user canceled
  console.error(err)
})

Properties

Instant

This method instantly charges the card (without putting a payment on hold). This is not recommended when vending purchased products, but may be useful in scenarios where vending isn't needed, or when the success of a vend isn't important. The charge is made instantly and you do not need to call OS.Payment.charge.confirm() afterwards.

OS.Payment.charge.instant({
  amount: 21.00,
  reference: 'Some reference'
}).then(res => {
  // Successful charge
  console.log(res)
}).catch(err => {
  // Payment declined or the user canceled
  console.error(err)
})

The OS.Payment.charge.instant() method takes the same arguments and has the same possible responses as OS.Payment.charge.hold().

Confirm

This will confirm a held charge on the card; and can only be used if a call to Payment.charge.hold() has previously been successful.

You should only confirm the payment once the product has vended. This will only work if there is an outstanding hold placed.

OS.Payment.charge.confirm().then(res => {
  // Payment successful
  console.log(res)
}).catch(err => {
  // Payment declined or the user canceled
  console.error(err)
})

Cancel

Cancelling a payment should be done if the item has not been vended. You can also place a button in your UI to cancel a payment. This can be called any time after the hold is initiated.

OS.Payment.charge.cancel()

Full example

OS.Payment.charge.hold({amount: 21.00}).then(() => {
  // Successful hold placed
  return OS.Machine.vend.optimal()
}).then(() => {
  // Item successfully vended
  return OS.Payment.charge.confirm()
}).then(res => {
  // Card charged
  console.log(res)
}).catch(err=>{
  switch(err.code) {
    case 'VEND_FAILED':
      console.log('Vend failed')
      OS.Payment.charge.cancel() // Refund the user
      break;
    default:
      console.err(err.code)
  }
})

Errors

vendOS DevTools currently only supports two error codes for Payment.charge, but more granular codes will be added soon.

Receipts

We do not currently handle receipting in vendOS, and so we encourage users of the Payment API to issue their own receipts to customers via email. This should be done in accordance with whatever consumer laws are relevant to the sale.

Receipting is something that we may add at a future date; so do watch this space or feel free to email us in support of this feature at [email protected].