Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
developer:api_specification:account_updater [2018/11/12 18:18]
thiago123 old revision restored (2018/05/25 16:31)
developer:api_specification:account_updater [2018/11/12 18:18] (current)
Line 1: Line 1:
 +====== Account Update and Background Notification ======
  
 +~~TOC~~
 +
 +\\
 +"​Account Updater"​ refers to secure cards saved on %CompanyName’s system, which have had their Cardholder details updated electronically via "Visa Account Updater"​ (VAU) and "​Mastercard Automatic Billing Updater"​ (ABU) respectively. This is a process which helps to ensure a smooth automatic billing cycle by minimizing payment disruptions due to account changes.
 +
 +Case example:
 +
 +  * Customers secure cards are saved to the gateway
 +  * A monthly subscription is created for the customer
 +  * As time passes, eventually, the cards expire
 +  * %CompanyName sends a request to Mastercard or Visa asking for the new cards' details
 +  * Visa/ Mastercard sends the updated card details back to %CompanyName
 +  * The customers'​ cards (secure cards) are updated with new info
 +  * Next months subscription won’t be affected because we now have the correct card details stored for the customers.
 +
 +The Account Updater operations run as a background task, constantly, and sends batches of Account Updater details to each terminal’s specified notification URL (Configured at Terminal Level for the specific purpose of notifying Terminals of this type of change). ​
 +
 +This allows integrations with the Payment Gateway to keep their customers masked card details with valid data on their side - always updating whenever the card scheme sends new data.
 +
 +Each request containing the Account Updater details will be stored until it has been accepted and validated by the specified notification host.
 +
 +After receiving this request, the Merchant'​s Integration side should send a reply messages to:
 +
 +%URLAccountUpdaterNotification
 +
 +The live URL will be provided once merchant testing is completed. ​
 +
 +<WRAP center info 100%>
 +**Additionally**:​ a new report was added under the Reporting section of %SelfCare System, where the Merchants can keep track of the updates performed by the Account Update feature. Take a look at the %selfCare Guide for more details >> **[[merchant:​existing_merchant:​selfcare_system|SelfCare System]]** <<.
 +</​WRAP>​
 +\\
 +
 +===== System Start-up =====
 +
 +To enable the Account Updater Background Notifications(AUBN) it is required to set up your terminal to use the new AUBN feature.
 +
 +Please note that as default the the number of cards sent for each notification will be set to 10,000. If you need to change this limit, please contact %CompanyName.
 +
 +===== Message Specification =====
 +
 +The body of each message is in the format of Comma Separated Values (CSV). Each Account Updater Notification Request from the gateway will contain the following CSV headers and appropriate values.
 +
 +==== Request From Gateway ====
 +
 +Format to HTTP Post:
 +
 +  * **Produces**:​​ text/plain
 +  * **Consumes**:​​ text/plain
 +
 +The request message size can be modified in a Gateway’s System Settings. The maximum size is 10,000. To ensure messages are not fragmented because of their Secure Card Custom Field names; the Secure Card custom fields are set as name/value pairs in the CSV string. More specifically,​ they are located under the SCCF1/2/3 columns, and have their names and values delimited by the String "<​AUBN||MSG>"​.
 +
 +**The Gateway Sends this request to**: The ​Account Updater Background Notification URL​ set in Terminal Settings.
 +
 +=== Request Body Fields ===
 +
 +^ HEADER ​                 ^ TYPE     ^ DESCRIPTION ​                                                                                                                                                    ^
 +| TERMINAL NUMBER ​        | Numeric ​ | Gateway terminal which the card belongs to                                                                                                                      |
 +| MASKED CARD DETAILS ​    | String ​  | Card Number with the first 6, and the last 4 digits visible. ​                                                                                                   |
 +| MERCHANT REFERENCE ​     | String ​  | Merchant reference stored on the gateway ​                                                                                                                       |
 +| HASH                    | String ​  | The hash of the current row of data. See **[[developer:​api_specification:​account_updater#​message_hash|Message Hash]]** subsection for more details. ​                                                                          |
 +| CARD TYPE               | String ​  | Card type, e.g. Visa, Mastercard, etc.                                                                                                                          |
 +| STATUS ​                 | Integer ​ | Status Code​ of the Secure Card Update. See **[[developer:​api_specification:​account_updater#​account_updater_status_codes|Account Updater Status Codes]]** for more details.|
 +| CURRENT EXPIRY ​         | String ​  | Card expiry date in the format of "​MMYY"​. ​                                                                                                                      |
 +| CARD MODIFICATION DATE  | String ​  | The date the secure card was last updated on the gateway via Account Updater. Date format = "​yyyy-MM-dd:​HH:​mm:​ss" ​                        |
 +| UUID                    | String ​  | Unique ID to validate message authenticity ​                                                                                                                     |
 +| MSG EXPIRES IN          | Numeric ​ | Milliseconds. When the gateway will stop accepting merchant responses for this request. ​                                                                        |
 +| SCCF1                   | String ​  | Any secure card custom fields will go here. The string will contain both name and value of the secure card custom field. For more information see **ND001** below  |
 +| SCCF2                   | String ​  | Same as SCCF1 |
 +| SCCF3                   | String ​  | Same as SCCF1 |
 +| ALGORITHM ​              | String ​  | The hashing algorithm used for the hash string |
 +
 +=== Notes and Details About the Request ===
 +
 +**ND001 - Name and Value Format** ​
 +
 +The name, and value will be delimited by the String “<​AUBN||MSG>​”.
 +
 +**For example:**
 +  * "​name<​AUBN|MSG>​value"​
 +  * "​exigoID<​AUBN|MSG>​213545"​
 +
 +==== Received Reply From Merchant ====
 +
 +Format to HTTP Post:
 +
 +  * **Produces**:​ text/plain
 +  * **Consumes**:​ text/plain
 +
 +Once the request is received by the merchant, they should reply with the String “OK” immediately,​ and a response code of 200.
 +
 +The server expects a **OK** as the reply.
 +
 +=== Processed Reply From Merchant ===
 +
 +Format to HTTP Post:
 +
 +  * **Produces**:​ text/plain
 +  * **Consumes**:​ text/plain
 +  * **Reply URL:** %URLAccountUpdaterNotification
 +
 +The live URL will be provided once merchant testing is completed. ​
 +
 +After the ‘received reply’ is sent, the merchant server can proceed with processing the account updater background notification data received from the gateway. Once the CSV has been processed on the merchant side, it is required that the gateway be notified if it has been a success or failure.
 +
 +The reply message must contain the following CSV Headers on the first line of the reply.
 +
 +=== Response Body Fields ===
 +
 +^ HEADER ​          ^ TYPE          ^ DESCRIPTION ​                                                                         ^
 +| TERMINAL NUMBER ​ | Numeric ​      | Gateway terminal which the card belongs to                                           |
 +| UUID             | String ​       | The original UUID from the original incoming request. Used for message authenticity ​ |
 +| SUCCESS ​         | Int - 0 or 1  | Flag that identifies if the card was processed successfully or not. Possible values: 0 or 1 |
 +| ERROR MSG        | String ​       | Error Message indicating why it failed. Empty String if successful. ​                 |
 +| HASH             | String ​       | Hash string of the previous values in the row. See **[[developer:​api_specification:​account_updater#​message_hash|Message Hash]]** subsection for more details. |
 +| ALGORITHM ​       | String ​       | The hashing algorithm used for the hash string. ​                                     |
 +
 +==== Message Hash ====
 +
 +To determine message authenticity on the merchant side, each row in the csv string of the request message has to be hashed along with the terminals secret passphrase. The hashing algorithm used will be specified in the “ALGORITHM” column in the CSV data. The default hashing algorithm used is “SHA-512”. Check section for valid algorithms. Each column in each row will be concatenated and hashed using the specified algorithm.
 +
 +=== Hashing with Algorithm ===
 +
 +  * Firstly, the each value in the CSV row will need to be concatenated with the other values in the row.
 +  * The terminal’s secret passphrase should be appended to the end of the string.
 +  * The order in which this should be done is as follows:
 +
 +The gerenal rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page. For this specific feature, you should use the following formats:
 +
 +**For Request Row Hash**
 +
 +<WRAP center box 100%>
 +TERMINALNUMBER:​MASKEDCARDDETAILS:​MERCHANTREF:​CARDTYPE:​STATUS:​CURRENTEXPIRYDATE:​CARDMODIFICATIONDATE:​UUID:​MSGEXPIRESIN:​SCCF1:​SCCF2:​SCCF3:​TERMINALSECRET
 +</​WRAP>​
 +
 +\\
 +**For Response Row Hash**
 +
 +<WRAP center box 100%>
 +TERMINALNUMBER:​UUID:​SUCCESS:​ERRORMSG:​TERMINALSECRET
 +</​WRAP>​
 +
 +=== Supported Hashing Algorithms ===
 +
 +The hashing algorithms that the gateway supports are listed below; these algorithms are valid values for the “ALGORITHM” column in the CSV data.
 +
 +^ Algorithm ​ ^ String Format ​ ^
 +| MD5        | Hexadecimal ​   |
 +| SHA-256 ​   | Hexadecimal ​   |
 +| SHA-384 ​   | Hexadecimal ​   |
 +| SHA-512 ​   | Hexadecimal ​   |
 +
 +===== Additional Information =====
 +
 +==== Account Updater Status Codes ====
 +
 +The message from the gateway contains a field called “STATUS”. This field reflects the gateways Secure Card account updater status. This means that the gateway has sent this secure card to Mastercard/​Visa (ABU/VAU) and received an update status from their service.
 +
 +The following table details the meaning of each status code.
 +
 +^ Code  ^ Name                          ^ Description ​                                                                                                                                    ^
 +| 1     | UPDATE ​                       | Match made; update data provided ​ / Account number change (the account number or account number and expiration date are updated). ​              |
 +| 2     | EXPIRY ​                       | Match made; expiration date changed ​                                                                                                            |
 +| 3     | VALID                         | Match made, account number and expiration date unchanged / No updates were found but the account is valid. ​                                     |
 +| 4     | CONTACT_CLOSED ​               | Match made; account closed / contact cardholder advice (the merchant should contact the cardholder for additional information on the account). ​ |
 +| 5     | CONTACT ​                      | Contact cardholder advice ​                                                                                                                      |
 +| 6     | UNKNOWN ​                      | The account number could not be found                                                                                                           |
 +| 7     | PARTICIPATING ​                | No match, participating BIN/​issuer ​                                                                                                             |
 +| 8     | NON_PARTICIPATING ​            | No match, non-participating BIN/​issuer ​                                                                                                         |
 +| 9     | ER_UNSUPPORTED_RESPONSE_CODE ​ | Unsupported response code                                                                                                                       |
 +| 10    | IN_PROCESS ​                   | Deprecated. No longer sending this response code to merchants. ​                                                                                 |
 +| 101   | ER_000101 ​                    | Non-numeric Account Number ​                                                                                                                     |
 +| 102   | ER_000102 ​                    | Account Number is not in BIN Range                                                                                                              |
 +| 103   | ER_000103 ​                    | Invalid Expiration Date                                                                                                                         |
 +| 104   | ER_000104 ​                    | Merchant Not Registered ​                                                                                                                        |
 +| 122   | ER_000122 ​                    | Unregistered Sub-merchant ​                                                                                                                      |
 +| -1    | UNDEFINED ​                    | STATUS_UNKNOWN status ​                                                                                                                          |
 +
 +==== Test Data ====
 +
 +The following test data can be used to test your AUBN Service.
 +
 +Note: The Terminal Secret used in the following data is: **secretpass**
 +
 +**Request From Gateway:**
 +
 +<​code>​
 +"​TERMINAL NUMBER","​MASKED CARD DETAILS","​MERCHANT REFERENCE","​HASH","​CARD TYPE","​STATUS","​CURRENT EXPIRY","​CARD MODIFICATION DATE","​UUID","​MSG EXPIRES IN","​SCCF1","​SCCF2","​SCCF3","​ALGORITHM"​
 +"​11001","​448596******3864","​1000029","​98643049966a2d1062f1a3c1f6fdbbccbf0b27cbc7151ddc3f27b5f8f19df989","​VISA","​1","​1218","​2016-09-20:​20:​00:​34","​5fa3e885-98f2-4e0b-9d29-8c6fe463ec33","​150000","​robsSCCF<​AUBN||MSG>​test123","","","​SHA-256"​
 +"​11001","​402400******8322","​1000021","​ff33eee3fc5bef72bafef621dd7e653c1d5c993744676daac850d63de11c5d89","​VISA","​1","​1218","​2016-09-20:​20:​00:​21","​7bae3ecf-97c4-43b1-89a0-25797ca325e9","​150000","​robsSCCF<​AUBN||MSG>​testtest","","","​SHA-256"​
 +"​11001","​541022******0093","​100002","​636159312e39094758f07edf3630720793f74bb5930f22ec3b867f968106462b","​MASTERCARD","​1","​1218","​2016-09-20:​20:​00:​07","​18c78348-cd35-4e35-a817-7dd34dad955c","​150000","​robsSCCF<​AUBN||MSG>​tester1","","","​SHA-256"​
 +</​code>​
 +
 +Service should immediately reply with “OK”, and process the CSV in a separate thread.
 +
 +After CSV parsing/​processing the service should respond to the URL specified in item **Processed Reply From Merchant**, under **[[developer:​api_specification:​account_updater#​received_reply_from_merchant|Received Reply From Merchant]]** subsection.
 +
 +
 +**Expected Reply From Service:**
 +
 +<​code>​
 +"​TERMINAL NUMBER","​UUID","​SUCCESS","​ERROR MSG","​HASH","​ALGORITHM"​
 +"​11001","​5fa3e885-98f2-4e0b-9d29-8c6fe463ec33","​1","","​bdd07d8c8dcd428536b2a9fbe4ac0f5f9d84f321af5f3d4f26c15968688dea8c","​SHA-256"​
 +"​11001","​7bae3ecf-97c4-43b1-89a0-25797ca325e9","​1","","​1dc620e8c4d8c82febaa0a2599c693b5a74cd7c0346c7f79af70b6db5d870396","​SHA-256"​
 +"​11001","​18c78348-cd35-4e35-a817-7dd34dad955c","​1","","​5ce1c3d9408a0c6d015132a67c2630bdddb3e73edd1bfec9c8ee0e7709e15dc2","​SHA-256"​
 +</​code>​
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International