Menu

User Tools

Create PDF

Site Tools


Differences

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

Go

Link to this comparison view

token_migration_tool [2019-07-03 11:13]
dorothea.bartel
token_migration_tool [2019-11-11 14:54] (current)
Line 1: Line 1:
 ====== Token Migration Tool ====== ====== Token Migration Tool ======
 +
  
 ===== Introduction ===== ===== Introduction =====
  
-The Token Migration Tool (ToMi) enables merchants to continue processing recurring payments after migration to the Wirecard REST API. With ToMi, you just need to provide the order number which is currently used to reference recurring transaction. ToMi uses this order number and returns the corresponding token (credit card) and transactionId (SEPA Direct Debit)which allows you to continue processing recurring transactions for that order without interruptions.+The Token Migration Tool (ToMi) enables merchants to continue processing recurring payments after migration to the Wirecard REST API. With ToMi, you just need to provide the order number which is currently used to reference recurring transaction. ToMi uses this order number and returns the ''transactionId'' for SEPA and the ''tokenId'' for Credit Card transactions. For Credit Card transactionsthe ''transactionId'' may be returned in addition to the ''tokenId'', depending on the processing system the order number is found in.  Both ''transactionId'' and ''tokenId'' allow you to continue processing recurring transactions for that order without interruptions. 
  
 ===== Supported Payment Methods ===== ===== Supported Payment Methods =====
Line 11: Line 12:
 ===== User Access ===== ===== User Access =====
 Access is secured with basic access authentication. \\ Access is secured with basic access authentication. \\
-You have to request access to the Token Migration Tool by contacting [[support.at@wirecard.com|merchant support]]. Merchant support provides you with username and password. +You have to request access to the Token Migration Tool by contacting [[support.at@wirecard.com|merchant support]]. \\ Merchant support provides you with username and password. 
  
-===== REST API endpoints =====+ 
 +===== Single Order Processing ===== 
 + 
 + 
 + 
 +  
 +==== Endpoint ====
  
 ^ Environment ^ URL ^ ^ Environment ^ URL ^
 | Production | %%https://checkout.wirecard.com/migration-transaction%% | | Production | %%https://checkout.wirecard.com/migration-transaction%% |
-| Test | %%https://checkout-test.wirecard.com/migration-transaction%% | +==== Request ====
-  +
-===== Request =====+
  
-==== Header ====+=== Header ===
  
 +  * POST /migration-transaction
 +  * Host: checkout.wirecard.com
   * Content-Type: application/json   * Content-Type: application/json
-  * HTTP method: POST 
  
-==== JSON Schema ====+ 
 +=== JSON Schema ===
  
 <code> <code>
Line 45: Line 52:
 </code> </code>
  
-==== Sample Requests ====+=== Sample Requests ===
  
-=== Sample Request for Credit Card ===+== Sample Request for Credit Card ==
 <code> <code>
 { {
-  "orderNumber": 123456,+  "orderNumber": "123456",
   "paymentMethod" : "creditcard"   "paymentMethod" : "creditcard"
 } }
 </code> </code>
  
-=== Sample Request for SEPA ===+== Sample Request for SEPA ==
 <code> <code>
 { {
-  "orderNumber": 654321,+  "orderNumber": "654321",
   "paymentMethod" : "sepa"   "paymentMethod" : "sepa"
 } }
 </code> </code>
  
-===== Response =====+==== Response ====
  
-==== Header ====+=== Header ===
   * Content-Type: application/json   * Content-Type: application/json
   * Possible status codes: 201 | 400 | 404 | 500   * Possible status codes: 201 | 400 | 404 | 500
  
-==== JSON Schema - Success Response ====+=== JSON Schema ===
  
 +== Success Response ==
 <code> <code>
 { {
Line 93: Line 101:
 </code> </code>
  
-==== JSON Schema - Error Response ====+== Error Response ==
  
 <code> <code>
Line 101: Line 109:
             "type": "integer"             "type": "integer"
         },         },
-        "message": "+        "message": { 
-            "type" "string"+            "type""string"
         }         }
     }     }
Line 108: Line 116:
 </code> </code>
  
-==== Sample Responses ====+== Sample Responses ==
 Here you find possible responses for success and failure. Here you find possible responses for success and failure.
  
