payments.create (to create, send, pause,
resume and cancel) and payments.view (to read).
Create one
Pick the MID it’s paid to (GET /accounts, its id), then:
The answer (
201) is the plan, with its id, status (PendingSetup) and the customer’s link. Send an
Idempotency-Key so a retry can’t create it twice.
Nothing is charged until the customer authorizes the plan on its page. If its first payment is today, it’s charged then;
otherwise the card is checked (nothing charged) and the first payment comes on its date.
Send the link again
POST /recurring-plans/{id}/send sends the setup link again, while the customer hasn’t authorized the plan. sentAt,
sentVia and sendProblem say what happened.
Follow it
GET /recurring-plans/{id} gives the plan with its lines (lineItems), every payment made or tried (charges), and
the card it charges (cardLastFour, cardExpiry). GET /recurring-plans lists them a page at a time
(Pagination): q searches the description, reference, PO, the customer’s company, name,
email and phone, the note, MID, location and amount; status keeps one status.
Each entry in
charges is one try: period (which payment), attempt, scheduledFor, amount, status
(Approved, Declined or Unconfirmed), the processor’s retRef and authCode, lastFour and message. A declined
payment is tried again on the merchant’s retry days, as a new attempt of the same period.
To hear about changes rather than poll, use webhooks: recurringPlan/created, and
recurringPlan/updated on authorization, every charge, a card change, pause, resume, cancel and completion.
Pause, resume or cancel
A call that doesn’t fit the plan’s status (pausing a cancelled plan, say) answers
422 with what’s wrong.