Create or retrieve funding instructions for a customer cash balance

Retrieve funding instructions for a customer cash balance. If funding instructions do not yet exist for the customer, new funding instructions will be created. If funding instructions have already been created for a given customer, the same funding instructions will be retrieved. In other words, we will return the same funding instructions each time.

Parameters

bank_transferobjectRequired
Additional parameters for bank_transfer funding types

currencyenumRequired
Three-letter ISO currency code, in lowercase. Must be a supported currency.

funding_typeenumRequired
The funding_type to get the instructions for.
Possible enum values
bank_transfer
Use a bank_transfer hash to define the bank transfer type

Returns

Returns funding instructions for a customer cash balance

POST /v1/customers/:id/funding_instructions

Server-side language

curl https://api.stripe.com/v1/customers/cus_9s6XKzkNRiz8i3/funding_instructions \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d funding_type=bank_transfer \
  -d currency=eur \
  -d "bank_transfer[type]"=eu_bank_transfer \
  -d "bank_transfer[eu_bank_transfer][country]"=DE

Response

{
  "object": "funding_instructions",
  "bank_transfer": {
    "country": "DE",
    "financial_addresses": [
      {
        "iban": {
          "account_holder_address": {
            "city": "Dublin",
            "country": "IE",
            "line1": "Some address",
            "line2": null,
            "postal_code": "D01H104",
            "state": "Dublin 1"
          },
          "account_holder_name": "Merchant name",
          "bank_address": {
            "city": "Dublin",
            "country": "IE",
            "line1": "1 North Wall Quay",
            "line2": null,
            "postal_code": "D01 T8Y1",
            "state": "Dublin"
          },
          "bic": "SOGEDEFFXXX",
          "country": "DE",
          "iban": "DE006847740991234567890"
        },
        "supported_networks": [
          "sepa",
          "swift"
        ],
        "type": "iban"
      }
    ],
    "type": "eu_bank_transfer"
  },
  "currency": "eur",
  "funding_type": "bank_transfer",
  "livemode": false
}

Retrieve a cash balance transaction

Retrieves a specific cash balance transaction, which updated the customer’s cash balance.

Parameters

No parameters.

Returns

Returns a cash balance transaction object if a valid identifier was provided.

GET /v1/customers/:id/cash_balance_transactions/:id

Server-side language

curl https://api.stripe.com/v1/customers/cus_9s6XKzkNRiz8i3/cash_balance_transactions/ccsbtxn_1Na16B2eZvKYlo2CUhyw3dsF \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"

Response

{
  "id": "ccsbtxn_1Na16B2eZvKYlo2CUhyw3dsF",
  "object": "customer_cash_balance_transaction",
  "created": 1690829143,
  "currency": "eur",
  "customer": "cus_9s6XKzkNRiz8i3",
  "ending_balance": 10000,
  "funded": {
    "bank_transfer": {
      "eu_bank_transfer": {
        "bic": "BANKDEAAXXX",
        "iban_last4": "7089",
        "sender_name": "Sample Business GmbH"
      },
      "reference": "Payment for Invoice 28278FC-155",
      "type": "eu_bank_transfer"
    }
  },
  "livemode": false,
  "net_amount": 5000,
  "type": "funded"
}

List cash balance transactions

Returns a list of transactions that modified the customer’s cash balance.

Parameters

No parameters.

More parameters

ending_beforestring

limitinteger

starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit cash balance transactions, starting after item starting_after. Each entry in the array is a separate cash balance transaction object. If no more items are available, the resulting array will be empty.

GET /v1/customers/:id/cash_balance_transactions

Server-side language

curl -G https://api.stripe.com/v1/customers/cus_9s6XKzkNRiz8i3/cash_balance_transactions \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d limit=3

Response

{
  "object": "list",
  "url": "/v1/customers/cus_9s6XKzkNRiz8i3/cash_balance_transactions",
  "has_more": false,
  "data": [
    {
      "id": "ccsbtxn_1Na16B2eZvKYlo2CUhyw3dsF",
      "object": "customer_cash_balance_transaction",
      "created": 1690829143,
      "currency": "eur",
      "customer": "cus_9s6XKzkNRiz8i3",
      "ending_balance": 10000,
      "funded": {
        "bank_transfer": {
          "eu_bank_transfer": {
            "bic": "BANKDEAAXXX",
            "iban_last4": "7089",
            "sender_name": "Sample Business GmbH"
          },
          "reference": "Payment for Invoice 28278FC-155",
          "type": "eu_bank_transfer"
        }
      },
      "livemode": false,
      "net_amount": 5000,
      "type": "funded"
    }
  ]
}

Fund a test mode cash balance Test helper

Create an incoming testmode bank transfer

Parameters

amountintegerRequired
Amount to be used for this test cash balance transaction. A positive integer representing how much to fund in the smallest currency unit (e.g., 100 cents to fund $1.00 or 100 to fund ¥100, a zero-decimal currency).

currencyenumRequired
Three-letter ISO currency code, in lowercase. Must be a supported currency.

More parameters

referencestring

Returns

Returns a specific cash balance transaction, which funded the customer’s cash balance.

POST /v1/test_helpers/customers/:id/fund_cash_balance

Server-side language

curl https://api.stripe.com/v1/test_helpers/customers/cus_9s6XKzkNRiz8i3/fund_cash_balance \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d amount=5000 \
  -d currency=eur

Response

{
  "id": "ccsbtxn_1NlhIV2eZvKYlo2CKwRcXkii",
  "object": "customer_cash_balance_transaction",
  "created": 1693612963,
  "currency": "eur",
  "customer": "cus_9s6XKzkNRiz8i3",
  "ending_balance": 10000,
  "funded": {
    "bank_transfer": {
      "eu_bank_transfer": {
        "bic": "BANKDEAAXXX",
        "iban_last4": "7089",
        "sender_name": "Sample Business GmbH"
      },
      "reference": "Payment for Invoice 28278FC-155",
      "type": "eu_bank_transfer"
    }
  },
  "livemode": false,
  "net_amount": 5000,
  "type": "funded"
}

Cards

You can store multiple cards on a customer in order to charge the customer later. You can also store multiple debit cards on a recipient in order to transfer to those cards later.

Related guide: Card payments with Sources

Endpoints

POST/v1/customers/:id/sources

POST/v1/customers/:id/sources/:id

GET/v1/customers/:id/cards/:id

GET/v1/customers/:id/cards

DELETE/v1/customers/:id/sources/:id