Test a Failed Payout

On staging, every payout is simulated and succeeds. To test the failure path, save one of the test bank accounts below as a payment method and create an offramp order against it. The deposit is processed as usual, then the payout fails every time.

Test Bank Accounts

These are the bank accounts that fail every payout on staging:

Country	Payment method `type`	Bank details
US	`bank-account-us`	Routing `021000021` Account `123456789012` (checking)
Europe (SEPA)	`bank-account-sepa-iban`	IBAN `LT871987090010999999`

Force a Failed Payout

Save a test bank account

Save one of the accounts above as a payment method, sending the bank details exactly as shown. Any userLocator and label work.

US
Europe (SEPA)

cURL

curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
  -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "bank-account-us",
    "userLocator": "<USER_LOCATOR>",
    "label": "Failed payout test",
    "bankAccount": {
      "accountNumber": "123456789012",
      "routingNumber": "021000021",
      "accountType": "checking",
      "entityType": "individual",
      "accountHolder": {
        "name": "Emily Carter"
      }
    }
  }'

cURL

curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
  -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "bank-account-sepa-iban",
    "userLocator": "<USER_LOCATOR>",
    "label": "Failed payout test",
    "bankAccount": {
      "iban": "LT871987090010999999",
      "entityType": "individual",
      "accountHolder": {
        "name": "Lukas Meier",
        "country": "LT"
      }
    }
  }'

The payment method becomes active like any other, and it stays active after the payout fails, so you can reuse it across orders. Save the returned paymentMethodId.

Create the order and deposit

Create the order with the test payment method as recipient.paymentMethodId, broadcast the deposit, and track the order as described in the Quickstart. The SEPA account pays out in EUR, so for that one set lineItems.currencyLocator to fiat:eur and payment.currency to eurc; the quickstart’s fiat:usd and usdc only match the US account. The order ends in phase: "completed" with the deposit received and the payout failed:

{
  "orderId": "a9a33fe8-7b62-4a1b-9324-816dd2919fb1",
  "phase": "completed",
  "lineItems": [
    {
      "delivery": {
        "status": "failed",
        "recipient": {
          "locator": "paymentMethodId:51982a3d-ae8e-4a82-b877-dca738d31570",
          "paymentMethodId": "51982a3d-ae8e-4a82-b877-dca738d31570"
        },
        "failureReason": {
          "code": "transfer-failed",
          "message": "The payout could not be completed. Please try again or contact support."
        }
      },
      "callData": {
        "mode": "exact-in",
        "amount": "300",
        "outFiatCurrency": "usd",
        "rail": "rtp",
        "effectiveAmount": "300"
      }
    }
  ],
  "payment": {
    "status": "completed",
    "method": "base-sepolia",
    "currency": "usdc",
    "received": {
      "chain": "base-sepolia",
      "txId": "0xc6da70cc5ef8800e4446ecb16514776c44553b840d5cc3f5e73777f2fefdbbb3",
      "amount": "300",
      "currency": "usdc"
    }
  }
}

Your app should treat this the same way as a bank rejection in production: phase: "completed" is terminal but not successful, so read lineItems[0].delivery.status and branch on failureReason.code. If you use webhooks, the orders.delivery.failed event fires. See Manage Orders for the status handling reference and the other failure codes you can receive in production.These accounts only fail on staging. In production they are ordinary bank accounts, so do not ship them in your app.

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

Test Bank Accounts

Force a Failed Payout

Next Steps

Manage Orders

Launch in Production

​Test Bank Accounts

​Force a Failed Payout

​Next Steps

Manage Orders

Launch in Production

Test Bank Accounts

Force a Failed Payout

Next Steps