From 22bfca097767234836fbbd69cce1d49e480865a9 Mon Sep 17 00:00:00 2001 From: Brandur Date: Tue, 3 Nov 2015 12:00:35 -0800 Subject: [PATCH] Use generated API responses in stripe-ruby tests This patch introduces a narrow working slice of tests that use data generated from within the API itself to produce sample responses from a stubbed out API in the test suite. This has a few advantages over the current situation: * More accurate test data back from the stub. The current `TestData` system is extremely prone to eroding (this is the biggest advantage). * Basic validation gets run on incoming request parameters. * Stubbing is run at a lower level (the HTTP library instead of the `Stripe` module) so we get a little more certainty that things work as expected. * Contributing new tests (especially for new resources) becomes very easy because no sections of `TestData` are required. Replacing the entire suite will take a few hours and involving a lot of copy and pasting, but is entirably doable and after we're done we can remove the entire `TestData` module and the monkey patching on the `Stripe` module. --- .gitattributes | 1 + schema/schema-2015-10-16.yaml | 10010 ++++++++++++++++++++++++++++++++ stripe.gemspec | 3 + test/stripe/account_test.rb | 46 +- test/test_helper.rb | 133 +- 5 files changed, 10171 insertions(+), 22 deletions(-) create mode 100644 .gitattributes create mode 100644 schema/schema-2015-10-16.yaml diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..b7b8bffa3 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +schema/schema-*.yaml binary diff --git a/schema/schema-2015-10-16.yaml b/schema/schema-2015-10-16.yaml new file mode 100644 index 000000000..26d58221b --- /dev/null +++ b/schema/schema-2015-10-16.yaml @@ -0,0 +1,10010 @@ +--- +"$schema": http://json-schema.org/draft-04/hyper-schema +definitions: + account: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + business_name: + description: The publicly visible name of the business + example: '' + type: + - string + business_primary_color: + description: A CSS hex color value representing the primary branding color + for this account + example: '' + type: + - string + business_url: + description: The publicly visible website of the business + example: '' + type: + - string + charges_enabled: + description: Whether or not the account can create live charges + example: false + type: + - boolean + country: + description: The country of the account + example: US + type: + - string + currencies_supported: + description: The currencies this account can submit when creating charges + example: + - "..." + - aed + - afn + - usd + type: + - array + debit_negative_balances: + description: Whether or not Stripe will attempt to reclaim negative account + balances from this account's bank account. + example: true + type: + - boolean + decline_charge_on: + description: Account-level settings to automatically decline certain types + of charges regardless of the bank's decision. + example: + avs_failure: false + cvc_failure: false + type: + - object + default_currency: + description: The currency this account has chosen to use as the default + example: usd + type: + - string + details_submitted: + description: Whether or not account details have been submitted yet. Standalone + accounts cannot receive transfers before this is true. + example: false + type: + - boolean + display_name: + description: The display name for this account. This is used on the Stripe + dashboard to help you differentiate between accounts. + example: '' + type: + - string + email: + description: The primary user's email address + example: site@stripe.com + type: + - string + external_accounts: + description: External accounts (bank accounts and/or cards) currently attached + to this account. + example: + data: [] + has_more: false + object: list + total_count: 0 + url: "/v1/accounts/acct_173u6sIw57t4eNNv/external_accounts" + type: + - object + id: + description: A unique identifier for the account + example: acct_173u6sIw57t4eNNv + type: + - string + legal_entity: + description: Information regarding the owner of this account, including verification + status. + example: + additional_owners: + address: + city: + country: US + line1: + line2: + postal_code: + state: + business_name: + dob: + day: + month: + year: + first_name: + last_name: + personal_address: + city: + country: + line1: + line2: + postal_code: + state: + personal_id_number_provided: false + ssn_last_4_provided: false + type: + verification: + details: + details_code: + document: + status: unverified + type: + - object + managed: + description: Whether or not the account is [managed](/docs/connect/managed-accounts) + by your platform. Returns null if the account was not created by a platform. + example: false + type: + - boolean + metadata: + example: {} + type: + - object + object: + example: account + type: + - string + product_description: + description: An internal-only description of the product or service provided. + This is used by Stripe in the event the account gets flagged for potential + fraud. + example: '' + type: + - string + statement_descriptor: + description: The text that will appear on credit card statements + example: '' + type: + - string + support_email: + description: A publicly shareable email address that can be reached for support + for this account + example: '' + type: + - string + support_phone: + description: The publicly visible support phone number for the business + example: '' + type: + - string + support_url: + description: A publicly shareable URL that can be reached for support for + this account + example: '' + type: + - string + timezone: + description: The timezone used in the Stripe dashboard for this account. A + list of possible timezone values is maintained at the [IANA Timezone Database](http://www.iana.org/time-zones). + example: Etc/UTC + type: + - string + tos_acceptance: + description: Who accepted the Stripe terms of service, and when they accepted + it. + example: + date: + ip: + user_agent: + type: + - object + transfer_schedule: + description: When payments collected will be automatically paid out to the + account holder's bank account. + example: + delay_days: 2 + interval: daily + type: + - object + transfers_enabled: + description: Whether or not Stripe will send automatic transfers for this + account. This is only false when Stripe is waiting for additional information + from the account holder. + example: false + type: + - boolean + verification: + description: The state of the account's information requests, including what + information is needed and by when it must be provided. + example: + disabled_reason: fields_needed + due_by: + fields_needed: + - business_url + - external_account + - product_description + - support_phone + - tos_acceptance.date + - tos_acceptance.ip + type: + - object + identity: + "$ref": "#/definitions/account/definitions/resource_id" + links: + - title: AccountUpdateMethod + method: POST + rel: self + href: "/v1/account" + targetSchema: + "$ref": "#/definitions/account" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + default_currency: + example: '' + type: + - string + description: Three-letter ISO currency code representing the default currency + for the account. This must be a currency that [Stripe supports in the + account's country](http://127.0.0.1:8080/questions/which-currencies-does-stripe-support). + statement_descriptor: + example: '' + type: + - string + description: The text that will appear on credit card statements by default + if a charge is being made [directly on the account](/docs/connect/payments-fees#charging-directly). + email: + example: '' + type: + - string + description: 'Email address of the account holder. For standalone accounts, + this is used to email them asking them to claim their Stripe account. + For managed accounts, this is only to make the account easier to identify + to you: Stripe will not email the account holder.' + product_description: + example: '' + type: + - string + description: Internal-only description of the product being sold or service + being provided by this account. It's used by Stripe for risk and underwriting + purposes. + external_account: + example: {} + type: + - object + - string + description: A card or bank account to attach to the account. You can + provide either a token, like the ones returned by [Stripe.js](/docs/stripe.js), + or a dictionary as documented in the external_account parameter for + either [card](/docs/api#create_card) or [bank account](/docs/api#create_bank_account) + creation.

This will create a new external account object, make + it the new default external account for its currency, and delete the + old default if one exists. If you want to add additional external accounts + instead of replacing the existing default for this currency, use the + bank account or card creation API. + debit_negative_balances: + example: false + type: + - boolean + description: A boolean for whether or not Stripe should try to reclaim + negative balances from the account holder's bank account. See our [managed + account bank transfer guide](/docs/connect/bank-transfers#negative-balances) + for more information + decline_charge_on: + example: {} + type: + - object + description: Account-level settings to automatically decline certain types + of charges regardless of the bank's decision. + legal_entity: + example: {} + type: + - object + description: Information about the holder of this account, i.e. the user + receiving funds from this account + tos_acceptance: + example: {} + type: + - object + description: Details on who accepted the Stripe terms of service, and + when they accepted it. See our [updating managed accounts guide](/docs/connect/updating-accounts#tos_acceptance) + for more information + transfer_schedule: + example: {} + type: + - object + description: Details on when this account will make funds from charges + available, and when they will be paid out to the account holder's bank + account. See our [managed account bank transfer guide](/docs/connect/bank-transfers#payout-information) + for more information + business_name: + example: '' + type: + - string + description: The publicly sharable name for this account + business_logo: + example: '' + type: + - string + business_primary_color: + example: '' + type: + - string + description: A CSS hex color value representing the primary branding color + for this account + business_url: + example: '' + type: + - string + description: The URL that best shows the service or product provided for + this account + support_url: + example: '' + type: + - string + description: A publicly shareable URL that can be reached for support + for this account + support_email: + example: '' + type: + - string + description: A publicly shareable email address that can be reached for + support for this account + support_phone: + example: '' + type: + - string + description: A publicly shareable phone number that can be reached for + support for this account + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to an account + object. It can be useful for storing additional information about the + account in a structured format. + - title: AccountUpdateMethod + method: POST + rel: self + href: "/v1/accounts/{account}" + targetSchema: + "$ref": "#/definitions/account" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + default_currency: + example: '' + type: + - string + description: Three-letter ISO currency code representing the default currency + for the account. This must be a currency that [Stripe supports in the + account's country](http://127.0.0.1:8080/questions/which-currencies-does-stripe-support). + statement_descriptor: + example: '' + type: + - string + description: The text that will appear on credit card statements by default + if a charge is being made [directly on the account](/docs/connect/payments-fees#charging-directly). + email: + example: '' + type: + - string + description: 'Email address of the account holder. For standalone accounts, + this is used to email them asking them to claim their Stripe account. + For managed accounts, this is only to make the account easier to identify + to you: Stripe will not email the account holder.' + product_description: + example: '' + type: + - string + description: Internal-only description of the product being sold or service + being provided by this account. It's used by Stripe for risk and underwriting + purposes. + external_account: + example: {} + type: + - object + - string + description: A card or bank account to attach to the account. You can + provide either a token, like the ones returned by [Stripe.js](/docs/stripe.js), + or a dictionary as documented in the external_account parameter for + either [card](/docs/api#create_card) or [bank account](/docs/api#create_bank_account) + creation.

This will create a new external account object, make + it the new default external account for its currency, and delete the + old default if one exists. If you want to add additional external accounts + instead of replacing the existing default for this currency, use the + bank account or card creation API. + debit_negative_balances: + example: false + type: + - boolean + description: A boolean for whether or not Stripe should try to reclaim + negative balances from the account holder's bank account. See our [managed + account bank transfer guide](/docs/connect/bank-transfers#negative-balances) + for more information + decline_charge_on: + example: {} + type: + - object + description: Account-level settings to automatically decline certain types + of charges regardless of the bank's decision. + legal_entity: + example: {} + type: + - object + description: Information about the holder of this account, i.e. the user + receiving funds from this account + tos_acceptance: + example: {} + type: + - object + description: Details on who accepted the Stripe terms of service, and + when they accepted it. See our [updating managed accounts guide](/docs/connect/updating-accounts#tos_acceptance) + for more information + transfer_schedule: + example: {} + type: + - object + description: Details on when this account will make funds from charges + available, and when they will be paid out to the account holder's bank + account. See our [managed account bank transfer guide](/docs/connect/bank-transfers#payout-information) + for more information + business_name: + example: '' + type: + - string + description: The publicly sharable name for this account + business_logo: + example: '' + type: + - string + business_primary_color: + example: '' + type: + - string + description: A CSS hex color value representing the primary branding color + for this account + business_url: + example: '' + type: + - string + description: The URL that best shows the service or product provided for + this account + support_url: + example: '' + type: + - string + description: A publicly shareable URL that can be reached for support + for this account + support_email: + example: '' + type: + - string + description: A publicly shareable email address that can be reached for + support for this account + support_phone: + example: '' + type: + - string + description: A publicly shareable phone number that can be reached for + support for this account + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to an account + object. It can be useful for storing additional information about the + account in a structured format. + - title: Delete an account + method: DELETE + rel: self + href: "/v1/accounts/{account}" + targetSchema: + "$ref": "#/definitions/account" + description: |- + With Connect, you may delete Stripe accounts you manage.

+ +

Managed accounts created using test-mode keys can be deleted at any time. Managed accounts created using live-mode keys may only be deleted once all balances are zero.

+ +

If you are looking to close your own account, use the data tab in your account settings instead. + - title: Delete an account + method: DELETE + rel: self + href: "/v1/account" + targetSchema: + "$ref": "#/definitions/account" + description: |- + With Connect, you may delete Stripe accounts you manage.

+ +

Managed accounts created using test-mode keys can be deleted at any time. Managed accounts created using live-mode keys may only be deleted once all balances are zero.

+ +

If you are looking to close your own account, use the data tab in your account settings instead. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + account: + example: '' + type: + - string + description: The identifier of the account to be deleted. If none is provided, + will default to the account of the API key. + - title: List all connected accounts + method: GET + rel: self + href: "/v1/accounts" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/account" + url: + example: "/v1/accounts" + type: + - string + description: Returns a list of accounts connected to your platform via Connect. + If you’re not a platform, the list will be empty. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + - title: Retrieve account details + method: GET + rel: self + href: "/v1/account" + targetSchema: + "$ref": "#/definitions/account" + description: Retrieves the details of the account. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + account: + example: '' + type: + - string + description: The identifier of the account to be retrieved. If none is + provided, will default to the account of the API key. + - title: Retrieve account details + method: GET + rel: self + href: "/v1/accounts/{account}" + targetSchema: + "$ref": "#/definitions/account" + description: Retrieves the details of the account. + properties: + business_name: + "$ref": "#/definitions/account/definitions/business_name" + business_primary_color: + "$ref": "#/definitions/account/definitions/business_primary_color" + business_url: + "$ref": "#/definitions/account/definitions/business_url" + charges_enabled: + "$ref": "#/definitions/account/definitions/charges_enabled" + country: + "$ref": "#/definitions/account/definitions/country" + currencies_supported: + "$ref": "#/definitions/account/definitions/currencies_supported" + debit_negative_balances: + "$ref": "#/definitions/account/definitions/debit_negative_balances" + decline_charge_on: + "$ref": "#/definitions/account/definitions/decline_charge_on" + default_currency: + "$ref": "#/definitions/account/definitions/default_currency" + details_submitted: + "$ref": "#/definitions/account/definitions/details_submitted" + display_name: + "$ref": "#/definitions/account/definitions/display_name" + email: + "$ref": "#/definitions/account/definitions/email" + external_accounts: + "$ref": "#/definitions/account/definitions/external_accounts" + id: + "$ref": "#/definitions/account/definitions/id" + legal_entity: + "$ref": "#/definitions/account/definitions/legal_entity" + managed: + "$ref": "#/definitions/account/definitions/managed" + metadata: + "$ref": "#/definitions/account/definitions/metadata" + object: + "$ref": "#/definitions/account/definitions/object" + product_description: + "$ref": "#/definitions/account/definitions/product_description" + statement_descriptor: + "$ref": "#/definitions/account/definitions/statement_descriptor" + support_email: + "$ref": "#/definitions/account/definitions/support_email" + support_phone: + "$ref": "#/definitions/account/definitions/support_phone" + support_url: + "$ref": "#/definitions/account/definitions/support_url" + timezone: + "$ref": "#/definitions/account/definitions/timezone" + tos_acceptance: + "$ref": "#/definitions/account/definitions/tos_acceptance" + transfer_schedule: + "$ref": "#/definitions/account/definitions/transfer_schedule" + transfers_enabled: + "$ref": "#/definitions/account/definitions/transfers_enabled" + verification: + "$ref": "#/definitions/account/definitions/verification" + required: + - charges_enabled + - country + - currencies_supported + - debit_negative_balances + - decline_charge_on + - default_currency + - details_submitted + - external_accounts + - id + - legal_entity + - managed + - object + - tos_acceptance + - transfer_schedule + - transfers_enabled + - verification + title: Account + type: + - object + account-authorization: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + access_token: + description: A live secret key for use with the account + example: '' + type: + - string + refresh_token: + description: Used to acquire a new set of access tokens after existing ones + expire + example: '' + type: + - string + scope: + description: The scope granted to the access token returned (typically read_only + or read_write) + example: '' + type: + - string + social_network_ids: + description: A set of social network identifiers associated with the newly + created user account + example: {} + type: + - object + stripe_partner_id: + example: '' + type: + - string + stripe_publishable_key: + description: A live publishable API key for use with the account + example: '' + type: + - string + stripe_user_id: + description: A unique identifier for the newly created user account + example: '' + type: + - string + token_type: + description: The authentication type of the access_token, will always be bearer + example: '' + type: + - string + links: + - title: AccountProvisionWithDelayedApplicationMethod + method: POST + rel: self + href: "/v1/provision" + targetSchema: + "$ref": "#/definitions/account-authorization" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + client_id: + example: '' + type: + - string + email: + example: '' + type: + - string + url: + example: '' + type: + - string + first_name: + example: '' + type: + - string + last_name: + example: '' + type: + - string + dob_day: + example: 0 + type: + - integer + dob_month: + example: 0 + type: + - integer + dob_year: + example: 0 + type: + - integer + ssn_last4: + example: '' + type: + - string + personal_id_number: + example: '' + type: + - string + street_address: + example: '' + type: + - string + city: + example: '' + type: + - string + state: + example: '' + type: + - string + zip: + example: '' + type: + - string + phone_number: + example: '' + type: + - string + business_name: + example: '' + type: + - string + business_type: + example: '' + type: + - string + business_tax_id: + example: '' + type: + - string + business_vat_id: + example: '' + type: + - string + statement_descriptor: + example: '' + type: + - string + product_description: + example: '' + type: + - string + product_category: + example: '' + type: + - string + physical_product: + example: false + type: + - boolean + shipping_days: + example: 0 + type: + - integer + average_payment: + example: 0 + type: + - integer + past_year_volume: + example: 0 + type: + - integer + country: + example: '' + type: + - string + currency: + example: '' + type: + - string + routing_number: + example: '' + type: + - string + account_number: + example: '' + type: + - string + bank_country: + example: '' + type: + - string + partner_id: + example: '' + type: + - string + iovation_blackbox: + example: '' + type: + - string + external_details: + example: {} + type: + - object + social_network_info: + example: {} + type: + - object + required: + - client_id + - email + - country + - currency + properties: + access_token: + "$ref": "#/definitions/account-authorization/definitions/access_token" + refresh_token: + "$ref": "#/definitions/account-authorization/definitions/refresh_token" + scope: + "$ref": "#/definitions/account-authorization/definitions/scope" + social_network_ids: + "$ref": "#/definitions/account-authorization/definitions/social_network_ids" + stripe_partner_id: + "$ref": "#/definitions/account-authorization/definitions/stripe_partner_id" + stripe_publishable_key: + "$ref": "#/definitions/account-authorization/definitions/stripe_publishable_key" + stripe_user_id: + "$ref": "#/definitions/account-authorization/definitions/stripe_user_id" + token_type: + "$ref": "#/definitions/account-authorization/definitions/token_type" + required: + - access_token + - refresh_token + - scope + - stripe_publishable_key + - stripe_user_id + - token_type + title: AccountAuthorization + type: + - object + account-with-keys: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + business_name: + description: The publicly visible name of the business + example: '' + type: + - string + business_primary_color: + description: A CSS hex color value representing the primary branding color + for this account + example: '' + type: + - string + business_url: + description: The publicly visible website of the business + example: '' + type: + - string + charges_enabled: + description: Whether or not the account can create live charges + example: false + type: + - boolean + country: + description: The country of the account + example: '' + type: + - string + currencies_supported: + description: The currencies this account can submit when creating charges + example: [] + type: + - array + debit_negative_balances: + description: Whether or not Stripe will attempt to reclaim negative account + balances from this account's bank account. + example: false + type: + - boolean + decline_charge_on: + description: Account-level settings to automatically decline certain types + of charges regardless of the bank's decision. + example: {} + type: + - object + default_currency: + description: The currency this account has chosen to use as the default + example: '' + type: + - string + details_submitted: + description: Whether or not account details have been submitted yet. Standalone + accounts cannot receive transfers before this is true. + example: false + type: + - boolean + display_name: + description: The display name for this account. This is used on the Stripe + dashboard to help you differentiate between accounts. + example: '' + type: + - string + email: + description: The primary user's email address + example: '' + type: + - string + external_accounts: + description: External accounts (bank accounts and/or cards) currently attached + to this account. + example: [] + type: + - array + id: + description: A unique identifier for the account + example: '' + type: + - string + keys: + example: {} + type: + - object + legal_entity: + description: Information regarding the owner of this account, including verification + status. + example: {} + type: + - object + managed: + description: Whether or not the account is [managed](/docs/connect/managed-accounts) + by your platform. Returns null if the account was not created by a platform. + example: false + type: + - boolean + metadata: + example: {} + type: + - object + object: + example: '' + type: + - string + product_description: + description: An internal-only description of the product or service provided. + This is used by Stripe in the event the account gets flagged for potential + fraud. + example: '' + type: + - string + statement_descriptor: + description: The text that will appear on credit card statements + example: '' + type: + - string + support_email: + description: A publicly shareable email address that can be reached for support + for this account + example: '' + type: + - string + support_phone: + description: The publicly visible support phone number for the business + example: '' + type: + - string + support_url: + description: A publicly shareable URL that can be reached for support for + this account + example: '' + type: + - string + timezone: + description: The timezone used in the Stripe dashboard for this account. A + list of possible timezone values is maintained at the [IANA Timezone Database](http://www.iana.org/time-zones). + example: '' + type: + - string + tos_acceptance: + description: Who accepted the Stripe terms of service, and when they accepted + it. + example: {} + type: + - object + transfer_schedule: + description: When payments collected will be automatically paid out to the + account holder's bank account. + example: {} + type: + - object + transfers_enabled: + description: Whether or not Stripe will send automatic transfers for this + account. This is only false when Stripe is waiting for additional information + from the account holder. + example: false + type: + - boolean + verification: + description: The state of the account's information requests, including what + information is needed and by when it must be provided. + example: {} + type: + - object + identity: + "$ref": "#/definitions/account-with-keys/definitions/resource_id" + links: + - title: AccountCreateFromTransferRecipientMethod + method: POST + rel: self + href: "/v1/accounts" + targetSchema: + "$ref": "#/definitions/account-with-keys" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + from_recipient: + example: '' + type: + - string + required: + - from_recipient + properties: + business_name: + "$ref": "#/definitions/account-with-keys/definitions/business_name" + business_primary_color: + "$ref": "#/definitions/account-with-keys/definitions/business_primary_color" + business_url: + "$ref": "#/definitions/account-with-keys/definitions/business_url" + charges_enabled: + "$ref": "#/definitions/account-with-keys/definitions/charges_enabled" + country: + "$ref": "#/definitions/account-with-keys/definitions/country" + currencies_supported: + "$ref": "#/definitions/account-with-keys/definitions/currencies_supported" + debit_negative_balances: + "$ref": "#/definitions/account-with-keys/definitions/debit_negative_balances" + decline_charge_on: + "$ref": "#/definitions/account-with-keys/definitions/decline_charge_on" + default_currency: + "$ref": "#/definitions/account-with-keys/definitions/default_currency" + details_submitted: + "$ref": "#/definitions/account-with-keys/definitions/details_submitted" + display_name: + "$ref": "#/definitions/account-with-keys/definitions/display_name" + email: + "$ref": "#/definitions/account-with-keys/definitions/email" + external_accounts: + "$ref": "#/definitions/account-with-keys/definitions/external_accounts" + id: + "$ref": "#/definitions/account-with-keys/definitions/id" + keys: + "$ref": "#/definitions/account-with-keys/definitions/keys" + legal_entity: + "$ref": "#/definitions/account-with-keys/definitions/legal_entity" + managed: + "$ref": "#/definitions/account-with-keys/definitions/managed" + metadata: + "$ref": "#/definitions/account-with-keys/definitions/metadata" + object: + "$ref": "#/definitions/account-with-keys/definitions/object" + product_description: + "$ref": "#/definitions/account-with-keys/definitions/product_description" + statement_descriptor: + "$ref": "#/definitions/account-with-keys/definitions/statement_descriptor" + support_email: + "$ref": "#/definitions/account-with-keys/definitions/support_email" + support_phone: + "$ref": "#/definitions/account-with-keys/definitions/support_phone" + support_url: + "$ref": "#/definitions/account-with-keys/definitions/support_url" + timezone: + "$ref": "#/definitions/account-with-keys/definitions/timezone" + tos_acceptance: + "$ref": "#/definitions/account-with-keys/definitions/tos_acceptance" + transfer_schedule: + "$ref": "#/definitions/account-with-keys/definitions/transfer_schedule" + transfers_enabled: + "$ref": "#/definitions/account-with-keys/definitions/transfers_enabled" + verification: + "$ref": "#/definitions/account-with-keys/definitions/verification" + required: + - charges_enabled + - country + - currencies_supported + - debit_negative_balances + - decline_charge_on + - default_currency + - details_submitted + - external_accounts + - id + - keys + - legal_entity + - managed + - object + - tos_acceptance + - transfer_schedule + - transfers_enabled + - verification + title: AccountWithKeys + type: + - object + alipay-account: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + created: + example: 0 + type: + - integer + customer: + example: '' + type: + - string + fingerprint: + description: Uniquely identifies the account and will be the same across all + Alipay account objects that are linked to the same Alipay account. + example: '' + type: + - string + id: + example: '' + type: + - string + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to a customer object. + It can be useful for storing additional information about the customer in + a structured format. + example: {} + type: + - object + object: + example: '' + type: + - string + payment_amount: + description: If the Alipay account object is not reusable, the exact amount + that you can create a charge for. + example: 0 + type: + - integer + payment_currency: + description: If the Alipay account object is not reusable, the exact currency + that you can create a charge for. + example: '' + type: + - string + reusable: + description: True if you can create multiple payments using this account. + If the account is reusable, then you can freely choose the amount of each + payment. + example: false + type: + - boolean + used: + description: Whether this Alipay account object has ever been used for a payment. + example: false + type: + - boolean + username: + description: The username for the Alipay account. + example: '' + type: + - string + identity: + "$ref": "#/definitions/alipay-account/definitions/resource_id" + links: + - title: AllCustomerAlipayAccountsMethod + method: GET + rel: self + href: "/v1/customers/{customer}/alipay_accounts" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/alipay-account" + url: + example: "/v1/customers/{customer}/alipay_accounts" + type: + - string + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + - title: RetrieveCustomerAlipayAccountMethod + method: GET + rel: self + href: "/v1/customers/{customer}/alipay_accounts/{%23%2Fdefinitions%2Falipay-account%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/alipay-account" + properties: + created: + "$ref": "#/definitions/alipay-account/definitions/created" + customer: + "$ref": "#/definitions/alipay-account/definitions/customer" + fingerprint: + "$ref": "#/definitions/alipay-account/definitions/fingerprint" + id: + "$ref": "#/definitions/alipay-account/definitions/id" + livemode: + "$ref": "#/definitions/alipay-account/definitions/livemode" + metadata: + "$ref": "#/definitions/alipay-account/definitions/metadata" + object: + "$ref": "#/definitions/alipay-account/definitions/object" + payment_amount: + "$ref": "#/definitions/alipay-account/definitions/payment_amount" + payment_currency: + "$ref": "#/definitions/alipay-account/definitions/payment_currency" + reusable: + "$ref": "#/definitions/alipay-account/definitions/reusable" + used: + "$ref": "#/definitions/alipay-account/definitions/used" + username: + "$ref": "#/definitions/alipay-account/definitions/username" + required: + - created + - fingerprint + - id + - livemode + - metadata + - object + - reusable + - used + - username + title: AlipayAccount + type: + - object + balance: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + available: + description: Funds that are available to be paid out automatically by Stripe + or explicitly via the transfers API. + example: + - amount: 0 + currency: usd + type: + - array + livemode: + example: false + type: + - boolean + object: + example: balance + type: + - string + pending: + description: Funds that are not available in the balance yet, due to the 7-day + rolling pay cycle. + example: + - amount: 0 + currency: usd + type: + - array + links: + - title: Retrieve balance + method: GET + rel: self + href: "/v1/balance" + targetSchema: + "$ref": "#/definitions/balance" + description: Retrieves the current account balance, based on the authentication + that was used to make the request. + properties: + available: + "$ref": "#/definitions/balance/definitions/available" + livemode: + "$ref": "#/definitions/balance/definitions/livemode" + object: + "$ref": "#/definitions/balance/definitions/object" + pending: + "$ref": "#/definitions/balance/definitions/pending" + required: + - available + - livemode + - object + - pending + title: Balance + type: + - object + balance-transaction: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + description: Gross amount of the transaction, in %s. + example: 0 + type: + - integer + available_on: + description: The date the transaction's net funds will become available in + the Stripe balance. + example: 0 + type: + - integer + created: + example: 0 + type: + - integer + currency: + example: '' + type: + - string + description: + example: '' + type: + - string + fee: + description: Fees (in %s) paid for this transaction + example: 0 + type: + - integer + fee_details: + description: Detailed breakdown of fees (in %s) paid for this transaction + example: [] + type: + - array + id: + example: '' + type: + - string + net: + description: Net amount of the transaction, in %s. + example: 0 + type: + - integer + object: + example: '' + type: + - string + source: + description: The Stripe object this transaction is related to. + example: '' + type: + - string + sourced_transfers: + description: The transfers (if any) for which `source` is a `source_transaction`. + example: [] + type: + - array + status: + description: If the transaction's net funds are available in the Stripe balance + yet. Either `available` or `pending`. + example: '' + type: + - string + type: + description: 'Type of the transaction, one of: `charge`, `refund`, `adjustment`, + `application_fee`, `application_fee_refund`, `transfer`, `transfer_cancel` + or `transfer_failure`.' + example: '' + type: + - string + identity: + "$ref": "#/definitions/balance-transaction/definitions/resource_id" + links: + - title: List balance history + method: GET + rel: self + href: "/v1/balance/history" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/balance-transaction" + url: + example: "/v1/balance/history" + type: + - string + description: Returns a list of transactions that have contributed to the Stripe + account balance (e.g., charges, transfers, and so forth). The transactions + are returned in sorted order, with the most recent transactions appearing + first. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + transfer: + example: '' + type: + - string + description: For automatic Stripe transfers only, only returns transactions + that were transferred out on the specified transfer ID. + available_on: + example: {} + type: + - object + - integer + - string + created: + example: {} + type: + - object + - integer + type: + example: '' + type: + - string + description: 'Only returns transactions of the given type. One of: `charge`, + `adjustment`, `application_fee`, `application_fee_refund`, `transfer`, + or `transfer_failure`' + source: + example: '' + type: + - string + description: Only returns transactions that are related to the specified + Stripe object ID (e.g. filtering by a charge ID will return all related + charge transactions). + currency: + example: '' + type: + - string + - title: Retrieve a balance transaction + method: GET + rel: self + href: "/v1/balance/history/{%23%2Fdefinitions%2Fbalance-transaction%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/balance-transaction" + description: Retrieves the balance transaction with the given ID. + properties: + amount: + "$ref": "#/definitions/balance-transaction/definitions/amount" + available_on: + "$ref": "#/definitions/balance-transaction/definitions/available_on" + created: + "$ref": "#/definitions/balance-transaction/definitions/created" + currency: + "$ref": "#/definitions/balance-transaction/definitions/currency" + description: + "$ref": "#/definitions/balance-transaction/definitions/description" + fee: + "$ref": "#/definitions/balance-transaction/definitions/fee" + fee_details: + "$ref": "#/definitions/balance-transaction/definitions/fee_details" + id: + "$ref": "#/definitions/balance-transaction/definitions/id" + net: + "$ref": "#/definitions/balance-transaction/definitions/net" + object: + "$ref": "#/definitions/balance-transaction/definitions/object" + source: + "$ref": "#/definitions/balance-transaction/definitions/source" + sourced_transfers: + "$ref": "#/definitions/balance-transaction/definitions/sourced_transfers" + status: + "$ref": "#/definitions/balance-transaction/definitions/status" + type: + "$ref": "#/definitions/balance-transaction/definitions/type" + required: + - amount + - available_on + - created + - currency + - fee + - fee_details + - id + - net + - object + - status + - type + title: BalanceTransaction + type: + - object + bitcoin-receiver: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + active: + description: True when this bitcoin receiver has received a non-zero amount + of bitcoin. + example: false + type: + - boolean + amount: + description: The amount of `currency` that you are collecting as payment. + example: 0 + type: + - integer + amount_received: + description: The amount of `currency` to which `bitcoin_amount_received` has + been converted. + example: 0 + type: + - integer + bitcoin_amount: + description: 'The amount of bitcoin that the customer should send to fill + the receiver. The `bitcoin_amount` is denominated in Satoshi: there are + 10^8 Satoshi in one bitcoin.' + example: 0 + type: + - integer + bitcoin_amount_received: + description: The amount of bitcoin that has been sent by the customer to this + receiver. + example: 0 + type: + - integer + bitcoin_uri: + description: This URI can be displayed to the customer as a clickable link + (to activate their bitcoin client) or as a QR code (for mobile wallets). + example: '' + type: + - string + created: + example: 0 + type: + - integer + currency: + description: Three-letter ISO currency code representing the currency to which + the bitcoin will be converted. + example: '' + type: + - string + customer: + example: '' + type: + - string + description: + example: '' + type: + - string + email: + description: The customer's email address, set by the API call that creates + the receiver. + example: '' + type: + - string + filled: + description: This flag is initially false and updates to true when the customer + sends the `bitcoin_amount` to this receiver. + example: false + type: + - boolean + id: + example: '' + type: + - string + inbound_address: + description: A bitcoin address that is specific to this receiver. The customer + can send bitcoin to this address to fill the receiver. + example: '' + type: + - string + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to a customer object. + It can be useful for storing additional information about the customer in + a structured format. + example: {} + type: + - object + object: + example: '' + type: + - string + payment: + description: The ID of the payment created from the receiver, if any. Hidden + when viewing the receiver with a publishable key. + example: '' + type: + - string + refund_address: + description: The refund address for these bitcoin, if communicated by the + customer. + example: '' + type: + - string + transactions: + description: A list with one entry for each time that the customer sent bitcoin + to the receiver. Hidden when viewing the receiver with a publishable key. + example: [] + type: + - array + uncaptured_funds: + description: This receiver contains uncaptured funds that can be used for + a payment or refunded. + example: false + type: + - boolean + used_for_payment: + example: false + type: + - boolean + identity: + "$ref": "#/definitions/bitcoin-receiver/definitions/resource_id" + links: + - title: Create a receiver + method: POST + rel: self + href: "/v1/bitcoin/receivers" + targetSchema: + "$ref": "#/definitions/bitcoin-receiver" + description: Creates a Bitcoin receiver object that can be used to accept bitcoin + payments from your customer. The receiver exposes a Bitcoin address and is + created with a bitcoin to USD exchange rate that is valid for 10 minutes. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + amount: + example: 0 + type: + - integer + description: The amount of `currency` that you will be paid. + currency: + example: '' + type: + - string + description: The currency to which the bitcoin will be converted. You + will be paid out in this currency. Only USD is currently supported. + description: + example: '' + type: + - string + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a customer + object. It can be useful for storing additional information about the + customer in a structured format. + email: + example: '' + type: + - string + description: The email address of the customer. + refund_mispayments: + example: false + type: + - boolean + description: 'A flag that indicates whether you would like Stripe to automatically + handle refunds for any [mispayments](/docs/guides/bitcoin#mispayments) + to the receiver. ' + required: + - amount + - currency + - title: DeleteReceiverMethod + method: DELETE + rel: self + href: "/v1/bitcoin/receivers/{%23%2Fdefinitions%2Fbitcoin-receiver%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/bitcoin-receiver" + - title: List all receivers + method: GET + rel: self + href: "/v1/bitcoin/receivers" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/bitcoin-receiver" + url: + example: "/v1/bitcoin/receivers" + type: + - string + description: Returns a list of your receivers. Receivers are returned sorted + by creation date, with the most recently created receivers appearing first. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + active: + example: false + type: + - boolean + description: Filter for active receivers. + filled: + example: false + type: + - boolean + description: Filter for filled receivers. + uncaptured_funds: + example: false + type: + - boolean + description: Filter for receivers with uncaptured funds. + - title: RefundReceiverMethod + method: POST + rel: self + href: "/v1/bitcoin/receivers/{%23%2Fdefinitions%2Fbitcoin-receiver%2Fdefinitions%2Fidentity}/refund" + targetSchema: + "$ref": "#/definitions/bitcoin-receiver" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + refund_address: + example: '' + type: + - string + description: If the receiver does not already have a refund address, then + you need to provide one to perform a refund. + - title: Retrieve a receiver + method: GET + rel: self + href: "/v1/bitcoin/receivers/{%23%2Fdefinitions%2Fbitcoin-receiver%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/bitcoin-receiver" + description: Retrieves the Bitcoin receiver with the given ID. + - title: UpdateReceiverMethod + method: POST + rel: self + href: "/v1/bitcoin/receivers/{%23%2Fdefinitions%2Fbitcoin-receiver%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/bitcoin-receiver" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + description: + example: '' + type: + - string + metadata: + example: {} + type: + - object + email: + example: '' + type: + - string + refund_address: + example: '' + type: + - string + properties: + active: + "$ref": "#/definitions/bitcoin-receiver/definitions/active" + amount: + "$ref": "#/definitions/bitcoin-receiver/definitions/amount" + amount_received: + "$ref": "#/definitions/bitcoin-receiver/definitions/amount_received" + bitcoin_amount: + "$ref": "#/definitions/bitcoin-receiver/definitions/bitcoin_amount" + bitcoin_amount_received: + "$ref": "#/definitions/bitcoin-receiver/definitions/bitcoin_amount_received" + bitcoin_uri: + "$ref": "#/definitions/bitcoin-receiver/definitions/bitcoin_uri" + created: + "$ref": "#/definitions/bitcoin-receiver/definitions/created" + currency: + "$ref": "#/definitions/bitcoin-receiver/definitions/currency" + customer: + "$ref": "#/definitions/bitcoin-receiver/definitions/customer" + description: + "$ref": "#/definitions/bitcoin-receiver/definitions/description" + email: + "$ref": "#/definitions/bitcoin-receiver/definitions/email" + filled: + "$ref": "#/definitions/bitcoin-receiver/definitions/filled" + id: + "$ref": "#/definitions/bitcoin-receiver/definitions/id" + inbound_address: + "$ref": "#/definitions/bitcoin-receiver/definitions/inbound_address" + livemode: + "$ref": "#/definitions/bitcoin-receiver/definitions/livemode" + metadata: + "$ref": "#/definitions/bitcoin-receiver/definitions/metadata" + object: + "$ref": "#/definitions/bitcoin-receiver/definitions/object" + payment: + "$ref": "#/definitions/bitcoin-receiver/definitions/payment" + refund_address: + "$ref": "#/definitions/bitcoin-receiver/definitions/refund_address" + transactions: + "$ref": "#/definitions/bitcoin-receiver/definitions/transactions" + uncaptured_funds: + "$ref": "#/definitions/bitcoin-receiver/definitions/uncaptured_funds" + used_for_payment: + "$ref": "#/definitions/bitcoin-receiver/definitions/used_for_payment" + required: + - active + - amount + - amount_received + - bitcoin_amount + - bitcoin_amount_received + - bitcoin_uri + - created + - currency + - filled + - id + - inbound_address + - livemode + - metadata + - object + - transactions + - uncaptured_funds + title: BitcoinReceiver + type: + - object + bitcoin-transaction: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + description: The amount of `currency` that the transaction was converted to + in real-time. + example: 0 + type: + - integer + bitcoin_amount: + description: The amount of bitcoin contained in the transaction. + example: 0 + type: + - integer + created: + example: 0 + type: + - integer + currency: + description: The currency to which this transaction was converted. + example: '' + type: + - string + id: + example: '' + type: + - string + object: + example: '' + type: + - string + receiver: + description: The receiver to which this transaction was sent. + example: '' + type: + - string + identity: + "$ref": "#/definitions/bitcoin-transaction/definitions/resource_id" + links: + - title: AllTransactionsMethod + method: GET + rel: self + href: "/v1/bitcoin/receivers/{receiver}/transactions" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/bitcoin-transaction" + url: + example: "/v1/bitcoin/receivers/{receiver}/transactions" + type: + - string + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + customer: + example: '' + type: + - string + description: Only return transactions for the customer specified by this + customer ID. + - title: AllTransactionsMethod + method: GET + rel: self + href: "/v1/bitcoin/transactions" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/bitcoin-transaction" + url: + example: "/v1/bitcoin/transactions" + type: + - string + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + customer: + example: '' + type: + - string + description: Only return transactions for the customer specified by this + customer ID. + receiver: + example: '' + type: + - string + description: Only return transactions for the receiver specified by this + receiver ID. + - title: RetrieveTransactionMethod + method: GET + rel: self + href: "/v1/bitcoin/transactions/{%23%2Fdefinitions%2Fbitcoin-transaction%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/bitcoin-transaction" + properties: + amount: + "$ref": "#/definitions/bitcoin-transaction/definitions/amount" + bitcoin_amount: + "$ref": "#/definitions/bitcoin-transaction/definitions/bitcoin_amount" + created: + "$ref": "#/definitions/bitcoin-transaction/definitions/created" + currency: + "$ref": "#/definitions/bitcoin-transaction/definitions/currency" + id: + "$ref": "#/definitions/bitcoin-transaction/definitions/id" + object: + "$ref": "#/definitions/bitcoin-transaction/definitions/object" + receiver: + "$ref": "#/definitions/bitcoin-transaction/definitions/receiver" + required: + - amount + - bitcoin_amount + - created + - currency + - id + - object + - receiver + title: BitcoinTransaction + type: + - object + charge: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + description: Amount charged in %s + example: 100 + type: + - integer + amount_refunded: + description: Amount in %s refunded (can be less than the amount attribute + on the charge if a partial refund was issued). + example: 0 + type: + - integer + application_fee: + description: The application fee (if any) for the charge. [See the Connect + documentation](/docs/connect/payments-fees#collecting-fees) for details. + example: '' + type: + - string + balance_transaction: + description: ID of the balance transaction that describes the impact of this + charge on your account balance (not including refunds or disputes). + example: txn_173zDIIw57t4eNNvXMCPHWEE + type: + - string + captured: + description: If the charge was created without capturing, this boolean represents + whether or not it is still uncaptured or has since been captured. + example: true + type: + - boolean + created: + example: 1446774024 + type: + - integer + currency: + description: Three-letter ISO currency code representing the currency in which + the charge was made. + example: usd + type: + - string + customer: + description: ID of the customer this charge is for if one exists. + example: '' + type: + - string + description: + example: My First Test Charge (created for API docs) + type: + - string + destination: + description: The account (if any) the charge was made on behalf of. [See the + Connect documentation](/docs/connect/payments-fees#charging-through-the-platform) + for details. + example: '' + type: + - string + dispute: + description: Details about the dispute if the charge has been disputed. + example: {} + type: + - object + failure_code: + description: Error code explaining reason for charge failure if available + (see [the errors section](/docs/api#errors) for a list of codes). + example: '' + type: + - string + failure_message: + description: Message to user further explaining reason for charge failure + if available. + example: '' + type: + - string + fraud_details: + description: Hash with information on fraud assessments for the charge. Assessments + reported by you have the key `user_report` and, if set, possible values + of `safe` and `fraudulent`. Assessments from Stripe have the key `stripe_report` + and, if set, the value `fraudulent`. + example: {} + type: + - object + id: + example: ch_173zDIIw57t4eNNvjJ1ECQp4 + type: + - string + invoice: + description: ID of the invoice this charge is for if one exists. + example: '' + type: + - string + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to a charge object. + It can be useful for storing additional information about the charge in + a structured format. + example: {} + type: + - object + object: + example: charge + type: + - string + paid: + description: "`true` if the charge succeeded, or was successfully authorized + for later capture." + example: true + type: + - boolean + receipt_email: + description: This is the email address that the receipt for this charge was + sent to. + example: '' + type: + - string + receipt_number: + description: This is the transaction number that appears on email receipts + sent for this charge. + example: '' + type: + - string + refunded: + description: Whether or not the charge has been fully refunded. If the charge + is only partially refunded, this attribute will still be false. + example: false + type: + - boolean + refunds: + description: A list of refunds that have been applied to the charge. + example: + data: [] + has_more: false + object: list + total_count: 0 + url: "/v1/charges/ch_173zDIIw57t4eNNvjJ1ECQp4/refunds" + type: + - object + shipping: + description: Shipping information for the charge. + example: {} + type: + - object + statement_descriptor: + description: Extra information about a charge. This will appear on your customer's + credit card statement. + example: '' + type: + - string + status: + description: The status of the payment is either `succeeded` or `failed`. + example: succeeded + type: + - string + transfer: + description: ID of the transfer to the `destination` account (only applicable + if the charge was created using the `destination` parameter). + example: '' + type: + - string + identity: + "$ref": "#/definitions/charge/definitions/resource_id" + links: + - title: AllPaymentsMethod + method: GET + rel: self + href: "/v1/payments" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/charge" + url: + example: "/v1/payments" + type: + - string + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + customer: + example: '' + type: + - string + description: Only return payments for the customer specified by this customer + ID. + - title: Capture a charge + method: POST + rel: self + href: "/v1/charges/{charge}/capture" + targetSchema: + "$ref": "#/definitions/charge" + description: |- + Capture the payment of an existing, uncaptured, charge. This is the second half of the two-step payment flow, where first you created a charge with the capture option set to false.

+ +

Uncaptured payments expire exactly seven days after they are created. If they are not captured by that point in time, they will be marked as refunded and will no longer be capturable. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + amount: + example: 0 + type: + - integer + description: The amount to capture, which must be less than or equal to + the original amount. Any additional amount will be automatically refunded. + application_fee: + example: 0 + type: + - integer + description: An application fee to add on to this charge. Can only be + used with Stripe Connect. + statement_descriptor: + example: '' + type: + - string + description: An arbitrary string to be displayed on your customer's credit + card statement. This may be up to *22 characters*. As an example, if + your website is `RunClub` and the item you're charging for is a race + ticket, you may want to specify a `statement_descriptor` of `RunClub + 5K race ticket`. The statement description may not include `<>"'` characters, + and will appear on your customer's statement in capital letters. Non-ASCII + characters are automatically stripped. Updating this value will overwrite + the previous statement descriptor of this charge. While most banks display + this information consistently, some may display it incorrectly or not + at all. + receipt_email: + example: '' + type: + - string + description: The email address to send this charge's receipt to. This + will override the previously-specified email address for this charge, + if one was set. Receipts will not be sent in test mode. + - title: CreateEMVCardPresentChargeMethod + method: POST + rel: self + href: "/v1/charges" + targetSchema: + "$ref": "#/definitions/charge" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + transfer: + example: {} + type: + - object + destination: + example: '' + type: + - string + source: + example: {} + type: + - object + card: + example: '' + type: + - string + description: + example: '' + type: + - string + metadata: + example: {} + type: + - object + statement_descriptor: + example: '' + type: + - string + capture: + example: false + type: + - boolean + application_fee: + example: 0 + type: + - integer + required: + - source + - title: CreatePaymentRefundWithPaymentResponseMethod + method: POST + rel: self + href: "/v1/charges/{charge}/refund" + targetSchema: + "$ref": "#/definitions/charge" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + amount: + example: 0 + type: + - integer + refund_application_fee: + example: false + type: + - boolean + metadata: + example: {} + type: + - object + description: + example: '' + type: + - string + reason: + example: '' + type: + - string + reverse_transfer: + example: false + type: + - boolean + refund_address: + example: '' + type: + - string + payment: + example: '' + type: + - string + - title: CreatePaymentRefundWithPaymentResponseMethod + method: POST + rel: self + href: "/v1/bitcoin/payments/{payment}/refund" + targetSchema: + "$ref": "#/definitions/charge" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + charge: + example: '' + type: + - string + amount: + example: 0 + type: + - integer + refund_application_fee: + example: false + type: + - boolean + metadata: + example: {} + type: + - object + description: + example: '' + type: + - string + reason: + example: '' + type: + - string + reverse_transfer: + example: false + type: + - boolean + refund_address: + example: '' + type: + - string + required: + - charge + - title: List all charges + method: GET + rel: self + href: "/v1/charges" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/charge" + url: + example: "/v1/charges" + type: + - string + description: Returns a list of charges you’ve previously created. The charges + are returned in sorted order, with the most recent charges appearing first. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + customer: + example: '' + type: + - string + description: Only return charges for the customer specified by this customer + ID. + created: + example: {} + type: + - object + - integer + source: + example: {} + type: + - object + - title: Retrieve a charge + method: GET + rel: self + href: "/v1/charges/{charge}" + targetSchema: + "$ref": "#/definitions/charge" + description: Retrieves the details of a charge that has previously been created. + Supply the unique charge ID that was returned from your previous request, + and Stripe will return the corresponding charge information. The same information + is returned when creating or refunding the charge. + - title: RetrievePaymentMethod + method: GET + rel: self + href: "/v1/payments/{payment}" + targetSchema: + "$ref": "#/definitions/charge" + - title: Update a charge + method: POST + rel: self + href: "/v1/charges/{charge}" + targetSchema: + "$ref": "#/definitions/charge" + description: Updates the specified charge by setting the values of the parameters + passed. Any parameters not provided will be left unchanged. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + description: + example: '' + type: + - string + metadata: + example: {} + type: + - object + fraud_details: + example: {} + type: + - object + receipt_email: + example: '' + type: + - string + level3: + example: {} + type: + - object + shipping: + example: {} + type: + - object + source: + example: {} + type: + - object + properties: + amount: + "$ref": "#/definitions/charge/definitions/amount" + amount_refunded: + "$ref": "#/definitions/charge/definitions/amount_refunded" + application_fee: + "$ref": "#/definitions/charge/definitions/application_fee" + balance_transaction: + "$ref": "#/definitions/charge/definitions/balance_transaction" + captured: + "$ref": "#/definitions/charge/definitions/captured" + created: + "$ref": "#/definitions/charge/definitions/created" + currency: + "$ref": "#/definitions/charge/definitions/currency" + customer: + "$ref": "#/definitions/charge/definitions/customer" + description: + "$ref": "#/definitions/charge/definitions/description" + destination: + "$ref": "#/definitions/charge/definitions/destination" + dispute: + "$ref": "#/definitions/charge/definitions/dispute" + failure_code: + "$ref": "#/definitions/charge/definitions/failure_code" + failure_message: + "$ref": "#/definitions/charge/definitions/failure_message" + fraud_details: + "$ref": "#/definitions/charge/definitions/fraud_details" + id: + "$ref": "#/definitions/charge/definitions/id" + invoice: + "$ref": "#/definitions/charge/definitions/invoice" + livemode: + "$ref": "#/definitions/charge/definitions/livemode" + metadata: + "$ref": "#/definitions/charge/definitions/metadata" + object: + "$ref": "#/definitions/charge/definitions/object" + paid: + "$ref": "#/definitions/charge/definitions/paid" + receipt_email: + "$ref": "#/definitions/charge/definitions/receipt_email" + receipt_number: + "$ref": "#/definitions/charge/definitions/receipt_number" + refunded: + "$ref": "#/definitions/charge/definitions/refunded" + refunds: + "$ref": "#/definitions/charge/definitions/refunds" + shipping: + "$ref": "#/definitions/charge/definitions/shipping" + statement_descriptor: + "$ref": "#/definitions/charge/definitions/statement_descriptor" + status: + "$ref": "#/definitions/charge/definitions/status" + transfer: + "$ref": "#/definitions/charge/definitions/transfer" + required: + - amount + - amount_refunded + - captured + - created + - currency + - id + - livemode + - metadata + - object + - paid + - refunded + - refunds + - status + title: Charge + type: + - object + coupon: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount_off: + description: 'Amount (in the `currency` specified) that will be taken off + the subtotal of any invoices for this customer. ' + example: 0 + type: + - integer + created: + example: 1446774024 + type: + - integer + currency: + description: If `amount_off` has been set, the currency of the amount to take + off. + example: usd + type: + - string + duration: + description: One of `forever`, `once`, and `repeating`. Describes how long + a customer who applies this coupon will get the discount. + example: repeating + type: + - string + duration_in_months: + description: If `duration` is `repeating`, the number of months the coupon + applies. Null if coupon `duration` is `forever` or `once`. + example: 3 + type: + - integer + id: + example: 25OFF + type: + - string + livemode: + example: false + type: + - boolean + max_redemptions: + description: Maximum number of times this coupon can be redeemed, in total, + before it is no longer valid. + example: 0 + type: + - integer + metadata: + description: A set of key/value pairs that you can attach to a coupon object. + It can be useful for storing additional information about the coupon in + a structured format. + example: {} + type: + - object + object: + example: coupon + type: + - string + percent_off: + description: Percent that will be taken off the subtotal of any invoices for + this customer for the duration of the coupon. For example, a coupon with + percent_off of 50 will make a %s100 invoice %s50 instead. + example: 25 + type: + - integer + redeem_by: + description: Date after which the coupon can no longer be redeemed + example: 0 + type: + - integer + times_redeemed: + description: Number of times this coupon has been applied to a customer. + example: 0 + type: + - integer + valid: + description: Taking account of the above properties, whether this coupon can + still be applied to a customer + example: true + type: + - boolean + identity: + "$ref": "#/definitions/coupon/definitions/resource_id" + links: + - title: Create a coupon + method: POST + rel: self + href: "/v1/coupons" + targetSchema: + "$ref": "#/definitions/coupon" + description: |- + You can create coupons easily via the coupon management page of the Stripe dashboard. Coupon creation is also accessible via the API if you need to create coupons on the fly.

+ +

A coupon has either a percent_off or an amount_off and currency. If you set an amount_off, that amount will be subtracted from any invoice’s subtotal. For example, an invoice with a subtotal of 10 will have a final total of 0 if a coupon with an amount_off of 2000 is applied to it and an invoice with a subtotal of 30 will have a final total of 10 if a coupon with an amount_off of 2000 is applied to it. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + id: + example: '' + type: + - string + description: Unique string of your choice that will be used to identify + this coupon when applying it to a customer. This is often a specific + code you'll give to your customer to use when signing up (e.g. *FALL25OFF*). + If you don't want to specify a particular code, you can leave the ID + blank and we'll generate a random code for you. + percent_off: + example: 0 + type: + - integer + description: A positive integer between 1 and 100 that represents the + discount the coupon will apply (required if `amount_off` is not passed) + amount_off: + example: 0 + type: + - integer + description: A positive integer representing the amount to subtract from + an invoice total (required if `percent_off` is not passed) + currency: + example: '' + type: + - string + description: Currency of the `amount_off` parameter (required if `amount_off` + is passed) + duration: + example: '' + type: + - string + description: Specifies how long the discount will be in effect. Can be + `forever`, `once`, or `repeating`. + max_redemptions: + example: 0 + type: + - integer + description: A positive integer specifying the number of times the coupon + can be redeemed before it's no longer valid. For example, you might + have a 50% off coupon that the first 20 readers of your blog can use. + redeem_by: + example: 0 + type: + - integer + description: Unix timestamp specifying the last time at which the coupon + can be redeemed. After the redeem_by date, the coupon can no longer + be applied to new customers. + duration_in_months: + example: 0 + type: + - integer + description: Required only if `duration` is `repeating`, in which case + it must be a positive integer that specifies the number of months the + discount will be in effect. + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a coupon + object. It can be useful for storing additional information about the + coupon in a structured format. + required: + - duration + - title: Delete a coupon + method: DELETE + rel: self + href: "/v1/coupons/{coupon}" + targetSchema: + "$ref": "#/definitions/coupon" + description: You can delete coupons via the coupon + management page of the Stripe dashboard. However, deleting a coupon does + not affect any customers who have already applied the coupon; it means that + new customers can’t redeem the coupon. You can also delete coupons via the + API. + - title: List all coupons + method: GET + rel: self + href: "/v1/coupons" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/coupon" + url: + example: "/v1/coupons" + type: + - string + description: Returns a list of your coupons. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + created: + example: {} + type: + - object + - integer + - title: Retrieve a coupon + method: GET + rel: self + href: "/v1/coupons/{coupon}" + targetSchema: + "$ref": "#/definitions/coupon" + description: Retrieves the coupon with the given ID. + - title: Update a coupon + method: POST + rel: self + href: "/v1/coupons/{coupon}" + targetSchema: + "$ref": "#/definitions/coupon" + description: Updates the metadata of a coupon. Other coupon details (currency, + duration, amount_off) are, by design, not editable. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a coupon + object. It can be useful for storing additional information about the + coupon in a structured format. + properties: + amount_off: + "$ref": "#/definitions/coupon/definitions/amount_off" + created: + "$ref": "#/definitions/coupon/definitions/created" + currency: + "$ref": "#/definitions/coupon/definitions/currency" + duration: + "$ref": "#/definitions/coupon/definitions/duration" + duration_in_months: + "$ref": "#/definitions/coupon/definitions/duration_in_months" + id: + "$ref": "#/definitions/coupon/definitions/id" + livemode: + "$ref": "#/definitions/coupon/definitions/livemode" + max_redemptions: + "$ref": "#/definitions/coupon/definitions/max_redemptions" + metadata: + "$ref": "#/definitions/coupon/definitions/metadata" + object: + "$ref": "#/definitions/coupon/definitions/object" + percent_off: + "$ref": "#/definitions/coupon/definitions/percent_off" + redeem_by: + "$ref": "#/definitions/coupon/definitions/redeem_by" + times_redeemed: + "$ref": "#/definitions/coupon/definitions/times_redeemed" + valid: + "$ref": "#/definitions/coupon/definitions/valid" + required: + - created + - duration + - id + - livemode + - metadata + - object + - times_redeemed + - valid + title: Coupon + type: + - object + customer: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + account_balance: + description: Current balance, if any, being stored on the customer's account. If + negative, the customer has credit to apply to the next invoice. If positive, + the customer has an amount owed that will be added to the next invoice. The + balance does not refer to any unpaid invoices; it solely takes into account + amounts that have yet to be successfully applied to any invoice. This balance + is only taken into account for recurring charges. + example: 0 + type: + - integer + created: + example: 1446754408 + type: + - integer + currency: + description: The currency the customer can be charged in for recurring billing + purposes (subscriptions, invoices, invoice items). + example: usd + type: + - string + default_source: + description: ID of the default source attached to this customer. + example: '' + type: + - string + delinquent: + description: Whether or not the latest charge for the customer's latest invoice + has failed + example: false + type: + - boolean + description: + example: '' + type: + - string + discount: + description: Describes the current discount active on the customer, if there + is one. + example: {} + type: + - object + email: + example: '' + type: + - string + id: + example: cus_7IV7zteF9TaFBj + type: + - string + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to a customer object. + It can be useful for storing additional information about the customer in + a structured format. + example: {} + type: + - object + object: + example: customer + type: + - string + shipping: + description: Shipping information associated with the customer. + example: {} + type: + - object + sources: + description: The customer's payment sources, if any + example: + data: [] + has_more: false + object: list + total_count: 0 + url: "/v1/customers/cus_7IV7zteF9TaFBj/sources" + type: + - object + subscriptions: + description: The customer's current subscriptions, if any + example: + data: [] + has_more: false + object: list + total_count: 0 + url: "/v1/customers/cus_7IV7zteF9TaFBj/subscriptions" + type: + - object + identity: + "$ref": "#/definitions/customer/definitions/resource_id" + links: + - title: Create a customer + method: POST + rel: self + href: "/v1/customers" + targetSchema: + "$ref": "#/definitions/customer" + description: Creates a new customer object. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + plan: + example: '' + type: + - string + description: The identifier of the plan to subscribe the customer to. If + provided, the returned customer object will have a list + of subscriptions that the customer is currently subscribed to. + If you subscribe a customer to a plan without a free trial, the + customer must have a valid card as well. + description: + example: '' + type: + - string + description: An arbitrary string that you can attach to a customer object. + It is displayed alongside the customer in the dashboard. + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a customer object. + It can be useful for storing additional information about the customer in + a structured format. + coupon: + example: '' + type: + - string + description: If you provide a coupon code, the customer will have a discount + applied on all recurring charges. Charges you create through + the API will not have the discount. + trial_end: + example: 0 + type: + - integer + - string + description: Unix timestamp representing the end of the trial period the + customer will get before being charged. If set, trial_end will + override the default trial period of the plan the customer + is being subscribed to. The special value now + can be provided to end the customer's trial immediately. Only + applies when the plan parameter is also provided. + email: + example: '' + type: + - string + description: Customer's email address. It's displayed alongside the customer + in your dashboard and can be useful for searching and tracking. + shipping: + example: {} + type: + - object + account_balance: + example: 0 + type: + - integer + description: An integer amount in %s that is the starting account + balance for your customer. A negative amount represents a + credit that will be used before attempting any charges to the customer's card; + a positive amount will be added to the next invoice. + source: + example: {} + type: + - object + - string + description: The source can either be a token, like the ones returned + by our [Stripe.js](/docs/stripe.js), or a dictionary containing + a user's credit card details (with the options shown below). + quantity: + example: 0 + type: + - integer + description: The quantity you'd like to apply to the subscription you're + creating (if you pass in a `plan`). For example, if your plan + is 10 %s/user/month, and your customer has 5 users, you could + pass 5 as the quantity to have the customer charged 50 %s (5 + x 10 %s) monthly. Defaults to 1 if not set. Only applies when the plan + parameter is also provided. + tax_percent: + example: 0.0 + type: + - number + description: A positive decimal (with at most two decimal places) between + 1 and 100. This represents the percentage of the subscription invoice + subtotal that will be calculated and added as tax to the final amount + each billing period. For example, a plan which charges $10/month with + a `tax_percent` of 20.0 will charge $12 per invoice. Can only be used + if a plan is provided. + - title: CustomerUpdateWithPlanMethod + method: POST + rel: self + href: "/v1/customers/{customer}" + targetSchema: + "$ref": "#/definitions/customer" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + plan: + example: '' + type: + - string + description: The identifier of the plan to subscribe the customer to. If + provided, the returned customer object will have a list + of subscriptions that the customer is currently subscribed to. + If you subscribe a customer to a plan without a free trial, the + customer must have a valid card as well. + description: + example: '' + type: + - string + description: An arbitrary string that you can attach to a customer object. + It is displayed alongside the customer in the dashboard. + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a customer object. + It can be useful for storing additional information about the customer in + a structured format. + coupon: + example: '' + type: + - string + description: If you provide a coupon code, the customer will have a discount + applied on all recurring charges. Charges you create through + the API will not have the discount. + trial_end: + example: 0 + type: + - integer + - string + description: Unix timestamp representing the end of the trial period the + customer will get before being charged. If set, trial_end will + override the default trial period of the plan the customer + is being subscribed to. The special value now + can be provided to end the customer's trial immediately. Only + applies when the plan parameter is also provided. + email: + example: '' + type: + - string + description: Customer's email address. It's displayed alongside the customer + in your dashboard and can be useful for searching and tracking. + shipping: + example: {} + type: + - object + account_balance: + example: 0 + type: + - integer + description: An integer amount in %s that is the starting account + balance for your customer. A negative amount represents a + credit that will be used before attempting any charges to the customer's card; + a positive amount will be added to the next invoice. + source: + example: {} + type: + - object + - string + description: The source can either be a token, like the ones returned + by our [Stripe.js](/docs/stripe.js), or a dictionary containing + a user's credit card details (with the options shown below). + quantity: + example: 0 + type: + - integer + description: The quantity you'd like to apply to the subscription you're + creating (if you pass in a `plan`). For example, if your plan + is 10 %s/user/month, and your customer has 5 users, you could + pass 5 as the quantity to have the customer charged 50 %s (5 + x 10 %s) monthly. Defaults to 1 if not set. Only applies when the plan + parameter is also provided. + tax_percent: + example: 0.0 + type: + - number + description: A positive decimal (with at most two decimal places) between + 1 and 100. This represents the percentage of the subscription invoice + subtotal that will be calculated and added as tax to the final amount + each billing period. For example, a plan which charges $10/month with + a `tax_percent` of 20.0 will charge $12 per invoice. Can only be used + if a plan is provided. + - title: Delete a customer + method: DELETE + rel: self + href: "/v1/customers/{customer}" + targetSchema: + "$ref": "#/definitions/customer" + description: Permanently deletes a customer. It cannot be undone. Also immediately + cancels any active subscriptions on the customer. + - title: List all customers + method: GET + rel: self + href: "/v1/customers" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/customer" + url: + example: "/v1/customers" + type: + - string + description: Returns a list of your customers. The customers are returned sorted + by creation date, with the most recent customers appearing first. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + created: + example: {} + type: + - object + - integer + - title: Retrieve a customer + method: GET + rel: self + href: "/v1/customers/{customer}" + targetSchema: + "$ref": "#/definitions/customer" + description: Retrieves the details of an existing customer. You need only supply + the unique customer identifier that was returned upon customer creation. + properties: + account_balance: + "$ref": "#/definitions/customer/definitions/account_balance" + created: + "$ref": "#/definitions/customer/definitions/created" + currency: + "$ref": "#/definitions/customer/definitions/currency" + default_source: + "$ref": "#/definitions/customer/definitions/default_source" + delinquent: + "$ref": "#/definitions/customer/definitions/delinquent" + description: + "$ref": "#/definitions/customer/definitions/description" + discount: + "$ref": "#/definitions/customer/definitions/discount" + email: + "$ref": "#/definitions/customer/definitions/email" + id: + "$ref": "#/definitions/customer/definitions/id" + livemode: + "$ref": "#/definitions/customer/definitions/livemode" + metadata: + "$ref": "#/definitions/customer/definitions/metadata" + object: + "$ref": "#/definitions/customer/definitions/object" + shipping: + "$ref": "#/definitions/customer/definitions/shipping" + sources: + "$ref": "#/definitions/customer/definitions/sources" + subscriptions: + "$ref": "#/definitions/customer/definitions/subscriptions" + required: + - account_balance + - created + - id + - livemode + - metadata + - object + - sources + - subscriptions + title: Customer + type: + - object + discount: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + coupon: + description: Hash describing the coupon applied to create this discount. + example: + amount_off: + created: 1446774024 + currency: usd + duration: repeating + duration_in_months: 3 + id: 25OFF + livemode: false + max_redemptions: + metadata: {} + object: coupon + percent_off: 25 + redeem_by: + times_redeemed: 0 + valid: true + type: + - object + customer: + example: cus_7IV7zteF9TaFBj + type: + - string + end: + description: If the coupon has a duration of `once` or `repeating`, the date + that this discount will end. If the coupon used has a `forever` duration, + this attribute will be null. + example: 1454722824 + type: + - integer + object: + example: discount + type: + - string + start: + description: Date that the coupon was applied. + example: 1446774024 + type: + - integer + subscription: + description: The subscription that this coupon is applied to, if it is applied + to a particular subscription. + example: '' + type: + - string + links: + - title: Delete a customer discount + method: DELETE + rel: self + href: "/v1/customers/{customer}/subscriptions/{subscription_exposed_id}/discount" + targetSchema: + "$ref": "#/definitions/discount" + description: Removes the currently applied discount on a customer. + - title: Delete a customer discount + method: DELETE + rel: self + href: "/v1/customers/{customer}/discount" + targetSchema: + "$ref": "#/definitions/discount" + description: Removes the currently applied discount on a customer. + - title: RetrieveCustomerDiscountMethod + method: GET + rel: self + href: "/v1/customers/{customer}/subscriptions/{subscription_exposed_id}/discount" + targetSchema: + "$ref": "#/definitions/discount" + - title: RetrieveCustomerDiscountMethod + method: GET + rel: self + href: "/v1/customers/{customer}/discount" + targetSchema: + "$ref": "#/definitions/discount" + properties: + coupon: + "$ref": "#/definitions/discount/definitions/coupon" + customer: + "$ref": "#/definitions/discount/definitions/customer" + end: + "$ref": "#/definitions/discount/definitions/end" + object: + "$ref": "#/definitions/discount/definitions/object" + start: + "$ref": "#/definitions/discount/definitions/start" + subscription: + "$ref": "#/definitions/discount/definitions/subscription" + required: + - coupon + - object + - start + title: Discount + type: + - object + dispute: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + description: Disputed amount. Usually the amount of the charge, but can differ + (usually because of currency fluctuation or because only part of the order + is disputed). + example: 1000 + type: + - integer + balance_transactions: + description: List of zero, one, or two balance transactions that show funds + withdrawn and reinstated to your Stripe account as a result of this dispute. + example: [] + type: + - array + charge: + description: ID of the charge that was disputed + example: ch_173zDIIw57t4eNNvjJ1ECQp4 + type: + - string + created: + description: Date dispute was opened + example: 1446774024 + type: + - integer + currency: + description: Three-letter ISO currency code representing the currency of the + amount that was disputed. + example: usd + type: + - string + evidence: + description: Evidence provided to respond to a dispute. Updating any field + in the hash will submit all fields in the hash for review. + example: + access_activity_log: + billing_address: + cancellation_policy: + cancellation_policy_disclosure: + cancellation_rebuttal: + customer_communication: + customer_email_address: + customer_name: + customer_purchase_ip: + customer_signature: + duplicate_charge_documentation: + duplicate_charge_explanation: + duplicate_charge_id: + product_description: + receipt: + refund_policy: + refund_policy_disclosure: + refund_refusal_explanation: + service_date: + service_documentation: + shipping_address: + shipping_carrier: + shipping_date: + shipping_documentation: + shipping_tracking_number: + uncategorized_file: + uncategorized_text: + type: + - object + evidence_details: + description: Information about the evidence submission. + example: + due_by: 1448495999 + has_evidence: false + past_due: false + submission_count: 0 + type: + - object + id: + example: dp_173zDIIw57t4eNNv1HQDc9Ks + type: + - string + is_charge_refundable: + description: If true, it is still possible to refund the disputed payment. + Once the payment has been fully refunded, no further funds will be withdrawn + from your Stripe account as a result of this dispute. + example: false + type: + - boolean + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to a dispute object. + It can be useful for storing additional information about the dispute in + a structured format. + example: {} + type: + - object + object: + example: dispute + type: + - string + reason: + description: Reason given by cardholder for dispute. Possible values are + `duplicate`, `fraudulent`, `subscription_canceled`, `product_unacceptable`, + `product_not_received`, `unrecognized`, `credit_not_processed`, `incorrect_account_details`, + `insufficient_funds`, `bank_cannot_process`, `debit_not_authorized`, `general`. Read + more about [dispute reasons](https://stripe.com/help/disputes#reasons). + example: general + type: + - string + status: + description: Current status of dispute. Possible values are `warning_needs_response`, + `warning_under_review`, `warning_closed`, `needs_response`, `response_disabled`, + `under_review`, `charge_refunded`, `won`, `lost`. + example: needs_response + type: + - string + identity: + "$ref": "#/definitions/dispute/definitions/resource_id" + links: + - title: Close a dispute + method: POST + rel: self + href: "/v1/disputes/{dispute}/close" + targetSchema: + "$ref": "#/definitions/dispute" + description: |- + Closing the dispute for a charge indicates that you do not have any evidence to submit and are essentially ‘dismissing’ the dispute, acknowledging it as lost

+ +

The status of the dispute will change from under_review to lost. Closing a dispute is irreversible. + - title: CloseChargeDisputeMethod + method: POST + rel: self + href: "/v1/charges/{charge}/dispute/close" + targetSchema: + "$ref": "#/definitions/dispute" + - title: List all disputes + method: GET + rel: self + href: "/v1/disputes" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/dispute" + url: + example: "/v1/disputes" + type: + - string + description: Returns a list of your disputes. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + created: + example: {} + type: + - object + - integer + - title: Retrieve a dispute + method: GET + rel: self + href: "/v1/disputes/{dispute}" + targetSchema: + "$ref": "#/definitions/dispute" + description: Retrieves the dispute with the given ID. + - title: RetrieveChargeDisputeMethod + method: GET + rel: self + href: "/v1/charges/{charge}/dispute" + targetSchema: + "$ref": "#/definitions/dispute" + - title: Update a dispute + method: POST + rel: self + href: "/v1/disputes/{dispute}" + targetSchema: + "$ref": "#/definitions/dispute" + description: |- + When you get a dispute, contacting your customer is always the best first step. If that doesn’t work, you can submit evidence in order to help us resolve the dispute in your favor. You can do this in your dashboard, but if you prefer, you can use the API to submit evidence programmatically.

+ +

Depending on your dispute type, different evidence fields will give you a better chance of winning your dispute. You may want to consult our guide to dispute types to help you figure out which evidence fields to provide. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + evidence: + example: {} + type: + - object + description: Evidence to upload to respond to a dispute. Updating any + field in the hash will submit all fields in the hash for review. + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a dispute object. + It can be useful for storing additional information about the dispute in + a structured format. + - title: UpdateChargeDisputeMethod + method: POST + rel: self + href: "/v1/charges/{charge}/dispute" + targetSchema: + "$ref": "#/definitions/dispute" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + evidence: + example: {} + type: + - object + description: Evidence to upload to respond to a dispute. Updating any + field in the hash will submit all fields in the hash for review. + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a dispute object. + It can be useful for storing additional information about the dispute in + a structured format. + properties: + amount: + "$ref": "#/definitions/dispute/definitions/amount" + balance_transactions: + "$ref": "#/definitions/dispute/definitions/balance_transactions" + charge: + "$ref": "#/definitions/dispute/definitions/charge" + created: + "$ref": "#/definitions/dispute/definitions/created" + currency: + "$ref": "#/definitions/dispute/definitions/currency" + evidence: + "$ref": "#/definitions/dispute/definitions/evidence" + evidence_details: + "$ref": "#/definitions/dispute/definitions/evidence_details" + id: + "$ref": "#/definitions/dispute/definitions/id" + is_charge_refundable: + "$ref": "#/definitions/dispute/definitions/is_charge_refundable" + livemode: + "$ref": "#/definitions/dispute/definitions/livemode" + metadata: + "$ref": "#/definitions/dispute/definitions/metadata" + object: + "$ref": "#/definitions/dispute/definitions/object" + reason: + "$ref": "#/definitions/dispute/definitions/reason" + status: + "$ref": "#/definitions/dispute/definitions/status" + required: + - amount + - balance_transactions + - charge + - created + - currency + - evidence + - evidence_details + - id + - is_charge_refundable + - livemode + - metadata + - object + - reason + - status + title: Dispute + type: + - object + event: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + api_version: + description: 'The Stripe API version used to render `data`. *Note: this property + is populated for events on or after October 31, 2014.*' + example: '2015-10-16' + type: + - string + created: + example: 1446754408 + type: + - integer + data: + description: Hash containing data associated with the event. + example: + object: + account_balance: 0 + created: 1446754408 + currency: usd + default_source: + delinquent: false + description: + discount: + email: + id: cus_7IV7zteF9TaFBj + livemode: false + metadata: {} + object: customer + shipping: + sources: + data: [] + has_more: false + object: list + total_count: 0 + url: "/v1/customers/cus_7IV7zteF9TaFBj/sources" + subscriptions: + data: [] + has_more: false + object: list + total_count: 0 + url: "/v1/customers/cus_7IV7zteF9TaFBj/subscriptions" + type: + - object + id: + example: evt_173u6uIw57t4eNNvPU2kN0dc + type: + - string + livemode: + example: false + type: + - boolean + object: + example: event + type: + - string + pending_webhooks: + description: Number of webhooks yet to be delivered successfully (return a + 20x response) to the URLs you've specified. + example: 0 + type: + - integer + request: + description: 'ID of the API request that caused the event. If null, the event + was automatic (e.g. Stripe''sautomatic subscription handling). Request logs + are available in the [dashboard](https://dashboard.stripe.com/logs)but currently + not in the API. *Note: this property is populated for events on or after + April 23, 2013.*' + example: '' + type: + - string + type: + description: 'Description of the event: e.g. `invoice.created`, `charge.refunded`, + etc.' + example: customer.created + type: + - string + identity: + "$ref": "#/definitions/event/definitions/resource_id" + links: + - title: List all events + method: GET + rel: self + href: "/v1/events" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/event" + url: + example: "/v1/events" + type: + - string + description: List events, going back up to 30 days. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + type: + example: '' + type: + - string + description: A string containing a specific event name, or group of events + using * as a wildcard. The list will be filtered to include only events + with a matching event property + created: + example: {} + type: + - object + - integer + - title: Retrieve an event + method: GET + rel: self + href: "/v1/events/{%23%2Fdefinitions%2Fevent%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/event" + description: Retrieves the details of an event. Supply the unique identifier + of the event, which you might have received in a webhook. + - title: Retry an event + method: POST + rel: self + href: "/v1/events/{%23%2Fdefinitions%2Fevent%2Fdefinitions%2Fidentity}/retry" + targetSchema: + "$ref": "#/definitions/event" + description: Resend an event. This only works in testmode + properties: + api_version: + "$ref": "#/definitions/event/definitions/api_version" + created: + "$ref": "#/definitions/event/definitions/created" + data: + "$ref": "#/definitions/event/definitions/data" + id: + "$ref": "#/definitions/event/definitions/id" + livemode: + "$ref": "#/definitions/event/definitions/livemode" + object: + "$ref": "#/definitions/event/definitions/object" + pending_webhooks: + "$ref": "#/definitions/event/definitions/pending_webhooks" + request: + "$ref": "#/definitions/event/definitions/request" + type: + "$ref": "#/definitions/event/definitions/type" + required: + - created + - data + - id + - livemode + - object + - pending_webhooks + - type + title: Event + type: + - object + fee-refund: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + description: Amount, in %s. + example: 0 + type: + - integer + balance_transaction: + description: Balance transaction that describes the impact on your account + balance. + example: '' + type: + - string + created: + example: 0 + type: + - integer + currency: + description: Three-letter ISO code representing the currency. + example: '' + type: + - string + fee: + description: ID of the application fee that was refunded. + example: '' + type: + - string + id: + example: '' + type: + - string + metadata: + description: A set of key/value pairs that you can attach to the object. It + can be useful for storing additional information in a structured format. + example: {} + type: + - object + object: + example: '' + type: + - string + identity: + "$ref": "#/definitions/fee-refund/definitions/resource_id" + links: + - title: AllPlatformEarningsRefundsMethod + method: GET + rel: self + href: "/v1/application_fees/{%23%2Fdefinitions%2Ffee-refund%2Fdefinitions%2Fidentity}/refunds" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/fee-refund" + url: + example: "/v1/application_fees/{%23%2Fdefinitions%2Ffee-refund%2Fdefinitions%2Fidentity}/refunds" + type: + - string + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + - title: CreatePlatformEarningRefundMethod + method: POST + rel: self + href: "/v1/application_fees/{%23%2Fdefinitions%2Ffee-refund%2Fdefinitions%2Fidentity}/refunds" + targetSchema: + "$ref": "#/definitions/fee-refund" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + directive: + example: '' + type: + - string + amount: + example: 0 + type: + - integer + metadata: + example: {} + type: + - object + - title: RetrievePlatformEarningRefundMethod + method: GET + rel: self + href: "/v1/application_fees/{fee}/refunds/{%23%2Fdefinitions%2Ffee-refund%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/fee-refund" + - title: UpdatePlatformEarningRefundMethod + method: POST + rel: self + href: "/v1/application_fees/{fee}/refunds/{%23%2Fdefinitions%2Ffee-refund%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/fee-refund" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + metadata: + example: {} + type: + - object + properties: + amount: + "$ref": "#/definitions/fee-refund/definitions/amount" + balance_transaction: + "$ref": "#/definitions/fee-refund/definitions/balance_transaction" + created: + "$ref": "#/definitions/fee-refund/definitions/created" + currency: + "$ref": "#/definitions/fee-refund/definitions/currency" + fee: + "$ref": "#/definitions/fee-refund/definitions/fee" + id: + "$ref": "#/definitions/fee-refund/definitions/id" + metadata: + "$ref": "#/definitions/fee-refund/definitions/metadata" + object: + "$ref": "#/definitions/fee-refund/definitions/object" + required: + - amount + - created + - currency + - fee + - id + - metadata + - object + title: FeeRefund + type: + - object + invoice: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount_due: + description: Final amount due at this time for this invoice. If the invoice's + total is smaller than the minimum charge amount, for example, or if there + is account credit that can be applied to the invoice, the `amount_due` may + be 0. If there is a positive `starting_balance` for the invoice (the customer + owes money), the amount_due will also take that into account. The charge + that gets generated for the invoice will be for the amount specified in + `amount_due`. + example: 0 + type: + - integer + application_fee: + description: The fee in %s that will be applied to the invoice and transferred + to the application owner's Stripe account when the invoice is paid. + example: 0 + type: + - integer + attempt_count: + description: Number of payment attempts made for this invoice, from the perspective + of the payment retry schedule. Any payment attempt counts as the first + attempt, and subsequently only automatic retries increment the attempt count. In + other words, manual payment attempts after the first attempt do not affect + the retry schedule. + example: 0 + type: + - integer + attempted: + description: Whether or not an attempt has been made to pay the invoice. An + invoice is not attempted until 1 hour after the `invoice.created` webhook, + for example, so you might not want to display that invoice as unpaid to + your users. + example: false + type: + - boolean + charge: + description: ID of the latest charge generated for this invoice, if any. + example: '' + type: + - string + closed: + description: Whether or not the invoice is still trying to collect payment. + An invoice is closed if it's either paid or it has been marked closed. A + closed invoice will no longer attempt to collect payment. + example: false + type: + - boolean + currency: + example: usd + type: + - string + customer: + example: cus_7IV7zteF9TaFBj + type: + - string + date: + example: 1446774024 + type: + - integer + description: + example: '' + type: + - string + discount: + example: {} + type: + - object + ending_balance: + description: Ending customer balance after attempting to pay invoice. If + the invoice has not been attempted yet, this will be null. + example: 0 + type: + - integer + forgiven: + description: Whether or not the invoice has been forgiven. Forgiving an invoice + instructs us to update the subscription status as if the invoice were succcessfully + paid. Once an invoice has been forgiven, it cannot be unforgiven or reopened + example: false + type: + - boolean + id: + example: in_173zDIIw57t4eNNvL01nNwlJ + type: + - string + lines: + description: 'The individual line items that make up the invoice. `lines` + is sorted as follows: invoice items in reverse chronological order, followed + by the subscription, if any.' + example: + data: + - id: sub_7IaOY6OeGFY8vB + object: line_item + amount: 2000 + currency: usd + description: + discountable: true + livemode: true + metadata: {} + period: + start: 1449366024 + end: 1452044424 + plan: + id: gold + object: plan + amount: 2000 + created: 1446754408 + currency: usd + interval: month + interval_count: 1 + livemode: false + metadata: {} + name: Gold Special + statement_descriptor: + trial_period_days: + proration: false + quantity: 1 + subscription: + type: subscription + object: list + total_count: 1 + url: "/v1/invoices/in_173zDIIw57t4eNNvL01nNwlJ/lines" + type: + - object + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to an invoice object. + It can be useful for storing additional information about the invoice in + a structured format. + example: {} + type: + - object + next_payment_attempt: + description: The time at which payment will next be attempted. + example: 1446777624 + type: + - integer + object: + example: invoice + type: + - string + paid: + description: Whether or not payment was successfully collected for this invoice. An + invoice can be paid (most commonly) with a charge or with credit from the + customer's account balance. + example: false + type: + - boolean + period_end: + description: End of the usage period during which invoice items were added + to this invoice + example: 1446774024 + type: + - integer + period_start: + description: Start of the usage period during which invoice items were added + to this invoice + example: 1446774024 + type: + - integer + receipt_number: + description: This is the transaction number that appears on email receipts + sent for this invoice. + example: '' + type: + - string + starting_balance: + description: Starting customer balance before attempting to pay invoice. If + the invoice has not been attempted yet, this will be the current customer + balance. + example: 0 + type: + - integer + statement_descriptor: + description: Extra information about an invoice for the customer's credit + card statement. + example: '' + type: + - string + subscription: + description: The subscription that this invoice was prepared for, if any. + example: '' + type: + - string + subscription_proration_date: + description: Only set for upcoming invoices that preview prorations. The time + used to calculate prorations. + example: 0 + type: + - integer + subtotal: + description: Total of all subscriptions, invoice items, and prorations on + the invoice before any discount is applied + example: 0 + type: + - integer + tax: + description: The amount of tax included in the total, calculated from `tax_percent` + and the subtotal. If no `tax_percent` is defined, this value will be null. + example: 0 + type: + - integer + tax_percent: + description: This percentage of the subtotal has been added to the total amount + of the invoice, including invoice line items and discounts. This field is + inherited from the subscription's `tax_percent` field, but can be changed + before the invoice is paid. This field defaults to null. + example: 0.0 + type: + - number + total: + description: Total after discount + example: 0 + type: + - integer + webhooks_delivered_at: + description: The time at which webhooks for this invoice were successfully + delivered (if the invoice had no webhooks to deliver, this will match `date`). Invoice + payment is delayed until webhooks are delivered, or until all webhook delivery + attempts have been exhausted. + example: 0 + type: + - integer + identity: + "$ref": "#/definitions/invoice/definitions/resource_id" + links: + - title: Create an invoice + method: POST + rel: self + href: "/v1/invoices" + targetSchema: + "$ref": "#/definitions/invoice" + description: |- + If you need to invoice your customer outside the regular billing cycle, you can create an invoice that pulls in all pending invoice items, including prorations. The customer’s billing cycle and regular subscription won’t be affected.

+ +

Once you create the invoice, it’ll be picked up and paid automatically, though you can choose to pay it right away. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + customer: + example: '' + type: + - string + application_fee: + example: 0 + type: + - integer + description: A fee in %s that will be applied to the invoice and transferred + to the application owner's Stripe account. The request must be made + with an OAuth key or the Stripe-Account header in order to take an application + fee. For more information, see the application fees [documentation](/docs/connect/collecting-fees#subscriptions). + subscription: + example: '' + type: + - string + description: The ID of the subscription to invoice. If not set, the created + invoice will include all pending invoice items for the customer. If + set, the created invoice will exclude pending invoice items that pertain + to other subscriptions. + description: + example: '' + type: + - string + metadata: + example: {} + type: + - object + statement_descriptor: + example: '' + type: + - string + description: Extra information about a charge for the customer's credit + card statement. + tax_percent: + example: 0.0 + type: + - number + description: 'The percent tax rate applied to the invoice, represented + as a decimal number. ' + required: + - customer + - title: List all invoices + method: GET + rel: self + href: "/v1/invoices" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/invoice" + url: + example: "/v1/invoices" + type: + - string + description: You can list all invoices, or list the invoices for a specific + customer. The invoices are returned sorted by creation date, with the most + recently created invoices appearing first. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + customer: + example: '' + type: + - string + description: The identifier of the customer whose invoices to return. + If none is provided, all invoices will be returned. + date: + example: {} + type: + - object + - integer + - title: Pay an invoice + method: POST + rel: self + href: "/v1/invoices/{invoice}/pay" + targetSchema: + "$ref": "#/definitions/invoice" + description: Stripe automatically creates and then attempts to pay invoices + for customers on subscriptions. We’ll also retry unpaid invoices according + to your retry settings. + However, if you’d like to attempt to collect payment on an invoice out of + the normal retry schedule or for some other reason, you can do so. + - title: Retrieve an invoice + method: GET + rel: self + href: "/v1/invoices/{invoice}" + targetSchema: + "$ref": "#/definitions/invoice" + description: Retrieves the invoice with the given ID. + - title: Update an invoice + method: POST + rel: self + href: "/v1/invoices/{invoice}" + targetSchema: + "$ref": "#/definitions/invoice" + description: Until an invoice is paid, it is marked as open (closed=false). + If you’d like to stop Stripe from automatically attempting payment on an invoice + or would simply like to close the invoice out as no longer owed by the customer, + you can update the closed parameter. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + closed: + example: false + type: + - boolean + description: Boolean representing whether an invoice is closed or not. To + close an invoice, pass true. + forgiven: + example: false + type: + - boolean + description: Boolean representing whether an invoice is forgiven or not. To + forgive an invoice, pass true. Forgiving an invoice instructs us to + update the subscription status as if the invoice were succcessfully + paid. Once an invoice has been forgiven, it cannot be unforgiven or + reopened. + application_fee: + example: 0 + type: + - integer + description: A fee in %s that will be applied to the invoice and transferred + to the application owner's Stripe account. The request must be made + with an OAuth key or the Stripe-Account header in order to take an application + fee. For more information, see the application fees [documentation](/docs/connect/collecting-fees#subscriptions). + metadata: + example: {} + type: + - object + description: + example: '' + type: + - string + statement_descriptor: + example: '' + type: + - string + description: Extra information about a charge for the customer's credit + card statement. + tax_percent: + example: 0.0 + type: + - number + description: The percent tax rate applied to the invoice, represented + as a decimal number. The tax rate of a paid or forgiven invoice cannot + be changed. + properties: + amount_due: + "$ref": "#/definitions/invoice/definitions/amount_due" + application_fee: + "$ref": "#/definitions/invoice/definitions/application_fee" + attempt_count: + "$ref": "#/definitions/invoice/definitions/attempt_count" + attempted: + "$ref": "#/definitions/invoice/definitions/attempted" + charge: + "$ref": "#/definitions/invoice/definitions/charge" + closed: + "$ref": "#/definitions/invoice/definitions/closed" + currency: + "$ref": "#/definitions/invoice/definitions/currency" + customer: + "$ref": "#/definitions/invoice/definitions/customer" + date: + "$ref": "#/definitions/invoice/definitions/date" + description: + "$ref": "#/definitions/invoice/definitions/description" + discount: + "$ref": "#/definitions/invoice/definitions/discount" + ending_balance: + "$ref": "#/definitions/invoice/definitions/ending_balance" + forgiven: + "$ref": "#/definitions/invoice/definitions/forgiven" + id: + "$ref": "#/definitions/invoice/definitions/id" + lines: + "$ref": "#/definitions/invoice/definitions/lines" + livemode: + "$ref": "#/definitions/invoice/definitions/livemode" + metadata: + "$ref": "#/definitions/invoice/definitions/metadata" + next_payment_attempt: + "$ref": "#/definitions/invoice/definitions/next_payment_attempt" + object: + "$ref": "#/definitions/invoice/definitions/object" + paid: + "$ref": "#/definitions/invoice/definitions/paid" + period_end: + "$ref": "#/definitions/invoice/definitions/period_end" + period_start: + "$ref": "#/definitions/invoice/definitions/period_start" + receipt_number: + "$ref": "#/definitions/invoice/definitions/receipt_number" + starting_balance: + "$ref": "#/definitions/invoice/definitions/starting_balance" + statement_descriptor: + "$ref": "#/definitions/invoice/definitions/statement_descriptor" + subscription: + "$ref": "#/definitions/invoice/definitions/subscription" + subscription_proration_date: + "$ref": "#/definitions/invoice/definitions/subscription_proration_date" + subtotal: + "$ref": "#/definitions/invoice/definitions/subtotal" + tax: + "$ref": "#/definitions/invoice/definitions/tax" + tax_percent: + "$ref": "#/definitions/invoice/definitions/tax_percent" + total: + "$ref": "#/definitions/invoice/definitions/total" + webhooks_delivered_at: + "$ref": "#/definitions/invoice/definitions/webhooks_delivered_at" + required: + - amount_due + - attempt_count + - attempted + - closed + - currency + - customer + - date + - forgiven + - id + - lines + - livemode + - object + - paid + - period_end + - period_start + - starting_balance + - subtotal + - total + title: Invoice + type: + - object + invoice-item: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + example: 0 + type: + - integer + currency: + example: '' + type: + - string + customer: + example: '' + type: + - string + date: + example: 0 + type: + - integer + description: + example: '' + type: + - string + discountable: + description: If true, discounts will apply to this invoice item. Always false + for prorations. + example: false + type: + - boolean + id: + example: '' + type: + - string + invoice: + example: '' + type: + - string + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to an invoice item object. + It can be useful for storing additional information about the invoice item in + a structured format. + example: {} + type: + - object + object: + example: '' + type: + - string + period: + example: {} + type: + - object + plan: + description: If the invoice item is a proration, the plan of the subscription + that the proration was computed for. + example: {} + type: + - object + proration: + description: Whether or not the invoice item was created automatically as + a proration adjustment when the customer switched plans + example: false + type: + - boolean + quantity: + description: If the invoice item is a proration, the quantity of the subscription + that the proration was computed for. + example: 0 + type: + - integer + subscription: + description: The subscription that this invoice item has been created for, + if any. + example: '' + type: + - string + identity: + "$ref": "#/definitions/invoice-item/definitions/resource_id" + links: + - title: Create an invoice item + method: POST + rel: self + href: "/v1/invoiceitems" + targetSchema: + "$ref": "#/definitions/invoice-item" + description: Adds an arbitrary charge or credit to the customer’s upcoming invoice. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + customer: + example: '' + type: + - string + description: The ID of the customer who will be billed when this invoice + item is billed. + amount: + example: 0 + type: + - integer + description: The integer amount in cents of the charge to be applied to + the upcoming invoice. If you want to apply a credit to the customer's + account, pass a negative amount. + currency: + example: '' + type: + - string + description: 3-letter [ISO code for currency](https://support.stripe.com/questions/which-currencies-does-stripe-support). + description: + example: '' + type: + - string + description: An arbitrary string which you can attach to the invoice item. + The description is displayed in the invoice for easy tracking. + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to an invoice + item object. It can be useful for storing additional information about + the invoice item in a structured format. + invoice: + example: '' + type: + - string + description: The ID of an existing invoice to add this invoice item to. + When left blank, the invoice item will be added to the next upcoming + scheduled invoice. Use this when adding invoice items in response to + an invoice.created webhook. You cannot add an invoice item to an invoice + that has already been paid, attempted or closed. + subscription: + example: '' + type: + - string + description: The ID of a subscription to add this invoice item to. When + left blank, the invoice item will be be added to the next upcoming scheduled + invoice. When set, scheduled invoices for subscriptions other than the + specified subscription will ignore the invoice item. Use this when you + want to express that an invoice item has been accrued within the context + of a particular subscription. + discountable: + example: false + type: + - boolean + description: Controls whether discounts apply to this invoice item. Defaults + to false for prorations or negative invoice items, and true for all + other invoice items. + required: + - customer + - amount + - currency + - title: Delete an invoice item + method: DELETE + rel: self + href: "/v1/invoiceitems/{invoiceitem}" + targetSchema: + "$ref": "#/definitions/invoice-item" + description: Removes an invoice item from the upcoming invoice. Removing an + invoice item is only possible before the invoice it’s attached to is closed. + - title: List all invoice items + method: GET + rel: self + href: "/v1/invoiceitems" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/invoice-item" + url: + example: "/v1/invoiceitems" + type: + - string + description: Returns a list of your invoice items. Invoice items are returned + sorted by creation date, with the most recently created invoice items appearing + first. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + customer: + example: '' + type: + - string + description: The identifier of the customer whose invoice items to return. + If none is provided, all invoice items will be returned. + created: + example: {} + type: + - object + - integer + - title: Retrieve an invoice item + method: GET + rel: self + href: "/v1/invoiceitems/{invoiceitem}" + targetSchema: + "$ref": "#/definitions/invoice-item" + description: Retrieves the invoice item with the given ID. + - title: Update an invoice item + method: POST + rel: self + href: "/v1/invoiceitems/{invoiceitem}" + targetSchema: + "$ref": "#/definitions/invoice-item" + description: Updates the amount or description of an invoice item on an upcoming + invoice. Updating an invoice item is only possible before the invoice it’s + attached to is closed. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + amount: + example: 0 + type: + - integer + description: + example: '' + type: + - string + metadata: + example: {} + type: + - object + currency: + example: '' + type: + - string + discountable: + example: false + type: + - boolean + properties: + amount: + "$ref": "#/definitions/invoice-item/definitions/amount" + currency: + "$ref": "#/definitions/invoice-item/definitions/currency" + customer: + "$ref": "#/definitions/invoice-item/definitions/customer" + date: + "$ref": "#/definitions/invoice-item/definitions/date" + description: + "$ref": "#/definitions/invoice-item/definitions/description" + discountable: + "$ref": "#/definitions/invoice-item/definitions/discountable" + id: + "$ref": "#/definitions/invoice-item/definitions/id" + invoice: + "$ref": "#/definitions/invoice-item/definitions/invoice" + livemode: + "$ref": "#/definitions/invoice-item/definitions/livemode" + metadata: + "$ref": "#/definitions/invoice-item/definitions/metadata" + object: + "$ref": "#/definitions/invoice-item/definitions/object" + period: + "$ref": "#/definitions/invoice-item/definitions/period" + plan: + "$ref": "#/definitions/invoice-item/definitions/plan" + proration: + "$ref": "#/definitions/invoice-item/definitions/proration" + quantity: + "$ref": "#/definitions/invoice-item/definitions/quantity" + subscription: + "$ref": "#/definitions/invoice-item/definitions/subscription" + required: + - amount + - currency + - customer + - date + - discountable + - id + - livemode + - metadata + - object + - proration + title: InvoiceItem + type: + - object + invoice-line-item: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + description: The amount, in %s + example: 0 + type: + - integer + currency: + example: '' + type: + - string + description: + description: A text description of the line item, if the line item is an invoice + item + example: '' + type: + - string + discountable: + description: If true, discounts will apply to this line item. Always false + for prorations. + example: false + type: + - boolean + id: + description: The ID of the source of this line item, either an invoice item + or a subscription + example: '' + type: + - string + livemode: + description: Whether or not this is a test line item + example: false + type: + - boolean + metadata: + description: Key-value pairs attached to the line item, if the line item is + an invoice item + example: {} + type: + - object + object: + description: line_item + example: '' + type: + - string + period: + description: The period this line_item covers. For subscription line items, + this is the subscription period. For prorations, this starts when the proration + was calculated, and ends at the period end of the subscription. For invoice + items, this is the time at which the invoice item was created, so the period + start and end are the same time. + example: {} + type: + - object + plan: + description: The plan of the subscription, if the line item is a subscription + or a proration + example: {} + type: + - object + proration: + description: Whether or not this is a proration + example: false + type: + - boolean + quantity: + description: The quantity of the subscription, if the line item is a subscription + or a proration + example: 0 + type: + - integer + subscription: + description: When type is `invoiceitem`, the subscription that the invoice + item pertains to, if any. Left blank when `type` is already subscription, + as it'd be redundant with `id`. + example: '' + type: + - string + type: + description: A string identifying the type of the source of this line item, + either an `invoiceitem` or a `subscription` + example: '' + type: + - string + identity: + "$ref": "#/definitions/invoice-line-item/definitions/resource_id" + links: + - title: Retrieve an invoice's line items + method: GET + rel: self + href: "/v1/invoices/{invoice}/lines" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/invoice-line-item" + url: + example: "/v1/invoices/{invoice}/lines" + type: + - string + description: When retrieving an invoice, you’ll get a lines property containing + the total count of line items and the first handful of those items. There + is also a URL where you can retrieve the full (paginated) list of line items. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: The maximum number of line items to return + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + customer: + example: '' + type: + - string + description: In the case of upcoming invoices, the customer of the upcoming + invoice is required. In other cases it is ignored. + subscription: + example: '' + type: + - string + description: In the case of upcoming invoices, the subscription of the + upcoming invoice is optional. In other cases it is ignored. + subscription_plan: + example: '' + type: + - string + subscription_quantity: + example: 0 + type: + - integer + subscription_prorate: + example: false + type: + - boolean + subscription_proration_date: + example: 0 + type: + - integer + subscription_trial_end: + example: 0 + type: + - integer + properties: + amount: + "$ref": "#/definitions/invoice-line-item/definitions/amount" + currency: + "$ref": "#/definitions/invoice-line-item/definitions/currency" + description: + "$ref": "#/definitions/invoice-line-item/definitions/description" + discountable: + "$ref": "#/definitions/invoice-line-item/definitions/discountable" + id: + "$ref": "#/definitions/invoice-line-item/definitions/id" + livemode: + "$ref": "#/definitions/invoice-line-item/definitions/livemode" + metadata: + "$ref": "#/definitions/invoice-line-item/definitions/metadata" + object: + "$ref": "#/definitions/invoice-line-item/definitions/object" + period: + "$ref": "#/definitions/invoice-line-item/definitions/period" + plan: + "$ref": "#/definitions/invoice-line-item/definitions/plan" + proration: + "$ref": "#/definitions/invoice-line-item/definitions/proration" + quantity: + "$ref": "#/definitions/invoice-line-item/definitions/quantity" + subscription: + "$ref": "#/definitions/invoice-line-item/definitions/subscription" + type: + "$ref": "#/definitions/invoice-line-item/definitions/type" + required: + - amount + - currency + - discountable + - id + - livemode + - metadata + - object + - period + - proration + - type + title: InvoiceLineItem + type: + - object + order: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + description: A positive integer in the smallest currency unit (that is, 100 + cents for $1.00, or 1 for ¥1, Japanese Yen being a 0-decimal currency) representing + the total amount for the order. + example: 1500 + type: + - integer + application: + description: ID of the Connect Application that created the order. + example: '' + type: + - string + application_fee: + example: 0 + type: + - integer + charge: + description: The ID of the payment used to pay for the order. Present if the + order status is `paid`, `fulfilled`, or `refunded`. + example: '' + type: + - string + created: + example: 1446774024 + type: + - integer + currency: + description: 3-letter [ISO code](https://support.stripe.com/questions/which-currencies-does-stripe-support) + representing the currency in which the order was made. + example: usd + type: + - string + customer: + description: The customer used for the order. + example: '' + type: + - string + email: + description: The email address of the customer placing the order. + example: '' + type: + - string + id: + example: or_173zDIIw57t4eNNvTmLeal08 + type: + - string + items: + description: List of items constituting the order. + example: + - object: order_item + amount: 1500 + currency: usd + description: T-shirt + parent: sk_173u6uIw57t4eNNv9V6k1Hb4 + quantity: + type: sku + type: + - array + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to an order object. + It can be useful for storing additional information about the order in a + structured format. + example: {} + type: + - object + object: + example: order + type: + - string + selected_shipping_method: + description: The shipping method that is currencly selected for this order, + if any. If present, it is equal to one of the `id`s of shipping methods + in the `shipping_methods` array. At order creation time, if there are multiple + shipping methods, Stripe will automatically selected the first method. + example: '' + type: + - string + shipping: + description: The shipping address for the order. Present if the order is for + goods to be shipped. + example: + address: + city: Anytown + country: US + line1: 1234 Main street + line2: + postal_code: '123456' + state: + name: Jenny Rosen + phone: + type: + - object + shipping_methods: + description: A list of supported shipping methods for this order. The desired + shipping method can be specified either by updating the order, or when paying + it. + example: [] + type: + - array + status: + description: Current order status. One of `created`, `paid`, `canceled`, `fulfilled`, + or `returned`. More detail in the [Relay API Overview](/docs/relay#understanding-order-statuses). + example: created + type: + - string + updated: + example: 1446774024 + type: + - integer + identity: + "$ref": "#/definitions/order/definitions/resource_id" + links: + - title: CreateOrderMethod + method: POST + rel: self + href: "/v1/orders" + targetSchema: + "$ref": "#/definitions/order" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + items: + example: {} + type: + - object + - array + - string + description: List of items constituting the order. + customer: + example: '' + type: + - string + description: The ID of an existing customer to use for this order. If + provided, the customer email and shipping address will be used to create + the order. Subsequently, the customer will also be charged to pay the + order. If `email` or `shipping` are also provided, they will override + the values retrieved from the customer object. + shipping: + example: {} + type: + - object + description: Shipping address for the order. Required if any of the SKUs + are for products that have `shippable` set to true. + email: + example: '' + type: + - string + description: The email address of the customer placing the order. + currency: + example: '' + type: + - string + description: 3-letter [ISO code](https://support.stripe.com/questions/which-currencies-does-stripe-support) + representing the currency in which the order should be made. Stripe + will convert the prices of the items associated with the order to this + currency. + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to an order + object. It can be useful for storing additional information about the + order in a structured format. + required: + - currency + - title: List all orders + method: GET + rel: self + href: "/v1/orders" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/order" + url: + example: "/v1/orders" + type: + - string + description: Returns a list of your orders. The orders are returned sorted by + creation date, with the most recently created orders appearing first. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + status: + example: '' + type: + - string + description: Only return orders that have the given status. One of `created`, + `paid`, `fulfilled`, or `refunded`. + ids: + example: [] + type: + - array + description: Only return orders with the given IDs + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + - title: PayOrderMethod + method: POST + rel: self + href: "/v1/orders/{%23%2Fdefinitions%2Forder%2Fdefinitions%2Fidentity}/pay" + targetSchema: + "$ref": "#/definitions/order" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + source: + example: {} + type: + - object + - string + description: The source can either be a token, like the ones returned + by our [Stripe.js](/docs/stripe.js), or a dictionary containing a user's + credit card details (with the options shown below). Whenever you create + a new card for a customer, Stripe will automatically validate the card. + If no customer was attached to the order at creation, either `source` + or `customer is required. Otherwise, the specified source will be charged + intead of the customer attached to the order. + customer: + example: '' + type: + - string + description: The ID of an existing customer that will be charged for this + order. If no customer was attached to the order at creation, either + `source` or `customer` is required. Otherwise, the specified customer + will be charged instead of the one attached to the order. + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to an order + object. It can be useful for storing additional information about the + order in a structured format. + email: + example: '' + type: + - string + description: The email address of the customer placing the order. Required + if not previously specified for the order. + shipping_method: + example: '' + type: + - string + application_fee: + example: 0 + type: + - integer + - title: Retrieve an order + method: GET + rel: self + href: "/v1/orders/{%23%2Fdefinitions%2Forder%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/order" + description: Retrieves the details of an existing order. Supply the unique order + ID from either an order creation request or the order list, and Stripe will + return the corresponding order information. + - title: UpdateOrderMethod + method: POST + rel: self + href: "/v1/orders/{%23%2Fdefinitions%2Forder%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/order" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + status: + example: '' + type: + - string + description: Current order status. One of `created`, `paid`, `canceled`, + `fulfilled`, or `returned`. More detail in the [Relay API Overview](/docs/relay#understanding-order-statuses). + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a product + object. It can be useful for storing additional information about the + order in a structured format. + coupon: + example: '' + type: + - string + description: A coupon code that represents a discount to be applied to + this order. Must be one-time duration and in same currency as the order. + selected_shipping_method: + example: '' + type: + - string + description: The shipping method to select for fulfilling this order. If + specified, must be one of the `id`s of a shipping method in the `shipping_methods` + array. If specified, will overwrite the existing selected shipping + method, updating `items` as necessary. + properties: + amount: + "$ref": "#/definitions/order/definitions/amount" + application: + "$ref": "#/definitions/order/definitions/application" + application_fee: + "$ref": "#/definitions/order/definitions/application_fee" + charge: + "$ref": "#/definitions/order/definitions/charge" + created: + "$ref": "#/definitions/order/definitions/created" + currency: + "$ref": "#/definitions/order/definitions/currency" + customer: + "$ref": "#/definitions/order/definitions/customer" + email: + "$ref": "#/definitions/order/definitions/email" + id: + "$ref": "#/definitions/order/definitions/id" + items: + "$ref": "#/definitions/order/definitions/items" + livemode: + "$ref": "#/definitions/order/definitions/livemode" + metadata: + "$ref": "#/definitions/order/definitions/metadata" + object: + "$ref": "#/definitions/order/definitions/object" + selected_shipping_method: + "$ref": "#/definitions/order/definitions/selected_shipping_method" + shipping: + "$ref": "#/definitions/order/definitions/shipping" + shipping_methods: + "$ref": "#/definitions/order/definitions/shipping_methods" + status: + "$ref": "#/definitions/order/definitions/status" + updated: + "$ref": "#/definitions/order/definitions/updated" + required: + - amount + - created + - currency + - id + - items + - livemode + - metadata + - object + - status + title: Order + type: + - object + payment-bank-account: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + bank_name: + description: Name of the bank associated with the routing number, e.g. `WELLS + FARGO`. + example: '' + type: + - string + country: + description: Two-letter ISO code representing the country the bank account + is located in. + example: '' + type: + - string + currency: + description: Three-letter ISO currency code representing the currency paid + out to the bank account. + example: '' + type: + - string + customer: + example: '' + type: + - string + fingerprint: + description: Uniquely identifies this particular bank account. You can use + this attribute to check whether two bank accounts are the same. + example: '' + type: + - string + id: + example: '' + type: + - string + last4: + example: '' + type: + - string + metadata: + example: {} + type: + - object + object: + example: '' + type: + - string + routing_number: + description: The routing transit number for the bank account. + example: '' + type: + - string + status: + description: Possible values are `new`, `validated`, `verified`, or `errored`. A + bank account that hasn't had any activity or validation performed is `new`. If + Stripe can determine that the bank account exists, its status will be `validated`. + Note that there often isn’t enough information to know (e.g. for smaller + credit unions), and the validation is not always run. If a transfer + sent to this bank account fails, we'll set the status to `errored` and will + not continue to send transfers until the bank details are updated. + example: '' + type: + - string + identity: + "$ref": "#/definitions/payment-bank-account/definitions/resource_id" + links: + - title: AllCustomerBankAccountsMethod + method: GET + rel: self + href: "/v1/customers/{customer}/bank_accounts" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/payment-bank-account" + url: + example: "/v1/customers/{customer}/bank_accounts" + type: + - string + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + - title: RetrieveCustomerBankAccountMethod + method: GET + rel: self + href: "/v1/customers/{customer}/bank_accounts/{%23%2Fdefinitions%2Fpayment-bank-account%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/payment-bank-account" + - title: VerifyCustomerSourceMethod + method: POST + rel: self + href: "/v1/customers/{customer}/sources/{%23%2Fdefinitions%2Fpayment-bank-account%2Fdefinitions%2Fidentity}/verify" + targetSchema: + "$ref": "#/definitions/payment-bank-account" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + verification_method: + example: '' + type: + - string + amounts: + example: [] + type: + - array + - title: VerifyCustomerSourceMethod + method: POST + rel: self + href: "/v1/customers/{customer}/bank_accounts/{%23%2Fdefinitions%2Fpayment-bank-account%2Fdefinitions%2Fidentity}/verify" + targetSchema: + "$ref": "#/definitions/payment-bank-account" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + verification_method: + example: '' + type: + - string + amounts: + example: [] + type: + - array + properties: + bank_name: + "$ref": "#/definitions/payment-bank-account/definitions/bank_name" + country: + "$ref": "#/definitions/payment-bank-account/definitions/country" + currency: + "$ref": "#/definitions/payment-bank-account/definitions/currency" + customer: + "$ref": "#/definitions/payment-bank-account/definitions/customer" + fingerprint: + "$ref": "#/definitions/payment-bank-account/definitions/fingerprint" + id: + "$ref": "#/definitions/payment-bank-account/definitions/id" + last4: + "$ref": "#/definitions/payment-bank-account/definitions/last4" + metadata: + "$ref": "#/definitions/payment-bank-account/definitions/metadata" + object: + "$ref": "#/definitions/payment-bank-account/definitions/object" + routing_number: + "$ref": "#/definitions/payment-bank-account/definitions/routing_number" + status: + "$ref": "#/definitions/payment-bank-account/definitions/status" + required: + - country + - currency + - id + - last4 + - metadata + - object + - status + title: PaymentBankAccount + type: + - object + payment-card: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + address_city: + example: '' + type: + - string + address_country: + description: Billing address country, if provided when creating card + example: '' + type: + - string + address_line1: + example: '' + type: + - string + address_line1_check: + description: 'If `address_line1` was provided, results of the check: `pass`, + `fail`, `unavailable`, or `unchecked`.' + example: '' + type: + - string + address_line2: + example: '' + type: + - string + address_state: + example: '' + type: + - string + address_zip: + example: '' + type: + - string + address_zip_check: + description: 'If `address_zip` was provided, results of the check: `pass`, + `fail`, `unavailable`, or `unchecked`.' + example: '' + type: + - string + brand: + description: Card brand. Can be `Visa`, `American Express`, `MasterCard`, + `Discover`, `JCB`, `Diners Club`, or `Unknown`. + example: '' + type: + - string + country: + description: Two-letter ISO code representing the country of the card. You + could use this attribute to get a sense of the international breakdown of + cards you've collected. + example: '' + type: + - string + customer: + example: '' + type: + - string + cvc_check: + description: 'If a CVC was provided, results of the check: `pass`, `fail`, + `unavailable`, or `unchecked`' + example: '' + type: + - string + dynamic_last4: + description: "(For tokenized numbers only.) The last four digits of the device + account number." + example: '' + type: + - string + exp_month: + example: 0 + type: + - integer + exp_year: + example: 0 + type: + - integer + fingerprint: + description: Uniquely identifies this particular card number. You can use + this attribute to check whether two customers who've signed up with you + are using the same card number, for example. + example: '' + type: + - string + funding: + description: Card funding type. Can be `credit`, `debit`, `prepaid`, or `unknown` + example: '' + type: + - string + id: + description: ID of card (used in conjunction with a customer or recipient + ID) + example: '' + type: + - string + last4: + example: '' + type: + - string + metadata: + description: A set of key/value pairs that you can attach to a card object. + It can be useful for storing additional information about the card in a + structured format. + example: {} + type: + - object + name: + description: Cardholder name + example: '' + type: + - string + object: + example: '' + type: + - string + tokenization_method: + description: If the card number is tokenized, this is the method that was + used. Can be `apple_pay` or `android_pay`. + example: '' + type: + - string + identity: + "$ref": "#/definitions/payment-card/definitions/resource_id" + links: + - title: AllCustomerCardsMethod + method: GET + rel: self + href: "/v1/customers/{customer}/cards" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/payment-card" + url: + example: "/v1/customers/{customer}/cards" + type: + - string + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + - title: RetrieveCustomerCardMethod + method: GET + rel: self + href: "/v1/customers/{customer}/cards/{%23%2Fdefinitions%2Fpayment-card%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/payment-card" + - title: UpdateCustomerCardMethod + method: POST + rel: self + href: "/v1/customers/{customer}/sources/{%23%2Fdefinitions%2Fpayment-card%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/payment-card" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + exp_year: + example: '' + type: + - string + exp_month: + example: '' + type: + - string + name: + example: '' + type: + - string + address_line1: + example: '' + type: + - string + address_line2: + example: '' + type: + - string + address_city: + example: '' + type: + - string + address_zip: + example: '' + type: + - string + address_state: + example: '' + type: + - string + address_country: + example: '' + type: + - string + metadata: + example: {} + type: + - object + - title: UpdateCustomerCardMethod + method: POST + rel: self + href: "/v1/customers/{customer}/cards/{%23%2Fdefinitions%2Fpayment-card%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/payment-card" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + exp_year: + example: '' + type: + - string + exp_month: + example: '' + type: + - string + name: + example: '' + type: + - string + address_line1: + example: '' + type: + - string + address_line2: + example: '' + type: + - string + address_city: + example: '' + type: + - string + address_zip: + example: '' + type: + - string + address_state: + example: '' + type: + - string + address_country: + example: '' + type: + - string + metadata: + example: {} + type: + - object + - title: UpdateCustomerCardMethod + method: POST + rel: self + href: "/v1/customers/{customer}/bank_accounts/{%23%2Fdefinitions%2Fpayment-card%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/payment-card" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + exp_year: + example: '' + type: + - string + exp_month: + example: '' + type: + - string + name: + example: '' + type: + - string + address_line1: + example: '' + type: + - string + address_line2: + example: '' + type: + - string + address_city: + example: '' + type: + - string + address_zip: + example: '' + type: + - string + address_state: + example: '' + type: + - string + address_country: + example: '' + type: + - string + metadata: + example: {} + type: + - object + properties: + address_city: + "$ref": "#/definitions/payment-card/definitions/address_city" + address_country: + "$ref": "#/definitions/payment-card/definitions/address_country" + address_line1: + "$ref": "#/definitions/payment-card/definitions/address_line1" + address_line1_check: + "$ref": "#/definitions/payment-card/definitions/address_line1_check" + address_line2: + "$ref": "#/definitions/payment-card/definitions/address_line2" + address_state: + "$ref": "#/definitions/payment-card/definitions/address_state" + address_zip: + "$ref": "#/definitions/payment-card/definitions/address_zip" + address_zip_check: + "$ref": "#/definitions/payment-card/definitions/address_zip_check" + brand: + "$ref": "#/definitions/payment-card/definitions/brand" + country: + "$ref": "#/definitions/payment-card/definitions/country" + customer: + "$ref": "#/definitions/payment-card/definitions/customer" + cvc_check: + "$ref": "#/definitions/payment-card/definitions/cvc_check" + dynamic_last4: + "$ref": "#/definitions/payment-card/definitions/dynamic_last4" + exp_month: + "$ref": "#/definitions/payment-card/definitions/exp_month" + exp_year: + "$ref": "#/definitions/payment-card/definitions/exp_year" + fingerprint: + "$ref": "#/definitions/payment-card/definitions/fingerprint" + funding: + "$ref": "#/definitions/payment-card/definitions/funding" + id: + "$ref": "#/definitions/payment-card/definitions/id" + last4: + "$ref": "#/definitions/payment-card/definitions/last4" + metadata: + "$ref": "#/definitions/payment-card/definitions/metadata" + name: + "$ref": "#/definitions/payment-card/definitions/name" + object: + "$ref": "#/definitions/payment-card/definitions/object" + tokenization_method: + "$ref": "#/definitions/payment-card/definitions/tokenization_method" + required: + - brand + - exp_month + - exp_year + - funding + - id + - last4 + - metadata + - object + title: PaymentCard + type: + - object + plan: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + description: The amount in %s to be charged on the interval specified + example: 2000 + type: + - integer + created: + example: 1446754408 + type: + - integer + currency: + description: Currency in which subscription will be charged + example: usd + type: + - string + id: + example: gold + type: + - string + interval: + description: One of `day`, `week`, `month` or `year`. The frequency with which + a subscription should be billed. + example: month + type: + - string + interval_count: + description: The number of intervals (specified in the `interval` property) + between each subscription billing. For example, `interval=month` and `interval_count=3` + bills every 3 months. + example: 1 + type: + - integer + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to a plan object. + It can be useful for storing additional information about the plan in a + structured format. + example: {} + type: + - object + name: + description: Display name of the plan + example: Gold Special + type: + - string + object: + example: plan + type: + - string + statement_descriptor: + description: Extra information about a charge for the customer's credit card + statement. + example: '' + type: + - string + trial_period_days: + description: Number of trial period days granted when subscribing a customer + to this plan. Null if the plan has no trial period. + example: 0 + type: + - integer + identity: + "$ref": "#/definitions/plan/definitions/resource_id" + links: + - title: Create a plan + method: POST + rel: self + href: "/v1/plans" + targetSchema: + "$ref": "#/definitions/plan" + description: You can create plans easily via the plan + management page of the Stripe dashboard. Plan creation is also accessible + via the API if you need to create plans on the fly. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + id: + example: '' + type: + - string + description: Unique string of your choice that will be used to identify + this plan when subscribing a customer. This could be an identifier like + "gold" or a primary key from your own database. + amount: + example: 0 + type: + - integer + description: A positive integer in **%s** (or 0 for a free plan) representing + how much to charge (on a recurring basis). + currency: + example: '' + type: + - string + description: 3-letter [ISO code for currency](https://support.stripe.com/questions/which-currencies-does-stripe-support). + name: + example: '' + type: + - string + description: Name of the plan, to be displayed on invoices and in the + web interface. + interval: + example: '' + type: + - string + description: Specifies billing frequency. Either day, week, month or year. + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a plan object. + It can be useful for storing additional information about the plan in + a structured format. + interval_count: + example: 0 + type: + - integer + description: The number of intervals between each subscription billing. + For example, `interval=month` and `interval_count=3` bills every 3 months. + Maximum of one year interval allowed (1 year, 12 months, or 52 weeks). + trial_period_days: + example: 0 + type: + - integer + description: Specifies a trial period in (an integer number of) days. + If you include a trial period, the customer won't be billed for the + first time until the trial period ends. If the customer cancels before + the trial period is over, she'll never be billed at all. + statement_descriptor: + example: '' + type: + - string + description: An arbitrary string to be displayed on your customer's credit + card statement. This may be up to **22 characters**. As an example, + if your website is `RunClub` and the item you're charging for is your + Silver Plan, you may want to specify a `statement_descriptor` of `RunClub + Silver Plan`. The statement description may not include `<>"'` characters, + and will appear on your customer's statement in capital letters. Non-ASCII + characters are automatically stripped. While most banks display this + information consistently, some may display it incorrectly or not at + all. + required: + - id + - amount + - currency + - name + - interval + - title: Delete a plan + method: DELETE + rel: self + href: "/v1/plans/{plan}" + targetSchema: + "$ref": "#/definitions/plan" + description: You can delete plans via the plan + management page of the Stripe dashboard. However, deleting a plan does + not affect any current subscribers to the plan; it merely means that new subscribers + can’t be added to that plan. You can also delete plans via the API. + - title: List all plans + method: GET + rel: self + href: "/v1/plans" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/plan" + url: + example: "/v1/plans" + type: + - string + description: Returns a list of your plans. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + created: + example: {} + type: + - object + - integer + - title: Retrieve a plan + method: GET + rel: self + href: "/v1/plans/{plan}" + targetSchema: + "$ref": "#/definitions/plan" + description: Retrieves the plan with the given ID. + - title: Update a plan + method: POST + rel: self + href: "/v1/plans/{plan}" + targetSchema: + "$ref": "#/definitions/plan" + description: Updates the name of a plan. Other plan details (price, interval, + etc.) are, by design, not editable. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + name: + example: '' + type: + - string + description: Name of the plan, to be displayed on invoices and in the + web interface. + statement_descriptor: + example: '' + type: + - string + description: An arbitrary string to be displayed on your customer's credit + card statement. This may be up to **22 characters**. As an example, + if your website is `RunClub` and the item you're charging for is your + Silver Plan, you may want to specify a `statement_descriptor` of `RunClub + Silver Plan`. The statement description may not include `<>"'` characters, + and will appear on your customer's statement in capital letters. Non-ASCII + characters are automatically stripped. While most banks display this + information consistently, some may display it incorrectly or not at + all. + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a plan object. + It can be useful for storing additional information about the plan in + a structured format. + properties: + amount: + "$ref": "#/definitions/plan/definitions/amount" + created: + "$ref": "#/definitions/plan/definitions/created" + currency: + "$ref": "#/definitions/plan/definitions/currency" + id: + "$ref": "#/definitions/plan/definitions/id" + interval: + "$ref": "#/definitions/plan/definitions/interval" + interval_count: + "$ref": "#/definitions/plan/definitions/interval_count" + livemode: + "$ref": "#/definitions/plan/definitions/livemode" + metadata: + "$ref": "#/definitions/plan/definitions/metadata" + name: + "$ref": "#/definitions/plan/definitions/name" + object: + "$ref": "#/definitions/plan/definitions/object" + statement_descriptor: + "$ref": "#/definitions/plan/definitions/statement_descriptor" + trial_period_days: + "$ref": "#/definitions/plan/definitions/trial_period_days" + required: + - amount + - created + - currency + - id + - interval + - interval_count + - livemode + - metadata + - name + - object + title: Plan + type: + - object + platform-earning: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + account: + description: ID of the Stripe account this fee was taken from. + example: '' + type: + - string + amount: + description: Amount earned, in %s. + example: 0 + type: + - integer + amount_refunded: + example: 0 + type: + - integer + application: + description: ID of the Connect Application that earned the fee. + example: '' + type: + - string + balance_transaction: + description: Balance transaction that describes the impact of this collected + application fee on your account balance (not including refunds). + example: '' + type: + - string + charge: + description: ID of the charge that the application fee was taken from. + example: '' + type: + - string + created: + example: 0 + type: + - integer + currency: + description: Three-letter ISO code representing the currency of the charge. + example: '' + type: + - string + id: + example: '' + type: + - string + livemode: + example: false + type: + - boolean + object: + example: '' + type: + - string + refunded: + description: Whether or not the fee has been fully refunded. If the fee is + only partially refunded, this attribute will still be false. + example: false + type: + - boolean + refunds: + description: A list of refunds that have been applied to the fee. + example: [] + type: + - array + identity: + "$ref": "#/definitions/platform-earning/definitions/resource_id" + links: + - title: List all application fees + method: GET + rel: self + href: "/v1/application_fees" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/platform-earning" + url: + example: "/v1/application_fees" + type: + - string + description: Returns a list of application fees you’ve previously collected. + The application fees are returned in sorted order, with the most recent fees + appearing first. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + created: + example: {} + type: + - object + - integer + charge: + example: '' + type: + - string + description: Only return application fees for the charge specified by + this charge ID. + - title: RefundPlatformEarningMethod + method: POST + rel: self + href: "/v1/application_fees/{%23%2Fdefinitions%2Fplatform-earning%2Fdefinitions%2Fidentity}/refund" + targetSchema: + "$ref": "#/definitions/platform-earning" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + directive: + example: '' + type: + - string + amount: + example: 0 + type: + - integer + - title: Retrieve an application fee + method: GET + rel: self + href: "/v1/application_fees/{%23%2Fdefinitions%2Fplatform-earning%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/platform-earning" + description: Retrieves the details of an application fee that your account has + collected. The same information is returned when refunding the application + fee. + properties: + account: + "$ref": "#/definitions/platform-earning/definitions/account" + amount: + "$ref": "#/definitions/platform-earning/definitions/amount" + amount_refunded: + "$ref": "#/definitions/platform-earning/definitions/amount_refunded" + application: + "$ref": "#/definitions/platform-earning/definitions/application" + balance_transaction: + "$ref": "#/definitions/platform-earning/definitions/balance_transaction" + charge: + "$ref": "#/definitions/platform-earning/definitions/charge" + created: + "$ref": "#/definitions/platform-earning/definitions/created" + currency: + "$ref": "#/definitions/platform-earning/definitions/currency" + id: + "$ref": "#/definitions/platform-earning/definitions/id" + livemode: + "$ref": "#/definitions/platform-earning/definitions/livemode" + object: + "$ref": "#/definitions/platform-earning/definitions/object" + refunded: + "$ref": "#/definitions/platform-earning/definitions/refunded" + refunds: + "$ref": "#/definitions/platform-earning/definitions/refunds" + required: + - account + - amount + - amount_refunded + - application + - balance_transaction + - charge + - created + - currency + - id + - livemode + - object + - refunded + - refunds + title: PlatformEarning + type: + - object + product: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + active: + description: Whether or not the product is currently available for purchase. + example: true + type: + - boolean + attributes: + description: A list of up to 5 attributes that each SKU can provide values + for (e.g. `["color", "size"]`). + example: + - gender + - size + type: + - array + caption: + description: A short one-line description of the product, meant to be displayable + to the customer. + example: '' + type: + - string + created: + example: 1446774024 + type: + - integer + description: + description: The product's description, meant to be displayable to the customer. + example: Comfortable gray cotton t-shirts + type: + - string + id: + example: prod_7IaOt0RZoSrcDU + type: + - string + images: + description: A list of up to 8 URLs of images for this product, meant to be + displayable to the customer. + example: [] + type: + - array + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to a product object. + It can be useful for storing additional information about the product in + a structured format. + example: {} + type: + - object + name: + description: The product's name, meant to be displayable to the customer. + example: T-shirt + type: + - string + object: + example: product + type: + - string + package_dimensions: + description: The dimensions of this product for shipping purposes. A SKU associated + with this product can override this value by having its own `package_dimensions` + example: {} + type: + - object + shippable: + description: Whether this product is a shipped good. + example: true + type: + - boolean + skus: + description: A sublist of active SKUs associated with this product. + example: + data: [] + has_more: false + object: list + total_count: 0 + url: "/v1/skus?product=prod_7IaOt0RZoSrcDU&active=true" + type: + - object + updated: + example: 1446774024 + type: + - integer + url: + description: A URL of a publicly-accessible webpage for this product. + example: '' + type: + - string + identity: + "$ref": "#/definitions/product/definitions/resource_id" + links: + - title: CreateProductMethod + method: POST + rel: self + href: "/v1/products" + targetSchema: + "$ref": "#/definitions/product" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + id: + example: '' + type: + - string + description: The identifier for the product. Must be unique. If not + provided, an identifier will be randomly generated. + name: + example: '' + type: + - string + description: The product's name, meant to be displayable to the customer. + caption: + example: '' + type: + - string + description: A short one-line description of the product, meant to be + displayable to the customer. + description: + example: '' + type: + - string + description: The product's description, meant to be displayable to the + customer. + attributes: + example: [] + type: + - array + description: A list of up to 5 alphanumeric attributes that each SKU can + provide values for (e.g. `["color", "size"]`). + shippable: + example: false + type: + - boolean + description: Whether this product is shipped (i.e. physical goods). Defaults + to `true`. + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a product object. + It can be useful for storing additional information about the product in + a structured format. + active: + example: false + type: + - boolean + description: Whether or not the product is currently available for purchase. + Defaults to `true`. + url: + example: '' + type: + - string + description: A URL of a publicly-accessible webpage for this product. + package_dimensions: + example: {} + type: + - object + description: The dimensions of this product for shipping purposes. A SKU associated + with this product can override this value by having its own `package_dimensions` + images: + example: [] + type: + - array + description: A list of up to 8 URLs of images for this product, meant + to be displayable to the customer. + required: + - name + - title: List all products + method: GET + rel: self + href: "/v1/products" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/product" + url: + example: "/v1/products" + type: + - string + description: Returns a list of your products. The products are returned sorted + by creation date, with the most recently created products appearing first. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + active: + example: false + type: + - boolean + description: Only return products that are active or inactive (e.g. pass + `false` to list all inactive products). + ids: + example: [] + type: + - array + description: Only return products with the given IDs. + shippable: + example: false + type: + - boolean + description: Only return products that can be shipped (i.e., physical, + not digital products). + url: + example: '' + type: + - string + description: Only return products with the given url + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + - title: Retrieve a product + method: GET + rel: self + href: "/v1/products/{%23%2Fdefinitions%2Fproduct%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/product" + description: Retrieves the details of an existing product. Supply the unique + product ID from either a product creation request or the product list, and + Stripe will return the corresponding product information. + - title: UpdateProductMethod + method: POST + rel: self + href: "/v1/products/{%23%2Fdefinitions%2Fproduct%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/product" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + name: + example: '' + type: + - string + description: The product's name, meant to be displayable to the customer. + description: + example: '' + type: + - string + description: The product's description, meant to be displayable to the + customer. + caption: + example: '' + type: + - string + description: A short one-line description of the product, meant to be + displayable to the customer. + shippable: + example: false + type: + - boolean + description: Whether this product is shipped (i.e. physical goods). Defaults + to `true`. + active: + example: false + type: + - boolean + description: Whether or not the product is available for purchase. Setting + this to `false` also deactivates any active, related SKUs. Setting this + to `true` does not automatically activate any deactivated, related SKUs. + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a product + object. It can be useful for storing additional information about the + product in a structured format. + url: + example: '' + type: + - string + description: A URL of a publicly-accessible webpage for this product. + package_dimensions: + example: {} + type: + - object + description: The dimensions of this product for shipping purposes. A SKU associated + with this product can override this value by having its own `package_dimensions` + images: + example: [] + type: + - array + description: A list of up to 8 URLs of images for this product, meant + to be displayable to the customer. + properties: + active: + "$ref": "#/definitions/product/definitions/active" + attributes: + "$ref": "#/definitions/product/definitions/attributes" + caption: + "$ref": "#/definitions/product/definitions/caption" + created: + "$ref": "#/definitions/product/definitions/created" + description: + "$ref": "#/definitions/product/definitions/description" + id: + "$ref": "#/definitions/product/definitions/id" + images: + "$ref": "#/definitions/product/definitions/images" + livemode: + "$ref": "#/definitions/product/definitions/livemode" + metadata: + "$ref": "#/definitions/product/definitions/metadata" + name: + "$ref": "#/definitions/product/definitions/name" + object: + "$ref": "#/definitions/product/definitions/object" + package_dimensions: + "$ref": "#/definitions/product/definitions/package_dimensions" + shippable: + "$ref": "#/definitions/product/definitions/shippable" + skus: + "$ref": "#/definitions/product/definitions/skus" + updated: + "$ref": "#/definitions/product/definitions/updated" + url: + "$ref": "#/definitions/product/definitions/url" + required: + - active + - created + - id + - images + - livemode + - metadata + - name + - object + - shippable + - skus + - updated + title: Product + type: + - object + recipient-payout-card: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + address_city: + example: '' + type: + - string + address_country: + description: Billing address country, if provided when creating card + example: '' + type: + - string + address_line1: + example: '' + type: + - string + address_line1_check: + description: 'If `address_line1` was provided, results of the check: `pass`, + `fail`, `unavailable`, or `unchecked`.' + example: '' + type: + - string + address_line2: + example: '' + type: + - string + address_state: + example: '' + type: + - string + address_zip: + example: '' + type: + - string + address_zip_check: + description: 'If `address_zip` was provided, results of the check: `pass`, + `fail`, `unavailable`, or `unchecked`.' + example: '' + type: + - string + brand: + description: Card brand. Can be `Visa`, `American Express`, `MasterCard`, + `Discover`, `JCB`, `Diners Club`, or `Unknown`. + example: '' + type: + - string + country: + description: Two-letter ISO code representing the country of the card. You + could use this attribute to get a sense of the international breakdown of + cards you've collected. + example: '' + type: + - string + cvc_check: + description: 'If a CVC was provided, results of the check: `pass`, `fail`, + `unavailable`, or `unchecked`' + example: '' + type: + - string + dynamic_last4: + description: "(For tokenized numbers only.) The last four digits of the device + account number." + example: '' + type: + - string + exp_month: + example: 0 + type: + - integer + exp_year: + example: 0 + type: + - integer + fingerprint: + description: Uniquely identifies this particular card number. You can use + this attribute to check whether two customers who've signed up with you + are using the same card number, for example. + example: '' + type: + - string + funding: + description: Card funding type. Can be `credit`, `debit`, `prepaid`, or `unknown` + example: '' + type: + - string + id: + description: ID of card (used in conjunction with a customer or recipient + ID) + example: '' + type: + - string + last4: + example: '' + type: + - string + metadata: + description: A set of key/value pairs that you can attach to a card object. + It can be useful for storing additional information about the card in a + structured format. + example: {} + type: + - object + name: + description: Cardholder name + example: '' + type: + - string + object: + example: '' + type: + - string + recipient: + example: '' + type: + - string + tokenization_method: + description: If the card number is tokenized, this is the method that was + used. Can be `apple_pay` or `android_pay`. + example: '' + type: + - string + identity: + "$ref": "#/definitions/recipient-payout-card/definitions/resource_id" + links: + - title: AllTransferRecipientCardsMethod + method: GET + rel: self + href: "/v1/recipients/{%23%2Fdefinitions%2Frecipient-payout-card%2Fdefinitions%2Fidentity}/cards" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/recipient-payout-card" + url: + example: "/v1/recipients/{%23%2Fdefinitions%2Frecipient-payout-card%2Fdefinitions%2Fidentity}/cards" + type: + - string + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + - title: CreateTransferRecipientCardMethod + method: POST + rel: self + href: "/v1/recipients/{%23%2Fdefinitions%2Frecipient-payout-card%2Fdefinitions%2Fidentity}/cards" + targetSchema: + "$ref": "#/definitions/recipient-payout-card" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + card: + example: {} + type: + - object + - string + description: The card can either be a token, like the ones returned by + our [Stripe.js](/docs/stripe.js), or a dictionary containing a + user's credit card details (with the options shown below). Whenever + you create a new card for a recipient, Stripe will automatically + validate the card. + required: + - card + - title: DeleteTransferRecipientCardMethod + method: DELETE + rel: self + href: "/v1/recipients/{recipient}/cards/{%23%2Fdefinitions%2Frecipient-payout-card%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/recipient-payout-card" + - title: RetrieveTransferRecipientCardMethod + method: GET + rel: self + href: "/v1/recipients/{recipient}/cards/{%23%2Fdefinitions%2Frecipient-payout-card%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/recipient-payout-card" + - title: UpdateTransferRecipientCardMethod + method: POST + rel: self + href: "/v1/recipients/{recipient}/cards/{%23%2Fdefinitions%2Frecipient-payout-card%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/recipient-payout-card" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + exp_year: + example: '' + type: + - string + exp_month: + example: '' + type: + - string + name: + example: '' + type: + - string + address_line1: + example: '' + type: + - string + address_line2: + example: '' + type: + - string + address_city: + example: '' + type: + - string + address_zip: + example: '' + type: + - string + address_state: + example: '' + type: + - string + address_country: + example: '' + type: + - string + properties: + address_city: + "$ref": "#/definitions/recipient-payout-card/definitions/address_city" + address_country: + "$ref": "#/definitions/recipient-payout-card/definitions/address_country" + address_line1: + "$ref": "#/definitions/recipient-payout-card/definitions/address_line1" + address_line1_check: + "$ref": "#/definitions/recipient-payout-card/definitions/address_line1_check" + address_line2: + "$ref": "#/definitions/recipient-payout-card/definitions/address_line2" + address_state: + "$ref": "#/definitions/recipient-payout-card/definitions/address_state" + address_zip: + "$ref": "#/definitions/recipient-payout-card/definitions/address_zip" + address_zip_check: + "$ref": "#/definitions/recipient-payout-card/definitions/address_zip_check" + brand: + "$ref": "#/definitions/recipient-payout-card/definitions/brand" + country: + "$ref": "#/definitions/recipient-payout-card/definitions/country" + cvc_check: + "$ref": "#/definitions/recipient-payout-card/definitions/cvc_check" + dynamic_last4: + "$ref": "#/definitions/recipient-payout-card/definitions/dynamic_last4" + exp_month: + "$ref": "#/definitions/recipient-payout-card/definitions/exp_month" + exp_year: + "$ref": "#/definitions/recipient-payout-card/definitions/exp_year" + fingerprint: + "$ref": "#/definitions/recipient-payout-card/definitions/fingerprint" + funding: + "$ref": "#/definitions/recipient-payout-card/definitions/funding" + id: + "$ref": "#/definitions/recipient-payout-card/definitions/id" + last4: + "$ref": "#/definitions/recipient-payout-card/definitions/last4" + metadata: + "$ref": "#/definitions/recipient-payout-card/definitions/metadata" + name: + "$ref": "#/definitions/recipient-payout-card/definitions/name" + object: + "$ref": "#/definitions/recipient-payout-card/definitions/object" + recipient: + "$ref": "#/definitions/recipient-payout-card/definitions/recipient" + tokenization_method: + "$ref": "#/definitions/recipient-payout-card/definitions/tokenization_method" + required: + - brand + - exp_month + - exp_year + - funding + - id + - last4 + - metadata + - object + title: RecipientPayoutCard + type: + - object + refund: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + description: Amount, in %s. + example: 100 + type: + - integer + balance_transaction: + description: Balance transaction that describes the impact on your account + balance. + example: '' + type: + - string + charge: + description: ID of the charge that was refunded. + example: ch_173zDIIw57t4eNNvjJ1ECQp4 + type: + - string + created: + example: 1446774024 + type: + - integer + currency: + description: Three-letter ISO code representing the currency. + example: usd + type: + - string + description: + example: '' + type: + - string + id: + example: re_173zDIIw57t4eNNvM5bqrzVp + type: + - string + metadata: + description: A set of key/value pairs that you can attach to the object. It + can be useful for storing additional information in a structured format. + example: {} + type: + - object + object: + example: refund + type: + - string + reason: + description: Reason for the refund. If set, possible values are `duplicate`, + `fraudulent`, and `requested_by_customer`. + example: '' + type: + - string + receipt_number: + description: This is the transaction number that appears on email receipts + sent for this refund. + example: '' + type: + - string + identity: + "$ref": "#/definitions/refund/definitions/resource_id" + links: + - title: CreateChargeRefundMethod + method: POST + rel: self + href: "/v1/charges/{charge}/refunds" + targetSchema: + "$ref": "#/definitions/refund" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + amount: + example: 0 + type: + - integer + refund_application_fee: + example: false + type: + - boolean + reason: + example: '' + type: + - string + reverse_transfer: + example: false + type: + - boolean + directive: + example: '' + type: + - string + metadata: + example: {} + type: + - object + - title: CreateChargeRefundMethod + method: POST + rel: self + href: "/v1/refunds" + targetSchema: + "$ref": "#/definitions/refund" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + charge: + example: '' + type: + - string + amount: + example: 0 + type: + - integer + refund_application_fee: + example: false + type: + - boolean + reason: + example: '' + type: + - string + reverse_transfer: + example: false + type: + - boolean + directive: + example: '' + type: + - string + metadata: + example: {} + type: + - object + required: + - charge + - title: List all refunds + method: GET + rel: self + href: "/v1/charges/{charge}/refunds" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/refund" + url: + example: "/v1/charges/{charge}/refunds" + type: + - string + description: You can see a list of the refunds belonging to a specific charge. + Note that the 10 most recent refunds are always available by default on the + charge object. If you need more than those 10, you can use this API method + and the limit and starting_after parameters to page + through additional refunds. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + - title: List all refunds + method: GET + rel: self + href: "/v1/refunds" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/refund" + url: + example: "/v1/refunds" + type: + - string + description: Returns a list of all refunds you’ve previously created. The refunds + are returned in sorted order, with the most recent refunds appearing first. + For convenience, the 10 most recent refunds are always available by default + on the charge object. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + charge: + example: '' + type: + - string + description: Only return refunds for the charge specified by this charge + ID. + - title: RetrieveChargeRefundMethod + method: GET + rel: self + href: "/v1/charges/{charge}/refunds/{refund}" + targetSchema: + "$ref": "#/definitions/refund" + - title: RetrieveRefundMethod + method: GET + rel: self + href: "/v1/refunds/{refund}" + targetSchema: + "$ref": "#/definitions/refund" + - title: UpdateChargeRefundMethod + method: POST + rel: self + href: "/v1/charges/{charge}/refunds/{refund}" + targetSchema: + "$ref": "#/definitions/refund" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + metadata: + example: {} + type: + - object + - title: UpdateRefundMethod + method: POST + rel: self + href: "/v1/refunds/{refund}" + targetSchema: + "$ref": "#/definitions/refund" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + metadata: + example: {} + type: + - object + properties: + amount: + "$ref": "#/definitions/refund/definitions/amount" + balance_transaction: + "$ref": "#/definitions/refund/definitions/balance_transaction" + charge: + "$ref": "#/definitions/refund/definitions/charge" + created: + "$ref": "#/definitions/refund/definitions/created" + currency: + "$ref": "#/definitions/refund/definitions/currency" + description: + "$ref": "#/definitions/refund/definitions/description" + id: + "$ref": "#/definitions/refund/definitions/id" + metadata: + "$ref": "#/definitions/refund/definitions/metadata" + object: + "$ref": "#/definitions/refund/definitions/object" + reason: + "$ref": "#/definitions/refund/definitions/reason" + receipt_number: + "$ref": "#/definitions/refund/definitions/receipt_number" + required: + - amount + - created + - currency + - id + - metadata + - object + title: Refund + type: + - object + sku: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + active: + description: Whether or not the SKU is available for purchase. + example: false + type: + - boolean + attributes: + description: 'A dictionary of attributes and values for the attributes defined + by the product. If, for example, a product''s attributes are `["size", "gender"]`, + a valid SKU has the following dictionary of attributes: `{"size": "Medium", + "gender": "Unisex"}`.' + example: {} + type: + - object + created: + example: 0 + type: + - integer + currency: + description: 3-letter [ISO code](https://support.stripe.com/questions/which-currencies-does-stripe-support) + for currency. + example: '' + type: + - string + id: + example: '' + type: + - string + image: + description: The URL of an image for this SKU, meant to be displayable to + the customer. + example: '' + type: + - string + inventory: + description: Description of the SKU's inventory. + example: {} + type: + - object + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to a SKU object. + It can be useful for storing additional information about the SKU in + a structured format. + example: {} + type: + - object + object: + example: '' + type: + - string + package_dimensions: + description: The dimensions of this SKU for shipping purposes. + example: {} + type: + - object + price: + description: The cost of the item as a positive integer in the smallest currency + unit (that is, 100 cents to charge $1.00, or 1 to charge ¥1, Japanese Yen + being a 0-decimal currency). + example: 0 + type: + - integer + product: + description: The ID of the product this SKU is associated with. The product + must be currently active. + example: '' + type: + - string + updated: + example: 0 + type: + - integer + identity: + "$ref": "#/definitions/sku/definitions/resource_id" + links: + - title: CreateSKUMethod + method: POST + rel: self + href: "/v1/skus" + targetSchema: + "$ref": "#/definitions/sku" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + id: + example: '' + type: + - string + description: The identifier for the SKU. Must be unique. If not provided, + an identifier will be randomly generated. + product: + example: '' + type: + - string + description: The ID of the product this SKU is associated with. + price: + example: 0 + type: + - integer + description: The cost of the item as a positive integer in the smallest + currency unit (that is, 100 cents to charge $1.00, or 1 to charge ¥1, + Japanese Yen being a 0-decimal currency). + currency: + example: '' + type: + - string + description: 3-letter [ISO code](https://support.stripe.com/questions/which-currencies-does-stripe-support) + for currency. + inventory: + example: {} + type: + - object + description: Description of the SKU's inventory. + attributes: + example: {} + type: + - object + description: 'A dictionary of attributes and values for the attributes + defined by the product. If, for example, a product''s attributes are + `["size", "gender"]`, a valid SKU has the following dictionary of attributes: + `{"size": "Medium", "gender": "Unisex"}`.' + active: + example: false + type: + - boolean + description: Whether or not the SKU is available for purchase. Default + to `true`. + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a SKU object. + It can be useful for storing additional information about the SKU in + a structured format. + image: + example: '' + type: + - string + description: The URL of an image for this SKU, meant to be displayable + to the customer. + package_dimensions: + example: {} + type: + - object + description: The dimensions of this SKU for shipping purposes. + required: + - product + - price + - currency + - inventory + - title: List all SKUs + method: GET + rel: self + href: "/v1/skus" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/sku" + url: + example: "/v1/skus" + type: + - string + description: Returns a list of your SKUs. The SKUs are returned sorted by creation + date, with the most recently created SKUs appearing first. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + product: + example: '' + type: + - string + description: The ID of the product whose SKUs will be retrieved. + active: + example: false + type: + - boolean + description: Only return SKUs that are active or inactive (e.g. pass `false` + to list all inactive products). + ids: + example: [] + type: + - array + description: Only return SKUs with the given IDs. + attributes: + example: {} + type: + - object + description: Only return SKUs that have the specified key/value pairs + in this partially constructed dictionary. Can + be specified only if `product` is also supplied. For instance, if the + associated product has attributes `["color", "size"]`, passing in `attributes[color]=red` + returns all the SKUs for this product that have `color` set to `red`. + in_stock: + example: false + type: + - boolean + description: Only return SKUs that are either in stock or out of stock + (e.g. pass `false` to list all SKUs that are out of stock). If no value + is provided, all SKUs are returned. + - title: Retrieve a SKU + method: GET + rel: self + href: "/v1/skus/{%23%2Fdefinitions%2Fsku%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/sku" + description: Retrieves the details of an existing SKU. Supply the unique SKU + identifier from either a SKU creation request or from the product, and Stripe + will return the corresponding SKU information. + - title: UpdateSKUMethod + method: POST + rel: self + href: "/v1/skus/{%23%2Fdefinitions%2Fsku%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/sku" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + metadata: + example: {} + type: + - object + description: A set of key/value pairs that you can attach to a SKU object. + It can be useful for storing additional information about the SKU in + a structured format. + inventory: + example: {} + type: + - object + description: Description of the SKU's inventory. + price: + example: 0 + type: + - integer + description: The cost of the item as a positive integer in the smallest + currency unit (that is, 100 cents to charge $1.00, or 1 to charge ¥1, + Japanese Yen being a 0-decimal currency). + currency: + example: '' + type: + - string + description: 3-letter [ISO code](https://support.stripe.com/questions/which-currencies-does-stripe-support) + for currency. + active: + example: false + type: + - boolean + description: Whether or not this SKU is available for purchase. + package_dimensions: + example: {} + type: + - object + description: The dimensions of this SKU for shipping purposes. + image: + example: '' + type: + - string + description: The URL of an image for this SKU, meant to be displayable + to the customer. + properties: + active: + "$ref": "#/definitions/sku/definitions/active" + attributes: + "$ref": "#/definitions/sku/definitions/attributes" + created: + "$ref": "#/definitions/sku/definitions/created" + currency: + "$ref": "#/definitions/sku/definitions/currency" + id: + "$ref": "#/definitions/sku/definitions/id" + image: + "$ref": "#/definitions/sku/definitions/image" + inventory: + "$ref": "#/definitions/sku/definitions/inventory" + livemode: + "$ref": "#/definitions/sku/definitions/livemode" + metadata: + "$ref": "#/definitions/sku/definitions/metadata" + object: + "$ref": "#/definitions/sku/definitions/object" + package_dimensions: + "$ref": "#/definitions/sku/definitions/package_dimensions" + price: + "$ref": "#/definitions/sku/definitions/price" + product: + "$ref": "#/definitions/sku/definitions/product" + updated: + "$ref": "#/definitions/sku/definitions/updated" + required: + - active + - attributes + - created + - currency + - id + - inventory + - livemode + - metadata + - object + - price + - product + - updated + title: SKU + type: + - object + subscription: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + application_fee_percent: + description: A positive decimal that represents the fee percentage of the + subscription invoice amount that will be transferred to the application + owner's Stripe account each billing period. + example: 0.0 + type: + - number + cancel_at_period_end: + description: If the subscription has been canceled with the `at_period_end` + flag set to `true`, `cancel_at_period_end` on the subscription will be true. You + can use this attribute to determine whether a subscription that has a status + of active is scheduled to be canceled at the end of the current period. + example: false + type: + - boolean + canceled_at: + description: If the subscription has been canceled, the date of that cancellation. + If the subscription was canceled with `cancel_at_period_end`, canceled_at + will still reflect the date of the initial cancellation request, not the + end of the subscription period when the subscription is automatically moved + to a canceled state. + example: 0 + type: + - integer + current_period_end: + description: End of the current period that the subscription has been invoiced + for. At the end of this period, a new invoice will be created. + example: 1449366024 + type: + - integer + current_period_start: + description: Start of the current period that the subscription has been invoiced + for + example: 1446774024 + type: + - integer + customer: + example: cus_7IV7zteF9TaFBj + type: + - string + discount: + description: Describes the current discount applied to this subscription, + if there is one. When billing, a discount applied to a subscription overrides + a discount applied on a customer-wide basis. + example: {} + type: + - object + ended_at: + description: If the subscription has ended (either because it was canceled + or because the customer was switched to a subscription to a new plan), the + date the subscription ended + example: 0 + type: + - integer + id: + example: sub_7IaOY6OeGFY8vB + type: + - string + metadata: + description: A set of key/value pairs that you can attach to a subscription object. + It can be useful for storing additional information about the subscription in + a structured format. + example: {} + type: + - object + object: + example: subscription + type: + - string + plan: + description: Hash describing the plan the customer is subscribed to + example: + amount: 2000 + created: 1446754408 + currency: usd + id: gold + interval: month + interval_count: 1 + livemode: false + metadata: {} + name: Gold Special + object: plan + statement_descriptor: + trial_period_days: + type: + - object + quantity: + example: 1 + type: + - integer + start: + description: Date the subscription started + example: 1446774024 + type: + - integer + status: + description: Possible values are `trialing`, `active`, `past_due`, `canceled`, + or `unpaid`. A subscription still in its trial period is `trialing` and + moves to `active` when the trial period is over. When payment to renew the + subscription fails, the subscription becomes `past_due`. After Stripe has + exhausted all payment retry attempts, the subscription ends up with a status + of either `canceled` or `unpaid` depending on your retry settings. Note + that when a subscription has a status of `unpaid`, no subsequent invoices + will be attempted (invoices will be created, but then immediately automatically + closed. Additionally, updating customer card details will not lead to Stripe + retrying the latest invoice.). After receiving updated card details from + a customer, you may choose to reopen and pay their closed invoices. + example: active + type: + - string + tax_percent: + description: If provided, each invoice created by this subscription will apply + the tax rate, increasing the amount billed to the customer. + example: 0.0 + type: + - number + trial_end: + description: If the subscription has a trial, the end of that trial. + example: 0 + type: + - integer + trial_start: + description: If the subscription has a trial, the beginning of that trial. + example: 0 + type: + - integer + identity: + "$ref": "#/definitions/subscription/definitions/resource_id" + links: + - title: Cancel a subscription + method: DELETE + rel: self + href: "/v1/customers/{customer}/subscriptions/{subscription_exposed_id}" + targetSchema: + "$ref": "#/definitions/subscription" + description: |- + Cancels a customer’s subscription. If you set the at_period_end parameter to true, the subscription will remain active until the end of the period, at which point it will be canceled and not renewed. By default, the subscription is terminated immediately. In either case, the customer will not be charged again for the subscription. Note, however, that any pending invoice items that you’ve created will still be charged for at the end of the period unless manually deleted. If you’ve set the subscription to cancel at period end, any pending prorations will also be left in place and collected at the end of the period, but if the subscription is set to cancel immediately, pending prorations will be removed.

+ +

By default, all unpaid invoices for the customer will be closed upon subscription cancellation. We do this in order to prevent unexpected payment retries once the customer has canceled a subscription. However, you can reopen the invoices manually after subscription cancellation to have us proceed with automatic retries, or you could even re-attempt payment yourself on all unpaid invoices before allowing the customer to cancel the subscription at all. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + at_period_end: + example: false + type: + - boolean + description: A flag that if set to true will delay the cancellation of + the subscription until the end of the current period. + - title: Create a subscription + method: POST + rel: self + href: "/v1/customers/{customer}/subscriptions" + targetSchema: + "$ref": "#/definitions/subscription" + description: Creates a new subscription on an existing customer. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + plan: + example: '' + type: + - string + prorate: + example: false + type: + - boolean + trial_end: + example: 0 + type: + - integer + - string + quantity: + example: 0 + type: + - integer + application_fee_percent: + example: 0.0 + type: + - number + coupon: + example: '' + type: + - string + start_in_past: + example: 0 + type: + - integer + source: + example: {} + type: + - object + - string + metadata: + example: {} + type: + - object + tax_percent: + example: 0.0 + type: + - number + required: + - plan + - title: List active subscriptions + method: GET + rel: self + href: "/v1/customers/{customer}/subscriptions" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/subscription" + url: + example: "/v1/customers/{customer}/subscriptions" + type: + - string + description: You can see a list of the customer’s active subscriptions. Note + that the 10 most recent active subscriptions are always available by default + on the customer object. If you need more than those 10, you can use the limit + and starting_after parameters to page through additional subscriptions. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + - title: Update a subscription + method: POST + rel: self + href: "/v1/customers/{customer}/subscriptions/{subscription_exposed_id}" + targetSchema: + "$ref": "#/definitions/subscription" + description: Updates an existing subscription on a customer to match the specified + parameters. When changing plans or quantities, we will optionally prorate + the price we charge next month to make up for any price changes. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + plan: + example: '' + type: + - string + prorate: + example: false + type: + - boolean + proration_date: + example: 0 + type: + - integer + trial_end: + example: 0 + type: + - integer + - string + quantity: + example: 0 + type: + - integer + application_fee_percent: + example: 0.0 + type: + - number + source: + example: {} + type: + - object + - string + coupon: + example: '' + type: + - string + metadata: + example: {} + type: + - object + start_in_past: + example: 0 + type: + - integer + tax_percent: + example: 0.0 + type: + - number + properties: + application_fee_percent: + "$ref": "#/definitions/subscription/definitions/application_fee_percent" + cancel_at_period_end: + "$ref": "#/definitions/subscription/definitions/cancel_at_period_end" + canceled_at: + "$ref": "#/definitions/subscription/definitions/canceled_at" + current_period_end: + "$ref": "#/definitions/subscription/definitions/current_period_end" + current_period_start: + "$ref": "#/definitions/subscription/definitions/current_period_start" + customer: + "$ref": "#/definitions/subscription/definitions/customer" + discount: + "$ref": "#/definitions/subscription/definitions/discount" + ended_at: + "$ref": "#/definitions/subscription/definitions/ended_at" + id: + "$ref": "#/definitions/subscription/definitions/id" + metadata: + "$ref": "#/definitions/subscription/definitions/metadata" + object: + "$ref": "#/definitions/subscription/definitions/object" + plan: + "$ref": "#/definitions/subscription/definitions/plan" + quantity: + "$ref": "#/definitions/subscription/definitions/quantity" + start: + "$ref": "#/definitions/subscription/definitions/start" + status: + "$ref": "#/definitions/subscription/definitions/status" + tax_percent: + "$ref": "#/definitions/subscription/definitions/tax_percent" + trial_end: + "$ref": "#/definitions/subscription/definitions/trial_end" + trial_start: + "$ref": "#/definitions/subscription/definitions/trial_start" + required: + - cancel_at_period_end + - customer + - id + - metadata + - object + - plan + - quantity + - start + - status + title: Subscription + type: + - object + system-refund: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + description: Amount, in %s. + example: 0 + type: + - integer + balance_transaction: + description: Balance transaction that describes the impact on your account + balance. + example: '' + type: + - string + charge: + description: ID of the charge that was refunded. + example: '' + type: + - string + created: + example: 0 + type: + - integer + currency: + description: Three-letter ISO code representing the currency. + example: '' + type: + - string + description: + example: '' + type: + - string + id: + example: '' + type: + - string + metadata: + description: A set of key/value pairs that you can attach to the object. It + can be useful for storing additional information in a structured format. + example: {} + type: + - object + object: + example: '' + type: + - string + reason: + description: Reason for the refund. If set, possible values are `duplicate`, + `fraudulent`, and `requested_by_customer`. + example: '' + type: + - string + receipt_number: + description: This is the transaction number that appears on email receipts + sent for this refund. + example: '' + type: + - string + identity: + "$ref": "#/definitions/system-refund/definitions/resource_id" + links: [] + properties: + amount: + "$ref": "#/definitions/system-refund/definitions/amount" + balance_transaction: + "$ref": "#/definitions/system-refund/definitions/balance_transaction" + charge: + "$ref": "#/definitions/system-refund/definitions/charge" + created: + "$ref": "#/definitions/system-refund/definitions/created" + currency: + "$ref": "#/definitions/system-refund/definitions/currency" + description: + "$ref": "#/definitions/system-refund/definitions/description" + id: + "$ref": "#/definitions/system-refund/definitions/id" + metadata: + "$ref": "#/definitions/system-refund/definitions/metadata" + object: + "$ref": "#/definitions/system-refund/definitions/object" + reason: + "$ref": "#/definitions/system-refund/definitions/reason" + receipt_number: + "$ref": "#/definitions/system-refund/definitions/receipt_number" + required: + - amount + - created + - currency + - id + - metadata + - object + title: SystemRefund + type: + - object + token: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + bank_account: + description: Hash describing the bank account + example: {} + type: + - object + card: + description: Hash describing the card used to make the charge + example: + address_city: + address_country: + address_line1: + address_line1_check: + address_line2: + address_state: + address_zip: + address_zip_check: + brand: Visa + country: + cvc_check: + dynamic_last4: + exp_month: 8 + exp_year: 2016 + funding: unknown + id: card_173u6sIw57t4eNNv3YoFzsPh + last4: '4242' + metadata: {} + name: + object: card + tokenization_method: + type: + - object + client_ip: + description: IP address of the client that generated the token + example: '' + type: + - string + created: + example: 1446754406 + type: + - integer + id: + example: tok_173u6sIw57t4eNNvYQSD2Yhy + type: + - string + livemode: + example: false + type: + - boolean + object: + example: token + type: + - string + type: + description: 'Type of the token: `card` or `bank_account`' + example: card + type: + - string + used: + description: Whether or not this token has already been used (tokens can be + used only once) + example: false + type: + - boolean + identity: + "$ref": "#/definitions/token/definitions/resource_id" + links: + - title: CreateDetailsTokenMethod + method: POST + rel: self + href: "/v1/tokens" + targetSchema: + "$ref": "#/definitions/token" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + request_id: + example: '' + type: + - string + account_details: + example: {} + type: + - object + email: + example: '' + type: + - string + client_id: + example: '' + type: + - string + iovation_blackbox: + example: '' + type: + - string + payment_user_agent: + example: '' + type: + - string + required: + - account_details + - email + - client_id + - title: RetrieveTokenMethod + method: GET + rel: self + href: "/v1/tokens/{token}" + targetSchema: + "$ref": "#/definitions/token" + properties: + bank_account: + "$ref": "#/definitions/token/definitions/bank_account" + card: + "$ref": "#/definitions/token/definitions/card" + client_ip: + "$ref": "#/definitions/token/definitions/client_ip" + created: + "$ref": "#/definitions/token/definitions/created" + id: + "$ref": "#/definitions/token/definitions/id" + livemode: + "$ref": "#/definitions/token/definitions/livemode" + object: + "$ref": "#/definitions/token/definitions/object" + type: + "$ref": "#/definitions/token/definitions/type" + used: + "$ref": "#/definitions/token/definitions/used" + required: + - created + - id + - livemode + - object + - type + - used + title: Token + type: + - object + transfer: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + description: Amount (in %s) to be transferred to your bank account + example: 1100 + type: + - integer + amount_reversed: + description: Amount in %s reversed (can be less than the amount attribute + on the transfer if a partial reversal was issued). + example: 0 + type: + - integer + application_fee: + example: '' + type: + - string + balance_transaction: + description: Balance transaction that describes the impact of this transfer + on your account balance. + example: txn_173zDIIw57t4eNNvXMCPHWEE + type: + - string + created: + description: Time that this record of the transfer was first created. + example: 1446774024 + type: + - integer + currency: + example: usd + type: + - string + date: + description: Date the transfer is scheduled to arrive in the bank. This doesn't + factor in delays like weekends or bank holidays. + example: 1446774024 + type: + - integer + description: + description: Internal-only description of the transfer + example: Transfer to test@example.com + type: + - string + destination: + description: ID of the bank account, card, or Stripe account the transfer + was sent to. + example: ba_173zDIIw57t4eNNvPDZ9uLPq + type: + - string + destination_payment: + description: If the destination is a Stripe account, this will be the ID of + the payment that the destination account received for the transfer. + example: '' + type: + - string + failure_code: + description: Error code explaining reason for transfer failure if available. + See [Types of transfer failures](/docs/api#transfer_failures) for a list + of failure codes. + example: '' + type: + - string + failure_message: + description: Message to user further explaining reason for transfer failure + if available. + example: '' + type: + - string + id: + example: tr_173zDIIw57t4eNNvmKpLXDrx + type: + - string + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to a transfer object. + It can be useful for storing additional information about the transfer in + a structured format. + example: {} + type: + - object + object: + example: transfer + type: + - string + reversals: + description: A list of reversals that have been applied to the transfer. + example: + data: [] + has_more: false + object: list + total_count: 0 + url: "/v1/transfers/tr_173zDIIw57t4eNNvmKpLXDrx/reversals" + type: + - object + reversed: + description: Whether or not the transfer has been fully reversed. If the + transfer is only partially reversed, this attribute will still be false. + example: false + type: + - boolean + source_transaction: + description: ID of the charge (or other transaction) that was used to fund + the transfer. If null, the transfer was funded from the available balance. + example: '' + type: + - string + statement_descriptor: + description: Extra information about a transfer to be displayed on the user's + bank statement. + example: '' + type: + - string + status: + description: Current status of the transfer (`paid`, `pending`, `in_transit`, + `canceled` or `failed`). A transfer will be `pending` until it is submitted + to the bank, at which point it becomes `in_transit`. It will then change + to `paid` if the transaction goes through. If it does not go through successfully, + its status will change to `failed` or `canceled`. + example: in_transit + type: + - string + type: + description: Can be `card`, `bank_account`, or `stripe_account`. + example: bank_account + type: + - string + identity: + "$ref": "#/definitions/transfer/definitions/resource_id" + links: + - title: CreateTransferMethod + method: POST + rel: self + href: "/v1/transfers" + targetSchema: + "$ref": "#/definitions/transfer" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + recipient: + example: '' + type: + - string + description: + example: '' + type: + - string + metadata: + example: {} + type: + - object + statement_descriptor: + example: '' + type: + - string + destination: + example: '' + type: + - string + amount: + example: 0 + type: + - integer + currency: + example: '' + type: + - string + card: + example: '' + type: + - string + bank_account: + example: '' + type: + - string + source_transaction: + example: '' + type: + - string + application_fee: + example: 0 + type: + - integer + destination_application_fee: + example: 0 + type: + - integer + required: + - amount + - currency + - title: List all transfers + method: GET + rel: self + href: "/v1/transfers" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/transfer" + url: + example: "/v1/transfers" + type: + - string + description: Returns a list of existing transfers sent to third-party bank accounts + or that Stripe has sent you. The transfers are returned in sorted order, with + the most recently created transfers appearing first. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + status: + example: '' + type: + - string + description: 'Only return transfers that have the given status: `pending`, + `paid`, `failed`, `in_transit`, or `canceled`.' + date: + example: {} + type: + - object + - integer + created: + example: {} + type: + - object + - integer + recipient: + example: '' + type: + - string + description: Only return transfers for the recipient specified by this + recipient ID. + - title: Retrieve a transfer + method: GET + rel: self + href: "/v1/transfers/{%23%2Fdefinitions%2Ftransfer%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/transfer" + description: Retrieves the details of an existing transfer. Supply the unique + transfer ID from either a transfer creation request or the transfer list, + and Stripe will return the corresponding transfer information. + - title: ReverseNonStripeTransferOnSlashCancelMethod + method: POST + rel: self + href: "/v1/transfers/{%23%2Fdefinitions%2Ftransfer%2Fdefinitions%2Fidentity}/cancel" + targetSchema: + "$ref": "#/definitions/transfer" + - title: UpdateTransferMethod + method: POST + rel: self + href: "/v1/transfers/{%23%2Fdefinitions%2Ftransfer%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/transfer" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + description: + example: '' + type: + - string + metadata: + example: {} + type: + - object + properties: + amount: + "$ref": "#/definitions/transfer/definitions/amount" + amount_reversed: + "$ref": "#/definitions/transfer/definitions/amount_reversed" + application_fee: + "$ref": "#/definitions/transfer/definitions/application_fee" + balance_transaction: + "$ref": "#/definitions/transfer/definitions/balance_transaction" + created: + "$ref": "#/definitions/transfer/definitions/created" + currency: + "$ref": "#/definitions/transfer/definitions/currency" + date: + "$ref": "#/definitions/transfer/definitions/date" + description: + "$ref": "#/definitions/transfer/definitions/description" + destination: + "$ref": "#/definitions/transfer/definitions/destination" + destination_payment: + "$ref": "#/definitions/transfer/definitions/destination_payment" + failure_code: + "$ref": "#/definitions/transfer/definitions/failure_code" + failure_message: + "$ref": "#/definitions/transfer/definitions/failure_message" + id: + "$ref": "#/definitions/transfer/definitions/id" + livemode: + "$ref": "#/definitions/transfer/definitions/livemode" + metadata: + "$ref": "#/definitions/transfer/definitions/metadata" + object: + "$ref": "#/definitions/transfer/definitions/object" + reversals: + "$ref": "#/definitions/transfer/definitions/reversals" + reversed: + "$ref": "#/definitions/transfer/definitions/reversed" + source_transaction: + "$ref": "#/definitions/transfer/definitions/source_transaction" + statement_descriptor: + "$ref": "#/definitions/transfer/definitions/statement_descriptor" + status: + "$ref": "#/definitions/transfer/definitions/status" + type: + "$ref": "#/definitions/transfer/definitions/type" + required: + - amount + - amount_reversed + - created + - currency + - date + - id + - livemode + - metadata + - object + - reversals + - reversed + - status + - type + title: Transfer + type: + - object + transfer-recipient: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + active_account: + description: Hash describing the current account on the recipient, if there + is one. + example: {} + type: + - object + cards: + example: [] + type: + - array + created: + example: 0 + type: + - integer + default_card: + description: The default card to use for creating transfers to this recipient. + example: '' + type: + - string + description: + example: '' + type: + - string + email: + example: '' + type: + - string + id: + example: '' + type: + - string + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to a recipient object. + It can be useful for storing additional information about the recipient in + a structured format. + example: {} + type: + - object + migrated_to: + description: 'The ID of the [managed account](/docs/connect/managed-accounts) + this recipient was migrated to. If set, the recipient can no longer be updated, + nor can transfers be made to it: use the managed account instead.' + example: '' + type: + - string + name: + description: Full, legal name of the recipient. + example: '' + type: + - string + object: + example: '' + type: + - string + type: + description: Type of the recipient, one of `individual` or `corporation`. + example: '' + type: + - string + identity: + "$ref": "#/definitions/transfer-recipient/definitions/resource_id" + links: + - title: Delete a recipient + method: DELETE + rel: self + href: "/v1/recipients/{%23%2Fdefinitions%2Ftransfer-recipient%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/transfer-recipient" + description: Permanently deletes a recipient. It cannot be undone. + - title: List all recipients + method: GET + rel: self + href: "/v1/recipients" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/transfer-recipient" + url: + example: "/v1/recipients" + type: + - string + description: Returns a list of your recipients. The recipients are returned + sorted by creation date, with the most recently created recipients appearing + first. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + verified: + example: false + type: + - boolean + description: Only return recipients that are verified or unverified. + created: + example: {} + type: + - object + - integer + type: + example: '' + type: + - string + - title: Retrieve a recipient + method: GET + rel: self + href: "/v1/recipients/{%23%2Fdefinitions%2Ftransfer-recipient%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/transfer-recipient" + description: Retrieves the details of an existing recipient. You need only supply + the unique recipient identifier that was returned upon recipient creation. + - title: TransferRecipientCreateMethod + method: POST + rel: self + href: "/v1/recipients" + targetSchema: + "$ref": "#/definitions/transfer-recipient" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + bank_account: + example: {} + type: + - object + - string + card: + example: {} + type: + - object + - string + description: + example: '' + type: + - string + metadata: + example: {} + type: + - object + tax_id: + example: '' + type: + - string + email: + example: '' + type: + - string + type: + example: '' + type: + - string + name: + example: '' + type: + - string + required: + - type + - name + - title: TransferRecipientUpdateMethod + method: POST + rel: self + href: "/v1/recipients/{%23%2Fdefinitions%2Ftransfer-recipient%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/transfer-recipient" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + bank_account: + example: {} + type: + - object + - string + card: + example: {} + type: + - object + - string + description: + example: '' + type: + - string + metadata: + example: {} + type: + - object + tax_id: + example: '' + type: + - string + email: + example: '' + type: + - string + type: + example: '' + type: + - string + name: + example: '' + type: + - string + default_card: + example: '' + type: + - string + properties: + active_account: + "$ref": "#/definitions/transfer-recipient/definitions/active_account" + cards: + "$ref": "#/definitions/transfer-recipient/definitions/cards" + created: + "$ref": "#/definitions/transfer-recipient/definitions/created" + default_card: + "$ref": "#/definitions/transfer-recipient/definitions/default_card" + description: + "$ref": "#/definitions/transfer-recipient/definitions/description" + email: + "$ref": "#/definitions/transfer-recipient/definitions/email" + id: + "$ref": "#/definitions/transfer-recipient/definitions/id" + livemode: + "$ref": "#/definitions/transfer-recipient/definitions/livemode" + metadata: + "$ref": "#/definitions/transfer-recipient/definitions/metadata" + migrated_to: + "$ref": "#/definitions/transfer-recipient/definitions/migrated_to" + name: + "$ref": "#/definitions/transfer-recipient/definitions/name" + object: + "$ref": "#/definitions/transfer-recipient/definitions/object" + type: + "$ref": "#/definitions/transfer-recipient/definitions/type" + required: + - created + - id + - livemode + - metadata + - object + - type + title: TransferRecipient + type: + - object + transfer-reversal: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + description: Amount, in %s. + example: 0 + type: + - integer + balance_transaction: + description: Balance transaction that describes the impact on your account + balance. + example: '' + type: + - string + created: + example: 0 + type: + - integer + currency: + description: Three-letter ISO code representing the currency. + example: '' + type: + - string + id: + example: '' + type: + - string + metadata: + description: A set of key/value pairs that you can attach to the object. It + can be useful for storing additional information in a structured format. + example: {} + type: + - object + object: + example: '' + type: + - string + transfer: + description: ID of the transfer that was reversed. + example: '' + type: + - string + identity: + "$ref": "#/definitions/transfer-reversal/definitions/resource_id" + links: + - title: CreateStripeAccountTransferReversalMethod + method: POST + rel: self + href: "/v1/transfers/{%23%2Fdefinitions%2Ftransfer-reversal%2Fdefinitions%2Fidentity}/reversals" + targetSchema: + "$ref": "#/definitions/transfer-reversal" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + amount: + example: 0 + type: + - integer + refund_application_fee: + example: false + type: + - boolean + metadata: + example: {} + type: + - object + description: + example: '' + type: + - string + - title: List all reversals + method: GET + rel: self + href: "/v1/transfers/{%23%2Fdefinitions%2Ftransfer-reversal%2Fdefinitions%2Fidentity}/reversals" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/transfer-reversal" + url: + example: "/v1/transfers/{%23%2Fdefinitions%2Ftransfer-reversal%2Fdefinitions%2Fidentity}/reversals" + type: + - string + description: You can see a list of the reversals belonging to a specific transfer. + Note that the 10 most recent reversals are always available by default on + the transfer object. If you need more than those 10, you can use this API + method and the limit and starting_after parameters + to page through additional reversals. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + - title: RetrieveTransferReversalMethod + method: GET + rel: self + href: "/v1/transfers/{transfer}/reversals/{%23%2Fdefinitions%2Ftransfer-reversal%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/transfer-reversal" + - title: UpdateTransferReversalMethod + method: POST + rel: self + href: "/v1/transfers/{transfer}/reversals/{%23%2Fdefinitions%2Ftransfer-reversal%2Fdefinitions%2Fidentity}" + targetSchema: + "$ref": "#/definitions/transfer-reversal" + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + metadata: + example: {} + type: + - object + properties: + amount: + "$ref": "#/definitions/transfer-reversal/definitions/amount" + balance_transaction: + "$ref": "#/definitions/transfer-reversal/definitions/balance_transaction" + created: + "$ref": "#/definitions/transfer-reversal/definitions/created" + currency: + "$ref": "#/definitions/transfer-reversal/definitions/currency" + id: + "$ref": "#/definitions/transfer-reversal/definitions/id" + metadata: + "$ref": "#/definitions/transfer-reversal/definitions/metadata" + object: + "$ref": "#/definitions/transfer-reversal/definitions/object" + transfer: + "$ref": "#/definitions/transfer-reversal/definitions/transfer" + required: + - amount + - created + - currency + - id + - metadata + - object + - transfer + title: TransferReversal + type: + - object + transfer-transaction: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount: + example: 0 + type: + - integer + created: + example: 0 + type: + - integer + currency: + example: '' + type: + - string + customer_details: + example: '' + type: + - string + description: + example: '' + type: + - string + fee: + example: 0 + type: + - integer + fee_details: + example: [] + type: + - array + id: + example: '' + type: + - string + net: + example: 0 + type: + - integer + type: + example: '' + type: + - string + identity: + "$ref": "#/definitions/transfer-transaction/definitions/resource_id" + links: + - title: AllTransferTransactionsMethod + method: GET + rel: self + href: "/v1/transfers/{%23%2Fdefinitions%2Ftransfer-transaction%2Fdefinitions%2Fidentity}/transactions" + targetSchema: + type: + - object + properties: + has_more: + example: false + type: + - boolean + data: + type: + - array + items: + "$ref": "#/definitions/transfer-transaction" + url: + example: "/v1/transfers/{%23%2Fdefinitions%2Ftransfer-transaction%2Fdefinitions%2Fidentity}/transactions" + type: + - string + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + limit: + example: 0 + type: + - integer + description: A limit on the number of objects to be returned. Limit can + range between 1 and 100 items. + starting_after: + example: '' + type: + - string + description: A cursor for use in pagination. `starting_after` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, ending with `obj_foo`, your subsequent + call can include `starting_after=obj_foo` in order to fetch the next + page of the list. + ending_before: + example: '' + type: + - string + description: A cursor for use in pagination. `ending_before` is an object + ID that defines your place in the list. For instance, if you make a + list request and receive 100 objects, starting with `obj_bar`, your + subsequent call can include `ending_before=obj_bar` in order to fetch + the previous page of the list. + old_api_style: + example: false + type: + - boolean + properties: + amount: + "$ref": "#/definitions/transfer-transaction/definitions/amount" + created: + "$ref": "#/definitions/transfer-transaction/definitions/created" + currency: + "$ref": "#/definitions/transfer-transaction/definitions/currency" + customer_details: + "$ref": "#/definitions/transfer-transaction/definitions/customer_details" + description: + "$ref": "#/definitions/transfer-transaction/definitions/description" + fee: + "$ref": "#/definitions/transfer-transaction/definitions/fee" + fee_details: + "$ref": "#/definitions/transfer-transaction/definitions/fee_details" + id: + "$ref": "#/definitions/transfer-transaction/definitions/id" + net: + "$ref": "#/definitions/transfer-transaction/definitions/net" + type: + "$ref": "#/definitions/transfer-transaction/definitions/type" + required: + - amount + - created + - currency + - fee + - fee_details + - id + - net + - type + title: TransferTransaction + type: + - object + upcoming-invoice: + "$schema": http://json-schema.org/draft-04/hyper-schema + definitions: + amount_due: + description: Final amount due at this time for this invoice. If the invoice's + total is smaller than the minimum charge amount, for example, or if there + is account credit that can be applied to the invoice, the `amount_due` may + be 0. If there is a positive `starting_balance` for the invoice (the customer + owes money), the amount_due will also take that into account. The charge + that gets generated for the invoice will be for the amount specified in + `amount_due`. + example: 0 + type: + - integer + application_fee: + description: The fee in %s that will be applied to the invoice and transferred + to the application owner's Stripe account when the invoice is paid. + example: 0 + type: + - integer + attempt_count: + description: Number of payment attempts made for this invoice, from the perspective + of the payment retry schedule. Any payment attempt counts as the first + attempt, and subsequently only automatic retries increment the attempt count. In + other words, manual payment attempts after the first attempt do not affect + the retry schedule. + example: 0 + type: + - integer + attempted: + description: Whether or not an attempt has been made to pay the invoice. An + invoice is not attempted until 1 hour after the `invoice.created` webhook, + for example, so you might not want to display that invoice as unpaid to + your users. + example: false + type: + - boolean + charge: + description: ID of the latest charge generated for this invoice, if any. + example: '' + type: + - string + closed: + description: Whether or not the invoice is still trying to collect payment. + An invoice is closed if it's either paid or it has been marked closed. A + closed invoice will no longer attempt to collect payment. + example: false + type: + - boolean + currency: + example: '' + type: + - string + customer: + example: '' + type: + - string + date: + example: 0 + type: + - integer + description: + example: '' + type: + - string + discount: + example: {} + type: + - object + ending_balance: + description: Ending customer balance after attempting to pay invoice. If + the invoice has not been attempted yet, this will be null. + example: 0 + type: + - integer + forgiven: + description: Whether or not the invoice has been forgiven. Forgiving an invoice + instructs us to update the subscription status as if the invoice were succcessfully + paid. Once an invoice has been forgiven, it cannot be unforgiven or reopened + example: false + type: + - boolean + lines: + description: 'The individual line items that make up the invoice. `lines` + is sorted as follows: invoice items in reverse chronological order, followed + by the subscription, if any.' + example: [] + type: + - array + livemode: + example: false + type: + - boolean + metadata: + description: A set of key/value pairs that you can attach to an invoice object. + It can be useful for storing additional information about the invoice in + a structured format. + example: {} + type: + - object + next_payment_attempt: + description: The time at which payment will next be attempted. + example: 0 + type: + - integer + object: + example: '' + type: + - string + paid: + description: Whether or not payment was successfully collected for this invoice. An + invoice can be paid (most commonly) with a charge or with credit from the + customer's account balance. + example: false + type: + - boolean + period_end: + description: End of the usage period during which invoice items were added + to this invoice + example: 0 + type: + - integer + period_start: + description: Start of the usage period during which invoice items were added + to this invoice + example: 0 + type: + - integer + receipt_number: + description: This is the transaction number that appears on email receipts + sent for this invoice. + example: '' + type: + - string + starting_balance: + description: Starting customer balance before attempting to pay invoice. If + the invoice has not been attempted yet, this will be the current customer + balance. + example: 0 + type: + - integer + statement_descriptor: + description: Extra information about an invoice for the customer's credit + card statement. + example: '' + type: + - string + subscription: + description: The subscription that this invoice was prepared for, if any. + example: '' + type: + - string + subscription_proration_date: + description: Only set for upcoming invoices that preview prorations. The time + used to calculate prorations. + example: 0 + type: + - integer + subtotal: + description: Total of all subscriptions, invoice items, and prorations on + the invoice before any discount is applied + example: 0 + type: + - integer + tax: + description: The amount of tax included in the total, calculated from `tax_percent` + and the subtotal. If no `tax_percent` is defined, this value will be null. + example: 0 + type: + - integer + tax_percent: + description: This percentage of the subtotal has been added to the total amount + of the invoice, including invoice line items and discounts. This field is + inherited from the subscription's `tax_percent` field, but can be changed + before the invoice is paid. This field defaults to null. + example: 0.0 + type: + - number + total: + description: Total after discount + example: 0 + type: + - integer + webhooks_delivered_at: + description: The time at which webhooks for this invoice were successfully + delivered (if the invoice had no webhooks to deliver, this will match `date`). Invoice + payment is delayed until webhooks are delivered, or until all webhook delivery + attempts have been exhausted. + example: 0 + type: + - integer + links: + - title: Retrieve an upcoming invoice + method: GET + rel: self + href: "/v1/invoices/upcoming" + targetSchema: + "$ref": "#/definitions/upcoming-invoice" + description: |- + At any time, you can preview the upcoming invoice for a customer. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discount that is applicable to the customer.

+ +

Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer’s discount.

+ +

You can preview the effects of updating a subscription, including a preview of what proration will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass a proration_date parameter when doing the actual subscription update. The value passed in should be the same as the subscription_proration_date returned on the upcoming invoice resource. The recommended way to get only the prorations being previewed is to consider only proration line items where period[start] is equal to the subscription_proration_date on the upcoming invoice resource. + encType: application/x-www-form-urlencoded + schema: + type: object + properties: + customer: + example: '' + type: + - string + description: The identifier of the customer whose upcoming invoice you'd + like to retrieve. + subscription: + example: '' + type: + - string + description: The identifier of the subscription for which you'd like to + retrieve the upcoming invoice. If not provided, but a `subscription_plan` + is provided, you will preview creating a subscription to that plan. + If neither `subscription` nor `subscription_plan` is provided, you will + retrieve the next upcoming invoice from among the customer's subscriptions. + subscription_plan: + example: '' + type: + - string + description: If set, the invoice returned will preview updating the subscription + given to this plan, or creating a new subscription to this plan if no + `subscription` is given. + subscription_quantity: + example: 0 + type: + - integer + description: If provided, the invoice returned will preview updating or + creating a subscription with that quantity. If set, one of `subscription_plan` + or `subscription` is required. + subscription_prorate: + example: false + type: + - boolean + description: If previewing an update to a subscription, this decides whether + the preview will show the result of applying prorations or not. If set, + one of `subscription_plan` or `subscription`, and one of `subscription_plan`, + `subscription_quantity` or `subscription_trial_end` are required. + subscription_proration_date: + example: 0 + type: + - integer + description: If previewing an update to a subscription, and doing proration, + `subscription_proration_date` forces the proration to be calculated + as though the update was done at the specified time. The time given + must be within the current subscription period, and cannot be before + the subscription was on its current plan.If set, `subscription`, and + one of `subscription_plan`, `subscription_quantity` or `subscription_trial_end` + are required. Also, `subscription_proration` cannot be set to false. + subscription_trial_end: + example: 0 + type: + - integer + description: If provided, the invoice returned will preview updating or + creating a subscripton with that trial end. If set, one of `subscription_plan` + or `subscription` is required. + required: + - customer + properties: + amount_due: + "$ref": "#/definitions/upcoming-invoice/definitions/amount_due" + application_fee: + "$ref": "#/definitions/upcoming-invoice/definitions/application_fee" + attempt_count: + "$ref": "#/definitions/upcoming-invoice/definitions/attempt_count" + attempted: + "$ref": "#/definitions/upcoming-invoice/definitions/attempted" + charge: + "$ref": "#/definitions/upcoming-invoice/definitions/charge" + closed: + "$ref": "#/definitions/upcoming-invoice/definitions/closed" + currency: + "$ref": "#/definitions/upcoming-invoice/definitions/currency" + customer: + "$ref": "#/definitions/upcoming-invoice/definitions/customer" + date: + "$ref": "#/definitions/upcoming-invoice/definitions/date" + description: + "$ref": "#/definitions/upcoming-invoice/definitions/description" + discount: + "$ref": "#/definitions/upcoming-invoice/definitions/discount" + ending_balance: + "$ref": "#/definitions/upcoming-invoice/definitions/ending_balance" + forgiven: + "$ref": "#/definitions/upcoming-invoice/definitions/forgiven" + lines: + "$ref": "#/definitions/upcoming-invoice/definitions/lines" + livemode: + "$ref": "#/definitions/upcoming-invoice/definitions/livemode" + metadata: + "$ref": "#/definitions/upcoming-invoice/definitions/metadata" + next_payment_attempt: + "$ref": "#/definitions/upcoming-invoice/definitions/next_payment_attempt" + object: + "$ref": "#/definitions/upcoming-invoice/definitions/object" + paid: + "$ref": "#/definitions/upcoming-invoice/definitions/paid" + period_end: + "$ref": "#/definitions/upcoming-invoice/definitions/period_end" + period_start: + "$ref": "#/definitions/upcoming-invoice/definitions/period_start" + receipt_number: + "$ref": "#/definitions/upcoming-invoice/definitions/receipt_number" + starting_balance: + "$ref": "#/definitions/upcoming-invoice/definitions/starting_balance" + statement_descriptor: + "$ref": "#/definitions/upcoming-invoice/definitions/statement_descriptor" + subscription: + "$ref": "#/definitions/upcoming-invoice/definitions/subscription" + subscription_proration_date: + "$ref": "#/definitions/upcoming-invoice/definitions/subscription_proration_date" + subtotal: + "$ref": "#/definitions/upcoming-invoice/definitions/subtotal" + tax: + "$ref": "#/definitions/upcoming-invoice/definitions/tax" + tax_percent: + "$ref": "#/definitions/upcoming-invoice/definitions/tax_percent" + total: + "$ref": "#/definitions/upcoming-invoice/definitions/total" + webhooks_delivered_at: + "$ref": "#/definitions/upcoming-invoice/definitions/webhooks_delivered_at" + required: + - amount_due + - attempt_count + - attempted + - closed + - currency + - customer + - date + - forgiven + - lines + - livemode + - object + - paid + - period_end + - period_start + - starting_balance + - subtotal + - total + title: UpcomingInvoice + type: + - object +description: The Stripe API empowers developers to easily accept payments online and + in mobile apps. +id: https://api.stripe.com# +links: +- href: https://api.stripe.com + rel: self +- href: "/schema" + method: GET + rel: self + targetSchema: + additionalProperties: true +properties: + account: + "$ref": "#/definitions/account" + account-authorization: + "$ref": "#/definitions/account-authorization" + account-with-keys: + "$ref": "#/definitions/account-with-keys" + alipay-account: + "$ref": "#/definitions/alipay-account" + balance: + "$ref": "#/definitions/balance" + balance-transaction: + "$ref": "#/definitions/balance-transaction" + bitcoin-receiver: + "$ref": "#/definitions/bitcoin-receiver" + bitcoin-transaction: + "$ref": "#/definitions/bitcoin-transaction" + charge: + "$ref": "#/definitions/charge" + coupon: + "$ref": "#/definitions/coupon" + customer: + "$ref": "#/definitions/customer" + discount: + "$ref": "#/definitions/discount" + dispute: + "$ref": "#/definitions/dispute" + event: + "$ref": "#/definitions/event" + fee-refund: + "$ref": "#/definitions/fee-refund" + invoice: + "$ref": "#/definitions/invoice" + invoice-item: + "$ref": "#/definitions/invoice-item" + invoice-line-item: + "$ref": "#/definitions/invoice-line-item" + order: + "$ref": "#/definitions/order" + payment-bank-account: + "$ref": "#/definitions/payment-bank-account" + payment-card: + "$ref": "#/definitions/payment-card" + plan: + "$ref": "#/definitions/plan" + platform-earning: + "$ref": "#/definitions/platform-earning" + product: + "$ref": "#/definitions/product" + recipient-payout-card: + "$ref": "#/definitions/recipient-payout-card" + refund: + "$ref": "#/definitions/refund" + sku: + "$ref": "#/definitions/sku" + subscription: + "$ref": "#/definitions/subscription" + system-refund: + "$ref": "#/definitions/system-refund" + token: + "$ref": "#/definitions/token" + transfer: + "$ref": "#/definitions/transfer" + transfer-recipient: + "$ref": "#/definitions/transfer-recipient" + transfer-reversal: + "$ref": "#/definitions/transfer-reversal" + transfer-transaction: + "$ref": "#/definitions/transfer-transaction" + upcoming-invoice: + "$ref": "#/definitions/upcoming-invoice" +title: Stripe API - 2015-10-16 diff --git a/stripe.gemspec b/stripe.gemspec index 47c8ab550..14dd6dcaa 100644 --- a/stripe.gemspec +++ b/stripe.gemspec @@ -16,10 +16,13 @@ spec = Gem::Specification.new do |s| s.add_dependency('rest-client', '~> 1.4') s.add_dependency('json', '~> 1.8.1') + s.add_development_dependency('committee', '~> 1.12.0') s.add_development_dependency('mocha', '~> 0.13.2') s.add_development_dependency('shoulda', '~> 3.4.0') s.add_development_dependency('test-unit') s.add_development_dependency('rake') + s.add_development_dependency('sinatra') + s.add_development_dependency('webmock') # to avoid problems, bring Byebug in on just versions of Ruby under which # it's known to work well diff --git a/test/stripe/account_test.rb b/test/stripe/account_test.rb index bf65d4200..f9647b0bc 100644 --- a/test/stripe/account_test.rb +++ b/test/stripe/account_test.rb @@ -2,20 +2,38 @@ module Stripe class AccountTest < Test::Unit::TestCase - should "be retrievable" do - resp = make_account({ - :charges_enabled => false, - :details_submitted => false, - :email => "test+bindings@stripe.com", - }) - @mock.expects(:get). - once. - with('https://api.stripe.com/v1/account', nil, nil). - returns(make_response(resp)) - a = Stripe::Account.retrieve - assert_equal "test+bindings@stripe.com", a.email - assert !a.charges_enabled - assert !a.details_submitted + should "be retrievable with generated responses" do + without_legacy_stubs do + stub_api do + get "/v1/account" do + generated_response.merge!({ + :charges_enabled => false, + :details_submitted => false, + :email => "test+bindings@stripe.com", + }) + end + end + + a = Stripe::Account.retrieve + assert_equal "test+bindings@stripe.com", a.email + assert !a.charges_enabled + assert !a.details_submitted + + assert_requested :get, "#{Stripe.api_url}/v1/account" + end + end + + # This test is made to demonstrate that we could offer a potential route + # for very easy-to-build tests that provide a very basic check that a + # method hits an API endpoint and responds with something. The idea here is + # that it could help our situation where tests are hard to write + # (especially for new resources that need new `TestData`, and are therefore + # not written). + should "be retrievable with generated responses (easy edition)" do + without_legacy_stubs do + Stripe::Account.retrieve + assert_requested :get, "#{Stripe.api_url}/v1/account" + end end should "be retrievable via plural endpoint" do diff --git a/test/test_helper.rb b/test/test_helper.rb index 3d007e2da..f757268c3 100644 --- a/test/test_helper.rb +++ b/test/test_helper.rb @@ -1,10 +1,17 @@ require 'stripe' +require 'committee' +require 'json_schema' require 'test/unit' require 'mocha/setup' -require 'stringio' require 'shoulda' +require 'sinatra' +require 'stringio' +require 'webmock/test_unit' + require File.expand_path('../test_data', __FILE__) +$execute_request_stub = true + # monkeypatch request methods module Stripe @mock_rest_client = nil @@ -13,29 +20,139 @@ def self.mock_rest_client=(mock_client) @mock_rest_client = mock_client end - def self.execute_request(opts) - get_params = (opts[:headers] || {})[:params] - post_params = opts[:payload] - case opts[:method] - when :get then @mock_rest_client.get opts[:url], get_params, post_params - when :post then @mock_rest_client.post opts[:url], get_params, post_params - when :delete then @mock_rest_client.delete opts[:url], get_params, post_params + # A little context here: the Stripe tests work traditionally by defining a + # single method that all HTTP requests go through (`Stripe.execute_request`) + # and then monkey patching so that no HTTP requests were made. + # + # For our next generation we want to test with some slightly more + # sophisticated techniques so we don't want these monkey patches applied. + # This introduces some testing infrastructure that allows them to be disabled + # conditionally using a helper that takes a block. Unfortunately the mechanic + # uses a global variable to work, but should be a short-lived measure. + class << self + alias :execute_request_regular :execute_request + + def execute_request(opts) + if $execute_request_stub + execute_request_stub(opts) + else + execute_request_regular(opts) + end + end + + def execute_request_stub(opts) + get_params = (opts[:headers] || {})[:params] + post_params = opts[:payload] + case opts[:method] + when :get then @mock_rest_client.get opts[:url], get_params, post_params + when :post then @mock_rest_client.post opts[:url], get_params, post_params + when :delete then @mock_rest_client.delete opts[:url], get_params, post_params + end + end + end +end + +# Provides a set of helpers for a test suite that help to mock out the Stripe +# API. +module StubHelpers + protected + + # Uses Webmock to stub out the Stripe API for testing purposes. The stub will + # by default respond on any routes that are defined in the bundled + # hyper-schema with generated response data. + # + # An `override_app` can be specified to get finer grain control over how a + # stubbed endpoint responds. It can be used to modify generated responses, + # mock expectations, or even to override the default stub completely. + def stub_api(override_app = nil, &block) + if block + override_app = Sinatra.new(OverrideSinatra, &block) + elsif !override_app + override_app = @@default_override_app + end + + stub_request(:any, /^#{Stripe.api_url}/).to_rack(new_api_stub(override_app)) + end + + private + + # A descendant of the standard `Sinatra::Base` with some added helpers to + # make working with generated responses more convenient. + class OverrideSinatra < Sinatra::Base + # The hash of data generated based on hyper-schema information for the + # requested route of the API. + # + # It's also worth nothing that this could be `nil` in the event of the + # schema not knowing how to respond to the requested route. + def generated_response + env["committee.response"] end + + # This instructs the response stubbing framework that it should *not* + # respond with a generated response on this request. Instead, control is + # wholly given over to the override method. + def override_response! + env["committee.suppress"] = true + end + end + + # Finds the latest schema in ROOT/schema/ and parses it for use with + # Committee. + def self.initialize_schema + path = File.expand_path("../../schema/", __FILE__) + file = Dir["#{path}/*.yaml"].last + schema_str = ::YAML.load(File.read(file)) + schema = JsonSchema.parse!(schema_str) + schema.expand_references! + schema end + + # Creates a new Rack app with Committee middleware wrapping an internal app. + def new_api_stub(override_app) + Rack::Builder.new { + use Committee::Middleware::RequestValidation, :schema => @@schema + use Committee::Middleware::Stub, :call => true, :schema => @@schema + run override_app + } + end + + # Parse and initialize the hyper-schema only once for the entire test suite. + @@schema = initialize_schema + + # The default override app. Doesn't respond on any route so generated + # responses will always take precedence. + @@default_override_app = Sinatra.new end class Test::Unit::TestCase include Stripe::TestData + include StubHelpers include Mocha setup do @mock = mock Stripe.mock_rest_client = @mock Stripe.api_key = "foo" + + # Stub the Stripe API with a default stub. Note that this method can be + # called again in test bodies in order to override responses on particular + # endpoints. + stub_api end teardown do Stripe.mock_rest_client = nil Stripe.api_key = nil end + + # Helper that disables the monkey patching on `Stripe.execute_request` for + # the duration of the given block. Useful for the move over from + # manually-generated responses to those generated from a hyper-schema. + def without_legacy_stubs + old = $execute_request_stub + $execute_request_stub = false + yield + ensure + $execute_request_stub = old + end end