Create a payment method update session.

POST

/v1/recurring-payments/{reference}/payment-method-session

const url = 'https://api.ridleypay.com/v1/recurring-payments/WOO-SUB-456/payment-method-session';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"success_url":"https://example.com/billing","cancel_url":"https://example.com/billing"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.ridleypay.com/v1/recurring-payments/WOO-SUB-456/payment-method-session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "success_url": "https://example.com/billing", "cancel_url": "https://example.com/billing" }'

Returns a hosted checkout_url where the customer replaces the card on file for this schedule. The new card is verified with 3DS and saved; nothing is charged. On success Ridley sends recurring.payment_method_updated. A schedule that is suspended or retrying after declines is reactivated and charged on the next processing run.

Authorizations

default

Parameters

Path Parameters

reference

required

string

The recurring payment reference.

Example

WOO-SUB-456

Request Body

application/json

object

success_url

Where to send the customer after the card is saved. ?payment_method=updated is appended.

string

nullable

Example

https://example.com/billing

cancel_url

Where to send the customer if they cancel or verification fails. ?payment_method=failed is appended on failure.

string

nullable

Example

https://example.com/billing

Responses

201

Session created

application/json

object

data

object

string

type

string

attributes

object

recurring_reference

string

checkout_url

string

expires_at

string

Example

{
  "data": {
    "id": "cs_a1b2c3",
    "type": "payment-method-sessions",
    "attributes": {
      "recurring_reference": "WOO-SUB-456",
      "checkout_url": "https://checkout.example.com/checkout/cs_a1b2c3",
      "expires_at": "2026-03-05T12:00:00.000000Z"
    }
  }
}

422

Not updatable

application/json

object

errors

Array<object>

object

status

string

title

string

detail

string

Example

{
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Entity",
      "detail": "Cannot update the payment method of a cancelled or completed recurring payment."
    }
  ]
}