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}
/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
Parameter | Description |
---|---|
id | The ID of this specific update. |
oldExpiry | The previous expiration date for the card. |
newExpiry | The new expiration after the account has been updated. |
oldToken | The previous token data for the card. |
newToken | The new token data for the updated card. |
updateId | The most recent update identifier associated with the record. |
updatedAt | The time that the account was updated. |
status | The status of an Account Updater Update. See the table below for more explanation on the statuses that can be received. |
recurringSchedules | The list of PayConex recurring schedules associated with this update. Not relevant for merchants who are managing their own recurring transaction routines. |
accountUpdaterScheduleRecordId | The id value associated with this update that returned after creating a subscription. |
format | The 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
Parameter | Description |
---|---|
id | The id value returned in the response is the scheduleId . |
periodId | This 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. |
periodDate | This is the date that the subscription began. |
responseFormat | The response format that was sent as part of the original subscription request. |
enabled | The current status of the subscription. |
createdAt | The date/time this subscription was created. |
updatedAt | The date/time of the last update for this subscription. |
records | This 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.
Status | Description |
---|---|
valid | The card is valid, but there were no updates that needed to be made to the account. |
contact | This 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_match | The 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_change | Similar to the valid status, the account is valid but there were no updates that needed to be made. |
updated_card | The card account and possibly expiration date were updated. |
updated_expiry | The card account remained the same and only the expiration date was updated. |
Updated 6 months ago
Check out code examples and more in the following articles!