Retrieving Card Updates

Below you will find two functions for retrieving the card updates associated with a subscription.

Retrieving Updates after a Webhook Notification

This is likely the primary method you will most want to use for retrieving your updated card information. This request is an HTTP GET request that contains a updateId within the URL path.

The updateId represents a group of records that were updated at a single point in time. It is not strictly linked to a subscription schedule.

For example, you may have a subscription schedule that contains three records:

On day 1, records 1 and 2 were updated. A updateId will be generated for those two records, and calling this endpoint will return those two updates.

On day 2, an update may arrive for the third card. It will be assigned a new updateId, and calling this endpoint will return just that one update.

End-point: /api/v4/accounts/{account}/account-updater/updates/{updateId}

An HTTP response code of 200 indicates a successful request. The body of the response will be a JSON array containing a JSON object for each update for the given updateId in the following format:

[
  {
    "id": "auru_2f418b31a4ce4736a54ed7d90126d8fe",
    "oldExpiry": "1230",
    "newExpiry": "1235",
    "oldToken": "123456789101",
    "newToken": "123456789121",
    "updateId": "aupres_7d7366c9b6564b9abff22829c3b9ce66",
    "updatedAt": "2022-10-11T03:06:47.488Z",
    "status": "valid",
    "recurringSchedules": [
      0
    ],
    "accountUpdaterScheduleRecordId": "cssr_d468d4061ab44c309a46d3c3f4fd96e0",
    "format": "payconex"
  }
]

Update Response Parameters

ParameterDescription
idThe ID of this specific update.
oldExpiryThe previous expiration date for the card.
newExpiryThe new expiration after the account has been updated.
oldTokenThe previous token data for the card.
newTokenThe new token data for the updated card.
updateIdThe most recent update identifier associated with the record.
updatedAtThe time that the account was updated.
statusThe status of an Account Updater Update. See the table below for more explanation on the statuses that can be received.
recurringSchedulesThe list of PayConex recurring schedules associated with this update. Not relevant for merchants who are managing their own recurring transaction routines.
accountUpdaterScheduleRecordIdThe id value associated with this update that returned after creating a subscription.
formatThe formats that an Account Updater Schedule is set to be returned in. This will be whatever was included as the responseFormat when creating subscriptions.

Retrieving Most Recent Results for a given Schedule ID

This endpoint allows you to check on the status of all records associated with a given scheduleId. The scheduleId is returned after creating a subscription.

This method is handy for cases where you may need to get the most recent data independently of the record actually being updated.

This request is an HTTP GET request that contains a scheduleId within the end-point URL path.

End-point: /api/v4/accounts/{account}/account-updater/schedules/{scheduleId}/results

{
  "id": "css_d4c2c2cd09924d71abad464ac3004a17",
  "periodId": "PERIOD_1W",
  "periodDate": "2022-10-11",
  "responseFormat": "payconex",
  "enabled": true,
  "createdAt": "2022-10-11T03:48:35.140Z",
  "updatedAt": "2022-10-11T03:48:35.140Z",
  "templateRef": "string",
  "records": [
    {
      "id": "css_5cd5614dd4514735ae2d274597824c5e",
      "token": "string",
      "createdAt": "2022-10-11T03:48:35.140Z",
      "updatedAt": "2022-10-11T03:48:35.140Z",
      "type": "payconex",
      "enabled": true,
      "expiry": "1230",
      "mostRecentUpdate": {
        "id": "auru_2f418b31a4ce4736a54ed7d90126d8fe",
        "oldExpiry": "1230",
        "newExpiry": "1235",
        "oldToken": "123456789101",
        "newToken": "4444333322221111",
        "updateId": "aupres_7d7366c9b6564b9abff22829c3b9ce66",
        "updatedAt": "2022-10-11T03:48:35.140Z",
        "status": "valid",
        "recurringSchedules": [
          0
        ],
        "accountUpdaterScheduleRecordId": "cssr_d468d4061ab44c309a46d3c3f4fd96e0",
        "format": "payconex"
      }
    }
  ]
}

Result Response Parameters

ParameterDescription
idThe id value returned in the response is the scheduleId.
periodIdThis is the period, or schedule, that the Account Updater API is following to issue the cards for updating. For a list of allowed periodId values please see the table below.
periodDateThis is the date that the subscription began.
responseFormatThe response format that was sent as part of the original subscription request.
enabledThe current status of the subscription.
createdAtThe date/time this subscription was created.
updatedAtThe date/time of the last update for this subscription.
recordsThis is a JSON array containing the details of each token or card that was included as a part of the original subscription.

Within each of these data elements is another JSON array called mostRecentUpdate that contains the same parameters as found in the update response parameters table above.

Update Statuses

The statuses below are what values can come back from the card issuers as a notification or update.

StatusDescription
validThe card is valid, but there were no updates that needed to be made to the account.
contactThis means the card issuer is reporting a problem with the account and you should contact the card holder.
contact_closedThis means the card issuer is reporting a problem with the account and you should contact the card holder as the account might be closed.
no_matchThe card issuer could not find a match for the given card. This does not mean the account is or isn't valid, it simply just couldn't be found for updating.
no_changeSimilar to the valid status, the account is valid but there were no updates that needed to be made.
updated_cardThe card account and possibly expiration date were updated.
updated_expiryThe card account remained the same and only the expiration date was updated.

What’s Next

Check out code examples and more in the following articles!