MPGS (mastercard): How to tokenize a transaction (how to create token)?

Question

I'm trying to create token with MPGS.

I'm following this guide:

https://sample-sub.domain.mastercard.com/api/documentation/integrationGuidelines/supportedFeatures/pickAdditionalFunctionality/tokenization/tokenization.html?locale=en_US#x_tokenConfiguration

In the section "Token Operations" > "Tokenize", it says:

You can use this operation to create or update a token by storing payment details against the token. ...

I'm posting this to help people who are frustrating like me with MPGS. I faced series of issues, and pulled my hair off many times. So here's the issues I faced and how to solve them (I'm stuck with issue #4).

---

Issue #1: Invalid credentials.

Fix: Make sure you're hitting the correct URL.

https://example-subdomain.mastercard.com/..

https://some.other-example.mastercard.com/..

https://MILLION-OTHER-POSSIBILITIES.mastercard.com/..

Even the documentation guide link have these same sub-domains, so make sure you're hitting the correct URL, and make sure you're following the correct documentation link.

---

Issue #2: Invalid parameters, or server asking for parameters although you've provided them.

Fix: If using Postman, make sure you set the parameters in "Body" > "raw" as JSON, like so:

{
    "sourceOfFunds": {
        "provided": {
            "card": {
                "expiry": {
                    "month": "05",
                    "year": "21"
                },
                "number": "5123456789012346"
            }
        },
        "type": "CARD"
    }
}

---

Issue #3: Authorization required

Fix: If using Postman, click on "Authorization", set "Type" it to Basic Auth, for "Username" set it to merchant.YOUR_MERCHANT_ID, for "Password" set it to YOUR_API_PASSWORD

---

Issue #4 (stuck here): Value '9999999999999999' is invalid. Card token must not be supplied

Method: PUT

URL: https://test-my.sample.gateway.mastercard.com/api/rest/version/46/merchant/MY_MERCHANT_ID/token/9999999999999999

Authorization: set correctly in Authorization tab

Body > raw:

{
    "sourceOfFunds": {
        "provided": {
            "card": {
                "expiry": {
                    "month": "05",
                    "year": "21"
                },
                "number": "5123456789012346"
            }
        },
        "type": "CARD"
    }
}

Response:

{
    "error": {
        "cause": "INVALID_REQUEST",
        "explanation": "Value '9999999999999999' is invalid. Card token must not be supplied",
        "field": "tokenid",
        "validationType": "INVALID"
    },
    "result": "ERROR"
}

Q: Not sure what to do to tokenize the transaction..?! I'm stuck with issue #4.

Sidky

Did you find a way out because I'm stuck here too! – Sd

@AdeelSiddiqui Finally got it working just now! Super lucky you!! – Sidky

Answer 1

Ok, finally figured it out. MPGS has 2 ways to create/update tokens:

1. Tokenization where YOU provide the token (notice: PUT method)
2. Tokenization where MPGS generate the token for you (notice: POST method)

They're very similar.

I got it working with the 2nd option.

Note: This is POST method !!

Method: POST

URL: https://SUBDOMAIN_YOU_SHOULD_BE_USING.mastercard.com/api/rest/version/50/merchant/YOUR_MERCHANT_ID/token

In postman, set Authorization (as described in the question, in issue #3).

Sample data to send (in postman, this should be in Body > raw):

{
    "sourceOfFunds": {
        "provided": {
            "card": {
                "expiry": {
                    "month": "05",
                    "year": "21"
                },
                "number": "5123456789012346"
            }
        },
        "type": "CARD"
    }
}

Sample response:

{
    "repositoryId": "1000000000002",
    "response": {
        "gatewayCode": "BASIC_VERIFICATION_SUCCESSFUL"
    },
    "result": "SUCCESS",
    "sourceOfFunds": {
        "provided": {
            "card": {
                "brand": "MASTERCARD",
                "expiry": "0521",
                "fundingMethod": "CREDIT",
                "issuer": "BANCO DEL PICHINCHA, C.A.",
                "number": "512345xxxxxx2346",
                "scheme": "MASTERCARD"
            }
        },
        "type": "CARD"
    },
    "status": "VALID",
    "token": "9717501974559694",
    "usage": {
        "lastUpdated": "2019-02-25T09:36:54.928Z",
        "lastUpdatedBy": "1015",
        "lastUsed": "2019-02-25T09:36:54.928Z"
    },
    "verificationStrategy": "BASIC"
}

Sidky

I get an error saying "Directly providing cardholder data is not supported. Consider using a session or token." Can you please help me? – Garibold

@Garibold MPGS is frustrating/tricky and has a lot of hidden configuration (that other party/bank has control over) that may affect the response, not to mention that some errors are not clear what is the cause. So: 1-Make sure you're hitting the correct URL and subdomain, 2-Make sure your using correct method (POST, PUT, etc), 3-Make sure you're providing the correct JSON structure and values, and if still fails, contact your bank/party for support. There is a chance that what you're trying to do is not enabled on one of the parties configuration. Read my question & answer again, that may help. – Sidky

Thanks @Sidky for the explanation – Garibold

@Garibold did u able to solve the problem.. I m also getting same . Please suggest – Indra

{ "error": { "cause": "INVALID_REQUEST", "explanation": "Missing parameter. Merchant is not enabled for Tokenization", "field": "sourceOfFunds.token", "validationType": "MISSING" }, "result": "ERROR" } that's my issue I am using POST with this endpoint ap-gateway.mastercard.com/api/rest/version/57/merchant{merchant_id}/token – Kalie

@PaulaGeorge as it's in explanation, it means tokenization feature must be enabled for your merchant, that means the bank must enable it for you, contact them. – Sidky

If this error appears for you "Merchant is not enabled for Tokenization" , so you should ask your bank for enable the Tokenization for you – Lacielacing