Datacap Pay API
The Datacap Pay API provides a secure, hosted credit card payment form. Card data is tokenized by Datacap's secure script — the raw card number never touches your server.
Prerequisites
An admin must configure the Datacap Pay API before it can be used. This requires:
- A Datacap merchant account with a merchant ID (MID)
- The Datacap public key configured in the system
Once configured, the credit card payment form appears at checkout.
Payment Details Panel
When the customer reaches the payment step, a structured grid displays the full payment breakdown:
| Line Item | Description |
|---|---|
| Order ID | The order reference number |
| Subtotal | The order subtotal before tax and tips |
| Included Gratuity | Any gratuity already applied to the order (e.g., for parties), shown with the percentage and a note: "Applied to subtotal before tax" |
| Tax | The calculated tax amount |
| Total | The final amount to be charged, including any tip or surcharge |
When gratuity is included, the panel shows both the dollar amount and the percentage (e.g., "18%") along with a note indicating it was applied before tax. Accepted card types are shown via the accepted cards image.
Card Entry
The customer enters their card details:
- Card number — 13 to 19 digits
- Month (MM) — Expiration month (1–12)
- Year (YYYY) — Expiration year
- CVV — 3 or 4 digit security code
Each field is validated as the customer types. Invalid values (bad expiry, wrong card format, invalid CVV) show an alert icon.
Cards on File
Returning customers can select a previously saved card instead of entering a new one. Saved cards are available when the customer is assigned to the order.
Surcharge
An admin can configure a surcharge percentage that is added to credit card transactions. The surcharge appears on the payment details panel and is included in the total. If no surcharge is configured, this line is hidden.
Pre-Authorization
Pre-authorization places a hold on the customer's card without charging it. The charge is captured later when the order is finalized. This is common in restaurants and hotels: the card is authorized at seating, then charged when the bill is ready.
How Pre-Auth Works
When the order is flagged for pre-authorization, the Datacap payment form runs in pre-auth mode. After the customer's card is authorized:
- A confirmation appears: "Your order is now authorized. Go to the menu to add items, then fire them off to be made."
- A "Go to Menu" button takes the customer to the ordering screen.
- When the order is finalized, the authorized amount is captured (or a new total is charged).
- If the order is cancelled, the authorization can be reversed, releasing the hold on the card.
Pre-Auth Buttons
When pre-authorization is enabled, the following buttons appear on the payment screen after authorization:
| Button | Action |
|---|---|
| Authorize | Places a hold on the card without charging it |
| Complete Payment | Captures the authorized amount and charges the card |
| Reverse Authorization | Cancels the hold and releases the funds on the card |
Status Messages
| State | What You See |
|---|---|
| Loading | "Prepping Credit Card Payment" while the payment script loads |
| Processing | Spinner while the transaction is being processed |
| Approved | Payment response with status and confirmation |
| Declined | Error message with details about the decline |
Validation Errors
| Error | Meaning |
|---|---|
| Invalid EXP | Card expiration date is invalid |
| Invalid Card | Card number format is incorrect |
| Invalid CVV | CVV does not match expected 3 or 4 digits |
Security
Card data is tokenized by Datacap's hosted form. The raw card number never touches your server. A Security & Policies link (set by the admin) is shown below the payment form.
Tip Selection
When the PAX A920 handheld or DSI EMV Android device is configured for tip prompts, customers are presented with a tip selection screen before their card is charged. The tip options are configured by the admin in the device settings.
How Tip Selection Works
After the initial Pay button is tapped (or the card is dipped), the payment screen displays a row of tip percentage buttons. The percentages shown are determined by the multipleChoiceList setting configured in the terminal's DSI EMV settings.
| Button | Action |
|---|---|
| Tip percentage buttons | Each button shows the tip amount (e.g., $3.50) and the percentage (e.g., 15%). Tapping a button selects that tip amount. |
| Custom Tip | Opens a numeric keypad for entering a custom tip amount that doesn't match the preset percentages. The button label reflects whatever the admin configured in the multipleChoiceList setting (e.g., "Additional Tip", "Custom Gratuity", "Enter Amount", "Enter Tip Amount"). |
After selecting a tip (or entering a custom amount), the customer taps the Pay button, which shows the final total including the tip. The transaction is then processed with the tip included.
Tip Configuration (Admin)
To configure tip percentages, an admin navigates to Settings → POS List → [Terminal] → DSI EMV Settings, then sets the multipleChoiceList field with the desired percentage values. Each value in the list becomes a tip button on the payment screen.
Troubleshooting
| Problem | Solution |
|---|---|
| "No MID Present" | The Datacap merchant ID is not configured. Check with your admin. |
| "No Key Present" | The Datacap public key is not configured. Check with your admin. |
| Payment form not showing | The payment API may not be enabled, or the order has no remaining balance. |
| Card declined | The customer's card may be declined or have insufficient funds. Ask the customer to try another card. |
Related
- Payments — General payment options and workflows
- Apple Pay — Apple Pay payment method (also uses Datacap)
- Google Pay — Google Pay payment method (also uses Datacap)