Payments

1 min

POST

https://api.butterpayments.com/recover/payments

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.

Expand the objects below and add field values to create an example payload on the right side of the screen.

Body Parameters

bodypaymentsrequired
- customercustomerrequired
  - idstringrequired
    Example
    11223344
    Description
    The internal identifier from your subscription management platform used to designate the customer.
  - psp_idstring
    Example
    cus_12345
    Description
    The identifier used by the Payment Processor to designate the customer.
  - created_attimestamp
    Example
    2023-10-25T03:57:26Z
    Description
    The timestamp that the customer was created.
  - postal_codepostal_code
    Example
    04102
    Description
    The postal code from the customer's address.
- subscriptionsubscriptionrequired
  - idstringrequired
    Example
    sub_1234
    Description
    The internal identifier from your subscription management platform used to designate the subscription.
  - start_datetimestamprequired
    Example
    2023-10-25T03:57:26Z
    Description
    Timestamp of when the subscription started.
  - end_datetimestamp
    Example
    2023-10-25T03:57:26Z
    Description
    Timestamp of when the subscription ended/will end if applicable.
  - discounted_or_free_periodboolean
    Description
    Boolean to designate free trials or discounted billing.
  - product_idstring
    Example
    sku_02901
    Description
    Unique identifier of the product/plan the subscription is for.
  - billingobject
    - periodstring<day | week | month | year>
      Example
      month
      Description
      The subscription billing period. This attribute should be one of the specified values, or absent.
    - frequencyinteger
      Example
      1
      Description
      The number of payments expected per billing period. This attribute should be a positive integer, or absent.
- invoiceinvoicerequired
  - idstringrequired
    Example
    inv_12345
    Description
    The internal identifier from your subscription management platform used to designate the invoice.
  - created_attimestamprequired
    Example
    2023-10-25T03:57:26Z
- transactionstransaction[]required
  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.
  - idstringrequired
    Example
    ts_12345
    Description
    The internal identifier from your subscription management platform used to designate the transaction.
  - psp_transaction_idstringrequired
    Example
    ts_12345
    Description
    The identifier used to designate the transaction from the PSP.
  - network_transaction_idstring
    Example
    PCQVZWBGA0912
    Description
    The original transaction id from the network. Required for Worldpay integrations.
  - pspstring<adyen | braintree | recurly | recharge | stripe | worldpay>required
    Example
    Worldpay
    Description
    The name of the PSP the transaction originated on. This should be one of the specified values.
  - midstring
    Example
    8224137
    Description
    The MID (merchant identification number) used to process a transaction with the PSP. Required for Worldpay integrations.
  - reporting_groupstring
    Example
    Pepsi
    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).
  - acquirer_countrystringrequired
    Example
    US
    Description
    The country in which the payment was processed and acquired in.
  - amountnumberrequired
    Example
    12.23
    Description
    The amount to be attempted, represented as a float.
  - billing_postal_codepostal_code
    Example
    04102
    Description
    The postal code from the customer's billing address.
  - authboolean
    Description
    Boolean to represent if this is a pre-authorization or final capture.
  - binstring
    Example
    112233
    Description
    The 6 digit Bank Identification Number of the payment card used.
  - capturedboolean
    Description
    Boolean to represent if the payment has been captured.
  - currencystringrequired
    Example
    USD
    Description
    The currency of the transaction in ISO standard format.
  - funding_sourcestring<CREDIT | DEBIT | MIXED | PAYPAL | PREPAID | UNCATEGORIZED | UNKNOWN>required
    Example
    CREDIT
    Description
    The account type funding the payment card. This should be one of the specified values.
  - issuer_countrystring
    Example
    US
    Description
    The country in which the payment card was issued.
  - outcomeobjectrequired
    - raw_response_messagestringrequired
      Example
      insufficient_funds
      Description
      The issuer approval or decline message provided in the authorization response.
    - psp_response_messagestring
      Example
      The customer has insufficient funds.
      Description
      The response description provided by the Payment Processor.
    - processor_response_codenumber
      Example
      2000
      Description
      The response code returned provided by the Payment Processor.
    - network_statusstring
      Example
      psp_block
      Description
      Additional net work data returned by certain Payment Processors (if applicable).
    - response_typestring
      Example
      hard_decline
      Description
      Category of decline code (Soft Decline, Hard Decline)
  - payment_method_idstringrequired
    Description
    The id from the psp representing the payment method attempted.
  - psp_transaction_created_attimestamprequired
    Example
    2023-10-25T03:57:26Z
  - refundedboolean
    Description
    Boolean to represent if the payment has been refunded.
  - schemestringrequired
    Example
    visa
    Description
    Network of the payment card (Visa, MasterCard, etc.).
  - successbooleanrequired
    Description
    Boolean to represent if the transaction was successfully processed.
  - descriptionstring
    Description
    A description of the item to show on a receipt or invoice.
  - statement_descriptorstring
    Example
    Butter* tshirt
    Description
    A short descriptor that will appear on the customer's bank statement.
  - enhanced_dataenhanced_data
    Description
    Optional enhanced data fields that can be added to processing.
    - level_2level_2
      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.
      - purchase_order_numberstring
        Example
        2337210904
        Description
        A unique identifier for the purchase.
      - total_tax_amountstring
        Example
        12.20
        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.
      - total_discount_amountstring
        Example
        20.00
        Description
        The total discount amount applied to the purchase.
    - level_3level_3
      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.
      - line_itemsobject[]
        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.
