Overview

The SoftPoint Gateway API processes card not present (CNP) and ecommerce payments. Use it to charge cards, authorize and later capture funds, refund and void transactions, adjust tips, and look up card metadata (BIN) — all server-to-server with a bearer token.

This overview explains the concepts shared by every Gateway payment endpoint. Each operation then has its own guide:

• Sale — authorize and capture in one step
• Authorize — reserve funds without capturing
• Capture — capture a previous authorization
• Void — cancel a transaction before it settles
• Refund — return funds after a sale settles
• ​Generate Network Token — Generate network token
• Iframe — take payments using our iframe solution

Base URL

The Gateway API is served from a dedicated host, separate from the Interface (boarding/configuration) host.

All Gateway payment paths are relative to {gtw_url} and scoped to a location:

{gtw_url}/locations/{location_id}/transactions/...

Authentication

Every request requires a bearer access token in the Authorization header. You obtain one by exchanging your API key for a token.

Get a gateway access token

curl --location '{gtw_url}/locations/{location_id}/access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "api_key": "YOUR_API_KEY",
    "client": "iframe_gtw"
  }'

Response

{
  "accessToken": "eyJhbGciOi...",
  "refresh_token": "def502...",
  "expires_in": 300
}

Then send the token on every payment call:

Authorization: Bearer {access_token}
Content-Type: application/json

Tokens expire in 300 seconds (5 minutes). Cache the token and reuse it until it is close to expiry, then request a new one (or use the refresh_token). A request with an expired token returns 401 Unauthorized with error code 10759 ("Token has expired").

Amounts and currency

The Gateway uses two conventions — be careful, they differ by direction:

Set the currency with currency_iso (e.g. "usd"). If omitted, the location's default currency is used.

The payment lifecycle

                 ┌─────────────┐      capture      ┌─────────────┐
   Authorize ───►│  AUTHORIZED │ ─────────────────►│  CAPTURED   │──┐
                 └─────────────┘                   └─────────────┘  │
                        │                                  │        │ settles
                        │ void (before settlement)         │ void   │
                        ▼                                  ▼        ▼
                 ┌─────────────┐                    ┌─────────────┐ ┌─────────────┐
                 │   VOIDED    │                    │   VOIDED    │ │  REFUND(ed) │
                 └─────────────┘                    └─────────────┘ └─────────────┘

   Sale = Authorize + Capture in a single call ──► CAPTURED

• Sale authorizes and captures at once — use it for immediate ecommerce checkout.
• Authorize then Capture splits the flow — reserve funds now, charge when you ship/fulfill.
• Void cancels a transaction that has not yet settled (same-day, before batch close).
• Refund returns money on a transaction that has already settled.
• Tip Adjust modifies the tip on an existing payment before settlement.

A single transaction is identified by the transaction_id returned in every payment response. Store it — Capture, Void, Refund, and Tip Adjust all reference it.

Idempotency & tracking

Pass a reconciliation_id (and/or inv_number) on Sale and Authorize to tie a transaction back to your own order records. This makes it possible to detect and reconcile duplicates if a network error leaves you unsure whether a charge succeeded.

Rate limits

Gateway responses include standard rate-limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59

The Gateway allows 60 requests/minute per token by default. When you exceed it you receive 429 Too Many Requests; back off and retry using exponential delay.

Error format

All Gateway errors share one envelope:

{
  "error": {
    "code": 19100,
    "name": "cybersource_40",
    "message": "Cannot VOID a reversed transaction",
    "details": []
  }
}

Common codes you will see across the payment endpoints:

Related

• Sale · Authorize · Capture · Void · Refund · Tip Adjust · BIN Lookup
• API Reference → Payments — Online (Gateway / Token)