Payment Schedules let you set up a series of future payments against a single card. The gateway processes due payments automatically each night and notifies your platform when each payment completes — approved or declined.

Use schedules for installment plans, recurring registration fees, multi-month billing, or any case where you want SportsPay to handle ongoing card billing on a fixed schedule.

Components of a Schedule

Every schedule has three pieces. All three must be in place before the gateway can process payments:

1. Schedule — the container, identified by SCHEDID. Created with TYPE=L, SUBTYPE=CS.
2. Payments — a list of dated amounts. Can be added during schedule creation or later.
3. Card data — a stored card the gateway charges. Can be attached during creation, attached later via Direct (TYPE=L, SUBTYPE=AC), or collected through Customized Checkout or Embedded Components.

Once all three are present, the schedule moves to Ready and the gateway processes payments automatically on their due dates.

A schedule holds one card, at the schedule level — not one per payment. Every payment that has not yet been processed is charged to whatever card the schedule is currently holding, so replacing the card is a single call and applies to the whole remaining schedule. Payments that have already been charged keep a record of the card that charged them, for reporting; that record is history and does not change when you attach a new card. There is no way to give one payment in a schedule a different card from another. See Replacing the Card on a Schedule.

Schedule Lifecycle

flowchart LR
    NEW[New] -->|All components added| READY[Ready]
    READY -->|Payment declines| ERR[Card Error]
    ERR -->|New card attached| READY
    READY -->|Suspended| SUSP[Suspended]
    SUSP -->|Restored| READY
    READY -->|All payments processed| DONE[Completed]
    READY -->|Cancelled| CANC[Cancelled]

Payments within a schedule have their own status:

All schedule operations use TYPE=L (Schedule). The SUBTYPE determines the action.

For field formats and full per-action parameter reference, see the API Reference.

Creating a Schedule

SUBTYPE=CS — Create a new schedule. You can create it empty and add payments and card data later, or include everything in one call.

Required parameters

• TERMID, PASS
• TYPE=L, SUBTYPE=CS
• INVOICE — invoice number for reporting

Optional parameters

• SCHEDID — your schedule identifier, 8 to 36 characters, unique per terminal. If you omit it, the gateway generates one and returns it — capture it from the response, because every later call needs it.
• DESC — schedule description
• PYMTS — list of payments to add immediately (see Adding Payments)
• FOLLOWUP — override which follow-up emails the gateway sends for this schedule (see Follow-Up Emails)
• Card fields — CARD, EXP, CUSTNAME, CUSTEMAIL to attach a card on creation

Example: empty schedule

curl --request POST --url {gateway_endpoint}/ \
  --header 'Content-Type: application/json' \
  --data '{
    "TERMID":  "TEST0058",
    "PASS":    "zX3Ht5va",
    "TYPE":    "L",
    "SUBTYPE": "CS",
    "SCHEDID": "U13-Boys-2026-001",
    "INVOICE": "REG-12345",
    "DESC":    "U13 Boys Fall Season",
    "JSON":    "Y"
  }'

Example: schedule with payments

curl --request POST --url {gateway_endpoint}/ \
  --header 'Content-Type: application/json' \
  --data '{
    "TERMID":  "TEST0058",
    "PASS":    "zX3Ht5va",
    "TYPE":    "L",
    "SUBTYPE": "CS",
    "SCHEDID": "U13-Boys-2026-001",
    "INVOICE": "REG-12345",
    "DESC":    "U13 Boys Fall Season",
    "PYMTS": [
      { "DATE": "20260901", "AMT": "125.00", "REFNUM": "u13-001-pmt1" },
      { "DATE": "20261001", "AMT": "125.00", "REFNUM": "u13-001-pmt2" },
      { "DATE": "20261101", "AMT": "125.00", "REFNUM": "u13-001-pmt3" }
    ],
    "JSON":    "Y"
  }'

Note: PYMTS accepts a JSON array of payment objects when you post application/json, as above. The bracket string form — "[DATE=20260901&AMT=125.00&REFNUM=u13-001-pmt1][...]" — is the form-encoded equivalent and is also accepted on a JSON body. Use the array form with a JSON request.

Attaching a Card

A schedule needs a card before any payment can process. There are three ways to attach one.

Option 1 — On Schedule Creation

Include card fields on the CS request (see above).

Option 2 — Direct (AC)

SUBTYPE=AC — Attach card data directly to an existing schedule.

Required parameters

• TERMID, PASS
• TYPE=L, SUBTYPE=AC
• SCHEDID
• TOKEN — accepts either a One-Time Token (OTT) from Embedded Tokenization or a permanent token from a previous transaction. The gateway handles both the same way. You can send CARD and EXP instead if your platform holds the card details directly.
• CUSTNAME, CUSTEMAIL

