Guides
  1. CORE FEATURES
  2. Payment Schedules

Hosted Payment Method

You can use Customized Checkout or Embedded Components to attach a card to an existing payment schedule — either to set up the schedule for the first time or to replace the card on a schedule that had a Card Error. Optionally, you can process an immediate payment as part of the same flow.

This is useful when the customer is signing up for the schedule themselves and you want them to enter their card on the SportsPay-hosted payment page rather than your platform collecting it.

How It Works

The flow is the same as any other hosted transaction — StartSession, browser redirect, GetResult, Ack — but you include SCHEDID on the StartSession to link the session to an existing schedule.

flowchart TD
    A[Registration platform creates schedule with CS] --> B[Server calls StartSession with SCHEDID]
    B --> C[Gateway returns SECUREID + Payment URL]
    C --> D[Customer enters card on hosted page]
    D --> E[Gateway attaches card to the schedule]
    E --> F{REFNUM provided?}
    F -- Yes --> G[Gateway processes that scheduled payment]
    F -- No --> H[Card attached only; no payment processed]
    G --> I[Browser redirected to Success/Failure URL]
    H --> I
    I --> J[Server calls GetResult and Ack]
    J --> K[Schedule is Ready for nightly processing]

Prerequisites

Before you can use this flow:

  • The schedule must already exist. Create it with TYPE=L, SUBTYPE=CS — see Payment Schedules.
  • The schedule must be in New (N), Ready (R), or Card Error (E) status. Schedules in Completed, Suspended, or Cancelled status reject the redirect call with SCHEDID NOT ALLOWED.

Attach a Card Only

To let the customer enter a card without processing a payment, call StartSession with SCHEDID and no REFNUM. The card is attached to the schedule and the nightly processor picks up the next due payment on its scheduled date.

Required parameters

  • TERMID, PASS
  • TYPE=W
  • ACTION=StartSession
  • SCHEDID — the existing schedule's identifier
  • CUSTEMAIL — cardholder email
  • REQUESTID — unique identifier for this session

Optional parameters

  • LANG — E (default) or F
  • CUSTNAME — cardholder name
  • EMBED — set this to load the page as an iframe fragment. See Embedded Components.

Important: AMT, PLATFEE, PLATCHRG, USERFEE, and SPLIT cannot be passed when SCHEDID is used. The amount comes from the scheduled payment. Sending any of these fields alongside SCHEDID will be rejected.

Example request

curl --request POST --url {gateway_endpoint}/ \
  --header 'Content-Type: application/json' \
  --data '{
    "TERMID":    "your_termid",
    "PASS":      "your_pass",
    "TYPE":      "W",
    "ACTION":    "StartSession",
    "SCHEDID":   "U13-Boys-2026-001",
    "CUSTEMAIL": "[email protected]",
    "CUSTNAME":  "Sample Parent",
    "REQUESTID": "1712864923456",
    "LANG":      "E",
    "JSON":      "Y"
  }'

The response is the same as any StartSession — a SECUREID and a URL to redirect the customer to (or load in an iframe for Embedded Components).

Attach a Card and Process a Payment

To attach a card and process a specific scheduled payment at the same time, include REFNUM referencing the payment you want to process. The gateway attaches the card, then runs that payment on the hosted page. The amount is pulled from the schedule — you don't pass it.

Only payments in New (N), Waiting (W), or Declined (D) status can be processed this way. Approved payments cannot be re-run.

Example request

curl --request POST --url {gateway_endpoint}/ \
  --header 'Content-Type: application/json' \
  --data '{
    "TERMID":    "your_termid",
    "PASS":      "your_pass",
    "TYPE":      "W",
    "ACTION":    "StartSession",
    "SCHEDID":   "U13-Boys-2026-001",
    "REFNUM":    "u13-001-pmt1",
    "CUSTEMAIL": "[email protected]",
    "REQUESTID": "1712864923456",
    "JSON":      "Y"
  }'

Completing the Flow

After the customer enters their card on the hosted page, the gateway redirects them to your Return URL. Your return page calls GetResult and Ack exactly as it would for any other hosted session — see Steps for Customized Checkout or Steps for Embedded Components for the details.

The GetResult response tells you whether the card was attached successfully and — if you sent REFNUM — whether the scheduled payment was approved.

Once the card is attached, the schedule moves from its previous status to Ready (R) and the nightly processor will handle the remaining payments automatically.

Replacing a Card After a Card Error

When a schedule moves to Card Error (E) status — typically after a payment declines because of an expired or invalid card — you can use this same flow to let the customer enter a new card.

  • Call StartSession with the existing SCHEDID and no REFNUM to attach the new card without processing a payment.
  • Or include the REFNUM of the failed payment to retry it with the new card in the same flow.

API Reference

Updated 13 days ago