Card Payments

Take card payments through the API

To use this capability add octo/cardPayments to your Octo-Capabilities header.

This capability allows you to accept card payments via the API. It is possible to support multiple gateways, we document 4 in this spec: VivaWallet Adyen Stripe and External

If you want us to add support for any other gateway please contact us at [e-mail]

Adyen Gateway

We add a cardPayment key to the booking object, but if you're using the octo/cart capability then we add the same key to that as well. The value will look like this:

// ..rest of the booking or order object
"cardPayment": {
  "gateway": "adyen",
  "adyen": {
    "environment": "live",
    "clientKey": "test_870be2...",
    "session": null,
    "paymentMethodsConfiguration": {
      "card": {
        "hasHolderName": true,
        "holderNameRequired": true,
        "billingAddressRequired": true
      }
    }
  }
}

In the response we provide all the values required to initialize Adyen's Drop-in Widget which you can find documented here:

Build your integration | Adyen Docs

Adyen Drop-in Integration Docs

The session field will be null until you have provided a returnUrl field on the order which will be used by the Adyen integration to redirect the guest after the payment is complete.

PATCH /orders/:id or PATCH /bookings/:uuid
{ "returnUrl": "https://www.example.com/redirect" }

Following that the response body will include the session data like so:

// ..rest of the booking or order object
"cardPayment": {
  "gateway": "adyen",
  "adyen": {
    "environment": "live",
    "clientKey": "test_870be2...",
    "session": {
      "id": "CSD9CAC3...",
      "sessionData": "Ab02b4c..."
    },
    "paymentMethodsConfiguration": {
      "card": {
        "hasHolderName": true,
        "holderNameRequired": true,
        "billingAddressRequired": true
      }
    }
  }
}

Once complete, and you're ready to confirm the order/booking then you must replay the sessionId back to the API like so:

POST /bookings/:uuid/confirm POST /orders/:orderId/confirm

{
  "cardPayment": {
    "gateway": "adyen",
    "adyen": {
      "sessionId": "CSD9CAC3..."
    }
  }
}

If Ventrata hasn't yet received the webhook notification from Adyen then you may receive a PAYMENT_PENDING error code returned, you can just repeat the confirm request until it works. If the payment is refused, you'll get a BAD_REQUEST error with the error message in the errorMessage field and a new session will be generated for you to try again with.

Unencrypted Card Payment

It's also possible to authorise an Adyen payment with unencrypted card details, the request body will be like:

// ..rest of the booking or order object
"cardPayment": {
  "gateway": "adyen",
  "adyen": {
    "paymentMethod": {
      "type": "scheme",
      "number": "4111111111111111",
      "expiryMonth": "03",
      "expiryYear": "2030",
      "holderName": "John Smith",
      "cvc": "737"
    }
  }
}

VivaWallet Gateway

We add a cardPayment key to the booking object, but if you're using the octo/cart capability then we add the same key to that as well. The value will look like this:

// ..rest of the booking or order object
"cardPayment": {
  "gateway": "vivawallet",
  "vivawallet": {
    "orderCode": 1272214778972604
  }
}

In the response we provide orderCode value which you can use to initiate the VivaWallet Smart Checkout as described in the documentation here:

Smart Checkout

VivaWallet Smart Checkout

As described in the docs, in production you just redirect the guest to a URL like so:

https://www.vivapayments.com/web2?ref=1272214778972604

Where the value for ref is the orderCode returned in the card payment object. The documentation also describes various ways to customise the checkout including using custom colors and payment methods.

