Create a Mastercard token for Straddle

Generate a Mastercard token for a checking account already connected through your Mastercard Open Finance integration. Mastercard’s Generate Third Party Access Key operation returns a consent receipt. Straddle calls the following three values from that receipt, taken together, a Mastercard token:

The receipt ID.
The returned customer ID.
The returned account ID.

Before you begin

Gather the following values for the environment you are using:

Your Mastercard app key, partner ID, and partner secret.
The Mastercard customer ID and account ID for the selected checking account.
Straddle’s Mastercard partner ID for your environment. Straddle provides this value; sandbox and production use different IDs.

Your Mastercard Open Finance partner account must be enabled for Partner Linked third-party access.

Send all Mastercard requests from your server. Do not expose Mastercard credentials or tokens in a browser or mobile client.

Authenticate with Mastercard

Use Mastercard’s Create Access Token operation to exchange your Mastercard partner ID and partner secret for a partner authentication token.

Get a partner authentication token

curl --request POST \
  --url https://api.finicity.com/aggregation/v2/partners/authentication \
  --header "Finicity-App-Key: YOUR_MASTERCARD_APP_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "partnerId": "YOUR_MASTERCARD_PARTNER_ID",
    "partnerSecret": "YOUR_MASTERCARD_PARTNER_SECRET"
  }'

A successful request returns the partner authentication token in token.

Partner authentication response

{
  "token": "YOUR_MASTERCARD_PARTNER_AUTHENTICATION_TOKEN"
}

Send this value in the Finicity-App-Token header when you create the Mastercard token. Partner authentication tokens are valid for two hours. Mastercard recommends replacing them after 90 minutes.

Set the token scope

Mastercard’s Generate Third Party Access Key request sets two limits for each product in the consent receipt:

accessPeriod controls how long Straddle can use the product.
maxCalls controls how many times Straddle can request the product before Mastercard blocks further requests.

Grant all three products for the same account.

Product	How Straddle uses it
`moneyTransferDetails`	Retrieves the routing number and account number during paykey creation.
`accountOwner`	Retrieves account holder names during paykey creation.
`availableBalanceLive`	Retrieves a balance during paykey creation and later charge balance checks or balance refreshes.

The request below sets maxCalls to Mastercard’s example value of 200. Paykey creation requests each product once. Later charge balance checks and balance refreshes can make additional availableBalanceLive requests.

200 is an example, not a published maximum. Confirm the supported limit for your Mastercard program if you need a different value.

Set maxCalls and accessPeriod for every product. Set accessPeriod.type to timeframe, then replace the timestamps in the following request before sending it.

Generate the Mastercard token

In Mastercard’s Generate Third Party Access Key request, set partnerId to your Mastercard partner ID. Set thirdPartyPartnerId to Straddle’s Mastercard partner ID for the same environment.

Generate a Mastercard token

curl --request POST \
  --url https://api.finicity.com/aggregation/v1/partners/accessKey \
  --header "Finicity-App-Key: YOUR_MASTERCARD_APP_KEY" \
  --header "Finicity-App-Token: YOUR_MASTERCARD_PARTNER_AUTHENTICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "customerId": "YOUR_MASTERCARD_CUSTOMER_ID",
    "partnerId": "YOUR_MASTERCARD_PARTNER_ID",
    "thirdPartyPartnerId": "STRADDLE_MASTERCARD_PARTNER_ID",
    "products": [
      {
        "product": "moneyTransferDetails",
        "accountId": "YOUR_MASTERCARD_ACCOUNT_ID",
        "maxCalls": 200,
        "accessPeriod": {
          "type": "timeframe",
          "startTime": "START_TIME_UTC",
          "endTime": "END_TIME_UTC"
        }
      },
      {
        "product": "accountOwner",
        "accountId": "YOUR_MASTERCARD_ACCOUNT_ID",
        "maxCalls": 200,
        "accessPeriod": {
          "type": "timeframe",
          "startTime": "START_TIME_UTC",
          "endTime": "END_TIME_UTC"
        }
      },
      {
        "product": "availableBalanceLive",
        "accountId": "YOUR_MASTERCARD_ACCOUNT_ID",
        "maxCalls": 200,
        "accessPeriod": {
          "type": "timeframe",
          "startTime": "START_TIME_UTC",
          "endTime": "END_TIME_UTC"
        }
      }
    ]
  }'

Read receiptId, customerId, and products[].accountId from the response.

Consent receipt response

{
  "data": [
    {
      "receipt": {
        "receiptId": "cr_4pfI2r1X8aOHrDDwrwC01NHTxOXlT1",
        "customerId": "3465230025077724000",
        "products": [
          {
            "product": "moneyTransferDetails",
            "accountId": "4633415743960374024"
          },
          {
            "product": "accountOwner",
            "accountId": "4633415743960374024"
          },
          {
            "product": "availableBalanceLive",
            "accountId": "4633415743960374024"
          }
        ]
      }
    }
  ]
}

Map the response to Straddle

Map the fields in Mastercard’s Generate Third Party Access Key response to the mastercard object in the Straddle Bridge request.

Straddle field	Mastercard response field
`mastercard.consent_receipt_id`	`data[].receipt.receiptId`
`mastercard.customer_id`	`data[].receipt.customerId`
`mastercard.account_id`	`data[].receipt.products[].accountId`

Confirm that the same returned account ID appears in all three product entries, then send that value as mastercard.account_id. Use the receipt ID and returned customer ID from that same consent receipt. Do not send Straddle the original customer or account IDs from the token request. Set the top-level customer_id in the Straddle request to the Straddle customer ID. mastercard.customer_id is the customer ID returned by Mastercard. Store mastercard.consent_receipt_id, mastercard.customer_id, and mastercard.account_id on your server with your record of the bank connection.

Create the Straddle paykey

Continue to Create a paykey from a Mastercard token after Mastercard returns the consent receipt. For Mastercard’s complete Partner Linked procedure, see Client steps.

Integrations

Open Banking

Events

Create a Mastercard token for Straddle

Before you begin

Authenticate with Mastercard

Set the token scope

Generate the Mastercard token

Map the response to Straddle

Create the Straddle paykey

​Before you begin

​Authenticate with Mastercard

​Set the token scope

​Generate the Mastercard token

​Map the response to Straddle

​Create the Straddle paykey

Before you begin

Authenticate with Mastercard

Set the token scope

Generate the Mastercard token

Map the response to Straddle

Create the Straddle paykey