Bitcoin Payments with Sources

Payments

Subscriptions

  • Overview
  • Quickstart
  • Account Types
  • Accounts Overview
  • Standard
  • Express
  • Custom-made
    • Updating Accounts
    • Identity Verification
    • Required Info
  • Processing Payments
  • Creating Charges
    • Direct Charges
    • Destination Charges
    • Separate Charges and Transfers
  • Account Debits
  • Using Subscriptions
  • Numerous Currencies
  • Account Balances
  • Bank Payouts
  • Best Practices
  • Migrating
  • OAuth Reference
  • Webhooks
  • Testing

Radar

Account

Atlas

Bitcoin Payments with Sources

Use Sources to accept payments using Bitcoin, the popular digital cryptocurrency.

Stripe users in the United States can accept Bitcoin for USD payments from customers using Sources—a single integration path for creating payments using any supported method.

During the payment process, a Source object is created and your customer is given a receiver address to send the required amount of bitcoin to. Your customer uses this information with their Bitcoin wallet service or app to send the bitcoin amount needed. After completing this, your integration uses the source to make a charge request and accomplish the payment.

Bitcoin is a push-based and single-use method of payment. This means your customer must take activity to send the required amount of bitcoin to you. The pushing of funds may take a few minutes since your customer must do this outside of your checkout flow, but the amount is instantaneously available as soon as the funds have been received. Once the source is chargeable, there can be instant confirmation about the success or failure of a payment.

Quickstart using Checkout

The simplest way to accept Bitcoin is with Checkout. After integrating Checkout for card payments, only one code switch is needed to begin accepting Bitcoin payments—the addition of data-bitcoin=”true” in the form’s code:

After specifying the amount in USD that you want to receive, Stripe treats displaying the converted amount in BTC that your customer needs to pay. Once a Bitcoin payment is received, Checkout submits the form with the following extra fields:

  • stripeToken : The ID of the chargeable Source object
  • stripeTokenType : The type of token returned—the value is source_bitcoin
  • stripeEmail : The email address provided by the customer

You can then instantaneously make a charge request using the source.

Step 1: Create a Source object

Stripe.js reference

This guide supplements our Stripe.js and Elements documentation with specific usage for Sources. Refer to this if you need further information on using Stripe.js or Elements.

If you want to build a custom-made integration for accepting Bitcoin, a Source object can be created client-side using Stripe.js or server-side using the API.

To create a source with Stripe.js, very first include the library within your payment page and set your publishable API key.

Once included, use the following source.create method to create a source, providing the following information:

Server-side source creation

The use of Stripe.js to create this type of source is optional, but very recommended. If you forgo this step and pass the information directly to Stripe when creating a Source object, you must take adequate steps to safeguard any sensitive information that may pass through your servers.

Using either method, Stripe comebacks a Source object containing the relevant details for the specified method of payment.

Error codes

Source creation for Bitcoin payments may comeback any of the following errors:

Step Two: Have the customer thrust funds

When creating a source, its status is primarily set to pending and cannot yet be used to create a charge. Your customer must send the specified amount of bitcoin to make the source chargeable. Customers thrust bitcoin to the address provided within the receiver[address] attribute. The bitcoin[amount] specifies the amount, in BTC, the customer needs to send.

There are three lumps of information you should display to the customer:

  • bitcoin[amount] : The amount (in Satoshi) that the customer must send. This amount, like all amounts used by the Stripe API, represents the smallest unit of currency. There are ten 8 (100,000,000) satoshi in one bitcoin, so the returned bitcoin[amount] must be divided by 100,000,000 to present the amount in BTC.
  • receiver[address] : The bitcoin address that is specific to this receiver
  • bitcoin[uri] : An encoding of the amount and address. If you encode this URI as a QR code, some Bitcoin apps can scan it. If this URI is introduced as a hyperlink, customers can click on it to activate their preferred Bitcoin client, if installed.

Step Three: Charge the Source

Using webhooks

Your integration needs to use webhooks to be notified of status switches on Source and Charge objects.

Once the customer has shoved the necessary funds, the source’s status transitions to chargeable and it can be used to make a charge request. This transitions happens asynchronously as confirming a Bitcoin transaction on the blockchain can take minutes.

For this reason it is essential that your integration rely on webhooks to determine when the source becomes chargeable in order to create a charge. Please refer to our best practices for more details on how to best integrate payment methods using webhooks.

Webhooks

The following webhook events are sent to notify you about switches to the source’s status:

Source expiration

A Bitcoin source must be used within six hours of becoming chargeable . If it is not, its status is automatically transitioned to canceled and your integration receives a source.canceled webhook event.

Similarly, a Bitcoin source’s ensured exchange rate expires after ten minutes, after which point it is canceled. Your JavaScript handler is called client-side and the source’s status transitions to canceled . Any fund received after a source is canceled are automatically refunded back to the customer.

Once a source is canceled, the customer’s bitcoin payment is refunded automatically—no funds are moved into your account. For this reason, make sure the order is canceled on your end and the customer is notified once you receive the source.canceled event.

