Import Merchant Data
If you have used a different payment provider, you can import your old payments data, such as payment service provider tokens or gateway tokens to the Mastercard Gateway payments platform. Importing the data helps in maintaining the history of payment activity for analysis or processing any subsequent transactions or recurring payments.
Merchant use cases
- Merchants migrating from their existing payment gateway or payment service provider to a Mastercard Payment Gateway.
- Merchants wanting to use existing gateway tokens and submit the token to the gateway as the payment instrument each time a payment is due.
- Merchants collecting payment details from the payer on a website and storing them as a token with the payer data. Present the masked account identifier or last four digits of the PAN when a payer returns to the website to make another purchase.
Requirements for importing merchant data
- You must have PCI DSS compliance to collect raw card data.
- You can perform token migration as part of a Direct API or Hosted Batch Upload integration.
- For creating token through hosted batch, ensure that your merchant profile is enabled for the Batch service. Before you commence integration, see Best Practices and Tips.
Configure merchant for gateway tokenization
Our payment gateway generates a gateway token, which we use exclusively within our ecosystem for secure transactions. Select the desired options mentioned in the following steps and ask your service provider to configure the tokenization service for your merchant profile.
- Log in to the Merchant Manager (MM) portal using MSO credentials.
- Search for your merchant in the
Searchtab. - Enable merchant configuration for API, Batch, and Tokenization.
- Select an existing or create a new token repository:
- Token Verification Strategy: Basic validates that the payment details you provide conform to the gateway rules for processing a payment with these payment details. You do not need to provide a currency in the token creation request.
- Token Management: Assigns a unique token every time you save a card number. This is defined as a one-to-many relationship between a card number and tokens.
- Token ID: Merchant Supplied means you can supply the same token from your service provider platform. The gateway validates any token that you provide as a valid card number.
Token creation through Direct API
Overview
Gateway Tokenization allows you to tokenize the sensitive payment details of the payer. You can store a token and use it instead of the payment details in subsequent transaction requests sent to the gateway.
To use Gateway Tokenization:
- Define your tokenization service configuration.
- Learn how to create tokens and use them in payment transactions.
- Decide whether to update tokens automatically or manually.
Merchant configuration in Merchant Manager
To create new tokens through Direct API, you must have the following privileges:
- API
Direct API Integration
Merchants request the gateway to store a payment instrument against a token by providing the token ID. The behavior of this call depends on two aspects of your token repository configuration:
- Token Generation Strategy: Merchant-Supplied means you can supply the same token from your service provider platform. The gateway validates any token that you provide as a valid card number.
- Token Management Strategy: Unique Account Identifier or Unique Token
Example Request
The following example request shows how to create a token request by providing both, the card details and the old payment token from the payment service provider:
https://test-gateway.mastercard.com/api/rest/version/100/merchant/{merchantId}/token/{oldpaymenttokenId}
- You want to use the existing payer token 9897480080564ABC from your current payment service provider. This will facilitate customer payments through the new gateway.
- You will request a new token using a merchant-supplied token strategy. The gateway will then validate 9897480080564ABC as a valid token.
- The gateway will store the payment details associated with the token for future reference. This allows the gateway to use them in subsequent payment transactions.
- The gateway stores a payment instrument linked to the specified token ID.
| https://test-gateway.mastercard.com/api/rest/version/78/merchant/Test/token/9897480080564ABC | |
|---|---|
| Token Creation Request | Response |
{
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "01",
"year": "39"
},
"number": "5123450000000008"
}
},
"type": "CARD"
},
"transaction": {
"currency": "USD"
}
}
|
{
"repositoryId": "MERSUPL",
"response": {
"gatewayCode": "BASIC_VERIFICATION_SUCCESSFUL"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"expiry": "0139",
"fundingMethod": "DEBIT",
"issuer": "AFRILAND FIRST BANK",
"number": "512345xxxxxx0008",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"status": "VALID",
"token": "9897480080564ABC",
"usage": {
"lastUpdated": {
"merchantId": "TEST",
"time": "2024-10-25T09:05:28.348Z"
},
"lastUsedTime": "2024-10-25T09:05:28.360Z"
},
"verificationStrategy": "BASIC"
}
|
Create a request in line with ongoing process for the Direct API integration method. Instead of providing payment details, provide the token ID in the sourceOfFunds.token field.
| AUTHORIZE Operation with new token | Response |
|---|---|
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "112",
"currency": "AED"
},
"sourceOfFunds": {
"token": "9897480080564ABC",
"provided": {
"card": {
"storedOnFile": "STORED"
}
},
"type": "CARD"
},
"transaction": {
"source": "INTERNET"
}
}
|
{
"authorizationResponse": {
"commercialCardIndicator": "1",
"date": "1025",
"financialNetworkCode": "MCC",
"financialNetworkDate": "2024-10-25",
"posData": "1025104006600",
"posEntryMode": "102",
"processingCode": "000000",
"responseCode": "00",
"stan": "125093",
"time": "091149",
"transactionIdentifier": "K5JU8X"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "DEEP001",
"order": {
"amount": 112.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"certainty": "ESTIMATED",
"chargeback": {
"amount": 0,
"currency": "AED"
},
"creationTime": "2024-10-25T09:11:49.617Z",
"currency": "AED",
"fundingStatus": "NON_FUNDED",
"id": "ABC1231",
"lastUpdatedTime": "2024-10-25T09:11:49.640Z",
"merchantAmount": 112.00,
"merchantCategoryCode": "5999",
"merchantCurrency": "AED",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 112.00,
"totalCapturedAmount": 0.00,
"totalDisbursedAmount": 0.00,
"totalRefundedAmount": 0.00
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Approved",
"gatewayCode": "APPROVED",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "DEBIT",
"number": "512345xxxxxx0008",
"scheme": "MASTERCARD",
"storedOnFile": "STORED"
}
},
"token": "9897480080564ABC",
"type": "CARD"
},
"timeOfLastUpdate": "2024-10-25T09:11:49.640Z",
"timeOfRecord": "2024-10-25T09:11:48.851Z",
"transaction": {
"acquirer": {
"batch": 20241025,
"date": "1025",
"id": "EEMEATEST_S2I",
"merchantId": "8573335668",
"transactionId": "K5JU8X"
},
"amount": 112.00,
"authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
"authorizationCode": "214360",
"currency": "AED",
"funding": {
"status": "NON_FUNDED"
},
"id": "2FF11",
"receipt": "429909125093",
"source": "INTERNET",
"stan": "125093",
"terminal": "UTIS2I01",
"type": "AUTHORIZATION"
},
"version": "70"
}
|
Create tokens through Hosted Batch
Overview
The Batch functionality provides an integration point to the gateway that can accept multiple Web Services API (WS API) operations sent in a single upload request. The version specified in the upload request determines the operations accepted. For example, if version X is specified, the operations accepted are those supported in version X of the WS API.
Merchant configuration in Merchant Manager portal
To upload and create new tokens through Hosted Batch, merchants must have the following privileges:
- Batch
Merchant operator configuration in Merchant Administrator portal
Once the Batch is enabled for Merchant administrator, you can assign Batch upload and download privileges to operators. Follow these steps to perform changes:
- Log in to the Merchant Administration (MA) portal using MerchantId and Administrator as OperatorId.
- Go to
Admin,and then select operator from the list to edit the operator. - Change the configuration to upload and download Batch files for operators and submit the changes.
For a merchant with the Batch privilege, a Batches tab is displayed in the main menu in MA. When the Batches tab is selected, the sub-menu entry Batches is also selected. In the Batches tab, the 50 most recent uploaded batches are displayed sorted by descending upload completed date and time. A merchant operator does not need any specific privileges to view and access the Batches tab. A batch file will be displayed in the list if it has been successfully uploaded in Merchant Administrator.
Merchant Operator Login into Merchant Administration Portal
Follow these steps:
- Log in to the Merchant Administration (MA) portal using Merchant ID, Operator ID, and Password. After successful login, go to the Batch tab.
- Create a comma-separated Batch file in .txt and UTF-8 format as per the Merchant supplied Tokenization configuration.
- Follow the MA snapshot below to upload the Batch file.
- Once the Batch Status is complete, you can download the response against the uploaded Batch file, which also shows any errors and batch status.
In the Batches tab, the following information is provided for each batch file:
- Batch file name
- Total records
- Upload completed date or time
- Batch status
- Processed- Contains the percentage and number of records
- Number of errors during processing
- Last action date/time
- Processing completed date/time
- Response file
Successful batch upload through Merchant Administration
Each batch file should contain a single header row with values that correspond to the Direct API field name.
Create batch request file
apiOperation,sourceOfFunds.type,sourceOfFunds.provided.card.number,sourceOfFunds.provided.card.expiry.month,sourceOfFunds.provided.card.expiry.year,result,error.cause,error.explanation,error.field,error.supportCode,error.validationType,token
TOKENIZE,CARD,5123456789012346,01,39,,,,,,,9019076675533210
Input field
| Field | Description | Expected Value |
|---|---|---|
| apiOperation | Name of the operation. | TOKENIZE |
| sourceOfFunds.type | The payment method used for this payment. | CARD |
| sourceOfFunds.provided.card.number | The card number of the payer's account used for the payment. | Actual FPAN |
| sourceOfFunds.provided.card.expiry.month | Month, as shown on the card. | Card Expiry Month |
| sourceOfFunds.provided.card.expiry.year | Year, as shown on the card. | Card Expiry Year |
| token | Merchant token ID | Merchant Supplied token from existing PSP. |
Output file
-
Upload the File
- Upon successful upload of the file, a response status is returned to you.
- The response status indicates the number of records parsed in the file and the number of errors.
-
Request a Response File
- After a batch has completed processing, you can request a response file that contains the result of each uploaded operation.
- The response file will be in CSV format and the same encoding as the batch upload request.
-
Check the Results
- If your batch upload is successful, you will see "success" in the result.
- If it fails, you will see "failure" in the result.
-
Download the Tokenize Operation Outcome
- Additionally, you can download a response file that includes the outcome of the Tokenize operation after the batch has finished processing.
The following are some example output files with four payment details successfully migrated.
| apiOperation | sourceOfFunds.type | sourceOfFunds.provided.card.number | sourceOfFunds.provided.card.expiry.month | sourceOfFunds.provided.card.expiry.year | result | error.cause | error.explanation | error.field | error.supportCode | error.validationType | token |
|---|---|---|---|---|---|---|---|---|---|---|---|
| CARD | 520449xxxxxx4258 | SUCCESS | 9019076675333210 |
| apiOperation | sourceOfFunds.type | sourceOfFunds.provided.card.number | sourceOfFunds.provided.card.expiry.month | sourceOfFunds.provided.card.expiry.year | result | error.cause | error.explanation | error.field | error.supportCode | error.validationType | token |
|---|---|---|---|---|---|---|---|---|---|---|---|
| CARD | 512345xxxxxx2346 | SUCCESS | 9019080000000000 |
After a batch has completed processing, you can request a response file that contains the result of each of the uploaded operations. The response file will be in CSV format and will use the same encoding as the batch upload request. If your batch upload is successful, you will see success in the result. If it fails, you will see failure in the result.
Failed batch upload via Merchant Administration
The following is an example output file with four payment details successfully migrated.
| apiOperation | sourceOfFunds.type | sourceOfFunds.provided.card.number | sourceOfFunds.provided.card.expiry.month | sourceOfFunds.provided.card.expiry.year | result | error.cause | error.explanation | error.field | error.supportCode | error.validationType | token |
|---|---|---|---|---|---|---|---|---|---|---|---|
| ERROR | INVALID_REQUEST | Value '555555xxxxx5444' is invalid. Invalid number for this card type | sourceOfFunds.provided.card.number | INVALID |
Validation
-
Upload the File
- Upon successful upload of the file, a response status is returned to you.
- The response status indicates the number of records parsed in the file and the number of errors.
-
Request a Response File
- After a batch has completed processing, you can request a response file that contains the result of each uploaded operation.
- The response file will be in CSV format and the same encoding as the batch upload request.
-
Check the Results
- If your batch upload is successful, you will see "success" in the result.
- If it fails, you will see "failure" in the result.
| Scenario while uploading batch file | Error Message | Result | Token | Error Cause | Error Field | Error Validation Type |
|---|---|---|---|---|---|---|
| When invalid Card number in sourceOfFunds.provided.card.number | Value '555555xxxxx5444' is invalid. Invalid number for this card type | ERROR | INVALID_REQUEST | sourceOfFunds.provided.card.number | INVALID | |
| When card number length exceeded | Value '555555xxxxxxxxxx' is invalid. Length is 20 characters, but must be less than 20 | ERROR | INVALID_REQUEST | sourceOfFunds.provided.card.number | INVALID | |
| When batch upload is successful | SUCCESS | Token generated |
Token usage in payment transactions
You can use tokens with the following operations once the tokenization configuration process is complete on the your profile:
Using payment token on new merchant ID
-
Requesting a Payment
- Use a token generated with merchant ID 1 while processing the transaction through merchant ID 2.
-
Verify Token Repository Configuration
- Ensure that both merchants are configured to the same token repository in Merchant Manager.
-
Check for Errors
- If the merchants are set up with different token repositories, you will encounter an error message stating "Invalid Request."
- This indicates that the payment cannot be processed.
URL
https://mtf.gateway.mastercard.com/api/rest/version/74/merchant/DMMERTEST/order/GWTOKEN_s122316102s1670/transaction/TID_01_10116116116
Request
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "13",
"currency": "USD"
},
"sourceOfFunds": {
"type": "CARD",
"token": "9019076675533210",
"provided": {
"card": {
"expiry": {
"month": "01",
"year": "39"
},
"storedOnFile": "TO_BE_STORED"
}
}
},
"transaction": {
"source": "INTERNET"
}
}
Response
{
"error": {
"cause": "INVALID_REQUEST",
"explanation": "Token not found"
},
"result": "ERROR"
}
Invalid token
The gateway can mark a token as invalid for the following reasons:
- Recurring Payment Advice: The acquirer response for a recurring payment indicates that the merchant must not attempt another recurring payment with this card number. If a token was used for a recurring payment and the acquirer responds that the merchant must not attempt another payment with these payment details (response.gatewayRecommendation = DO_NOT_PROCEED_CONTACT_PAYER), the gateway marks the token as invalid (status=INVALID).
If a token is marked as invalid:
- The gateway will reject subsequent payment requests with this token that is not submitted to the acquirer for processing.
- The merchant must update the payment details stored against the token to successfully use it again for a payment.
If a token is marked as invalid and the merchant submits a Web Services API request with this token, the merchant receives an error message:
- result=ERROR
- error.field=sourceOfFunds.token
- error.validationType=INVALID
- error.explanation: The token provided in the request is marked as invalid. The card details stored against the token must be updated before they can be used as the acquirer has informed the gateway that the card details are no longer valid.