> ## Documentation Index > Fetch the complete documentation index at: https://docs.straddle.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a paykey from a Mastercard token > Use a Mastercard Open Finance connection for charges and payouts through Straddle. 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](/guides/bridge/paykeys) 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](/integrations/open-banking/mastercard). ## Before you begin Confirm the following: * [Create a customer in Straddle](/api-reference/customers/create). 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. ```bash Create a paykey from a Mastercard token theme={null} 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](/api-reference/idempotency). `inline` processing is the default. If Straddle returns a `pending` paykey, processing continues asynchronously and Straddle sends status changes through [paykey webhook events](/webhooks/overview/events). ## Read the response An inline request that creates an `active` paykey returns `201 Created`. ```json theme={null} { "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](/guides/bridge/paykeys#manual-review-process). See [Paykey status details](/guides/bridge/paykeys#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](/webhooks/overview/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](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-linked/client/client-steps/#operation/GenerateThirdPartyAccessKey) example uses `maxCalls: 200`. See [Set the token scope](/integrations/open-banking/mastercard#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](/api-reference/paykeys/cancel). ## 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](/guides/resources/sandbox-paybybank) for more scenarios. ## Disconnect the account Complete both actions when the customer disconnects the account: 1. Call Mastercard's [Revoke Third Party Access](https://developer.mastercard.com/open-finance-us/documentation/api-reference/#operation/RevokeThirdPartyAccessKey) operation with the consent receipt ID. 2. [Cancel the Straddle paykey](/api-reference/paykeys/cancel). 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. ## Related topics - [Create a Mastercard token for Straddle](/integrations/open-banking/mastercard.md) - [Create paykeys from Quiltt tokens](/guides/bridge/quiltt-token.md) - [Create paykeys from Plaid processor tokens](/guides/bridge/plaid-token.md) - [Bridge a Mastercard consent receipt](/api-reference/bridge/mastercard.md) - [Welcome to Straddle](/guides/overview.md)