Accept card payments online - Vori Help Center

Use the Vori Payments API to tokenize a shopper’s card in the browser, charge it through the payment processor configured for the store, and issue full or partial refunds.

Online card payments are a beta feature. Contact Vori Support to enroll.

Never send raw card numbers, expiration dates, or CVV values to Vori or your own server. Tokenize the card in the shopper’s browser and send only the one-time token to your server.

Before you begin

You need:

A Vori API key with access to the store and payments.
The store ID.
An e-commerce merchant account for live payments. Contact Vori Support if the store does not have one.
A public tokenization key from the store’s ecommerce_credentials property.

Use mode: "test" while developing. Test payments move no money. Switch both tokenization and API requests to mode: "live" only after the store’s live e-commerce merchant account is ready.

Get the store’s public key

Retrieve the store:

curl "https://api.vori.com/v1/stores/<store_id>" \
  -H "Authorization: Bearer sk_live_<secret>"

The response includes up to one public key for each mode:

{
  "id": "<store_id>",
  "ecommerce_credentials": [
    {
      "mode": "live",
      "public_key": "<live_public_key>"
    },
    {
      "mode": "test",
      "public_key": "<test_public_key>"
    }
  ]
}

The live credential is absent until the store has an e-commerce merchant account. A test credential can be used only with test tokenization and mode: "test" API requests.

Tokenize the card in the browser

Load the Datacap JavaScript client that matches the payment mode:

Live: https://token.dcap.com/v1/client
Test: https://token-cert.dcap.com/v1/client

Add data-token attributes to the card inputs. Pass the store’s matching public key, the form ID, and a callback to DatacapWebToken.requestToken.

<form id="payment-form">
  <label>
    Card number
    <input type="text" inputmode="numeric" data-token="card_number" autocomplete="cc-number" required>
  </label>

  <label>
    Expiration month
    <input type="text" inputmode="numeric" data-token="exp_month" autocomplete="cc-exp-month" maxlength="2" required>
  </label>

  <label>
    Expiration year
    <input type="text" inputmode="numeric" data-token="exp_year" autocomplete="cc-exp-year" maxlength="4" required>
  </label>

  <label>
    CVV
    <input type="text" inputmode="numeric" data-token="cvv" autocomplete="cc-csc" maxlength="4" required>
  </label>

  <button type="submit">Pay</button>
</form>

<script src="https://token-cert.dcap.com/v1/client"></script>
<script>
  const publicKey = "<test_public_key>";
  const form = document.getElementById("payment-form");

  form.addEventListener("submit", (event) => {
    event.preventDefault();

    DatacapWebToken.requestToken(publicKey, form.id, async (response) => {
      if (response.Error) {
        showPaymentError(response.Error);
        return;
      }

      await sendTokenToYourServer(response.Token);
    });
  });
</script>

The token is valid for one charge. Send it to your server immediately. Do not store it for later use.

Create the payment

Your server sends the token to POST /v1/payments:

curl -X POST "https://api.vori.com/v1/payments" \
  -H "Authorization: Bearer sk_live_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<one_time_token>",
    "amount": "42.17",
    "idempotency_key": "checkout-100234-payment-1",
    "store_id": "<store_id>",
    "mode": "test",
    "metadata": {
      "order_id": "100234"
    }
  }'

amount is in dollars and must be between 0.01 and 99999.99. Create a unique idempotency_key for each intended charge. If the request times out or its result is unclear, retry the same request with the same key and token. While the processor is still working, a retry can return HTTP 409 Conflict with error_code: "payment_in_progress" and the payment ID in error_details.payment_id. Continue retrying with the same key and token until Vori returns the captured payment or a definitive decline. Do not treat the first retry as the final outcome. A successful response includes the payment ID, status, payment mode, processor, and card details that are safe to display:

{
  "id": "pay_<payment_id>",
  "amount": "42.17",
  "idempotency_key": "checkout-100234-payment-1",
  "store_id": "<store_id>",
  "metadata": {
    "order_id": "100234"
  },
  "status": "captured",
  "mode": "test",
  "processor": "datacap",
  "payment_method": {
    "type": "card",
    "last4": "1111",
    "brand": "visa"
  }
}

Store the Vori payment id with your order. You need it to retrieve or refund the payment.

A gateway timeout does not prove the card was not charged. Retry with the same idempotency_key and token. Do not create a new key unless Vori confirms the original payment was declined.

Handle payment results

captured: The charge succeeded.
failed: The processor declined the charge. This status appears when you retrieve the payment, not in the create response.

A declined POST /v1/payments request returns HTTP 402 Payment Required with error_code: "card_declined". The error_details.payment_id property identifies the payment, and error_details.processor_message contains the processor’s explanation when available:

{
  "error_code": "card_declined",
  "error_details": {
    "payment_id": "pay_<payment_id>",
    "processor_message": "<processor_message>"
  }
}

Treat this HTTP error as a declined payment. If you subsequently retrieve error_details.payment_id, the payment response has status: "failed". Ask the shopper for another payment method and tokenize it again. A new charge requires a new token and a new idempotency key. Retrieve a payment at any time:

curl "https://api.vori.com/v1/payments/<payment_id>" \
  -H "Authorization: Bearer sk_live_<secret>"

List payments in one mode:

curl -G "https://api.vori.com/v1/payments" \
  -H "Authorization: Bearer sk_live_<secret>" \
  --data-urlencode 'mode=test' \
  --data-urlencode 'store_id=<store_id>'

A list never mixes live and test payments.

Refund a payment

Create a full or partial refund with POST /v1/refunds:

curl -X POST "https://api.vori.com/v1/refunds" \
  -H "Authorization: Bearer sk_live_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "pay_<payment_id>",
    "amount": "10.00",
    "idempotency_key": "checkout-100234-refund-1",
    "store_id": "<store_id>",
    "mode": "test",
    "metadata": {
      "reason": "item_unavailable"
    }
  }'

The store and mode must match the original payment. The total refunded across all refunds cannot exceed the payment amount. Vori chooses how to return the money:

void: Cancels a full charge before it settles, when the processor still permits it.
return: Sends money back to the card. Partial refunds always use this type.

Use a unique refund idempotency key for each intended refund. If the result is unclear, retry with the same key. Do not create a new key while the original refund may still be processing. Retrieve a refund:

curl "https://api.vori.com/v1/refunds/<refund_id>" \
  -H "Authorization: Bearer sk_live_<secret>"

List refunds for a payment:

curl -G "https://api.vori.com/v1/refunds" \
  -H "Authorization: Bearer sk_live_<secret>" \
  --data-urlencode 'mode=test' \
  --data-urlencode 'payment_id=pay_<payment_id>'

Go live safely

Confirm the live credential

Retrieve the store and verify ecommerce_credentials contains a live public key. If it is missing, contact Vori Support.

Load the production tokenizer

Change the Datacap script URL to https://token.dcap.com/v1/client and use the store’s live public key.

Use live mode on the server

Send mode: "live" for payments and refunds. Never mix a test token or credential with a live API request.

Verify one controlled payment

Run a small live charge, confirm its captured status, and refund it before opening checkout to shoppers.

Complete API reference

Download the OpenAPI specification for every request property, response property, filter, and error shape.

API

AI tools

Before you begin

Get the store’s public key

Tokenize the card in the browser

Create the payment

Handle payment results

Refund a payment

Go live safely

Complete API reference