Account Updater¶
Version: 3
1.0 Introduction¶
Merchants can use the Account Updater to check for changes in customer's card details and ensure they are up to date.
This is especially useful alongside recurring payments whereby a customer uses the same card to make the recurring payments over a period. But payments can fail if a customer's card details have to change due to a card expiring or being reported lost or stolen.
The Account Updater gives you access to the VISA Account Updater (VAU) and Mastercard Automatic Billing Updater (ABU) service which will help you to keep customers payment card details up to date.
This API may not be immediately available to you, you should contact your Paythru account representative to find out how you can start using this API.
2.0 API Overview¶
This API is a web service. All functionality of the API is accessed by performing HTTP POST method requests directly from the merchant's web servers using an SSL connection.
2.1 API Requests¶
This API accepts HTTP POST method requests using an SSL connection (HTTPS). The key-value parameters sent in body of the request must be encoded using the application/form-url-encoded Internet media type.
The data returned in the response to the HTTP request can be encoded in a choice of either XML or JSON encoding.
The request must be submitted from the merchant's servers to Paythru's servers using the appropriate URL. Under no circumstances should requests be made to the API directly from the customer's web browser or mobile application.
2.2 Request URL¶
| Environment | URL |
|---|---|
| Live | https://ws.paythru.com |
| Staging (or sandbox) | https://ws.demo.paythru.com |
The examples in the document use relative URLs, which must be prepended with a URL from the above table depending on the environment in use. To use the sandbox account, the format of the request will be the same but you will need to change the URL you send requests into. Note that credentials are not shared between Staging and Live.
Requests to the Paythru Account Updater API should be sent to a URL constructed in the following manner:
/v{version number}/token/{method name}/{response encoding}
The {version number} segment within the URL should be replaced with the version of the API. The current version of the API is 3.
The {method name} segment within the URL should be replaced with the method of the API being requested.
The last segment of the URL - {response encoding} indicates whether the response from the web service should be encoded in XML or JSON.
Example URL¶
For example, a request to the requestAccountUpdater method of version 3 of this API with the response encoded in JSON should be sent to the following URL:
/v3/token/requestAccountUpdater/json
Please note that if the response encoding segment of the URL is not provided, the response will be encoded in XML.
2.3 API Responses¶
Requests to the API processed successfully will be responded to with a 200 (OK) HTTP response code. The data contained within the body of the response will be encoded in either XML or JSON as requested. Requests that are unable to be processed will be responded to with either the HTTP response code 400 (Bad Request), 401 (Unauthorized) or 403 (Forbidden) depending on the nature of the error.
XML encoded responses¶
The response parameters within an XML encoded response will be returned as XML elements, the name of which will be the parameter name, and the value contained within, its associated value. All the response data elements will be contained within a root element named 'paythruResponse'.
<?xml version="1.0" encoding="UTF-8"?>
<paythruResponse>
<responseParameter>Response value</responseParameter>
...
</paythruResponse>
JSON encoded responses¶
The response parameters within a JSON encoded response will be returned as properties of a single JSON object, the name of which will be parameter name and the value, its associated value.
{"responseParameter":"response Value", ...}
2.4 Authentication¶
All requests made to the API require authentication. Two request parameters (apiKey and apiPassword) are required to be sent with each request to the service. These parameters will be provided by Paythru when the account is created.
If more than 5 requests are made containing invalid credentials within the same day, Paythru will not accept any further requests from the originating IP address for a period of one minute. After 10 requests failing authentication, the IP address will be blocked for 5 minutes.
2.5 Signing the request¶
All requests to this API must be signed by constructing a hash of the request parameters and the shaKey (provided by Paythru) using the following steps:
- Arrange all request parameters in ascending alphabetical order (i.e. a-z) by parameter name (not including the shaSignature parameter)
- Remove parameters with no value
- Concatenate the parameter name, an equals symbol, the parameter value and your shaKey
- Concatenate all resulting strings in order
- Hash the resulting string using SHA512
See gateway API documentation for more details about signing the request
3.0 Methods¶
3.1 Request Account Updater¶
Description¶
The Request Account Updater request can be used to submit new account update requests to obtain updated card details from the card schemes.
This API call queues an update request for the cards provided within the request, the response to this request will be posted back to your provided callbackUrl when the batch has finished processing. This process will typically take 24 hours.
Note: cards which are duplicated in the request will cause the call to fail. You can check the cardUniqueIdentifier to help establish uniqueness of cards being submitted.
URL¶
/v3/token/requestAccountUpdater
Request parameters¶
| Name | Description | Format |
|---|---|---|
| apiKey† | The API Key provided by Paythru used for authentication. | Alpha-numeric characters |
| apiPassword† | The API Password provided by Paythru used for authentication. | Alpha-numeric characters |
| accountUpdaterKey† | A key provided by Paythru to specify the service configuration on our side. | Alpha-numeric characters |
| cardKey† | The card key, or keys, to check for an update. Multiple card keys should be separated with a comma. All cards submitted in the same request must be unique. | String. Maximum of 5,000 individual cardKeys. |
| callbackUrl | A URL (with a valid SSL certificate) to which Paythru will send response of the account updater when we retrieve data from the acquirer. See section 4 for more details. | String |
† denotes a required field
Response parameters¶
| Name | Description | Format |
|---|---|---|
| result | The result of the request. | OK / ERROR |
| batchKey | The unique reference for the request generated by Paythru. This key is needed to retrieve data with retrieveAccountUpdater or match a request if you're using a callbackUrl. | 32 alpha numeric characters |
Example Requests¶
HTTP Request¶
POST /v3/token/requestAccountUpdater/xml HTTP/1.1
Host: ws.paythru.com
Content-Length: 352
Content-Type: application/x-www-form-urlencoded
apiKey=************
&apiPassword=**********
&accountUpdaterKey=accUpdaterKeyA
&cardKey=ad269ad7-d40b-fc01-5bf1-86aaa379f611,ff3af4d9-8a0a-33d9-3434-a3160041deba,e5dc5818-40a8-cca3-230c-0420585847b0
&callbackUrl=https://example.com/handleAccountUpdater
&shaSignature=146583b28e89fgeb56ce2a8b925d25e9g05ddacf5b5f91
gbceb0e63f7321acd29bfe804e06eg0e017173f1bcb3a5b3g5f6b5337g0g
a3bfg36bb64d78381f8249
Example Responses¶
HTTP Response (XML)¶
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 363
<?xml version="1.0" encoding="UTF-8"?>
<paythruResponse>
<result>OK</result>
<batchKey>61eafe55a22b13064db2d6eb3a00e688</batchKey>
</paythruResponse>
HTTP Response (JSON)¶
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: 97
{"result":"OK",
"batchKey":"61eafe55a22b13064db2d6eb3a00e688"}
3.2 Retrieve Account Updater¶
Description¶
The Retrieve Account Update request can be used to retrieve a request that was previously submitted to Request Account Update.
If the batch is finished processing you will receive information on any updated cards. Each updated card is given a new Paythru Card Key and you will be in control of when to use the new Paythru Card Key and what to do with the old Paythru Card Key.
URL¶
/v3/token/retrieveAccountUpdater
Request parameters¶
All parameters are required.
| Name | Description | Format |
|---|---|---|
| apiKey† | The API Key provided by Paythru used for authentication. | Alpha-numeric characters |
| apiPassword† | The API Password provided by Paythru used for authentication. | Alpha-numeric characters |
| batchKey† | The key received from the Request Account Updater response, | Alpha-numeric characters |
† denotes a required field
Response parameters¶
| Name | Description | Format |
|---|---|---|
| batchKey | The batch key | 32 alpha numeric characters |
| createdOn | The date and time the batch was created | ISO 8601 date |
| cardKeyDetails | Node containing details of each card token returned | n/a |
| cardKeyDetails > cardKeyDetail | Node containing the details of the card token | n/a |
| cardKeyDetails > cardKeyDetail > cardKey > oldCardKey | The reference of the old card token | Alpha-numeric characters |
| cardKeyDetails > cardKeyDetail > cardKey > response | The status of the card retrieval | See Appendix 5.2 |
| cardKeyDetails > cardKeyDetail > cardKey | The reference of the new card token | Alpha-numeric characters |
| cardKeyDetails > cardKeyDetail > cardUniqueIdentifier | A unique identifier for a card | Numeric characters |
| cardKeyDetails > cardKeyDetail > merchantCustomerReference | The merchant's reference of the customer to whom the card belongs | Alpha-numeric characters |
| cardKeyDetails > cardKeyDetail > enabled | Flag indicating if the card token is enabled - "1" if enabled, "0" if disabled | "1" or "0" |
| cardKeyDetails > cardKeyDetail > card | Node containing the card details of the card token | n/a |
| cardKeyDetails > cardKeyDetail > card > cardDescription | The name for the card | Alpha-numeric characters |
| cardKeyDetails > cardKeyDetail > card > cardHolderName | The cardholder's name as printed on their card | Alpha-numeric characters and symbols |
| cardKeyDetails > cardKeyDetail > card > cardNumber | The full primary account number (PAN) of the card. (Please node that the card number will be masked) | Up to 16 numeric an "*" characters |
| cardKeyDetails > cardKeyDetail > card > cardExpiryMonth | The month of the card's expiration date | 2 numeric characters |
| cardKeyDetails > cardKeyDetail > card > cardExipryYear | The year of the card's expiration date | 4 numeric characters |
| cardKeyDetails > cardKeyDetail > card > cardType | The type of card (e.g. "CREDIT", "DEBIT" etc.) where resolved | Alpha-numeric characters and symbols |
| cardKeyDetails > cardKeyDetail > card > cardScheme | The scheme of card (e.g. "VISA", "MasterCard" etc.) where resolved | Alpha-numeric characters and symbols |
| cardKeyDetails > cardKeyDetail > card > cardBank | The issuing bank of the card where resolved | Alpha-numeric characters and symbols |
Example Requests¶
HTTP Request¶
POST /v3/token/requestAccountUpdater/xml HTTP/1.1
Host: ws.paythru.com
Content-Length: 355
Content-Type: application/x-www-form-urlencoded
apiKey=************
&apiPassword=**********
&batchKey=61eafe55a22b13064db2d6eb3a00e688
Example Responses¶
HTTP Response (XML)¶
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 363
<?xml version="1.0" encoding="UTF-8"?>
<paythruResponse>
<batchKey>1b9c8ba95bd439302d51c4c9bb6e3fb4</batchKey>
<createdOn>2019-09-26T12:27:25+00:00</createdOn>
<cardKeyDetails>
<cardKeyDetail>
<oldCardKey>07310f19-13e9-64af-be17-dcdf319443e6</oldCardKey>
<response>702</response>
<cardKey>3297a926-68f5-8feb-1c5b-8da0a3f4e48e</cardKey>
<cardUniqueIdentifier>65102</cardUniqueIdentifier>
<merchantCustomerReference>mrd002</merchantCustomerReference>
<enabled>1</enabled>
<card>
<cardDescription>Card desc 203</cardDescription>
<cardholderName>John Smith</cardholderName>
<cardNumber>545454******5454</cardNumber>
<cardExpiryMonth>03</cardExpiryMonth>
<cardExpiryYear>2020</cardExpiryYear>
<cardType/>
<cardScheme>Mastercard</cardScheme>
<cardBank>BANK HANDLOWY W WARSZAWIE, S.A.</cardBank>
</card>
</cardKeyDetail>
<cardKeyDetail>
<oldCardKey>4254f5a2-98bd-7572-0035-875ff8a90aa9</oldCardKey>
<response>700</response>
<cardKey>242ca6df-ae08-1db0-20ed-ad5fff8dba31</cardKey>
<cardUniqueIdentifier>66005</cardUniqueIdentifier>
<merchantCustomerReference>mrd002</merchantCustomerReference>
<enabled>1</enabled>
<card>
<cardDescription>Card desc 635</cardDescription>
<cardholderName>John Smith</cardholderName>
<cardNumber>111122******4444</cardNumber>
<cardExpiryMonth>12</cardExpiryMonth>
<cardExpiryYear>2020</cardExpiryYear>
<cardType>CREDIT</cardType>
<cardScheme>Visa</cardScheme>
<cardBank>Paythru</cardBank>
</card>
</cardKeyDetail>
<cardKeyDetail>
<oldCardKey>8a74acd4-fe4c-6394-c882-439172b32cc3</oldCardKey>
<response>706</response>
</cardKeyDetail>
</cardKeyDetails>
</paythruResponse>
HTTP Response (JSON)¶
HTTP/1.1 200 OK
Content-Type: text/json; charset=utf-8
Content-Length: 497
{
"batchKey":"1b9c8ba95bd439302d51c4c9bb6e3fb4",
"createdOn":"2019-09-26T12:27:25+00:00",
"cardKeyDetails":[
{
"oldCardKey":"07310f19-13e9-64af-be17-dcdf319443e6",
"response":"702",
"cardKey":"3297a926-68f5-8feb-1c5b-8da0a3f4e48e",
"cardUniqueIdentifier":"65102",
"merchantCustomerReference":"mrd002",
"enabled":"1",
"card":{
"cardDescription":"Card desc 203",
"cardholderName":"John Smith",
"cardNumber":"545454******5454",
"cardExpiryMonth":"03",
"cardExpiryYear":"2020",
"cardType":null,
"cardScheme":"Mastercard",
"cardBank":"BANK HANDLOWY W WARSZAWIE, S.A."
}
},
{
"oldCardKey":"4254f5a2-98bd-7572-0035-875ff8a90aa9",
"response":"700",
"cardKey":"242ca6df-ae08-1db0-20ed-ad5fff8dba31",
"cardUniqueIdentifier":"66005",
"merchantCustomerReference":"mrd002",
"enabled":"1",
"card":{
"cardDescription":"Card desc 635",
"cardholderName":"John Smith",
"cardNumber":"111122******4444",
"cardExpiryMonth":"12",
"cardExpiryYear":"2020",
"cardType":"CREDIT",
"cardScheme":"Visa",
"cardBank":"Paythru"
}
},
{
"oldCardKey":"8a74acd4-fe4c-6394-c882-439172b32cc3",
"response":"706"
}
]
}
4.0 Callbacks¶
If a callback URL is specified in the Request Account Updater call, an HTTP POST will be sent to the supplied URL when the update has finished processing.
The callback data will be formatted as either XML or JSON depending on the response type of the Request Account Updater call. See the response format of calls to retrieveAccountUpdater for the format of the callback data.
Processing a batch takes up to 24 hours, and only at the end of processing will a callback be sent. You can query retrieveAccountUpdater any time, but it will only return updated cards once the batch has finished processing.
5.0 Appendix¶
5.1 Error codes and messages¶
| Error code | Error message |
|---|---|
| 101 | No data sent |
| 102 | Invalid API credentials |
| 103 | Invalid function call |
| 104 | Invalid return type |
| 105 | Cannot find API settings for merchant |
| 106 | Permission denied to access this function |
| 180 | Invalid account updater key |
| 181 | Error getting data from the batch |
| 182 | Account updater batch is still pending |
| 183 | Invalid account updater batch key |
| 184 | Invalid callback URL |
5.2 Card retrieval response code¶
Card responses may contain a code which represents the reason for the given status of the card.
| Response Code | Description |
|---|---|
| 700 | Account number updated |
| 701 | Closed account advice |
| 702 | Expiration date changed |
| 703 | Participating BIN, no match |
| 704 | Non-participating BIN |
| 705 | Contact cardholder advice (the merchant should contact the cardholder for additional information on the account) |
| 706 | Match made, account number and expiration date unchanged |
| 707 | Account number change (the account number or account number and expiration date are updated) |
| 708 | Invalid account number |
| 709 | Invalid expiration date |
| 710 | Merchant not registered |
| 711 | Sub merchant not registered |
| 712 | Brand flip to Mastercard |
5.3 Test card numbers¶
If your account on our demo environment is configured to use our Paythru account updater simulator then you will be able to make use of the following card number values to simulate specific account updater events.
The Paythru account updater simulator processes after 2 minutes to allow for more rapid prototyping, but the live account updater processes just once in 24 hours.
| Card number | Result |
|---|---|
| 4444333322221111 | 700 - returns a new card with the number 1111222233334444 |
| 1111222233334444 | 700 - returns a new card with the number 4444333322221111 |
| 5454545454545454 | 702 - returns the same card number back with the expiry date incremented by one month |
| Any other Luhn valid card number | 706 - Match made, account number and expiration date unchanged |
You can use the Client POST API to create an initial cardKey.