- customobject
  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.

Responses

200Request Successful

inline_response_200
- messagestring
  Example
  Request submitted for processing
  Default
  Request submitted for processing
- request_idstring
  Example
  2c941653-b229-4528-b576-70fcfd388543:49645839701979566120793328447151049151317978254208401410:000000000000
  Default
  2c941653-b229-4528-b576-70fcfd388543:49645839701979566120793328447151049151317978254208401410:000000000000

400Request Failed Validation

inline_response_400
- messagestring
  Example
  Invalid request body
  Default
  Invalid request body
- errorsobject[]
  Example
```
[
  {
    "('subscription', 'start_date')": "Field required"
  }
]
```
  Default
  {"('subscription', 'start_date')":"Field required"}

403Invalid API Key

inline_response_403
- messagestring
  Example
  Forbidden
  Default
  Forbidden
- errorsstring
  Example
  Invalid API Key
  Default
  Invalid API Key

404Method/Path Not Found

inline_response_404
- messagestring
  Example
  Method/Path combination not found.
  Default
  Method/Path combination not found.

415Unsupported Media Type

inline_response_415
- messagestring
  Example
  Unsupported Media Type
  Default
  Unsupported Media Type
- errorsstring
  Example
  Content-Type must be application/json
  Default
  Content-Type must be application/json

500Server Error

curl

curl --request POST \
     --url https://api.butterpayments.com/recover/payments \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "customer": {
     "id": "11223344"
     },
     "subscription": {
     "id": "sub_1234",
     "start_date": "2023-10-25T03:57:26Z"
     },
     "invoice": {
     "id": "inv_12345",
     "created_at": "2023-10-25T03:57:26Z"
     },
     "transactions": [
     {
     "id": "ts_12345",
     "psp_transaction_id": "ts_12345",
     "psp": "Worldpay",
     "acquirer_country": "US",
     "amount": 12.23,
     "currency": "USD",
     "funding_source": "CREDIT",
     "outcome": {
     "raw_response_message": "insufficient_funds"
     },
     "payment_method_id": "",
     "psp_transaction_created_at": "2023-10-25T03:57:26Z",
     "scheme": "visa",
     "success": false
     }
     ]
     }'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
   "customer": {
      "id": "11223344"
   },
   "subscription": {
      "id": "sub_1234",
      "start_date": "2023-10-25T03:57:26Z"
   },
   "invoice": {
      "id": "inv_12345",
      "created_at": "2023-10-25T03:57:26Z"
   },
   "transactions": [
      {
         "id": "ts_12345",
         "psp_transaction_id": "ts_12345",
         "psp": "Worldpay",
         "acquirer_country": "US",
         "amount": 12.23,
         "currency": "USD",
         "funding_source": "CREDIT",
         "outcome": {
            "raw_response_message": "insufficient_funds"
         },
         "payment_method_id": "",
         "psp_transaction_created_at": "2023-10-25T03:57:26Z",
         "scheme": "visa",
         "success": false
      }
   ]
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://api.butterpayments.com/recover/payments", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.butterpayments.com/recover/payments")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request.body = JSON.dump({
   "customer": {
      "id": "11223344"
   },
   "subscription": {
      "id": "sub_1234",
      "start_date": "2023-10-25T03:57:26Z"
   },
   "invoice": {
      "id": "inv_12345",
      "created_at": "2023-10-25T03:57:26Z"
   },
   "transactions": [
      {
         "id": "ts_12345",
         "psp_transaction_id": "ts_12345",
         "psp": "Worldpay",
         "acquirer_country": "US",
         "amount": 12.23,
         "currency": "USD",
         "funding_source": "CREDIT",
         "outcome": {
            "raw_response_message": "insufficient_funds"
         },
         "payment_method_id": "",
         "psp_transaction_created_at": "2023-10-25T03:57:26Z",
         "scheme": "visa",
         "success": false
      }
   ]
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://api.butterpayments.com/recover/payments"

payload = json.dumps({
   "customer": {
      "id": "11223344"
   },
   "subscription": {
      "id": "sub_1234",
      "start_date": "2023-10-25T03:57:26Z"
   },
   "invoice": {
      "id": "inv_12345",
      "created_at": "2023-10-25T03:57:26Z"
   },
   "transactions": [
      {
         "id": "ts_12345",
         "psp_transaction_id": "ts_12345",
         "psp": "Worldpay",
         "acquirer_country": "US",
         "amount": 12.23,
         "currency": "USD",
         "funding_source": "CREDIT",
         "outcome": {
            "raw_response_message": "insufficient_funds"
         },
         "payment_method_id": "",
         "psp_transaction_created_at": "2023-10-25T03:57:26Z",
         "scheme": "visa",
         "success": False
      }
   ]
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

200

// Request Successful
{
  "message": "Request submitted for processing",
  "request_id": "2c941653-b229-4528-b576-70fcfd388543:49645839701979566120793328447151049151317978254208401410:000000000000"
}

400

// Request Failed Validation
{
  "message": "Invalid request body",
  "errors": [
    {}
  ]
}

403

// Invalid API Key
{
  "message": "Forbidden",
  "errors": "Invalid API Key"
}

404

// Method/Path Not Found
{
  "message": "Method/Path combination not found."
}

415

// Unsupported Media Type
{
  "message": "Unsupported Media Type",
  "errors": "Content-Type must be application/json"
}

500

// Server Error

Expand the objects below and add field values to create an example payload on the right side of the screen.