curl --request POST --url {gateway_endpoint}/ \
  --header 'Content-Type: application/json' \
  --data '{
    "TERMID":    "TEST0058",
    "PASS":      "zX3Ht5va",
    "TYPE":      "L",
    "SUBTYPE":   "AC",
    "SCHEDID":   "U13-Boys-2026-001",
    "TOKEN":     "4xxxxxxxxxxx1111",
    "CUSTNAME":  "Sample Parent",
    "CUSTEMAIL": "[email protected]",
    "JSON":      "Y"
  }'

Option 3 — Customized Checkout or Embedded Components

Pass the schedule's SCHEDID on StartSession. The hosted page collects the card from the customer and attaches it to the schedule. Useful when the customer is signing up for the schedule themselves.

You control whether a payment is processed as part of the same flow:

• Omit REFNUM — the card is attached only. No payment runs until the nightly processor picks up the next due payment on its scheduled date.
• Include REFNUM pointing to a specific scheduled payment — the gateway attaches the card and processes that payment on the hosted page in the same flow.

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

Note: AMT, PLATFEE, PLATCHRG, USERFEE, and SPLIT cannot be passed on a StartSession that includes SCHEDID. The amount, if any, comes from the scheduled payment.

See Attaching a Card via Hosted Checkout for the full flow — including the GetResult / Ack handling after the customer returns, replacing a card after a Card Error, and the complete list of prerequisites.

Replacing the Card on a Schedule

Cards expire, get reissued, and get declined. A schedule whose most recent payment failed for a card reason sits in E (Card Error) and will keep failing until a working card is attached.

There is no separate "update card" action. You replace a card with the same calls you used to attach one — the new card data replaces whatever the schedule was holding, and attaching it clears E and returns the schedule to R (Ready).

Which route you use depends on who has the new card details.

You already hold a token — send AC with the new TOKEN, exactly as in Option 2 above.

You are retrying a specific declined payment — send PP with the payment's REFNUM and the new card fields. This replaces the card and reprocesses that payment in one call, rather than waiting for the next scheduled date. See Processing a Payment Now.

The cardholder needs to enter the new card themselves — send them through Customized Checkout or Embedded Components with the schedule's SCHEDID, as in Option 3. Omit REFNUM to swap the card without taking a payment, or include one to collect the card and process that payment in the same flow. Embedded Components also has a dedicated update-card session variant — see Embedded Components.

Managing Payments

Every payment in a schedule is identified by its REFNUM. This is the field name on every call — creating payments, updating them, removing them, and processing them on demand.

A REFNUM you supply must be unique across every schedule on the terminal, not just the one you are adding it to. A duplicate is rejected with 8304 DUPLICATE REFNUM. If you derive references from a per-schedule counter, prefix them with something schedule-specific.

Adding Payments

SUBTYPE=PA — Add one or more payments to an existing schedule.

Required parameters

• TERMID, PASS, TYPE=L, SUBTYPE=PA
• SCHEDID
• PYMTS — array of payment objects. Each entry needs DATE and AMT; REFNUM is optional and generated by the gateway if omitted.

Optional per-payment fields

• PLATFEE — platform fee added to the payment, charged to the cardholder. Maximum 100.00.
• PLATCHRG — platform fee billed to the merchant instead. Capped at the lesser of 100.00 and the payment AMT.
• PROGRAM, PLAYER, ACCOUNT — optional breakdowns for reporting. Each entry needs a name, ID, or description plus an AMT greater than zero, and each breakdown must total no more than the payment AMT.

PLATFEE and PLATCHRG are mutually exclusive — sending both returns 8304. Both, and all three breakdowns, can be set on CS and PA. PU changes only the date and amount.

curl --request POST --url {gateway_endpoint}/ \
  --header 'Content-Type: application/json' \
  --data '{
    "TERMID":  "TEST0058",
    "PASS":    "zX3Ht5va",
    "TYPE":    "L",
    "SUBTYPE": "PA",
    "SCHEDID": "U13-Boys-2026-001",
    "PYMTS": [
      { "DATE": "20261201", "AMT": "125.00", "REFNUM": "u13-001-pmt4" }
    ],
    "JSON":    "Y"
  }'

Updating Payments

SUBTYPE=PU — Update the date and amount of an unprocessed payment. Approved payments cannot be modified.

Required parameters

• TERMID, PASS, TYPE=L, SUBTYPE=PU
• SCHEDID
• REFNUM — reference of the payment to update
• DATE and AMT — both are required on every PU. Send the current value for whichever one you are not changing.

