--- title: Retry Status slug: retry-status docTags: createdAt: 2025-02-19T21:10:58.084Z --- { "id": "j_wVFQq5m_MO9Ws4ktnEt", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api..com/retry/{invoice_id}", "servers": [ { "url": "https://api..com/retry/{invoice_id}", "description": "An example of a url the merchant would create to receive these events." } ], "name": "Retry Status", "description": "This endpoint is provisioned on the merchant's servers for Recover to retrieve invoice retry information. It serves as a final check to make sure that Recover is able to attempt a payment before executing.\n\nAdd field values in the boxes below to create an example payload on the right side of the screen.", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "invoice_id", "type": "string", "example": "inv_12345", "description": "The id of an invoice within your subscription management system." } ], "headerParameters": [], "queryParameters": [], "bodyDataParameters": [ { "kind": "optional", "name": "body", "type": "object", "description": "", "customType": "get_retry_information_body", "schema": [ { "name": "custom", "kind": "optional", "type": "object", "description": "Any custom fields passed to the Get Payment Information endpoint of the Recover Enterprise API will be included in this request.", "example": "{\"brand\":\"Pepsi\"}", "schema": [] } ], "modelRef": "#/components/schemas/get_retry_information_body", "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": "The request succeeded", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "retry_status_200", "schema": [ { "name": "retry", "kind": "required", "type": "boolean", "description": "Should Butter retry this invoice?", "example": false }, { "name": "reason", "kind": "required", "type": "string", "description": "Reason Examples:\n- User Cancelation\n- Dunning Window Reached\n- User Recovered via Payment Method Update\n- User Outstanding Invoice Forgiven\n- Other (Work with Butter to determine other reasons to send)\n", "example": "User Cancelation" }, { "name": "amount", "kind": "optional", "type": "number", "description": "The amount to attempt a retry for.", "example": 19.99 }, { "name": "metadata", "kind": "optional", "type": "object", "description": "Any metadata not passed into the initial /payments request that should be added to the PSP retry request.", "example": "", "schema": [] }, { "name": "payment_methods", "kind": "optional", "type": "array", "description": "The payment methods that can be used for a retry.", "example": "", "itemType": "object", "customType": "object[]", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "The ID of the payment method from the PSP.", "example": "pm_12345" }, { "name": "network_transaction_id", "kind": "optional", "type": "string", "description": "The original transaction id recorded with the network from the first success on this payment method.", "example": "QKSX6RP250903" }, { "name": "bin", "kind": "optional", "type": "string", "description": "The first four to six numbers on a payment card that identifies the financial institution that issued the card.", "example": "621035" }, { "name": "token", "kind": "optional", "type": "object", "description": "The details of the token a retry should be attempted for.", "example": "", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "The id of the token from the payment service provider.", "example": "4457010000000009" }, { "name": "expiration_month", "kind": "optional", "type": "string", "description": "The 2 digit month the underlying card will expire in.", "example": "02" }, { "name": "expiration_year", "kind": "optional", "type": "string", "description": "The 2 digit year the underlying card will expire in.", "example": "27" }, { "name": "card_validation_number", "kind": "optional", "type": "string", "description": "The CVV of the underlying card. If using Worldpay you can pass 000 to use the stored value in the token.", "example": "445" } ] }, { "name": "billing_address", "kind": "optional", "type": "object", "description": "The billing address associated with the payment method.", "example": "", "schema": [ { "name": "name", "kind": "optional", "type": "string", "description": "The full name of the person associated with the billing address.", "example": "John Smith" }, { "name": "city", "kind": "optional", "type": "string", "description": "The city associated with the billing address.", "example": "Boston" }, { "name": "state", "kind": "optional", "type": "string", "description": "The 2 character code for the state associated with the billing address.", "example": "MA" }, { "name": "zip", "kind": "optional", "type": "string", "description": "The 5 digit zip code associated with the billing address.", "example": "02108" }, { "name": "phone", "kind": "optional", "type": "string", "description": "The phone number associated with the billing address.", "example": "555-309-9999" } ] } ] } ], "modelRef": "#/components/schemas/retry_status_200", "isExpanded": true } ] }, { "statusCode": "401", "description": "Invalid Credentials", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "retry_status_401", "schema": [ { "name": "detail", "kind": "optional", "type": "string", "example": "Missing or invalid api key" } ], "modelRef": "#/components/schemas/retry_status_401", "isExpanded": true } ] }, { "statusCode": "404", "description": "Invoice Not Found", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "retry_status_404", "schema": [ { "name": "detail", "kind": "optional", "type": "string", "example": "An invoice with the provided ID cannot be found" } ], "modelRef": "#/components/schemas/retry_status_404", "isExpanded": true } ] }, { "statusCode": "429", "description": "Too Many Requests", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "retry_status_429", "schema": [ { "name": "detail", "kind": "optional", "type": "string", "example": "Requests have exceeded rate limiting" } ], "modelRef": "#/components/schemas/retry_status_429", "isExpanded": true } ] }, { "statusCode": "500", "description": "Server Error", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "retry_status_500", "schema": [ { "name": "detail", "kind": "optional", "type": "string", "example": "A server error has occurred" } ], "modelRef": "#/components/schemas/retry_status_500", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "tcV1AZxCmsKPPiAKbPYeJ", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api..com/retry/{invoice_id} \\\n --header 'accept: application/json'" }, { "id": "1l4FsaBcBOzkoVoNetQpH", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://api..com/retry/{invoice_id}\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "dmZc3VsMlx0-M_UEtY5ZH", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api..com/retry/{invoice_id}\")\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\"\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "ZuiAVXcthw4T53XEywB99", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api..com/retry/{invoice_id}\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "tcV1AZxCmsKPPiAKbPYeJ" }, "results": { "languages": [ { "id": "Ed8zDTbnUxrQVzkuRPhRU", "language": "200", "code": "// The request succeeded\n{\n \"retry\": false,\n \"reason\": \"User Cancelation\",\n \"amount\": 19.99,\n \"metadata\": {},\n \"payment_methods\": [\n {\n \"id\": \"pm_12345\",\n \"network_transaction_id\": \"QKSX6RP250903\",\n \"bin\": \"621035\",\n \"token\": {\n \"id\": \"4457010000000009\",\n \"expiration_month\": \"02\",\n \"expiration_year\": \"27\",\n \"card_validation_number\": \"445\"\n },\n \"billing_address\": {\n \"name\": \"John Smith\",\n \"city\": \"Boston\",\n \"state\": \"MA\",\n \"zip\": \"02108\",\n \"phone\": \"555-309-9999\"\n }\n }\n ]\n}" }, { "id": "vA8Jjgs5UaHkS88IwyGYZ", "language": "401", "code": "// Invalid Credentials\n{\n \"detail\": \"Missing or invalid api key\"\n}" }, { "id": "MB2HZR5Bg8ZobiF87D1Qf", "language": "404", "code": "// Invoice Not Found\n{\n \"detail\": \"An invoice with the provided ID cannot be found\"\n}" }, { "id": "UpgD5LJ3hv_ZoNtJNL5mW", "language": "429", "code": "// Too Many Requests\n{\n \"detail\": \"Requests have exceeded rate limiting\"\n}" }, { "id": "N8kyJIEsWspNIoFtvSnMr", "language": "500", "code": "// Server Error\n{\n \"detail\": \"A server error has occurred\"\n}" } ], "selectedLanguageId": "Ed8zDTbnUxrQVzkuRPhRU" } }, "children": [ { "id": "k4VpNnttIQrSTiWsqzJ7u", "type": "paragraph", "children": [ { "text": "This endpoint is provisioned on the merchant's servers for Recover to retrieve invoice retry information. It serves as a final check to make sure that Recover is able to attempt a payment before executing." } ] }, { "id": "GqN2DaCgjL-mGWmWE-mHD", "type": "paragraph", "children": [ { "text": "Add field values in the boxes below to create an example payload on the right side of the screen." } ] } ] }