If you receive that callback, you can instruct your servers to create a fresh source, then update the payment page with the fresh receiver’s information and begin polling.

Make a charge request using the source

Once the source is chargeable, from your source.chargeable webhook handler, you can make a charge request using the source ID as the value for the source parameter to accomplish the payment.

Bitcoin Sources are single-use and cannot not be used for recurring or extra payments. Refer to our Sources & Customers guide for more information on how single-use Sources interact with Customers.

Step Four: Confirm that the charge has succeeded

Since the customer has already shoved the funds at the time the Source is chargeable , unless there is an unexpected error, the Charge will instantaneously succeed.

You will also receive the following webhook event as the charge is created:

We recommend that you rely on the charge.succeeded webhook event to notify your customer that the payment process has been finished and their order is confirmed. Please refer to our best practices for more details on how to best integrate payment methods using webhooks.

Refunding Bitcoin payments

Bitcoin payments can be refunded through either the Dashboard or API. However, the Bitcoin address where to come back the funds needs to be provided by the customer. By default, we automatically contact the customer at the email address provided during source creation when a refund is created (or the source is canceled and funds need to be returned). Once the customer provides us with their Bitcoin address, we process the refund automatically.

Some users may want to manage the collection of the refund addresses themselves. Please contact us to learn more about this option.

Treating mispayments

The customer is responsible for sending the correct amount of bitcoin to pack the source. While uncommon, it is possible for a customer to send an unexpected amount that prevents a payment from being completed—resulting in a mispayment. This can happen when:

  • The customer sends too few bitcoin so the payment cannot be finished
  • The customer sends too many bitcoin and needs to be partially refunded
  • The customer sends the correct amount of bitcoin but they send it after too long a delay, or there’s a network error such that the source token is never posted to your server

All mispayments are treated automatically by Stripe. When a source is charged, any unused bitcoin received in excess will be returned to the customer automatically (after collecting their refund address as described in the previous section). Similarly, if a source is never charged, it is eventually canceled and any unused bitcoin is also returned the customer automatically.

You can help avoid the third possibility of mispayments through the use of webhooks. You can configure your integration to receive source.chargeable events, then subsequently create charges from those sources.

Testing Bitcoin payments

When creating a Source object using your test API keys, use one of Stripe’s test email addresses when you need to test Bitcoin payments under different conditions.

Related resources

Questions?

We’re always blessed to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also talk live with other developers in #stripe on freenode.

Bitcoin Payments with Sources

Payments

Subscriptions

  • Overview
  • Quickstart
  • Account Types
  • Accounts Overview
  • Standard
  • Express
  • Custom-built
    • Updating Accounts
    • Identity Verification
    • Required Info
  • Processing Payments
  • Creating Charges
    • Direct Charges
    • Destination Charges
    • Separate Charges and Transfers
  • Account Debits
  • Using Subscriptions
  • Numerous Currencies
  • Account Balances
  • Bank Payouts
  • Best Practices
  • Migrating
  • OAuth Reference
  • Webhooks
  • Testing

Radar

Account

Atlas

Bitcoin Payments with Sources

Use Sources to accept payments using Bitcoin, the popular digital cryptocurrency.

Stripe users in the United States can accept Bitcoin for USD payments from customers using Sources—a single integration path for creating payments using any supported method.

During the payment process, a Source object is created and your customer is given a receiver address to send the required amount of bitcoin to. Your customer uses this information with their Bitcoin wallet service or app to send the bitcoin amount needed. After completing this, your integration uses the source to make a charge request and accomplish the payment.

Bitcoin is a push-based and single-use method of payment. This means your customer must take act to send the required amount of bitcoin to you. The pushing of funds may take a few minutes since your customer must do this outside of your checkout flow, but the amount is instantly available as soon as the funds have been received. Once the source is chargeable, there can be instantaneous confirmation about the success or failure of a payment.

Quickstart using Checkout

The simplest way to accept Bitcoin is with Checkout. After integrating Checkout for card payments, only one code switch is needed to begin accepting Bitcoin payments—the addition of data-bitcoin=”true” in the form’s code:

After specifying the amount in USD that you want to receive, Stripe treats displaying the converted amount in BTC that your customer needs to pay. Once a Bitcoin payment is received, Checkout submits the form with the following extra fields:

  • stripeToken : The ID of the chargeable Source object
  • stripeTokenType : The type of token returned—the value is source_bitcoin
  • stripeEmail : The email address provided by the customer

You can then instantly make a charge request using the source.

Step 1: Create a Source object

Stripe.js reference

This guide supplements our Stripe.js and Elements documentation with specific usage for Sources. Refer to this if you need further information on using Stripe.js or Elements.

If you want to build a custom-made integration for accepting Bitcoin, a Source object can be created client-side using Stripe.js or server-side using the API.

To create a source with Stripe.js, very first include the library within your payment page and set your publishable API key.

Once included, use the following source.create method to create a source, providing the following information:

Server-side source creation