-=== Success Example 201 Credit Card === +//Success Example 201 Credit Card// \\ 
-For payment method credit card, there is the additional response field ''tokenId''.+For payment method ''creditcard'', there is the additional response field ''tokenId''.
 <code> <code>
 { {
-  "orderNumber": 123456,+  "orderNumber": "123456",
   "merchantAccountId": "62652b50-01d5-11e9-b568-0800200c9a66",   "merchantAccountId": "62652b50-01d5-11e9-b568-0800200c9a66",
   "transactionId": "5d7fadd8-37d5-4578-a815-dcac8626121c",   "transactionId": "5d7fadd8-37d5-4578-a815-dcac8626121c",
-  "tokenId": "4351742214741003" +  "tokenId": "4351742214741003", 
-  "transactionServer": "api-wdcee.wirecard.com",+  "transactionServer": "api-wdcee.wirecard.com"
 } }
 </code> </code>
  
-=== Success Example 201 SEPA ===+//Success Example 201 SEPA//
  
 <code> <code>
 { {
-  "orderNumber": 654321,+  "orderNumber": "654321",
   "merchantAccountId": "62652b50-01d5-11e9-b568-0800200c9a66",   "merchantAccountId": "62652b50-01d5-11e9-b568-0800200c9a66",
   "transactionId": "5d7fadd8-37d5-4578-a815-dcac8626121c",   "transactionId": "5d7fadd8-37d5-4578-a815-dcac8626121c",
-  "transactionServer": "api-wdcee.wirecard.com",+  "transactionServer": "api-wdcee.wirecard.com"
 } }
 </code> </code>
  
-=== Error Example 404 ===+//Error Example 404//
  
 <code> <code>
Line 143: Line 151:
 </code> </code>
  
-=== Error Example 400 ===+//Error Example 400//
  
 <code> <code>
