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-05 09:24]
token_migration_tool [2019-11-11 14:54] (current)
Line 1: Line 1:
 +====== Token Migration Tool ======
 +
 +
 +===== 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 a recurring transaction. ToMi uses this order number and returns the ''transactionId'' for SEPA and the ''tokenId'' for Credit Card transactions. For Credit Card transactions, the ''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 =====
 +  * Credit Card 
 +  * SEPA Direct Debit
 + 
 +===== User Access =====
 +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. 
 +
 +
 +===== Single Order Processing =====
 +
 +
 +
 + 
 +==== Endpoint ====
 +
 +^ Environment ^ URL ^
 +| Production | %%https://checkout.wirecard.com/migration-transaction%% |
 +==== Request ====
 +
 +=== Header ===
 +
 +  * POST /migration-transaction
 +  * Host: checkout.wirecard.com
 +  * Content-Type: application/json
 +
 +
 +=== JSON Schema ===
 +
 +<code>
 +{
 +    "required": [
 +        "orderNumber",
 +        "paymentMethod"
 +    ],
 +    "properties": {
 +      "orderNumber": {
 +          "type": "integer",
 +      },
 +      "paymentMethod": {
 +          "type": "string",
 +      }
 +    }
 +}
 +</code>
 +
 +=== Sample Requests ===
 +
 +== Sample Request for Credit Card ==
 +<code>
 +{
 +  "orderNumber": "123456",
 +  "paymentMethod" : "creditcard"
 +}
 +</code>
 +
 +== Sample Request for SEPA ==
 +<code>
 +{
 +  "orderNumber": "654321",
 +  "paymentMethod" : "sepa"
 +}
 +</code>
 +
 +==== Response ====
 +
 +=== Header ===
 +  * Content-Type: application/json
 +  * Possible status codes: 201 | 400 | 404 | 500
 +
 +=== JSON Schema ===
 +
 +== Success Response ==
 +<code>
 +{
 +    "properties": {
 +        "orderNumber": {
 +            "type": "integer"
 +        },
 +        "merchantAccountId": {
 +            "type": "string"
 +        },
 +        "transactionId": {
 +            "type": "string"
 +        },
 +        "tokenId": {
 +            "type": "string"
 +        },
 +        "transactionServer": {
 +            "type": "string"
 +        }
 +    }
 +}
 +</code>
 +
 +== Error Response ==
 +
 +<code>
 +{
 +    "properties": {
 +        "status": {
 +            "type": "integer"
 +        },
 +        "message": {
 +            "type": "string"
 +        }
 +    }
 +}
 +</code>
 +
 +== Sample Responses ==
 +Here you find possible responses for success and failure.
 +
 +//Success Example 201 Credit Card// \\
 +For payment method ''creditcard'', there is the additional response field ''tokenId''.
 +<code>
 +{
 +  "orderNumber": "123456",
 +  "merchantAccountId": "62652b50-01d5-11e9-b568-0800200c9a66",
 +  "transactionId": "5d7fadd8-37d5-4578-a815-dcac8626121c",
 +  "tokenId": "4351742214741003",
 +  "transactionServer": "api-wdcee.wirecard.com"
 +}
 +</code>
 +
 +//Success Example 201 SEPA//
 +
 +<code>
 +{
 +  "orderNumber": "654321",
 +  "merchantAccountId": "62652b50-01d5-11e9-b568-0800200c9a66",
 +  "transactionId": "5d7fadd8-37d5-4578-a815-dcac8626121c",
 +  "transactionServer": "api-wdcee.wirecard.com"
 +}
 +</code>
 +
 +//Error Example 404//
 +
 +<code>
 +{
 +  "status": 404,
 +  "message": "Order not found."
 +}
 +</code>
 +
 +//Error Example 400//
 +
 +<code>
 +{
 +  "status": 400,
 +  "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>
 +
 +===== Error Handling =====
 +
 +^ Error Message ^ Status Code ^ Description ^ Remedy ^
 +| 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: 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 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'', ... |
  

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.