Create a paykey from a Mastercard token

Use this guide after your customer connects a checking account through Mastercard Open Finance. Straddle uses that connection to retrieve account data, verify ownership, and return a paykey for charges and payouts. Straddle calls the following values from one Mastercard consent receipt a Mastercard token:

Receipt ID.
Mastercard customer ID.
Mastercard account ID.

Need a Mastercard token? See Create a Mastercard token for Straddle.

Before you begin

Confirm the following:

Create a customer in Straddle. The customer cannot be inactive or rejected.
Use a Mastercard consent receipt that includes moneyTransferDetails, accountOwner, and availableBalanceLive for the same account.

Mastercard does not include the account type in the consent receipt. Straddle records a paykey created from a Mastercard token as a checking account.

Create the paykey

Send the following IDs to POST /v1/bridge/mastercard.

Request field	What to send
`customer_id`	The Straddle customer ID.
`mastercard.consent_receipt_id`	`data[].receipt.receiptId` from Mastercard.
`mastercard.customer_id`	`data[].receipt.customerId` from Mastercard.
`mastercard.account_id`	The `data[].receipt.products[].accountId` value for the selected account.

The Mastercard values must come from the same consent receipt.

Create a paykey from a Mastercard token

curl --request POST https://sandbox.straddle.com/v1/bridge/mastercard \
  --header "Authorization: Bearer YOUR_STRADDLE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  --data '{
    "customer_id": "0191ef41-8de5-716c-bfa4-41cd79e85705",
    "mastercard": {
      "consent_receipt_id": "cr_4pfI2r1X8aOHrDDwrwC01NHTxOXlT1",
      "customer_id": "3465230025077724000",
      "account_id": "4633415743960374024"
    },
    "external_id": "bank-connection-4412",
    "metadata": {
      "nickname": "Primary checking"
    }
  }'

For retry behavior, see Idempotency keys for safe API retries. inline processing is the default. If Straddle returns a pending paykey, processing continues asynchronously and Straddle sends status changes through paykey webhook events.

Read the response

An inline request that creates an active paykey returns 201 Created.

Example active response

{
  "data": {
    "id": "0191ef49-892c-7460-99d1-f5589d7d9989",
    "paykey": "2cd3e7b4.02.e271f11e0bd28fd609e5f7a426dabb2fc67646c7908ce8769c92c8c9448bce5e",
    "customer_id": "0191ef41-8de5-716c-bfa4-41cd79e85705",
    "external_id": "bank-connection-4412",
    "label": "FINBANK - *0725",
    "source": "mastercard",
    "institution_name": "FINBANK",
    "status": "active",
    "status_details": {
      "message": "Successfully matched account holder with customer.",
      "reason": "ok",
      "source": "system",
      "changed_at": "2026-09-01T18:35:12.4821903Z"
    },
    "bank_data": {
      "routing_number": "011401850",
      "account_number": "**0725",
      "account_type": "checking"
    },
    "balance": {
      "account_balance": 723419,
      "status": "completed",
      "updated_at": "2026-09-01T18:35:12.4821899Z"
    },
    "config": {
      "processing_method": "inline",
      "sandbox_outcome": "standard"
    },
    "metadata": {
      "nickname": "Primary checking"
    },
    "created_at": "2026-09-01T18:35:12.4821897Z",
    "updated_at": "2026-09-01T18:35:12.4821903Z"
  },
  "meta": {
    "api_request_id": "243431dd-7deb-4445-820d-55a942ace70f",
    "api_request_timestamp": "2026-09-01T18:35:12.4832104Z"
  },
  "response_type": "object"
}

Store data.paykey for charges and payouts. Straddle uses the available balance returned by Mastercard and falls back to the cleared balance when Mastercard does not return an available balance. Store the Mastercard token with the account connection. You’ll need the consent receipt ID to revoke Mastercard access.

Act on the paykey status

Use data.status to decide the next action.

Status	Payment behavior
`active`	Create charges and payouts with the paykey.
`review`	Create charges and payouts. Straddle holds the payments until review resolves.
`pending`	Wait for asynchronous processing to finish before using the paykey.
`rejected`	Do not use the paykey for charges or payouts.

