Setting up the auth/capture flow for orders
This guide provides the necessary steps to configure an auth/capture flow for orders.
Platform:
- Custom
Before you start
- Your store settings need to be updated to enable auth/capture. Contact Recharge support to get this enabled. Specify if you’d like auth/capture on checkout orders only, or on recurring orders as well.
- The API token you're using to send the request may also need permissions to write_checkouts. Recharge support can assist you with this as well.
- If a charge is left pending, it will expire after 7 days. This is due to a payment processor limitation. On the 6th day, Recharge will emit a charge/uncaptured webhook to remind you to capture or cancel the charge.
Configure the auth/capture flow
To configure the auth/capture flow, you will create the pending order, listen to the charge/created webhook, and capture the pending charge.
Step 1 - Use the POST checkouts/import route to create the customer, address, subscription, and authorize the charge
You may need to generate a nonce. After your store is setup correctly, you can hit the checkouts/import route endpoint. Make sure to include the payment nonce so that the payment method gets created correctly.
{
"checkout": {
"billing_address": {
"address1": "1234 Test",
"address2": "",
"city": "Los Angeles",
"company": "",
"country_code": "US",
"first_name": "Natasha",
"last_name": "Test",
"phone": "null",
"province": "California",
"zip": "90007"
},
"created_at": "2023-08-14T17:13:43+00:00",
"currency": "USD",
"email": "[email protected]",
"external_checkout_id": "2af0f994-ff5d-4881-a9d9-ce33f1723ea7",
"external_checkout_source": "headless",
"line_items": [{
"id": 0,
"external_inventory_policy": "decrement_obeying_policy",
"external_product_id": {
"ecommerce": "123"
},
"external_variant_id": {
"ecommerce": "201"
},
"handle": "test product",
"images": {
"original": "https://cdn11.bigcommerce.com/s-eqef6gb637/products/132/images/396/photo-1590005024862-6b67679a29fb__38980.1642025687.386.513__45733.1650483624.220.290.jpg?c=1"
},
"properties": [],
"purchase_item_type": "subscription",
"quantity": 1,
"requires_shipping": true,
"sku": "subonly-variants-RE-1",
"subscription_preferences": {
"charge_interval_frequency": 1,
"order_interval_frequency": 1,
"interval_unit": "month"
},
"taxable": true,
"title": "test product",
"total_price": 77.27,
"unit_price": 73.59,
"recurring_unit_price": 73.59,
"variant_title": "Color -> Red",
"weight": 708,
"weight_unit": "g"
}],
"note": "",
"order_attributes": [{
"name": "store_credit_amount",
"value": 0.0
}, {
"name": "customerGroup",
"value": {}
}, {
"name": "cartId",
"value": "2af0f994-ff5d-4881-a9d9-ce33f1723ea7"
}],
"payment_data": [{
"payment_processor": "braintree",
"processor_payment_method_token": "tokencc_bc_srg647_nv8c9t_dch552_2348n7_5t3"
}],
"payment_processor": "braintree",
"requires_shipping": true,
"shipping_address": {
"address1": "1234 Test",
"address2": "",
"city": "Los Angeles",
"company": "",
"country_code": "US",
"first_name": "Natasha",
"last_name": "Test",
"phone": "null",
"province": "California",
"zip": "90007"
},
"shipping_lines": [{
"code": "592bf99edab2ade4be599e1d049c0b29",
"price": 7.0,
"source": "BigCommerce",
"tax_lines": [{
"rate": "0.0494752623688156",
"price": 0.33000000000000007,
"title": "Tax on Shipping"
}],
"taxable": true,
"title": "Flat Rate",
"handle": "shipping_flatrate"
}],
"subtotal_price": 77.27,
"tax_lines": [{
"rate": "0",
"price": 4.01,
"title": "Tax"
}],
"taxable": true,
"taxes_included": true,
"total_price": 84.27,
"total_tax": 4.01,
"updated_at": "2023-08-14T17:14:36+00:00",
"send_avalara_invoice": false
}
}
{
"checkout": {
"charge_id": 884059485,
"analytics_data": {
"utm_params": []
},
"applied_discounts": [],
"applied_shipping_rate": {},
"available_shipping_rates": [],
"billing_address": {
"address1": "1234 Test",
"address2": null,
"city": "Los Angeles",
"company": null,
"country_code": null,
"first_name": "Natasha",
"last_name": "Lioe",
"phone": "null",
"province": "California",
"zip": "90007"
},
"completed_at": null,
"created_at": "2023-08-14T17:24:46+00:00",
"currency": "USD",
"custom_shipping_rate_options": [],
"email": "[email protected]",
"external_checkout_id": "2af0f994-ff5d-4881-a9d9-ce33f1723ea7",
"external_checkout_source": "headless",
"external_customer_id": {
"ecommerce": null,
"payment_processor": null
},
"external_transaction_id": {
"payment_processor": null
},
"line_items": [
{
"id": null,
"external_inventory_policy": null,
"external_product_id": {
"ecommerce": null
},
"external_variant_id": {
"ecommerce": null
},
"handle": "test product",
"images": {},
"properties": null,
"purchase_item_type": null,
"quantity": 1,
"recurring_unit_price": "73.59",
"requires_shipping": true,
"sku": "subonly-variants-RE-1",
"subscription_preferences": {
"charge_interval_frequency": null,
"cutoff_day_of_month": null,
"cutoff_day_of_week": null,
"expire_after_specific_number_of_charges": null,
"interval_unit": null,
"order_day_of_month": null,
"order_day_of_week": null,
"order_interval_frequency": null
},
"tax_lines": [],
"taxable": true,
"title": "test product",
"total_price": "0.00",
"unit_price": "0.00",
"variant_title": "Color -> Red",
"weight": 708,
"weight_unit": "g"
}
],
"note": null,
"notification_preferences": {
"email": {
"promotional": {
"last_opt_in_at": null,
"last_opt_in_source": null,
"last_opt_out_at": null,
"last_opt_out_source": null,
"status": "unspecified"
},
"replenishment": {
"last_opt_in_at": null,
"last_opt_in_source": null,
"last_opt_out_at": null,
"last_opt_out_source": null,
"status": "unspecified"
},
"transactional": {
"last_opt_in_at": null,
"last_opt_in_source": null,
"last_opt_out_at": null,
"last_opt_out_source": null,
"status": "unspecified"
}
},
"sms": {
"promotional": {
"last_opt_in_at": null,
"last_opt_in_source": null,
"last_opt_out_at": null,
"last_opt_out_source": null,
"status": "unspecified"
},
"replenishment": {
"last_opt_in_at": null,
"last_opt_in_source": null,
"last_opt_out_at": null,
"last_opt_out_source": null,
"status": "unspecified"
},
"transactional": {
"last_opt_in_at": null,
"last_opt_in_source": null,
"last_opt_out_at": null,
"last_opt_out_source": null,
"status": "unspecified"
}
}
},
"order_attributes": null,
"payment_processor": null,
"requires_shipping": true,
"shipping_address": {
"address1": "1234 Test",
"address2": null,
"city": "Los Angeles",
"company": null,
"country_code": null,
"first_name": "Natasha",
"last_name": "Lioe",
"phone": "null",
"province": "California",
"zip": "90007"
},
"shipping_lines": [
{
"code": "592bf99edab2ade4be599e1d049c0b29",
"price": "7.00",
"source": "BigCommerce",
"tax_lines": [
{
"price": "0.330",
"rate": "0.0494752623688156",
"title": "Tax on Shipping"
}
],
"taxable": true,
"title": "Flat Rate"
}
],
"subtotal_price": "73.59",
"tax_lines": [
{
"price": "4.01",
"rate": "0",
"title": "Tax"
}
],
"taxable": false,
"taxes_included": false,
"token": "2f8e95aef21e4989b9682400ce47cf95",
"total_price": "84.27",
"total_tax": "4.01",
"updated_at": "2023-08-14T17:24:46+00:00"
}
}
This makes the customer, subscription, and payment method. The order is saved in pending status and does not show up in the Orders tab yet.
Step 2 - Listen to the charge/created webhook
For status PENDING
With this information, you can listen to the webhook and perform actions, such as checking its inventory system. If the charge is good to go through, add the 2021-11 version of the webhook by passing the version in the body.
{
"address":"https://engxi90onzqh.x.pipedream.net/",
"topic":"charge/created",
"version": "2021-11"
}
Take the charge id from the payload and then capture the charge when ready
{
"charge": {
"id": 884909434,
"address_id": 131451201,
"analytics_data": {
"utm_params": []
},
"billing_address": {
"address1": "1234 Test",
"address2": null,
"city": "Los Angeles",
"company": null,
"country_code": "US",
"first_name": "Natasha",
"last_name": "Lioe",
"phone": null,
"province": "California",
"zip": "90007"
},
"client_details": {
"browser_ip": "104.162.239.56",
"user_agent": "PostmanRuntime/7.32.3"
},
"created_at": "2023-08-15T18:20:27+00:00",
"currency": "USD",
"customer": {
"id": 120261051,
"email": "[email protected]",
"external_customer_id": {
"ecommerce": null
},
"hash": "1dba5a67feccc2656ec2f9506ccddf"
},
"discounts": [],
"error": null,
"error_type": null,
"external_order_id": {
"ecommerce": null
},
"external_transaction_id": {
"payment_processor": "d6qfs92a"
},
"has_uncommitted_changes": false,
"line_items": [
{
"purchase_item_id": 396034989,
"external_product_id": {
"ecommerce": "123"
},
"external_variant_id": {
"ecommerce": "201"
},
"grams": 708,
"handle": null,
"images": {},
"original_price": "73.59",
"properties": [],
"purchase_item_type": "subscription",
"quantity": 1,
"sku": "subonly-variants-RE-1",
"tax_due": "0.00",
"tax_lines": [],
"taxable": false,
"taxable_amount": "0.00",
"title": "test product",
"total_price": "73.59",
"unit_price": "73.59",
"unit_price_includes_tax": false,
"variant_title": "Color -> Red"
}
],
"note": null,
"order_attributes": [
{
"name": "store_credit_amount",
"value": null
},
{
"name": "customerGroup",
"value": null
},
{
"name": "cartId",
"value": "2af0f994-ff5d-4881-a9d9-ce33f1723ea7"
}
],
"orders_count": 1,
"payment_processor": "braintree",
"processed_at": null,
"retry_date": null,
"scheduled_at": "2023-08-15",
"shipping_address": {
"address1": "1234 Test",
"address2": null,
"city": "Los Angeles",
"company": null,
"country_code": "US",
"first_name": "Natasha",
"last_name": "Lioe",
"phone": null,
"province": "California",
"zip": "90007"
},
"shipping_lines": [
{
"code": "592bf99edab2ade4be599e1d049c0b29",
"price": "7.00",
"tax_lines": [
{
"price": "0.330",
"rate": "0.0494752623688156",
"title": "Tax on Shipping"
}
],
"taxable": false,
"title": "Flat Rate"
}
],
"status": "pending",
"subtotal_price": "73.59",
"tags": "Subscription, Subscription First Order",
"tax_lines": [
{
"price": "4.010",
"rate": "0",
"title": "Tax"
}
],
"taxable": false,
"taxes_included": false,
"total_discounts": "0.00",
"total_duties": null,
"total_line_items_price": "73.59",
"total_price": "84.27",
"total_refunds": "0.00",
"total_tax": "4.01",
"total_weight_grams": 708,
"type": "checkout",
"updated_at": "2023-08-15T18:20:27+00:00"
}
}
Step 3 - Capture the charge
Capture the charge with the charge id that is created on the pending order.
POST https://api.rechargeapps.com/charges/{{charge_id}}/capture_payment
{
"charge": {
"id": 884059485,
"address_id": 131370369,
"analytics_data": {
"utm_params": []
},
"billing_address": {
"address1": "1234 Test",
"address2": null,
"city": "Los Angeles",
"company": null,
"country_code": "US",
"first_name": "Natasha",
"last_name": "Test",
"phone": null,
"province": "California",
"zip": "90007"
},
"client_details": {
"browser_ip": "104.162.239.56",
"user_agent": "PostmanRuntime/7.32.3"
},
"created_at": "2023-08-14T17:24:51+00:00",
"currency": "USD",
"customer": {
"id": 120191814,
"email": "[email protected]",
"external_customer_id": {
"ecommerce": null
},
"hash": "cc16d999ad769bc2ee1370bb910ea4"
},
"discounts": [],
"error": null,
"error_type": null,
"external_order_id": {
"ecommerce": null
},
"external_transaction_id": {
"payment_processor": "1kat42ev"
},
"has_uncommitted_changes": false,
"line_items": [
{
"purchase_item_id": 395740410,
"external_product_id": {
"ecommerce": "123"
},
"external_variant_id": {
"ecommerce": "201"
},
"grams": 708,
"handle": null,
"images": {},
"original_price": "73.59",
"properties": [],
"purchase_item_type": "subscription",
"quantity": 1,
"sku": "subonly-variants-RE-1",
"tax_due": "0.00",
"tax_lines": [],
"taxable": false,
"taxable_amount": "0.00",
"title": "test product",
"total_price": "73.59",
"unit_price": "73.59",
"unit_price_includes_tax": false,
"variant_title": "Color -> Red"
}
],
"note": null,
"order_attributes": [
{
"name": "store_credit_amount",
"value": null
},
{
"name": "customerGroup",
"value": null
},
{
"name": "cartId",
"value": "2af0f994-ff5d-4881-a9d9-ce33f1723ea7"
}
],
"orders_count": 1,
"payment_processor": "braintree",
"processed_at": "2023-08-14T17:33:15+00:00",
"retry_date": null,
"scheduled_at": "2023-08-14",
"shipping_address": {
"address1": "1234 Test",
"address2": null,
"city": "Los Angeles",
"company": null,
"country_code": "US",
"first_name": "Natasha",
"last_name": "Test",
"phone": null,
"province": "California",
"zip": "90007"
},
"shipping_lines": [
{
"code": "592bf99edab2ade4be599e1d049c0b29",
"price": "7.00",
"tax_lines": [
{
"price": "0.330",
"rate": "0.0494752623688156",
"title": "Tax on Shipping"
}
],
"taxable": false,
"title": "Flat Rate"
}
],
"status": "success",
"subtotal_price": "73.59",
"tags": "Subscription, Subscription First Order",
"tax_lines": [
{
"price": "4.010",
"rate": "0",
"title": "Tax"
}
],
"taxable": false,
"taxes_included": false,
"total_discounts": "0.00",
"total_duties": null,
"total_line_items_price": "73.59",
"total_price": "84.27",
"total_refunds": "0.00",
"total_tax": "4.01",
"total_weight_grams": 708,
"type": "checkout",
"updated_at": "2023-08-14T17:33:15+00:00"
}
}
Step 4 - Successful order
After completing the previous steps, the charge will display in the Orders tab if you were successful.
Cancel the subscription
If there is a pending charge that you need to cancel:
- Refund the charge. Refunding the charge will delete the pending charge and order.
- Delete the subscription.
- Cancelling the subscription will not work.
- If there is a pending order, deleting the subscription will still work, though this will not delete the pending order.
Updated about 2 months ago