Once the payment is complete, the customer will be redirected back to the Success URL or Failure URL as setup in your gateway account. If directed to the Success URL you will also receive a query parameter t which is a UUID (example t=2b4c6b5b-49ff-4e46-adc5-f53740212361), you must then send this to Ventrata along with the original orderCode using either of the confirmation endpoints (depending if you're using the octo/cart capability):

POST /bookings/:uuid/confirm POST /orders/:orderId/confirm

{
  "cardPayment": {
    "gateway": "vivawallet",
    "vivawallet": {
      "orderCode": 1272214778972604,
      "transactionId": "2b4c6b5b-49ff-4e46-adc5-f53740212361"
    }
  }
}

Ventrata will then verify the payment has actually been approved and if so will confirm the order.

Spreedly Gateway

We add a cardPayment key to the booking object, but if you're using the octo/cart capability then we add the same key to that as well. The value will look like this:

// ..rest of the booking or order object
"cardPayment": {
  "gateway": "spreedly",
  "spreedly": {
    "env": "C7cRfNJGODKh4Iu5Ox3PToKjniY"
  }
}

In the response we provide env value which you can use with Spreedly's Express Payment Form or Javascript API described in the documentation here:

Express Payment FormSpreedly

On the client side, the payment page should look something like this:

<form id="payment-form" action="https://yoursite.com/checkout">
  <input type="hidden" name="payment_method_token" id="payment_method_token">
  <input type="button" value="Enter Payment Info" onclick="SpreedlyExpress.openView();">
</form>

<script src="https://core.spreedly.com/iframe/express-3.min.js"></script>
<script>
SpreedlyExpress.init("C7cRfNJGODKh4Iu5Ox3PToKjniY", {
  "amount": "$9.83",
  "company_name": "Acme Widgets",
  "sidebar_top_description": "Providing quality widgets since 2015",
  "sidebar_bottom_description": "Your order total today",
  "full_name": "First Last"
}, {
  "email": "[e-mail]"
});

SpreedlyExpress.onPaymentMethod(function(token, paymentMethod) {

  // Send requisite payment method info to backend
  var tokenField = document.getElementById("payment_method_token");

  tokenField.setAttribute("value", token);

  var masterForm = document.getElementById('payment-form');
  masterForm.submit();
});
</script>

The value of token which in this example we set on the hidden input field in the form. You must then send this to Ventrata using either of the confirmation endpoints (depending if you're using the octo/cart capability):

POST /bookings/:uuid/confirm POST /orders/:orderId/confirm

"cardPayment": {
  "gateway": "spreedly",
  "spreedly": {
    "env": "C7cRfNJGODKh4Iu5Ox3PToKjniY",
    "paymentMethodToken": "56wyNnSmuA6CWYP7w0MiYCVIbW6"
  }
}

Ventrata will then use the card token to authorise and capture the payment amount on the order and confirm the booking.

External Gateway

The external gateway is the simplest and isn't actually a gateway at all. It allows you to register a virtual card payment which might have been taken on another gateway not supported by Ventrata.

We add a cardPayment key to the booking object, but if you're using the octo/cart capability then we add the same key to that as well. The value will look like this:

// ..rest of the booking or order object
"cardPayment": {
  "gateway": "external"
}

Once the payment is confirmed you can perform either:

POST /bookings/:uuid/confirm POST /orders/:orderId/confirm

The second endpoint is if you're using the octo/cart capability. You can then optionally include notes in the external field which will can record an external payment reference which might be useful for backend reconciliation later. For example:

{
  "cardPayment": {
    "gateway": "external",
    "amount": 9130,
    "currency": "EUR",
    "notes": "Ref#25172328"
  }
}

Reusable Cards

If the order has had existing transactions made against it using cards that are re-usable it's possible to use the same card again without requiring any input from the guest. There is a "reusableCards" field on the gateway which will be populated with the cards that you can re-use like:

"cardPayment": {
  "gateway": "adyen",
  "reusableCards": [
    {
      "id": "a22bf21c-6af1-443c-aade-27ad306e5380",
      "brand": "Visa",
      "bin": "123456",
      "last4": "4321",
      "expMonth": 4,
      "expYear": 2030
    }
  ]
}

Whenever a gateway has a reusable card you're able to use it during checkout simply by including cardId in the card payment object, for example:

{
  "cardPayment": {
    "gateway": "adyen",
    "cardId": "a22bf21c-6af1-443c-aade-27ad306e5380"
  }
}