The use of Stripe.js to create this type of source is optional, but very recommended. If you forgo this step and pass the information directly to Stripe when creating a Source object, you must take adequate steps to safeguard any sensitive information that may pass through your servers.

Using either method, Stripe comebacks a Source object containing the relevant details for the specified method of payment.

Error codes

Source creation for Bitcoin payments may comeback any of the following errors:

Step Two: Have the customer thrust funds

When creating a source, its status is primarily set to pending and cannot yet be used to create a charge. Your customer must send the specified amount of bitcoin to make the source chargeable. Customers thrust bitcoin to the address provided within the receiver[address] attribute. The bitcoin[amount] specifies the amount, in BTC, the customer needs to send.

There are three chunks of information you should display to the customer:

  • bitcoin[amount] : The amount (in Satoshi) that the customer must send. This amount, like all amounts used by the Stripe API, represents the smallest unit of currency. There are ten 8 (100,000,000) satoshi in one bitcoin, so the returned bitcoin[amount] must be divided by 100,000,000 to present the amount in BTC.
  • receiver[address] : The bitcoin address that is specific to this receiver
  • bitcoin[uri] : An encoding of the amount and address. If you encode this URI as a QR code, some Bitcoin apps can scan it. If this URI is introduced as a hyperlink, customers can click on it to activate their preferred Bitcoin client, if installed.

Step Trio: Charge the Source

Using webhooks

Your integration needs to use webhooks to be notified of status switches on Source and Charge objects.

Once the customer has shoved the necessary funds, the source’s status transitions to chargeable and it can be used to make a charge request. This transitions happens asynchronously as confirming a Bitcoin transaction on the blockchain can take minutes.

For this reason it is essential that your integration rely on webhooks to determine when the source becomes chargeable in order to create a charge. Please refer to our best practices for more details on how to best integrate payment methods using webhooks.

Webhooks

The following webhook events are sent to notify you about switches to the source’s status:

Source expiration

A Bitcoin source must be used within six hours of becoming chargeable . If it is not, its status is automatically transitioned to canceled and your integration receives a source.canceled webhook event.

Similarly, a Bitcoin source’s ensured exchange rate expires after ten minutes, after which point it is canceled. Your JavaScript handler is called client-side and the source’s status transitions to canceled . Any fund received after a source is canceled are automatically refunded back to the customer.

Once a source is canceled, the customer’s bitcoin payment is refunded automatically—no funds are moved into your account. For this reason, make sure the order is canceled on your end and the customer is notified once you receive the source.canceled event.

If you receive that callback, you can instruct your servers to create a fresh source, then update the payment page with the fresh receiver’s information and commence polling.

Make a charge request using the source

Once the source is chargeable, from your source.chargeable webhook handler, you can make a charge request using the source ID as the value for the source parameter to finish the payment.

Bitcoin Sources are single-use and cannot not be used for recurring or extra payments. Refer to our Sources & Customers guide for more information on how single-use Sources interact with Customers.

Step Four: Confirm that the charge has succeeded

Since the customer has already shoved the funds at the time the Source is chargeable , unless there is an unexpected error, the Charge will instantly succeed.

You will also receive the following webhook event as the charge is created:

We recommend that you rely on the charge.succeeded webhook event to notify your customer that the payment process has been ended and their order is confirmed. Please refer to our best practices for more details on how to best integrate payment methods using webhooks.

Refunding Bitcoin payments

Bitcoin payments can be refunded through either the Dashboard or API. However, the Bitcoin address where to comeback the funds needs to be provided by the customer. By default, we automatically contact the customer at the email address provided during source creation when a refund is created (or the source is canceled and funds need to be returned). Once the customer provides us with their Bitcoin address, we process the refund automatically.

Some users may want to manage the collection of the refund addresses themselves. Please contact us to learn more about this option.

Treating mispayments

The customer is responsible for sending the correct amount of bitcoin to pack the source. While uncommon, it is possible for a customer to send an unexpected amount that prevents a payment from being completed—resulting in a mispayment. This can happen when:

  • The customer sends too few bitcoin so the payment cannot be ended
  • The customer sends too many bitcoin and needs to be partially refunded
  • The customer sends the correct amount of bitcoin but they send it after too long a delay, or there’s a network error such that the source token is never posted to your server

All mispayments are treated automatically by Stripe. When a source is charged, any unused bitcoin received in excess will be returned to the customer automatically (after collecting their refund address as described in the previous section). Similarly, if a source is never charged, it is eventually canceled and any unused bitcoin is also returned the customer automatically.

You can help avoid the third possibility of mispayments through the use of webhooks. You can configure your integration to receive source.chargeable events, then subsequently create charges from those sources.

Testing Bitcoin payments

When creating a Source object using your test API keys, use one of Stripe’s test email addresses when you need to test Bitcoin payments under different conditions.

Related resources

Questions?

We’re always blessed to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also talk live with other developers in #stripe on freenode.

Related video:

Leave a Reply

Your email address will not be published. Required fields are marked *