REFNUM identifies the payment; it is not itself editable. To change a payment's reference, remove it with PR and add a replacement with PA.

The response to a PU carries the payment's previous USERFEE — the fee is recalculated against the new amount the next time the schedule is read. Issue a GS if you need the updated figure to show a customer.

curl --request POST --url {gateway_endpoint}/ \
  --header 'Content-Type: application/json' \
  --data '{
    "TERMID":  "TEST0058",
    "PASS":    "zX3Ht5va",
    "TYPE":    "L",
    "SUBTYPE": "PU",
    "SCHEDID": "U13-Boys-2026-001",
    "REFNUM":  "u13-001-pmt4",
    "DATE":    "20261215",
    "AMT":     "150.00",
    "JSON":    "Y"
  }'

Removing Payments

SUBTYPE=PR — Remove an unprocessed payment from the schedule. Approved payments cannot be removed.

Required parameters

• TERMID, PASS, TYPE=L, SUBTYPE=PR
• SCHEDID
• REFNUM — reference of the payment to remove

Removing all remaining payments from a schedule moves it to Completed.

User Fees on Schedules

Where the merchant is on auto user fee, each scheduled payment carries a cardholder-paid fee. Two things about how it is calculated matter when you quote a total to a customer.

The fee is calculated on AMT + PLATFEE. A platform fee added to the payment raises the base the user fee is worked out on. PLATCHRG does not — it is billed to the merchant rather than added to what the cardholder pays.

The fee is not fixed at creation. Each time a payment that is still waiting is read, its user fee is recalculated at the merchant's current rate. A rate change moves the fee on every payment not yet processed. Fees on already-processed payments do not change.

Suppressing the fee for one schedule — NOUSERFEE. Send NOUSERFEE on the CS call, either bare or with a value of Y or T, to suppress the fee for the life of that schedule regardless of the merchant setting. It can only be set at creation and is not returned by GS.

Note: NOUSERFEE is a flag, not a yes/no field. A value of N is read as "not set", so the fee still applies. Omit the field to follow the merchant's setting.

When you omit it, the merchant's auto user fee setting is recorded as it stands at creation. A schedule created while that setting is off will not charge a fee on any payment, even if the merchant is switched on later.

Processing a Payment Now

SUBTYPE=PP — Process a payment immediately rather than waiting for its scheduled date. Useful for early payment, retrying a declined payment, or running a payment on demand.

Required parameters

• TERMID, PASS, TYPE=L, SUBTYPE=PP
• SCHEDID
• REFNUM — reference of the payment to process

The payment must be Waiting (W) or Declined (D). One that is already Approved, Stopped, or an Archived Decline returns 8309 PYMT LOCKED.

You can also attach new card data on a PP request (same fields as AC) — useful for retrying a declined payment with a different card.

A PP triggers a notification callback to your NOTIFICATION URL just like a nightly-processed payment.

Suspend, Restore, and Cancel

All three require only TERMID, PASS, TYPE=L, the appropriate SUBTYPE, and SCHEDID.

Cancelling stops every payment still outstanding — each one moves to S (Stopped) — and the schedule moves to X. A schedule that is already Completed or Cancelled returns 8311.

curl --request POST --url {gateway_endpoint}/ \
  --header 'Content-Type: application/json' \
  --data '{
    "TERMID":  "TEST0058",
    "PASS":    "zX3Ht5va",
    "TYPE":    "L",
    "SUBTYPE": "SS",
    "SCHEDID": "U13-Boys-2026-001",
    "JSON":    "Y"
  }'

Getting Schedule Status

SUBTYPE=GS — Retrieve the current state of a schedule, including all payments and attached card data. Use this to synchronize your platform's view of the schedule with the gateway's.

Required parameters

• TERMID, PASS, TYPE=L, SUBTYPE=GS
• SCHEDID

The response includes the full Schedule Data Block — see API Reference for the response shape.

Notifications

When a scheduled payment is processed (whether nightly, via PP, or after a hosted attach), the gateway sends an HTTP POST to the terminal's configured NOTIFICATION URL. This is how your platform learns whether each payment was approved or declined.

The notification carries the result of the one payment, then the full current state of the schedule:

• TERMID, TYPE=N, SUBTYPE=SP — identifies the message
• REFNUM — the payment this notification is about; PYMTS contains an entry with the same REFNUM
• APPROVED — Y or N
• CODE, RESPONSE — 0000 / APPROVED on success; on a decline the text comes verbatim from the processing gateway
• AUTH — sent only when APPROVED is Y
• GATEREF — the processing gateway's reference, sent on the first delivery attempt. A retried notification carries it on the matching PYMTS entry instead.
• DATETIME — YYYYMMDDHHMMSS
• Then the full Schedule Data Block, matching a GS response