For a review result, follow the manual review process. See Paykey status details for the full lifecycle.

Recover from errors

For an inline request, use the HTTP status code to decide how to handle the error. For asynchronous processing, use the paykey status from paykey webhook events.

Treat error.detail and status_details.message as diagnostic text. Do not match their contents in code.

Recognized Mastercard token failures return 422 Unprocessable Entity during inline processing. Straddle maps them to these diagnostic messages:

Diagnostic message	Recovery
`The Mastercard consent is not valid for this account, or does not grant the access this request requires.`	Verify `mastercard.consent_receipt_id`, `mastercard.customer_id`, and `mastercard.account_id`. Confirm that the consent receipt includes all three required products for the account.
`The Mastercard consent has been revoked.`	Create a new Mastercard token, then retry with a new idempotency key.
`The Mastercard consent has expired.`	Create a new Mastercard token, then retry with a new idempotency key.
`The Mastercard consent has reached its usage limit.`	Create a new Mastercard token, then retry with a new idempotency key.
`Mastercard did not return ACH routing and account numbers.`	Use an account that returns the ACH details required to create a paykey.
`Mastercard is not enabled.`	Ask your Straddle contact to enable Mastercard for the request environment.
`Mastercard partner token is not available.`	Contact Straddle and include `meta.api_request_id`.
`Customer not found.`	Verify the top-level `customer_id` and the account scope of your API key.
`Cannot create paykey as customer is inactive.` or `Cannot create paykey as customer is rejected.`	Resolve the customer status or use an eligible customer.
`Institution not found for routing number '...'.`	Contact Straddle and include `meta.api_request_id`.

During asynchronous processing, a failure listed in the table changes the paykey to rejected and sends a paykey webhook event. Other failures leave the paykey in pending while Straddle retries. During inline processing, a Mastercard failure that is not listed in the table returns 500 Internal Server Error. Contact Straddle before retrying and include meta.api_request_id.

Keep the Mastercard token available

When you create the Mastercard token, set maxCalls and accessPeriod for each product. Mastercard’s Generate Third Party Access Key example uses maxCalls: 200. See Set the token scope.

Unless your use case has a set expiration date, set accessPeriod.endTime as far into the future as your Mastercard configuration allows. Contact Mastercard for more information about access periods and call limits.

If the Mastercard token expires, is revoked, or reaches a call limit, Straddle cannot request a new balance. The paykey can remain active and keeps its last bank data and balance. If Straddle cannot refresh the balance for a charge:

disabled: Straddle does not request a balance.
enabled: The charge can continue without a completed balance check.
required: The charge fails because Straddle cannot verify the balance.

You cannot replace the Mastercard token on an existing paykey. If Mastercard returns a new consent receipt, create a new paykey and cancel the old paykey.

Test in sandbox

Create the Mastercard token in Mastercard’s sandbox, then send the Bridge request to https://sandbox.straddle.com. Name matching runs when config.sandbox_outcome is standard. Set config.sandbox_outcome to active, rejected, or review to force that paykey status. Use expired, revoked, under-scoped, and exhausted Mastercard tokens to test the recovery paths. See Sandbox testing for Pay by Bank for more scenarios.

Disconnect the account

Complete both actions when the customer disconnects the account:

Call Mastercard’s Revoke Third Party Access operation with the consent receipt ID.
Cancel the Straddle paykey.

Mastercard revocation stops future account data requests. Paykey cancellation stops future payment use through Straddle. Revoking the consent receipt alone does not cancel the paykey.

Get Started

Identity

Bridge

Payments

Embed

Resources

Create a paykey from a Mastercard token

Before you begin

Create the paykey

Read the response

Act on the paykey status

Recover from errors

Keep the Mastercard token available

Test in sandbox

Disconnect the account

​Before you begin

​Create the paykey

​Read the response

​Act on the paykey status

​Recover from errors

​Keep the Mastercard token available

​Test in sandbox

​Disconnect the account

Before you begin

Create the paykey

Read the response

Act on the paykey status

Recover from errors

Keep the Mastercard token available

Test in sandbox

Disconnect the account