API Reference

recover enterprise api the recover enterprise api offers an endpoint for sending payment events—both successful and failed this endpoint is designed to be source agnostic, working seamlessly with any payment service provider please review the authentication docid\ x cpa5gd9fcb6rydarzov documentation for how to securly connect to recover apis post payments the payments api is an http endpoint that handles standardized payment events forwarded from a merchant's payment processing system please check the recover payment object properties docid\ j6svye nzgbcop9av0ua for additional descriptions of required and optional properties payments docid\ livadqn50dnn5r1jhv5nm example url https //api butterpayments com/payments https //api butterpayments com/payments example request body { "customer" { "id" "11223344", // required "psp id" "cus 12345", "created at" "2023 09 25t03 57 26z", "postal code" "04102" }, "subscription" { "id" "sub 1234", // required "start date" "2023 09 25t03 57 26z", // required "end date" "2023 10 25t03 57 26z", "discounted or free period" false, "product id" "sku 020901", "billing" { "period" "month", "frequency" 1 } }, "invoice" { "id" "inv 12345", // required "created at" "2023 09 25t03 57 26z" // required }, "transactions" \[ { "id" "ts 12345", // required "psp transaction id" "ts 12345", // required "acquirer country" "us", // required "amount" 12 23, // required "psp" "stripe", // required "currency" "usd", // required "funding source" "credit", // required "payment method id" "pm 12345", // required "psp transaction created at" "2023 10 25t03 57 26z", // required "outcome" { "raw response message" "insufficient funds", // required "psp response message" "the customer has insufficient funds ", "processor response code" 2000, "network status" "psp block", "response type" "soft decline" }, "network transaction id" "pcqvzzwbga0912", "mid" "8224137", "reporting group" "pepsi", "billing postal code" "04102", "auth" true, "bin" "112233", "captured" false, "issuer country" "us", "refunded" false, "scheme" "visa", "success" false } ] } example response body { "message" "request submitted for processing", "request id" "2c941653 b229 4528 b576 70fcfd388543 49645839701979566120793328447151049151317978254208401410 000000000000" } post payment method update this endpoint allows merchants to notify recover of updates to a customer's payment method whenever a payment method is added, updated, or removed, the event should be forwarded to this endpoint these updates are crucial as changes in payment methods influence the calculation of the optimal retry time api reference docid\ oylr8swr hn9dqzoscpcw example url https //api butterpayments com/payment method updates https //api butterpayments com/payment method updates example request body { "customer id" "11223344", "psp customer id" "cust 12345", "payment method id" "pm 12345", "reason" "network updated" } example response body { "message" "request submitted for processing", "request id" "2c941653 b229 4528 b576 70fcfd388543 49645839701979566120793328447151049151317978254208401410 000000000000" } merchant endpoints to integrate with the recover enterprise api effectively, merchants must provision specific endpoints these endpoints are essential for maintaining consistency in payment recovery and ensuring accurate payment reconciliation please review the authentication docid\ x cpa5gd9fcb6rydarzov section for details on what schemes butter systems currently support post retrystatus the retrystatus endpoint, provided by the merchant, determines whether an invoice is eligible for retry before initiating a retry, the recover service calls this endpoint as a final security check prior to submitting the transaction this check is crucial because various changes can occur to an invoice between the time it is sent to recover and when a retry is attempted depending on what recover's underlying models determine to be optimal, this interval may range from hours to days one of the most common reasons to cancel a retry during this period is if the user cancels their subscription retry status docid\ idcldp2jt0gopaquo xyx example url https //api \<merchant url>/retry/\<invoice id> https //api \<merchant url>/retry/\<invoice id> example request body { // optional custom filter paramaters // {brand pepsi} // merchant to define filter parameters, if required } example response body { "retry" false, "reason" "user cancellation", "amount" 19 99, "metadata" {}, "payment methods" \[ { "id" "pm 12345", "network transaction id" "qksx6rp250903", "bin" "621035", "token" { "id" "4457010000000009", "expiration month" "02", "expiration year" "27", "card validation number" "445" }, "billing address" { "name" "john smith", "city" "boston", "state" "ma", "zip" "02108", "phone" "555 309 9999" } } ] } post retryresults the retryresults endpoint acts as a webhook consumer for retry events, providing real time visibility into the operations of the recover system these events deliver detailed information about each retry attempt, including its outcome, enabling merchants to reconcile their systems efficiently if payment is successfully recovered on a retry attempt, "success"\ true will be returned if payment is not successfully recovered on a retry attempt, "success"\ false will be returned retry results docid\ aphoqkslqpubkr7vo46x3 example url https //api \<merchant url>/retry results https //api \<merchant url>/retry results example request body { "timestamp" "2025 01 22t22 31 08 893377", "butter id" "1040432066964226052", "customer id" "cust 1234", "subscription id" "sub 12345", "invoice id" "inv 12345", "transaction id" "txn 12345", "original psp transaction id" "9472768581", "psp transactions" \[ { "psp transaction id" "9472768583", "network transaction id"\ null, "merchant payment method id" "pm 12345", "success"\ true } ], "original amount" 50, "amount collected" 50, "currency" "usd", "success"\ true, "dunning complete"\ true, "custom" {} } example response body { "detail" "event delivered successfully" } post endofdunning recover will send webhooks to this endpoint via http post requests when the dunning process is complete this signifies the end of the retry window, after which the recover service will cease any further payment retry attempts end of dunning docid xpgisw24gh d43ozixvg example url https //api \<merchant url>/end of dunning https //api \<merchant url>/end of dunning example request body { "timestamp" "2025 04 05t19 41 01 396550", "invoice id" "inv 12345", "recovered" true "custom"\ null } example response body { "detail" "event delivered successfully" } interested in working with butter to bring more revenue back to your business? reach out to us here contact\@butterpayments com