Line 150: Line 158:
   "message": "OrderNumber '0' is too small."   "message": "OrderNumber '0' is too small."
 } }
 +</code>
 +
 +===== Batch Processing =====
 +
 +You can process multiple orders at once by uploading a CSV file containing the respective order data.
 +
 +==== CSV File Format Requirements ====
 +
 +  * File extension:*.csv* (* = any filename, e.g. tomi_example.csv)
 +  * The CSV file must contain a header row naming the label of each column (OrderNumber, PaymentMethod).
 +  * The header row is followed by data rows for each order to be processed.
 +  * All entries of a row must be separated by a comma.
 +
 +=== Sample CSV file ===
 +
 +<code>
 +OrderNumber,PaymentMethod
 +13926123,creditcard
 +2569588,creditcard
 +4504686,creditcard
 +382313,creditcard
 +9380547,sepa
 +</code>
 +
 +<note important>''PaymentMethod'' only allows the values ''creditcard'' or ''sepa''.</note>
 +==== Endpoint ====
 +
 +^ Environment ^ URL ^
 +| Production | %%https://checkout.wirecard.com/migration-batch-transaction%% |
 +
 +==== Workflow ====
 +
 +<note important>As each step has a functional dependency on the preceding one, make sure to follow the given order.</note>
 +
 +To process multiple orders at once,
 +
 +**1. Upload the CSV file.**
 +
 +=== Sample Request ===
 +
 +== Header ==
 +
 +  * POST /migration-batch-transaction/file-upload
 +  * Host: checkout.wirecard.com
 +  * Content-Type: multipart/form-data
 +  * cache-control: no-cache
 +  * file=@tomi_example.csv
 +
 +=== Sample Response ===
 +
 +<code>
 +{
 +    "File process started, process id:7"
 +}
 +</code>
 +
 +**2. Process the CSV file.**
 +
 +=== Sample Request ===
 +
 +== Header ==
 +
 +  * GET /migration-batch-transaction/file/7
 +  * Host: checkout.wirecard.com
 +  * cache-control: no-cache
 +
 +<note important> Make sure the file path ends with the value returned for ''process id'' in the response of step 1. Follow the example above: ''/migration-batch-transaction/file/**7**''</note>
 +
 +=== Sample Response ===
 +
 +<code>
 +{
 +    "fileId": 7,
 +    "fileName": "tomi_example.csv", 
 +    "status": "Completed", 
 +    "startTime": "2019-10-14T16:07:21", 
 +    "endTime": "2019-10-14T16:07:22", 
 +    "totalRecordsToProcess": 2, 
 +    "errorsCount": 0, 
 +    "completedCount": 2, 
 +    "recordsProcessed": 2 
 +}
 +</code>
 +
 +Possible ''status'' values are:
 +
 +^ Status ^ Description ^ 
 +| ''InProgress'' | Processing of the file / individual orders is not yet complete. | 
 +| ''Completed'' | All orders listed in the file were succesfully processed. |
 +| ''CompletedWithErrors'' | Processing of the file / individual orders was completed with errors. |
 +| ''Error'' | A major error occured, processing failed to start. |
 +
 +<note important>Processing cannot be interrupted until all orders listed in the CSV file have been successfully processed.</note>
 +
 +**3. View Results.**
 +
 +<note warning>Only request results once ''"status": "Completed"'' is returned in the response of step 2. Sending a request earlier leads to incomplete results.</note>
 +
 +=== Sample Request ===
 +
 +== Header ==
 +
 +  * GET /migration-batch-transaction/file/7/records
 +  * Host: checkout.wirecard.com
 +  * cache-control: no-cache
 +
 +=== Sample Response ===
 +
 +<code>
 +[
 +    { 
 +        "id": 16, 
 +        "migrationTransactionFileId": 7, 
 +        "status": "Completed", 
 +        "message": "Migration successfully completed.", 
 +        "orderNumber": "03976124", 
 +        "paymentMethod": "creditcard", 
 +        "merchantAccountId": "6b116488-cfff-4d2f-a345-0d8ede7bd496", 
 +        "transactionId": "d4bc4b14-e598-478f-a542-4abc62c6ffb8", 
 +        "tokenId": "1957638834868024", 
 +        "rowNumber": 1 
 +    }
 +,
 +    { 
 +        "id": 19, 
 +        "migrationTransactionFileId": 7, 
 +        "status": "Completed", 
 +        "message": "Migration successfully completed.", 
 +        "orderNumber": "0769528", 
 +        "paymentMethod": "creditcard", 
 +        "merchantAccountId": "6b116488-cfff-4d2f-a345-0d8ede7bd496", 
 +        "tokenId": "5954438830678018", 
 +        "rowNumber": 2
 +    }
 +]
 </code> </code>
  
Line 155: Line 298:
  
 ^ Error Message ^ Status Code ^ Description ^ Remedy ^ ^ Error Message ^ Status Code ^ Description ^ Remedy ^
-| Provided Payment Method is not valid | 400 | This happens when POST payload as payment method has a value other than creditcard or sepa | To recover from this, verify if payment method is one of those two. | +| Provided Payment Method is not valid | 400 | This happens if the ''paymentMethod'' in the request has a value other than ''creditcard'' or ''sepa''. Verify that the payment method is set to ''creditcard'' or ''sepa''. | 
-| Entity not found | 404 | Possible reason is that merchant configuration is not valid, e.g. there are many configurations for same merchant_account | [[support.at@wirecard.com|Contact merchant support]]. | +| Entity not found | 404 | Possible reason: The merchant configuration is not valid, e.g. there are many configurations for the same ''merchant_account''. Contact [[support.at@wirecard.com|merchant support]] for further questions. | 
-| Order with number '<x>' could not be found | 404 | This error occurs for CREDITCARD or SEPA requestwhen order does not exist in database | Provide a valid order number in request. | +| Order with number '<x>' could not be found | 404 | This error occurs for a ''creditcard'' or ''sepa'' request when the order does not exist in the database| Provide a valid order number in the request. \\ **The error is most likely caused by an outdated order number. Check the order creation date. An order number is valid for 400 days.** \\ Contact [[support.at@wirecard.com|merchant support]] for further questions. | 
-| Internal server error | 500 | Possible reason: HTTP method is not POST | Change HTTP method to POST. Do not use GET, PUT, ... |+| Internal server error | 500 | Possible reason: HTTP method is not ''POST'' | Change HTTP method to ''POST''. Do not use ''GET''''PUT'', ... |
  

This website uses cookies to deliver the best service to you. By continuing to browse the site, you are agreeing to our use of cookies.