--- title: Retry Results slug: retry-results description: Learn how Butter Payments' Retry Results webhooks provide detailed outcomes of each payment recovery attempt, enabling seamless reconciliation and improved subscription management. docTags: createdAt: 2024-11-21T18:23:44.897Z --- { "id": "ur3Qi6Kx3-d8CHSf3U-4o", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api..com/webhooks/retry-results", "servers": [ { "url": "https://api..com/webhooks/retry-results", "description": "An example of a url the merchant would create to receive these events." } ], "name": "Retry Results", "description": "

Butter will send webhooks via HTTP POST requests to this endpoint each time we try to recover a payment with the results of our retry attempt. Butter guarantees 'at least once' delivery of events, and provides a deduplication ID to enable integrators to handle duplicate event delivery.

\n

Note - The Butter webhook payload is a simple JSON object containing the attributes specified below. The payload does not contain a higher-level 'body' object that contains the other attributes.

\n

Add field values in the boxes below to create an example payload on the right side of the screen.

", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [ { "kind": "optional", "name": "X-Butter-Webhook-Type", "type": "string", "description": "" }, { "kind": "optional", "name": "X-Butter-Webhook-Expiration", "type": "integer", "description": "The unix timestamp that the webhook signature expires at.", "default": 1698251668 }, { "kind": "optional", "name": "X-Butter-Webhook-Signature", "type": "string", "description": "The signature the merchant can use for validating the security of the webhook.", "default": "06cf8a25ef73841fea0b20f13499f173e7767da53cccba2412b261816515f30d" }, { "kind": "optional", "name": "X-Butter-Webhook-Deduplication-ID", "type": "string", "description": "A unique identifier that can be used to deduplicate the webhook.", "default": "47bce5c74f589f4867dbd57e9ca9f808" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "optional", "name": "body", "type": "object", "description": "The outcome of a retry attempt to recover a failed payment.", "customType": "retry_result", "schema": [ { "name": "timestamp", "kind": "optional", "type": "string", "description": "The time when this webhook was created and sent, not necessarily when the retry attempt occurred.", "default": "2023-10-25T03:57:26Z", "modelRef": "#/components/schemas/timestamp", "customType": "timestamp", "schema": [] }, { "name": "butter_id", "kind": "optional", "type": "string", "description": "The ID of the retry from Recover.", "example": "", "default": "911536259375759362" }, { "name": "customer_id", "kind": "optional", "type": "string", "description": "The ID of the customer from the merchant's internal subscription management system.", "example": "", "default": "cust_12345" }, { "name": "subscription_id", "kind": "optional", "type": "string", "description": "The ID of the subscription from the merchant's internal subscription management system.", "example": "", "default": "sub_12345" }, { "name": "invoice_id", "kind": "optional", "type": "string", "description": "The ID of the invoice from the merchant's internal subscription management system.", "example": "", "default": "inv_12345" }, { "name": "transaction_id", "kind": "optional", "type": "string", "description": "The ID of the transaction from the merchant's internal subscription management system.", "example": "", "default": "ts_12345" }, { "name": "original_psp_transaction_id", "kind": "optional", "type": "string", "description": "The original transaction id from the PSP passed by the merchant to the Recover Enterprise API.", "example": "", "default": "9472768581" }, { "name": "psp_transactions", "kind": "optional", "type": "array", "description": "The ids of the transactions created with the PSP during the retry attempt.", "modelRef": "#/components/schemas/psp_transaction", "customType": "psp_transaction[]", "schema": [ { "name": "psp_transaction_id", "kind": "optional", "type": "string", "description": "The transaction ID from the PSP.", "example": "6386243129177352", "default": "6386243129177352" }, { "name": "network_transaction_id", "kind": "optional", "type": "string", "description": "The network transaction id returned from the PSP after executing a transaction.", "example": "QKSX6RP250903", "default": "QKSX6RP250903" }, { "name": "merchant_payment_method_id", "kind": "optional", "type": "string", "description": "The ID of the payment method used for the transaction from the merchant's system.", "example": "pm_12566742", "default": "pm_12566742" }, { "name": "success", "kind": "optional", "type": "boolean", "description": "Whether or not the transaction attempt was successful.", "example": true, "default": true } ] }, { "name": "original_amount", "kind": "optional", "type": "number", "description": "The original amount from the initial transaction.", "example": "", "default": 49.99 }, { "name": "amount_collected", "kind": "optional", "type": "number", "description": "The amount collected/attempted to be collected. This number will differ from the original_amount if you pass a different retry amount in the response of the Client Retry API. This most often happens if a merchant reduces the amount to be collected later in the dunning cycle to attempt to collect on an invoice that has been difficult to recover.", "example": "", "default": 49.99 }, { "name": "currency", "kind": "optional", "type": "string", "description": "The currency the retry was attempted with.", "example": "", "default": "USD" }, { "name": "success", "kind": "optional", "type": "boolean", "description": "Boolean designating if the retry attempt was successful or not.", "example": "", "default": true }, { "name": "custom", "kind": "optional", "type": "object", "description": "Any custom fields the merchant passed to the Recover Enterprise API.", "example": "{\"brand\":\"DTC\"}", "schema": [] } ], "modelRef": "#/components/schemas/retry_result", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "basic_auth", "name": "basic_auth", "kind": "optional", "type": "http", "description": "

