---
title: Payments
slug: payments
description: Learn how to use Butter's Payments API to handle standardized payment events from your payment processing system, supporting both successful and failed transactions.
docTags:
createdAt: 2024-11-20T22:35:55.860Z
---
{
"id": "UykOLw1C6-gnlqaqo7v7-",
"type": "api-oas-v2",
"data": {
"method": "POST",
"url": "https://api.butterpayments.com/recover/payments",
"servers": [
{
"url": "https://api.butterpayments.com/recover/payments"
}
],
"name": "Payments",
"description": "This endpoint serves as the entry point into Recover for all transaction events related to payment processing, including successful payments, failed payments, and Butter retry events. All transaction events, besides disputes, should be sent by the merchant to this endpoint.
\nExpand the objects below and add field values to create an example payload on the right side of the screen.
",
"contentType": "application/json",
"request": {
"pathParameters": [],
"headerParameters": [],
"queryParameters": [],
"bodyDataParameters": [
{
"kind": "required",
"name": "body",
"type": "object",
"description": "",
"customType": "payments",
"schema": [
{
"name": "customer",
"kind": "required",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/customer",
"customType": "customer",
"schema": [
{
"name": "id",
"kind": "required",
"type": "string",
"description": "The internal identifier from your subscription management platform used to designate the customer.",
"example": "11223344"
},
{
"name": "psp_id",
"kind": "optional",
"type": "string",
"description": "The identifier used by the Payment Processor to designate the customer.",
"example": "cus_12345"
},
{
"name": "created_at",
"kind": "optional",
"type": "string",
"description": "The timestamp that the customer was created.",
"example": "2023-10-25T03:57:26Z",
"modelRef": "#/components/schemas/timestamp",
"customType": "timestamp",
"schema": []
},
{
"name": "postal_code",
"kind": "optional",
"type": "string",
"description": "The postal code from the customer's address.",
"example": "04102",
"modelRef": "#/components/schemas/postal_code",
"customType": "postal_code",
"schema": []
}
]
},
{
"name": "subscription",
"kind": "required",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/subscription",
"customType": "subscription",
"schema": [
{
"name": "id",
"kind": "required",
"type": "string",
"description": "The internal identifier from your subscription management platform used to designate the subscription.",
"example": "sub_1234"
},
{
"name": "start_date",
"kind": "required",
"type": "string",
"description": "Timestamp of when the subscription started.",
"example": "2023-10-25T03:57:26Z",
"modelRef": "#/components/schemas/timestamp",
"customType": "timestamp",
"schema": []
},
{
"name": "end_date",
"kind": "optional",
"type": "string",
"description": "Timestamp of when the subscription ended/will end if applicable.",
"example": "2023-10-25T03:57:26Z",
"modelRef": "#/components/schemas/timestamp",
"customType": "timestamp",
"schema": []
},
{
"name": "discounted_or_free_period",
"kind": "optional",
"type": "boolean",
"description": "Boolean to designate free trials or discounted billing.",
"example": false
},
{
"name": "product_id",
"kind": "optional",
"type": "string",
"description": "Unique identifier of the product/plan the subscription is for.",
"example": "sku_02901"
},
{
"name": "billing",
"kind": "optional",
"type": "object",
"example": "",
"schema": [
{
"name": "period",
"kind": "optional",
"type": "string",
"description": "The subscription billing period. This attribute should be one of the specified values, or absent.",
"example": "month"
},
{
"name": "frequency",
"kind": "optional",
"type": "integer",
"description": "The number of payments expected per billing period. This attribute should be a positive integer, or absent.",
"example": 1
}
]
}
]
},
{
"name": "invoice",
"kind": "required",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/invoice",
"customType": "invoice",
"schema": [
{
"name": "id",
"kind": "required",
"type": "string",
"description": "The internal identifier from your subscription management platform used to designate the invoice.",
"example": "inv_12345"
},
{
"name": "created_at",
"kind": "required",
"type": "string",
"description": "",
"example": "2023-10-25T03:57:26Z",
"modelRef": "#/components/schemas/timestamp",
"customType": "timestamp",
"schema": []
}
]
},
{
"name": "transactions",
"kind": "required",
"type": "array",
"description": "An array of transactions. At least one transaction is required. If your retry strategy includes multiple payment methods, list each of them here rather than sending an additional event for each transaction. If there is only one transaction per retry, then just list that single transaction.",
"modelRef": "#/components/schemas/transaction",
"customType": "transaction[]",
"schema": [
{
"name": "id",
"kind": "required",
"type": "string",
"description": "The internal identifier from your subscription management platform used to designate the transaction.",
"example": "ts_12345"
},
{
"name": "psp_transaction_id",
"kind": "required",
"type": "string",
"description": "The identifier used to designate the transaction from the PSP.",
"example": "ts_12345"
},
{
"name": "network_transaction_id",
"kind": "optional",
"type": "string",
"description": "The original transaction id from the network. Required for Worldpay integrations.",
"example": "PCQVZWBGA0912"
},
{
"name": "psp",
"kind": "required",
"type": "string",
"description": "The name of the PSP the transaction originated on. This should be one of the specified values.",
"example": "Worldpay"
},
{
"name": "mid",
"kind": "optional",
"type": "string",
"description": "The MID (merchant identification number) used to process a transaction with the PSP. Required for Worldpay integrations.",
"example": "8224137"
},
{
"name": "reporting_group",
"kind": "optional",
"type": "string",
"description": "The identifier used to categorize the transaction data. Commonly used for reporting and analysis, identifying business units and branches, currencies, etc. PSP may use different names. For example, Worldpay uses Reporting Groups while Braintree uses Merchant Account IDs (MAID).",
"example": "Pepsi"
},
{
"name": "acquirer_country",
"kind": "required",
"type": "string",
"description": "The country in which the payment was processed and acquired in.",
"example": "US"
},
{
"name": "amount",
"kind": "required",
"type": "number",
"description": "The amount to be attempted, represented as a float.",
"example": 12.23
},
{
"name": "billing_postal_code",
"kind": "optional",
"type": "string",
"description": "The postal code from the customer's billing address.",
"example": "04102",
"modelRef": "#/components/schemas/postal_code",
"customType": "postal_code",
"schema": []
},
{
"name": "auth",
"kind": "optional",
"type": "boolean",
"description": "Boolean to represent if this is a pre-authorization or final capture.",
"example": false
},
{
"name": "bin",
"kind": "optional",
"type": "string",
"description": "The 6 digit Bank Identification Number of the payment card used.",
"example": "112233"
},
{
"name": "captured",
"kind": "optional",
"type": "boolean",
"description": "Boolean to represent if the payment has been captured.",
"example": false
},
{
"name": "currency",
"kind": "required",
"type": "string",
"description": "The currency of the transaction in ISO standard format.",
"example": "USD"
},
{
"name": "funding_source",
"kind": "required",
"type": "string",
"description": "The account type funding the payment card. This should be one of the specified values.",
"example": "CREDIT"
},
{
"name": "issuer_country",
"kind": "optional",
"type": "string",
"description": "The country in which the payment card was issued.",
"example": "US"
},
{
"name": "outcome",
"kind": "required",
"type": "object",
"example": "",
"schema": [
{
"name": "raw_response_message",
"kind": "required",
"type": "string",
"description": "The issuer approval or decline message provided in the authorization response.",
"example": "insufficient_funds"
},
{
"name": "psp_response_message",
"kind": "optional",
"type": "string",
"description": "The response description provided by the Payment Processor.",
"example": "The customer has insufficient funds."
},
{
"name": "processor_response_code",
"kind": "optional",
"type": "number",
"description": "The response code returned provided by the Payment Processor.",
"example": 2000
},
{
"name": "network_status",
"kind": "optional",
"type": "string",
"description": "Additional net work data returned by certain Payment Processors (if applicable).",
"example": "psp_block"
},
{
"name": "response_type",
"kind": "optional",
"type": "string",
"description": "Category of decline code (Soft Decline, Hard Decline)",
"example": "hard_decline"
}
]
},
{
"name": "payment_method_id",
"kind": "required",
"type": "string",
"description": "The id from the psp representing the payment method attempted.",
"example": ""
},
{
"name": "psp_transaction_created_at",
"kind": "required",
"type": "string",
"description": "",
"example": "2023-10-25T03:57:26Z",
"modelRef": "#/components/schemas/timestamp",
"customType": "timestamp",
"schema": []
},
{
"name": "refunded",
"kind": "optional",
"type": "boolean",
"description": "Boolean to represent if the payment has been refunded.",
"example": false
},
{
"name": "scheme",
"kind": "required",
"type": "string",
"description": "Network of the payment card (Visa, MasterCard, etc.).",
"example": "visa"
},
{
"name": "success",
"kind": "required",
"type": "boolean",
"description": "Boolean to represent if the transaction was successfully processed.",
"example": false
},
{
"name": "description",
"kind": "optional",
"type": "string",
"description": "A description of the item to show on a receipt or invoice.",
"example": ""
},
{
"name": "statement_descriptor",
"kind": "optional",
"type": "string",
"description": "A short descriptor that will appear on the customer's bank statement.",
"example": "Butter* tshirt"
},
{
"name": "enhanced_data",
"kind": "optional",
"type": "object",
"description": "Optional enhanced data fields that can be added to processing.",
"modelRef": "#/components/schemas/enhanced_data",
"customType": "enhanced_data",
"schema": [
{
"name": "level_2",
"kind": "optional",
"type": "object",
"description": "This adds additional information to what is captured in Level 1. Level 2 processing typically includes all Level 1 data plus extra details such as customer code (often a purchase order number), sales tax amount, and a merchant's tax ID. The inclusion of this data often qualifies the merchant for lower processing fees. It's particularly beneficial for corporate or government transactions.",
"modelRef": "#/components/schemas/level_2",
"customType": "level_2",
"schema": [
{
"name": "purchase_order_number",
"kind": "optional",
"type": "string",
"description": "A unique identifier for the purchase.",
"example": "2337210904"
},
{
"name": "total_tax_amount",
"kind": "optional",
"type": "string",
"description": "The amount of sales tax applied to the purchase. Note that there usually needs to be a tax amount greater than zero, as transactions with no sales tax might not qualify for Level 2 rates.",
"example": "12.20"
},
{
"name": "total_discount_amount",
"kind": "optional",
"type": "string",
"description": "The total discount amount applied to the purchase.",
"example": "20.00"
}
]
},
{
"name": "level_3",
"kind": "optional",
"type": "object",
"description": "This goes a step further than Level 2 by providing the most detailed transaction data. Along with Level 1 and Level 2 data, Level 3 processing includes line-item details such as item descriptions, quantities, unit prices, and product codes. This level of detail is similar to what's found on an itemized invoice. Level 3 processing is typically used for large corporate and government transactions and can lead to even lower interchange rates due to the reduced risk and enhanced information provided.",
"modelRef": "#/components/schemas/level_3",
"customType": "level_3",
"schema": [
{
"name": "line_items",
"kind": "optional",
"type": "array",
"description": "A list of objects that contain the line item details required for Level 3 processing. The requirements for these objects may differ between each card type and PSP, so see your PSP's documentation to determine the exact format of the payloads required. Recover will pass-through the objects provided here to the psp without alteration when performing a retry.",
"example": "",
"itemType": "object",
"customType": "object[]",
"itemExample": "",
"itemDefault": ""
}
]
}
]
}
]
},
{
"name": "custom",
"kind": "optional",
"type": "object",
"description": "Additional fields can be provided as custom metadata. This may be required in the case that additional data is required to be provided in transaction requests to your Payment Processor, or for persisting cer tain metadata within Butter. This can be specified and defined in collaboration with Butter Solutions Engineers.",
"example": "",
"schema": []
}
],
"modelRef": "#/components/schemas/payments",
"isExpanded": true
}
],
"formDataParameters": [],
"oAuthParameters": [
{
"id": "api_key_auth",
"name": "x-api-key",
"kind": "optional",
"type": "apiKey",
"description": "API key to authorize requests.",
"in": "header"
}
]
},
"responses": [
{
"statusCode": "200",
"description": "Request Successful",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "",
"customType": "inline_response_200",
"schema": [
{
"name": "message",
"kind": "optional",
"type": "string",
"example": "Request submitted for processing",
"default": "Request submitted for processing"
},
{
"name": "request_id",
"kind": "optional",
"type": "string",
"example": "2c941653-b229-4528-b576-70fcfd388543:49645839701979566120793328447151049151317978254208401410:000000000000",
"default": "2c941653-b229-4528-b576-70fcfd388543:49645839701979566120793328447151049151317978254208401410:000000000000"
}
],
"modelRef": "#/components/schemas/inline_response_200",
"isExpanded": true
}
]
},
{
"statusCode": "400",
"description": "Request Failed Validation",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "",
"customType": "inline_response_400",
"schema": [
{
"name": "message",
"kind": "optional",
"type": "string",
"example": "Invalid request body",
"default": "Invalid request body"
},
{
"name": "errors",
"kind": "optional",
"type": "array",
"example": "[{\"('subscription', 'start_date')\":\"Field required\"}]",
"default": [
{
"('subscription', 'start_date')": "Field required"
}
],
"itemType": "object",
"customType": "object[]",
"itemExample": "",
"itemDefault": ""
}
],
"modelRef": "#/components/schemas/inline_response_400",
"isExpanded": true
}
]
},
{
"statusCode": "403",
"description": "Invalid API Key",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "",
"customType": "inline_response_403",
"schema": [
{
"name": "message",
"kind": "optional",
"type": "string",
"example": "Forbidden",
"default": "Forbidden"
},
{
"name": "errors",
"kind": "optional",
"type": "string",
"example": "Invalid API Key",
"default": "Invalid API Key"
}
],
"modelRef": "#/components/schemas/inline_response_403",
"isExpanded": true
}
]
},
{
"statusCode": "404",
"description": "Method/Path Not Found",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "",
"customType": "inline_response_404",
"schema": [
{
"name": "message",
"kind": "optional",
"type": "string",
"example": "Method/Path combination not found.",
"default": "Method/Path combination not found."
}
],
"modelRef": "#/components/schemas/inline_response_404",
"isExpanded": true
}
]
},
{
"statusCode": "415",
"description": "Unsupported Media Type",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "",
"customType": "inline_response_415",
"schema": [
{
"name": "message",
"kind": "optional",
"type": "string",
"example": "Unsupported Media Type",
"default": "Unsupported Media Type"
},
{
"name": "errors",
"kind": "optional",
"type": "string",
"example": "Content-Type must be application/json",
"default": "Content-Type must be application/json"
}
],
"modelRef": "#/components/schemas/inline_response_415",
"isExpanded": true
}
]
},
{
"statusCode": "500",
"description": "Server Error",
"jsonExample": "",
"isExpanded": true
}
],
"hasXCodeSamples": false,
"examples": {
"languages": [
{
"id": "oGVuYdcZNehibpDVteU7V",
"language": "curl",
"label": "cURL",
"code": "curl --request POST \\\n --url https://api.butterpayments.com/recover/payments \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"customer\": {\n \"id\": \"11223344\"\n },\n \"subscription\": {\n \"id\": \"sub_1234\",\n \"start_date\": \"2023-10-25T03:57:26Z\"\n },\n \"invoice\": {\n \"id\": \"inv_12345\",\n \"created_at\": \"2023-10-25T03:57:26Z\"\n },\n \"transactions\": [\n {\n \"id\": \"ts_12345\",\n \"psp_transaction_id\": \"ts_12345\",\n \"psp\": \"Worldpay\",\n \"acquirer_country\": \"US\",\n \"amount\": 12.23,\n \"currency\": \"USD\",\n \"funding_source\": \"CREDIT\",\n \"outcome\": {\n \"raw_response_message\": \"insufficient_funds\"\n },\n \"payment_method_id\": \"\",\n \"psp_transaction_created_at\": \"2023-10-25T03:57:26Z\",\n \"scheme\": \"visa\",\n \"success\": false\n }\n ]\n }'"
},
{
"id": "hBUYCdIu8lssrQCAlV4e8",
"language": "javascript",
"label": "javascript",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"customer\": {\n \"id\": \"11223344\"\n },\n \"subscription\": {\n \"id\": \"sub_1234\",\n \"start_date\": \"2023-10-25T03:57:26Z\"\n },\n \"invoice\": {\n \"id\": \"inv_12345\",\n \"created_at\": \"2023-10-25T03:57:26Z\"\n },\n \"transactions\": [\n {\n \"id\": \"ts_12345\",\n \"psp_transaction_id\": \"ts_12345\",\n \"psp\": \"Worldpay\",\n \"acquirer_country\": \"US\",\n \"amount\": 12.23,\n \"currency\": \"USD\",\n \"funding_source\": \"CREDIT\",\n \"outcome\": {\n \"raw_response_message\": \"insufficient_funds\"\n },\n \"payment_method_id\": \"\",\n \"psp_transaction_created_at\": \"2023-10-25T03:57:26Z\",\n \"scheme\": \"visa\",\n \"success\": false\n }\n ]\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.butterpayments.com/recover/payments\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));"
},
{
"id": "RY-YAMGU88cMoUCqjKeh7",
"language": "ruby",
"label": "Ruby",
"code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.butterpayments.com/recover/payments\")\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.body = JSON.dump({\n \"customer\": {\n \"id\": \"11223344\"\n },\n \"subscription\": {\n \"id\": \"sub_1234\",\n \"start_date\": \"2023-10-25T03:57:26Z\"\n },\n \"invoice\": {\n \"id\": \"inv_12345\",\n \"created_at\": \"2023-10-25T03:57:26Z\"\n },\n \"transactions\": [\n {\n \"id\": \"ts_12345\",\n \"psp_transaction_id\": \"ts_12345\",\n \"psp\": \"Worldpay\",\n \"acquirer_country\": \"US\",\n \"amount\": 12.23,\n \"currency\": \"USD\",\n \"funding_source\": \"CREDIT\",\n \"outcome\": {\n \"raw_response_message\": \"insufficient_funds\"\n },\n \"payment_method_id\": \"\",\n \"psp_transaction_created_at\": \"2023-10-25T03:57:26Z\",\n \"scheme\": \"visa\",\n \"success\": false\n }\n ]\n})\n\nresponse = https.request(request)\nputs response.read_body\n"
},
{
"id": "eFT8pDMkY0LPxguHtzRJy",
"language": "python",
"label": "Python",
"code": "import requests\nimport json\n\nurl = \"https://api.butterpayments.com/recover/payments\"\n\npayload = json.dumps({\n \"customer\": {\n \"id\": \"11223344\"\n },\n \"subscription\": {\n \"id\": \"sub_1234\",\n \"start_date\": \"2023-10-25T03:57:26Z\"\n },\n \"invoice\": {\n \"id\": \"inv_12345\",\n \"created_at\": \"2023-10-25T03:57:26Z\"\n },\n \"transactions\": [\n {\n \"id\": \"ts_12345\",\n \"psp_transaction_id\": \"ts_12345\",\n \"psp\": \"Worldpay\",\n \"acquirer_country\": \"US\",\n \"amount\": 12.23,\n \"currency\": \"USD\",\n \"funding_source\": \"CREDIT\",\n \"outcome\": {\n \"raw_response_message\": \"insufficient_funds\"\n },\n \"payment_method_id\": \"\",\n \"psp_transaction_created_at\": \"2023-10-25T03:57:26Z\",\n \"scheme\": \"visa\",\n \"success\": False\n }\n ]\n})\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": "oGVuYdcZNehibpDVteU7V"
},
"results": {
"languages": [
{
"id": "vcIUGPiSAfA3wMyYQjJGq",
"language": "200",
"code": "// Request Successful\n{\n \"message\": \"Request submitted for processing\",\n \"request_id\": \"2c941653-b229-4528-b576-70fcfd388543:49645839701979566120793328447151049151317978254208401410:000000000000\"\n}"
},
{
"id": "dFRv5EIILOJ_lgKofWyZJ",
"language": "400",
"code": "// Request Failed Validation\n{\n \"message\": \"Invalid request body\",\n \"errors\": [\n {}\n ]\n}"
},
{
"id": "M75bEQ8hX080MUc4HWXcH",
"language": "403",
"code": "// Invalid API Key\n{\n \"message\": \"Forbidden\",\n \"errors\": \"Invalid API Key\"\n}"
},
{
"id": "gjw6tyt9mjV9s75ORrBpG",
"language": "404",
"code": "// Method/Path Not Found\n{\n \"message\": \"Method/Path combination not found.\"\n}"
},
{
"id": "6LiKipnN-rZ9ZG0nqy3Mz",
"language": "415",
"code": "// Unsupported Media Type\n{\n \"message\": \"Unsupported Media Type\",\n \"errors\": \"Content-Type must be application/json\"\n}"
},
{
"id": "YJ-AHOUiUWPCByuRO1UjW",
"language": "500",
"code": "// Server Error\n"
}
],
"selectedLanguageId": "vcIUGPiSAfA3wMyYQjJGq"
}
},
"children": [
{
"id": "ySsIg158mzBx_-SXiNdYE",
"type": "paragraph",
"children": [
{
"text": "This endpoint serves as the entry point into Recover for all transaction events related to payment processing, including successful payments, failed payments, and Butter retry events. All transaction events, besides disputes, should be sent by the merchant to this endpoint."
}
]
},
{
"id": "aXXYSc9BGtcvP6Cs8pmZ1",
"type": "paragraph",
"children": [
{
"text": "Expand the objects below and add field values to create an example payload on the right side of the screen."
}
]
}
]
}