Account Updater

Version: 3

1.0 Introduction

Merchants can use the Account Updater to check for changes in customers' 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:

  1. Arrange all request parameters in ascending alphabetical order (i.e. a-z) by parameter name (not including the shaSignature parameter)
  2. Remove parameters with no value
  3. Concatenate the parameter name, an equals symbol, the parameter value and your shaKey
  4. Concatenate all resulting strings in order
  5. 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.