Virtual Terminal

Summary

The RapidCents Virtual Terminal allows merchants to process card-not-present (CNP) transactions through the API. It supports manual card entry and saved (card-on-file) payments.

Transaction Types

Transaction Lifecycle

Processing Flow

1. Merchant sends a transaction request (Sale, Auth Only, or Refund) to the RapidCents Virtual Terminal API with card details or a saved card ID.
2. RapidCents validates the request, resolves the customer, and prepares the transaction payload.
3. RapidCents submits the transaction to Visa, Mastercard, Discover, Amex.
4. The card network returns an authorization response (approved / declined).
5. RapidCents records the transaction, updates the wallet/batch, and returns the result to the merchant.
6. If approved and automatic invoicing is enabled, an invoice email is sent to the customer.

Authentication

All Virtual Terminal endpoints require:

Sale (Credit Sale)

A Sale transaction authorizes and captures payment in a single step. Funds are settled immediately.

{
  "cardEntryMethod": "0",
  "customerId": "customer-uuid",
  "amount": 25.00,
  "cardData": {
    "nameOnCard": "John Doe",
    "cardNumber": "4111111111111111",
    "month": 12,
    "year": 2028,
    "cvv": "123",
    "saveCard": true
  },
  "description": "Order #1234",
  "customInvoiceNumber": "INV-001"
}

{
  "amount": 25.00,
  "cardId": "stored-card-uuid"
}

Response (Sale)

{
  "ok": true,
  "message": "Transaction approved",
  "transaction": {
    "id": "txn-uuid",
    "status": "Approved",
    "auth_code": "123456",
    "amount": 25.00,
    "type": "Sale"
  }
}

Auth Only (Pre-Authorization)

An Auth Only transaction reserves funds on the cardholder's account without capturing. Use the Force endpoint to capture later.

{
  "cardEntryMethod": "0",
  "customerId": "customer-uuid",
  "amount": 100.00,
  "cardData": {
    "nameOnCard": "Jane Smith",
    "cardNumber": "4111111111111111",
    "month": 6,
    "year": 2027,
    "cvv": "456",
    "saveCard": false
  }
}

{
  "amount": 100.00,
  "cardId": "stored-card-uuid"
}

Response (Auth Only)

{
  "ok": true,
  "message": "Transaction approved",
  "transaction": {
    "id": "txn-uuid",
    "status": "Approved",
    "auth_code": "789012",
    "amount": 100.00,
    "type": "Auth Only"
  }
}

Force (Capture Pre-Auth)

A Force (capture) converts a previously authorized Auth Only transaction into a completed charge. The funds are moved from hold to settlement.

POST /api/{business_id}/transactions/{transaction_id}/force

{
  "amount": 100.00
}

Response (Force)

{
  "ok": true,
  "message": "Transaction captured successfully",
  "transaction": {
    "id": "txn-uuid",
    "status": "Approved",
    "amount": 100.00,
    "type": "Force"
  }
}

Auth Only → Force Workflow

1. Submit an Auth Only request to /api/{business_id}/vt/pre-auth. Note the returned transaction.id.
2. When ready to capture, submit a Force request to /api/{business_id}/transactions/{transaction_id}/force with the desired amount.
3. The transaction is captured and funds move to settlement.

Refund / Return

A Refund (return) sends funds back to the cardholder. Can be processed with manual card entry or a saved card.

{
  "cardEntryMethod": "0",
  "customerId": "customer-uuid",
  "amount": 15.00,
  "cardData": {
    "nameOnCard": "John Doe",
    "cardNumber": "4111111111111111",
    "month": 12,
    "year": 2028,
    "cvv": "123"
  }
}

{
  "amount": 15.00,
  "cardId": "stored-card-uuid"
}

Response (Refund)

{
  "ok": true,
  "message": "Refund processed successfully",
  "transaction": {
    "id": "txn-uuid",
    "status": "Approved",
    "amount": 15.00,
    "type": "Return"
  }
}

All Endpoints

Card Data Fields

Manual Entry (cardEntryMethod: "0")

Saved Card (cardEntryMethod: "1")

Common Fields

Error Handling

{
  "ok": false,
  "message": "Transaction declined",
  "errors": {
    "amount": ["The amount field is required."]
  }
}

Notifications

When a Sale transaction is approved and the business has automatic invoice emailing enabled, RapidCents automatically sends an invoice email to the customer.