API Reference

Update a payment plan

PUT/payment_plans/{id_or_reference}

Body Parameters

card_tokenstring(optional)

The card token to link this payment plan to

new_statusstring(optional)

Status to update to. Valid values are "Suspended", "Active", "Cancelled",

reasonstring(optional)

Reason for updating payment plan status

until_datestring (date)(optional)

Optionally used when suspending or activating a plan. This date will be saved on the payment plan for record-keeping purposes. The plan will need to be manually actioned on this date.

amountinteger (int32)(optional)

Recurring payment amount in the smallest unit of the currency.

setup_feeinteger (int32)(optional)

Setup fee to be charged upon creation of the payment plan.

frequencystring(optional)

Frequency of the payments. Acceptable values are: Daily, Weekly, Fortnightly, Monthly, 4 Weekly, Quarterly, Half Yearly, Annually.

payment_methodstring(optional)

Payment method for the plan - this can be Credit Card or Direct Debit. Note that if the customer is not setup with the defined payment method an error will be returned.

anniversarystring(optional)

Anniversary of the recurring payments. For Weekly and Fortnightly payments this will be the day of the week (1 - Monday, 2 - Tuesday, 3 - Wednesday, 4 - Thursday, 5 - Friday) For Monthly this will be the day of the month. If the day of the month is greater then 28, and the month is shorter then the anniversary this date will be moved forward to the nearest possible date (i.e. a payment for the 31st will fall on the 30th for monthly like September etc).

start_datestring (date)(optional)

Date that the payment plan should start. This must be in the future.

end_datestring (date)(optional)

Date that the payment plan should end on. This must be in the future and greater than the start_date.

referencestring(optional)

Reference for the payment plan.

descriptionstring(optional)

Description for the payment plan (e.g. Model 200R Blender Lay-by).

currencystring(optional)

ISO 4217 currency code for the plan.

total_countinteger (int32)(optional)

Total number of payments to process for this plan.

total_amountinteger (int32)(optional)

Total amount of all payments to be processed for this plan.

failed_payment_feeinteger (int32)(optional)· Defaults to 0

Fee that applies to the retried payment in the event of any declined payment. Note: This amount will compound for the total number of retries (3) performed.

retry_intervalinteger (int32)(optional)· Defaults to 3

Number of days between payment retries for any declined payments.

Query Parameters

id_or_referencestring

ID or merchant's reference of the payment plan to update.

Request

curl

curl https://gateway.pmnts-sandbox.io/v1.0/payment_plans/071-PP-8389G3DA -u TEST:TEST -X PUT -d '
{
  "new_status": "Suspended",
  "until_date": "2025-08-25"
}'

curl

curl https://gateway.pmnts-sandbox.io/v1.0/payment_plans/071-PP-8389G3DA -u TEST:TEST -X PUT -d '
{
  "amount": 100,
  "frequency": "Weekly",
  "payment_method": "Credit Card",
  "anniversary": 5,
  "start_date": "2025-07-16",
  "total_count": 2
}'

Response

200cURL Suspend 200 OK

json

{
  "successful":true,
  "response":{
  "id":"071-PP-8389G3DA",
  "customer":"071-C-JE34F66V",
  "amount":100,
  "currency":null,"setup_fee":0,
  "frequency":"Weekly",
  "anniversary":5,
  "start_date":"2025-07-16",
  "end_date":null,
  "total_count":2,
  "total_amount":null,
  "payment_method":"Credit Card",
  "reference":"071-PP-8389G3DA",
  "description":null,
  "status":"Suspended",
  "status_reason":"Other",
  "created_at":"2018-07-11T16:23:39+10:00",
  "failed_payment_fee":0,
  "retry_interval":3,
  "status_change_date":null,
  "card_token": "ABC12345",
  "payments":[]
  },
  "errors":[],
  "test":true
}

200cURL Update 200 OK

json

{
   "successful":true,
   "response":{
    "amount":100,
    "currency":"AUD",
    "setup_fee":0,
    "frequency":"Weekly",
    "anniversary":5,
    "start_date":"2025-07-17",
    "end_date":"nil",
    "total_count":2,
    "total_amount":200,
    "payment_method":"Credit Card",
    "reference":"8774b9d1-57b3-4bc7-854b-f81ae1e51aa7",
    "description":"nil",
    "status":"Active",
    "status_reason":"None",
    "created_at":"2022-11-24T09:22:02+11:00",
    "failed_payment_fee":0,
    "retry_interval":1,
    "status_change_date":"nil",
    "display_reason":"None",
    "card_token": "ABC12345",
    "payments":[
     {
      "id":"001-PT-ZD1Y124",
      "payment_plan":"001-PP-2CLZQHLI",
      "reference":"8774b9d1-57b3-4bc7-854b-f81ae1e51aa7-0001",
      "amount":100,
      "currency":"AUD",
      "scheduled_date":"2025-07-18",
      "payment_method":"Credit Card",
      "status":"Scheduled",
      "result":"nil",
      "records":[
         
      ]
     },
     {
      "id":"001-PT-L1MCLPL6",
      "payment_plan":"001-PP-2CLZQHLI",
      "reference":"8774b9d1-57b3-4bc7-854b-f81ae1e51aa7-0002",
      "amount":100,
      "currency":"AUD",
      "scheduled_date":"2025-07-25",
      "payment_method":"Credit Card",
      "status":"Scheduled",
      "result":"nil",
      "records":[
         
      ]
     }
    ]
   },
  "errors":[],
  "test":true
}

404Result

json

{
  "successful":false,
  "response":{},
  "errors":["Could not find Payment Plan"],
  "test":true
}