Body format. The default is tag-value (text/plain); JSON (application/json) and XML (text/xml) are also available. The format is fixed per terminal and the same fields are sent whichever one you use. Where credentials are configured for your terminal the request carries HTTP Basic authentication. Contact support to set any of this up or change it.

Acknowledging. Your endpoint must return a body beginning with OK — leading whitespace and letter case are ignored. Acknowledgement is based on the response body rather than the HTTP status code, so a 200 with an empty body is treated as an undelivered notification and retried.

Retries. A payment gets one notification when it is processed and, if that is not acknowledged, one automatic retry on the next processing sweep roughly three minutes later. If the retry is also unacknowledged the payment is marked with a NOTIFY of E and no further attempts are made — contact SportsPay support to have it resent.

Delivery state is visible as the NOTIFY field of each payment in a GS response:

To configure a NOTIFICATION URL for your terminals, see Production.

Follow-Up Emails

Separately from the server-to-server notifications above, the gateway also emails the cardholder about the schedule itself — payment receipts, upcoming-payment reminders, decline follow-ups, and schedule-change notices. Which of these go out is configured at the partner level when you integrate.

If your platform already sends its own customer email, you don't have to use ours. A partner that issues its own receipts doesn't need the gateway sending a second one; a partner that runs its own dunning doesn't want the gateway chasing its customers. You can turn our follow-ups off completely, or keep some and replace others.

Opting Out Entirely

There are two ways to stop the gateway emailing your cardholders. Which one you want depends on whether this is a decision about your platform or about one schedule.

Across your whole account — tell us at integration. If your platform handles all of its own customer email, ask us to configure your account with follow-ups off. Nothing is emailed to any cardholder on any schedule, and you never need to send FOLLOWUP at all.

For a single schedule — send FOLLOWUP=N. This suppresses every follow-up email for that schedule only, leaving your configured settings intact for every other schedule.

Note: FOLLOWUP can only be set when a schedule is created, and cannot be changed afterwards. If you are relying on FOLLOWUP=N for a blanket opt-out, every CS call has to carry it — one omission means that schedule follows your configured settings and cannot be corrected. If you want the opt-out to apply everywhere, configure it at the account level instead.

Sending FOLLOWUP

FOLLOWUP is an optional field on SUBTYPE=CS, sent alongside INVOICE, DESC and PYMTS. Its value is a short string of letters — one letter per email type you want switched on:

Up to four letters, so all four can be switched on together with CSAW. Values longer than four characters, or containing anything other than a letter, return 1040.

Send the letters in uppercase — FOLLOWUP is matched case-sensitively.

N is the exception — it turns everything off rather than on. Send it on its own, not combined with other letters. See Opting Out Entirely.

curl --request POST --url {gateway_endpoint}/ \
  --header 'Content-Type: application/json' \
  --data '{
    "TERMID":   "TEST0058",
    "PASS":     "zX3Ht5va",
    "TYPE":     "L",
    "SUBTYPE":  "CS",
    "SCHEDID":  "U13-Boys-2026-001",
    "INVOICE":  "REG-12345",
    "DESC":     "U13 Boys Fall Season",
    "FOLLOWUP": "CS",
    "JSON":     "Y"
  }'

That schedule gets decline follow-ups and schedule-change notices, and nothing else.

It replaces your configured settings — it does not merge with them

So FOLLOWUP=CS suppresses receipts and upcoming-payment reminders even when both are enabled at the partner level. Send every letter you want on — not just the ones you want to change.

Managing Declined Payments

When a payment declines, its status becomes D. You have three options:

• Retry — issue a PP (Process Payment) request to try the same payment again. Optionally attach new card data if the original card is the issue.
• Remove — issue a PR (Remove Payment) request to drop the payment from the schedule.
• Wait — leave it in place. The gateway does not automatically retry declined payments; they remain in D status until you take action.

When a payment moves from D to A (after a successful retry), the previous decline is preserved as an X (Archived Decline) entry with a blank REFNUM. This keeps the historical record intact.

A payment decline also moves the schedule itself to E (Card Error), signaling that the customer may need a new card. Attaching a new card clears the Card Error status.

For the specific decline and error codes returned on scheduled payments, see Payment Schedules Errors.

API Reference

For the per-action field reference, see the Payment Schedule API Reference:

• Create Schedule (CS)
• Attach Card (AC)
• Process Payment (PP)
• Add / Update / Remove Payment (PA, PU, PR)
• Suspend / Restore / Cancel (SS, SR, SC)
• Get Schedule (GS)

For StartSession with SCHEDID — see Customized Checkout or Embedded Components API Reference