Basic auth credentials you (the merchant) provide to Butter to authorize webhook requests.

", "scheme": "basic" }, { "id": "api_key_auth", "name": "x-api-key", "kind": "optional", "type": "apiKey", "description": "

API key credentials you (the merchant) provide to Butter to authorize requests to the Retry API.

", "in": "header" } ] }, "responses": [ { "statusCode": "200", "description": "Event Delivered Successfully", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "The webhook event was delivered successfully.", "customType": "inline_response_200", "schema": [ { "name": "detail", "kind": "optional", "type": "string", "example": "Event delivered successfully", "default": "Event delivered successfully" } ], "modelRef": "#/components/schemas/inline_response_200", "isExpanded": true } ] }, { "statusCode": "500", "description": "Event Not Delivered", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "The webhook event failed to deliver due to an internal server error. Webhooks will retry delivery every 12 hours for 7 days on failure.", "customType": "inline_response_500", "schema": [ { "name": "detail", "kind": "optional", "type": "string", "example": "Server is unavailable", "default": "Server is unavailable" } ], "modelRef": "#/components/schemas/inline_response_500", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "LSE4aAVWKNeKloPMRm-Ez", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api..com/webhooks/retry-results \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header 'x-butter-webhook-expiration: 1698251668' \\\n --header 'x-butter-webhook-signature: 06cf8a25ef73841fea0b20f13499f173e7767da53cccba2412b261816515f30d' \\\n --header 'x-butter-webhook-deduplication-id: 47bce5c74f589f4867dbd57e9ca9f808' \\\n --data '{\n \"timestamp\": \"2023-10-25T03:57:26Z\",\n \"butter_id\": \"911536259375759362\",\n \"customer_id\": \"cust_12345\",\n \"subscription_id\": \"sub_12345\",\n \"invoice_id\": \"inv_12345\",\n \"transaction_id\": \"ts_12345\",\n \"original_psp_transaction_id\": \"9472768581\",\n \"psp_transactions\": [\n {\n \"psp_transaction_id\": \"6386243129177352\",\n \"network_transaction_id\": \"QKSX6RP250903\",\n \"merchant_payment_method_id\": \"pm_12566742\",\n \"success\": true\n }\n ],\n \"original_amount\": 49.99,\n \"amount_collected\": 49.99,\n \"currency\": \"USD\",\n \"success\": true\n }'" }, { "id": "1-OpPkp0VfsL9aCS0ZwO1", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\nmyHeaders.append(\"x-butter-webhook-expiration\", \"1698251668\");\nmyHeaders.append(\"x-butter-webhook-signature\", \"06cf8a25ef73841fea0b20f13499f173e7767da53cccba2412b261816515f30d\");\nmyHeaders.append(\"x-butter-webhook-deduplication-id\", \"47bce5c74f589f4867dbd57e9ca9f808\");\n\nvar raw = JSON.stringify({\n \"timestamp\": \"2023-10-25T03:57:26Z\",\n \"butter_id\": \"911536259375759362\",\n \"customer_id\": \"cust_12345\",\n \"subscription_id\": \"sub_12345\",\n \"invoice_id\": \"inv_12345\",\n \"transaction_id\": \"ts_12345\",\n \"original_psp_transaction_id\": \"9472768581\",\n \"psp_transactions\": [\n {\n \"psp_transaction_id\": \"6386243129177352\",\n \"network_transaction_id\": \"QKSX6RP250903\",\n \"merchant_payment_method_id\": \"pm_12566742\",\n \"success\": true\n }\n ],\n \"original_amount\": 49.99,\n \"amount_collected\": 49.99,\n \"currency\": \"USD\",\n \"success\": true\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api..com/webhooks/retry-results\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "IvgH7cdwDtliEZa-b5Um3", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api..com/webhooks/retry-results\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest[\"x-butter-webhook-expiration\"] = \"1698251668\"\nrequest[\"x-butter-webhook-signature\"] = \"06cf8a25ef73841fea0b20f13499f173e7767da53cccba2412b261816515f30d\"\nrequest[\"x-butter-webhook-deduplication-id\"] = \"47bce5c74f589f4867dbd57e9ca9f808\"\nrequest.body = JSON.dump({\n \"timestamp\": \"2023-10-25T03:57:26Z\",\n \"butter_id\": \"911536259375759362\",\n \"customer_id\": \"cust_12345\",\n \"subscription_id\": \"sub_12345\",\n \"invoice_id\": \"inv_12345\",\n \"transaction_id\": \"ts_12345\",\n \"original_psp_transaction_id\": \"9472768581\",\n \"psp_transactions\": [\n {\n \"psp_transaction_id\": \"6386243129177352\",\n \"network_transaction_id\": \"QKSX6RP250903\",\n \"merchant_payment_method_id\": \"pm_12566742\",\n \"success\": true\n }\n ],\n \"original_amount\": 49.99,\n \"amount_collected\": 49.99,\n \"currency\": \"USD\",\n \"success\": true\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "9K-w3koYYHnEcu1tINg6c", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api..com/webhooks/retry-results\"\n\npayload = json.dumps({\n \"timestamp\": \"2023-10-25T03:57:26Z\",\n \"butter_id\": \"911536259375759362\",\n \"customer_id\": \"cust_12345\",\n \"subscription_id\": \"sub_12345\",\n \"invoice_id\": \"inv_12345\",\n \"transaction_id\": \"ts_12345\",\n \"original_psp_transaction_id\": \"9472768581\",\n \"psp_transactions\": [\n {\n \"psp_transaction_id\": \"6386243129177352\",\n \"network_transaction_id\": \"QKSX6RP250903\",\n \"merchant_payment_method_id\": \"pm_12566742\",\n \"success\": True\n }\n ],\n \"original_amount\": 49.99,\n \"amount_collected\": 49.99,\n \"currency\": \"USD\",\n \"success\": True\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json',\n 'x-butter-webhook-expiration': '1698251668',\n 'x-butter-webhook-signature': '06cf8a25ef73841fea0b20f13499f173e7767da53cccba2412b261816515f30d',\n 'x-butter-webhook-deduplication-id': '47bce5c74f589f4867dbd57e9ca9f808'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "LSE4aAVWKNeKloPMRm-Ez" }, "results": { "languages": [ { "id": "Cx-yP4e3Zdw0s6keWMXo3", "language": "200", "code": "// Event Delivered Successfully\n{\n \"detail\": \"Event delivered successfully\"\n}" }, { "id": "ph_fUg6JDxdZkOAkKSyyH", "language": "500", "code": "// Event Not Delivered\n{\n \"detail\": \"Server is unavailable\"\n}" } ], "selectedLanguageId": "Cx-yP4e3Zdw0s6keWMXo3" } }, "children": [ { "id": "ARIkbvkNbUNgS5N0Ur9pE", "type": "paragraph", "children": [ { "text": "Butter will send webhooks via HTTP POST requests to this endpoint each time we try to recover a payment with the results of our retry attempt. Butter guarantees 'at least once' delivery of events, and provides a deduplication ID to enable integrators to handle duplicate event delivery." } ] }, { "id": "gF2zaKH7zwxwY_cKy10Qn", "type": "paragraph", "children": [ { "text": "Note - The Butter webhook payload is a simple JSON object containing the attributes specified below. The payload does not contain a higher-level 'body' object that contains the other attributes." } ] }, { "id": "MfsEzUAdQT0dpgtwvZAdM", "type": "paragraph", "children": [ { "text": "Add field values in the boxes below to create an example payload on the right side of the screen." } ] } ] }