Use this endpoint when a customer’s card is expired, declined, replaced, or when a subscription is PAST_DUE because the saved card can no longer be charged.

This endpoint starts a hosted card update/payment flow. The customer is redirected to authorize a new card. After successful authorization, the subscription is updated with the new card and can become active again.

Endpoint

POST /v1/subscriptions/:subscriptionIdOrCode/update-card

Authentication

Include your secret key in the request header:

x-api-key: your_secret_key

Path Parameters

Request Body

Sample

{
  "redirectUrl": "https://merchant.com/subscription/card-updated"
}

{
  "status": true,
  "message": "Success",
  "code": 201,
  "data": {
    "authorizationUrl": "https://checkout.provider.com/xxxx",
    "accessCode": "xxxx",
    "reference": "KYSHI-123456789"
  }
}

Flow

1. Merchant calls the update-card endpoint.
2. Kyshi creates a card update transaction.
3. Kyshi returns an authorizationUrl.
4. Merchant redirects the customer to the authorizationUrl.
5. Customer completes card authorization/payment.
6. On successful payment confirmation, Kyshi saves the new card authorization on the subscription.
7. The subscription is reactivated if applicable.

Behavior

If the Card Update Succeeds

• subscription.card = new card authorization
• subscription.status = ACTIVE
• subscription.isActive = true
• subscription.pastDueAt = null

If the subscription was PAST_DUE, the customer can regain access after the new card is successfully authorized and:

• the outstanding charge succeeds, or
• the subscription is reactivated according to the merchant’s flow.

Use Cases

Webhook Events

The card update itself is confirmed through the payment/transaction webhook flow.

After successful card update, subscription-related events may be emitted:

Important Notes

• Updating a card does not by itself guarantee a successful renewal payment unless the outstanding charge is also paid.
• If the subscription is PAST_DUE, the business should continue to block access until the subscription returns to ACTIVE.
• The customer should be redirected to the returned authorizationUrl.
• The returned reference can be used to track the card update transaction.

Error Responses