Menu

User Tools

Create PDF

Site Tools


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 merchant support.
Merchant support provides you with username and password.

Single Order Processing

Endpoint

Environment URL
Production https://checkout.wirecard.com/migration-transaction

Request

  • POST /migration-transaction
  • Host: checkout.wirecard.com
  • Content-Type: application/json

JSON Schema

{
    "required": [
        "orderNumber",
        "paymentMethod"
    ],
    "properties": {
      "orderNumber": {
          "type": "integer",
      },
      "paymentMethod": {
          "type": "string",
      }
    }
}

Sample Requests

Sample Request for Credit Card
{
  "orderNumber": "123456",
  "paymentMethod" : "creditcard"
}
Sample Request for SEPA
{
  "orderNumber": "654321",
  "paymentMethod" : "sepa"
}

Response

Header

  • Content-Type: application/json
  • Possible status codes: 201 | 400 | 404 | 500

JSON Schema

Success Response
{
    "properties": {
        "orderNumber": {
            "type": "integer"
        },
        "merchantAccountId": {
            "type": "string"
        },
        "transactionId": {
            "type": "string"
        },
        "tokenId": {
            "type": "string"
        },
        "transactionServer": {
            "type": "string"
        }
    }
}
Error Response
{
    "properties": {
        "status": {
            "type": "integer"
        },
        "message": {
            "type": "string"
        }
    }
}
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.

{
  "orderNumber": "123456",
  "merchantAccountId": "62652b50-01d5-11e9-b568-0800200c9a66",
  "transactionId": "5d7fadd8-37d5-4578-a815-dcac8626121c",
  "tokenId": "4351742214741003",
  "transactionServer": "api-wdcee.wirecard.com"
}

Success Example 201 SEPA

{
  "orderNumber": "654321",
  "merchantAccountId": "62652b50-01d5-11e9-b568-0800200c9a66",
  "transactionId": "5d7fadd8-37d5-4578-a815-dcac8626121c",
  "transactionServer": "api-wdcee.wirecard.com"
}

Error Example 404

{
  "status": 404,
  "message": "Order not found."
}

Error Example 400

{
  "status": 400,
  "message": "OrderNumber '0' is too small."
}

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

OrderNumber,PaymentMethod
13926123,creditcard
2569588,creditcard
4504686,creditcard
382313,creditcard
9380547,sepa

PaymentMethod only allows the values creditcard or sepa.

Endpoint

Environment URL
Production https://checkout.wirecard.com/migration-batch-transaction

Workflow

As each step has a functional dependency on the preceding one, make sure to follow the given order.

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

{
    "File process started, process id:7"
}

2. Process the CSV file.

Sample Request

Header
  • GET /migration-batch-transaction/file/7
  • Host: checkout.wirecard.com
  • cache-control: no-cache

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

Sample Response

{
    "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 
}

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.

Processing cannot be interrupted until all orders listed in the CSV file have been successfully processed.

3. View Results.

Only request results once “status”: “Completed” is returned in the response of step 2. Sending a request earlier leads to incomplete results.

Sample Request

Header
  • GET /migration-batch-transaction/file/7/records
  • Host: checkout.wirecard.com
  • cache-control: no-cache

Sample Response

[
    { 
        "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
    }
]

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 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 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.