Revenue Recovery - Create
curl --request POST \
--url https://sandbox.hyperswitch.io/v2/payments/recovery \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"action": "schedule_failed_payment",
"amount_details": {
"currency": "USD",
"order_amount": 6540
},
"billing_merchant_connector_id": "mca_billing_1234567890",
"connector_customer_id": "cust_12345",
"connector_transaction_id": "993672945374576J",
"error": {
"code": "card_declined",
"message": "The card was declined."
},
"merchant_reference_id": "invoice_mbabizu24mvu3mela5njyh",
"payment_merchant_connector_id": "mca_payment_1234567890",
"payment_method_data": {
"payment_method_metadata": {
"card_network": "Visa",
"card_type": "credit",
"last4": "4242"
},
"primary_processor_payment_method_token": "token_1234"
},
"payment_method_sub_type": "credit",
"payment_method_type": "card",
"transaction_created_at": "2022-09-10T10:11:12Z",
"transaction_status": "failure"
}
'import requests
url = "https://sandbox.hyperswitch.io/v2/payments/recovery"
payload = {
"action": "schedule_failed_payment",
"amount_details": {
"currency": "USD",
"order_amount": 6540
},
"billing_merchant_connector_id": "mca_billing_1234567890",
"connector_customer_id": "cust_12345",
"connector_transaction_id": "993672945374576J",
"error": {
"code": "card_declined",
"message": "The card was declined."
},
"merchant_reference_id": "invoice_mbabizu24mvu3mela5njyh",
"payment_merchant_connector_id": "mca_payment_1234567890",
"payment_method_data": {
"payment_method_metadata": {
"card_network": "Visa",
"card_type": "credit",
"last4": "4242"
},
"primary_processor_payment_method_token": "token_1234"
},
"payment_method_sub_type": "credit",
"payment_method_type": "card",
"transaction_created_at": "2022-09-10T10:11:12Z",
"transaction_status": "failure"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
action: 'schedule_failed_payment',
amount_details: {currency: 'USD', order_amount: 6540},
billing_merchant_connector_id: 'mca_billing_1234567890',
connector_customer_id: 'cust_12345',
connector_transaction_id: '993672945374576J',
error: {code: 'card_declined', message: 'The card was declined.'},
merchant_reference_id: 'invoice_mbabizu24mvu3mela5njyh',
payment_merchant_connector_id: 'mca_payment_1234567890',
payment_method_data: {
payment_method_metadata: {card_network: 'Visa', card_type: 'credit', last4: '4242'},
primary_processor_payment_method_token: 'token_1234'
},
payment_method_sub_type: 'credit',
payment_method_type: 'card',
transaction_created_at: '2022-09-10T10:11:12Z',
transaction_status: 'failure'
})
};
fetch('https://sandbox.hyperswitch.io/v2/payments/recovery', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.hyperswitch.io/v2/payments/recovery",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'action' => 'schedule_failed_payment',
'amount_details' => [
'currency' => 'USD',
'order_amount' => 6540
],
'billing_merchant_connector_id' => 'mca_billing_1234567890',
'connector_customer_id' => 'cust_12345',
'connector_transaction_id' => '993672945374576J',
'error' => [
'code' => 'card_declined',
'message' => 'The card was declined.'
],
'merchant_reference_id' => 'invoice_mbabizu24mvu3mela5njyh',
'payment_merchant_connector_id' => 'mca_payment_1234567890',
'payment_method_data' => [
'payment_method_metadata' => [
'card_network' => 'Visa',
'card_type' => 'credit',
'last4' => '4242'
],
'primary_processor_payment_method_token' => 'token_1234'
],
'payment_method_sub_type' => 'credit',
'payment_method_type' => 'card',
'transaction_created_at' => '2022-09-10T10:11:12Z',
'transaction_status' => 'failure'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.hyperswitch.io/v2/payments/recovery"
payload := strings.NewReader("{\n \"action\": \"schedule_failed_payment\",\n \"amount_details\": {\n \"currency\": \"USD\",\n \"order_amount\": 6540\n },\n \"billing_merchant_connector_id\": \"mca_billing_1234567890\",\n \"connector_customer_id\": \"cust_12345\",\n \"connector_transaction_id\": \"993672945374576J\",\n \"error\": {\n \"code\": \"card_declined\",\n \"message\": \"The card was declined.\"\n },\n \"merchant_reference_id\": \"invoice_mbabizu24mvu3mela5njyh\",\n \"payment_merchant_connector_id\": \"mca_payment_1234567890\",\n \"payment_method_data\": {\n \"payment_method_metadata\": {\n \"card_network\": \"Visa\",\n \"card_type\": \"credit\",\n \"last4\": \"4242\"\n },\n \"primary_processor_payment_method_token\": \"token_1234\"\n },\n \"payment_method_sub_type\": \"credit\",\n \"payment_method_type\": \"card\",\n \"transaction_created_at\": \"2022-09-10T10:11:12Z\",\n \"transaction_status\": \"failure\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.hyperswitch.io/v2/payments/recovery")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"action\": \"schedule_failed_payment\",\n \"amount_details\": {\n \"currency\": \"USD\",\n \"order_amount\": 6540\n },\n \"billing_merchant_connector_id\": \"mca_billing_1234567890\",\n \"connector_customer_id\": \"cust_12345\",\n \"connector_transaction_id\": \"993672945374576J\",\n \"error\": {\n \"code\": \"card_declined\",\n \"message\": \"The card was declined.\"\n },\n \"merchant_reference_id\": \"invoice_mbabizu24mvu3mela5njyh\",\n \"payment_merchant_connector_id\": \"mca_payment_1234567890\",\n \"payment_method_data\": {\n \"payment_method_metadata\": {\n \"card_network\": \"Visa\",\n \"card_type\": \"credit\",\n \"last4\": \"4242\"\n },\n \"primary_processor_payment_method_token\": \"token_1234\"\n },\n \"payment_method_sub_type\": \"credit\",\n \"payment_method_type\": \"card\",\n \"transaction_created_at\": \"2022-09-10T10:11:12Z\",\n \"transaction_status\": \"failure\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.hyperswitch.io/v2/payments/recovery")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"action\": \"schedule_failed_payment\",\n \"amount_details\": {\n \"currency\": \"USD\",\n \"order_amount\": 6540\n },\n \"billing_merchant_connector_id\": \"mca_billing_1234567890\",\n \"connector_customer_id\": \"cust_12345\",\n \"connector_transaction_id\": \"993672945374576J\",\n \"error\": {\n \"code\": \"card_declined\",\n \"message\": \"The card was declined.\"\n },\n \"merchant_reference_id\": \"invoice_mbabizu24mvu3mela5njyh\",\n \"payment_merchant_connector_id\": \"mca_payment_1234567890\",\n \"payment_method_data\": {\n \"payment_method_metadata\": {\n \"card_network\": \"Visa\",\n \"card_type\": \"credit\",\n \"last4\": \"4242\"\n },\n \"primary_processor_payment_method_token\": \"token_1234\"\n },\n \"payment_method_sub_type\": \"credit\",\n \"payment_method_type\": \"card\",\n \"transaction_created_at\": \"2022-09-10T10:11:12Z\",\n \"transaction_status\": \"failure\"\n}"
response = http.request(request)
puts response.read_body{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"intent_status": "requires_confirmation",
"merchant_reference_id": "pay_mbabizu24mvu3mela5njyhpit4"
}{
"error_type": "invalid_request",
"message": "Missing required param: {param}",
"code": "IR_04"
}Revenue Recovery
Revenue Recovery - Create
Record a payment attempt made outside of Hyperswitch against a billing connector invoice, and take the requested recovery action on it, such as scheduling a retry for a failed payment or cancelling the invoice.
POST
/
v2
/
payments
/
recovery
Revenue Recovery - Create
curl --request POST \
--url https://sandbox.hyperswitch.io/v2/payments/recovery \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"action": "schedule_failed_payment",
"amount_details": {
"currency": "USD",
"order_amount": 6540
},
"billing_merchant_connector_id": "mca_billing_1234567890",
"connector_customer_id": "cust_12345",
"connector_transaction_id": "993672945374576J",
"error": {
"code": "card_declined",
"message": "The card was declined."
},
"merchant_reference_id": "invoice_mbabizu24mvu3mela5njyh",
"payment_merchant_connector_id": "mca_payment_1234567890",
"payment_method_data": {
"payment_method_metadata": {
"card_network": "Visa",
"card_type": "credit",
"last4": "4242"
},
"primary_processor_payment_method_token": "token_1234"
},
"payment_method_sub_type": "credit",
"payment_method_type": "card",
"transaction_created_at": "2022-09-10T10:11:12Z",
"transaction_status": "failure"
}
'import requests
url = "https://sandbox.hyperswitch.io/v2/payments/recovery"
payload = {
"action": "schedule_failed_payment",
"amount_details": {
"currency": "USD",
"order_amount": 6540
},
"billing_merchant_connector_id": "mca_billing_1234567890",
"connector_customer_id": "cust_12345",
"connector_transaction_id": "993672945374576J",
"error": {
"code": "card_declined",
"message": "The card was declined."
},
"merchant_reference_id": "invoice_mbabizu24mvu3mela5njyh",
"payment_merchant_connector_id": "mca_payment_1234567890",
"payment_method_data": {
"payment_method_metadata": {
"card_network": "Visa",
"card_type": "credit",
"last4": "4242"
},
"primary_processor_payment_method_token": "token_1234"
},
"payment_method_sub_type": "credit",
"payment_method_type": "card",
"transaction_created_at": "2022-09-10T10:11:12Z",
"transaction_status": "failure"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
action: 'schedule_failed_payment',
amount_details: {currency: 'USD', order_amount: 6540},
billing_merchant_connector_id: 'mca_billing_1234567890',
connector_customer_id: 'cust_12345',
connector_transaction_id: '993672945374576J',
error: {code: 'card_declined', message: 'The card was declined.'},
merchant_reference_id: 'invoice_mbabizu24mvu3mela5njyh',
payment_merchant_connector_id: 'mca_payment_1234567890',
payment_method_data: {
payment_method_metadata: {card_network: 'Visa', card_type: 'credit', last4: '4242'},
primary_processor_payment_method_token: 'token_1234'
},
payment_method_sub_type: 'credit',
payment_method_type: 'card',
transaction_created_at: '2022-09-10T10:11:12Z',
transaction_status: 'failure'
})
};
fetch('https://sandbox.hyperswitch.io/v2/payments/recovery', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.hyperswitch.io/v2/payments/recovery",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'action' => 'schedule_failed_payment',
'amount_details' => [
'currency' => 'USD',
'order_amount' => 6540
],
'billing_merchant_connector_id' => 'mca_billing_1234567890',
'connector_customer_id' => 'cust_12345',
'connector_transaction_id' => '993672945374576J',
'error' => [
'code' => 'card_declined',
'message' => 'The card was declined.'
],
'merchant_reference_id' => 'invoice_mbabizu24mvu3mela5njyh',
'payment_merchant_connector_id' => 'mca_payment_1234567890',
'payment_method_data' => [
'payment_method_metadata' => [
'card_network' => 'Visa',
'card_type' => 'credit',
'last4' => '4242'
],
'primary_processor_payment_method_token' => 'token_1234'
],
'payment_method_sub_type' => 'credit',
'payment_method_type' => 'card',
'transaction_created_at' => '2022-09-10T10:11:12Z',
'transaction_status' => 'failure'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.hyperswitch.io/v2/payments/recovery"
payload := strings.NewReader("{\n \"action\": \"schedule_failed_payment\",\n \"amount_details\": {\n \"currency\": \"USD\",\n \"order_amount\": 6540\n },\n \"billing_merchant_connector_id\": \"mca_billing_1234567890\",\n \"connector_customer_id\": \"cust_12345\",\n \"connector_transaction_id\": \"993672945374576J\",\n \"error\": {\n \"code\": \"card_declined\",\n \"message\": \"The card was declined.\"\n },\n \"merchant_reference_id\": \"invoice_mbabizu24mvu3mela5njyh\",\n \"payment_merchant_connector_id\": \"mca_payment_1234567890\",\n \"payment_method_data\": {\n \"payment_method_metadata\": {\n \"card_network\": \"Visa\",\n \"card_type\": \"credit\",\n \"last4\": \"4242\"\n },\n \"primary_processor_payment_method_token\": \"token_1234\"\n },\n \"payment_method_sub_type\": \"credit\",\n \"payment_method_type\": \"card\",\n \"transaction_created_at\": \"2022-09-10T10:11:12Z\",\n \"transaction_status\": \"failure\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.hyperswitch.io/v2/payments/recovery")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"action\": \"schedule_failed_payment\",\n \"amount_details\": {\n \"currency\": \"USD\",\n \"order_amount\": 6540\n },\n \"billing_merchant_connector_id\": \"mca_billing_1234567890\",\n \"connector_customer_id\": \"cust_12345\",\n \"connector_transaction_id\": \"993672945374576J\",\n \"error\": {\n \"code\": \"card_declined\",\n \"message\": \"The card was declined.\"\n },\n \"merchant_reference_id\": \"invoice_mbabizu24mvu3mela5njyh\",\n \"payment_merchant_connector_id\": \"mca_payment_1234567890\",\n \"payment_method_data\": {\n \"payment_method_metadata\": {\n \"card_network\": \"Visa\",\n \"card_type\": \"credit\",\n \"last4\": \"4242\"\n },\n \"primary_processor_payment_method_token\": \"token_1234\"\n },\n \"payment_method_sub_type\": \"credit\",\n \"payment_method_type\": \"card\",\n \"transaction_created_at\": \"2022-09-10T10:11:12Z\",\n \"transaction_status\": \"failure\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.hyperswitch.io/v2/payments/recovery")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"action\": \"schedule_failed_payment\",\n \"amount_details\": {\n \"currency\": \"USD\",\n \"order_amount\": 6540\n },\n \"billing_merchant_connector_id\": \"mca_billing_1234567890\",\n \"connector_customer_id\": \"cust_12345\",\n \"connector_transaction_id\": \"993672945374576J\",\n \"error\": {\n \"code\": \"card_declined\",\n \"message\": \"The card was declined.\"\n },\n \"merchant_reference_id\": \"invoice_mbabizu24mvu3mela5njyh\",\n \"payment_merchant_connector_id\": \"mca_payment_1234567890\",\n \"payment_method_data\": {\n \"payment_method_metadata\": {\n \"card_network\": \"Visa\",\n \"card_type\": \"credit\",\n \"last4\": \"4242\"\n },\n \"primary_processor_payment_method_token\": \"token_1234\"\n },\n \"payment_method_sub_type\": \"credit\",\n \"payment_method_type\": \"card\",\n \"transaction_created_at\": \"2022-09-10T10:11:12Z\",\n \"transaction_status\": \"failure\"\n}"
response = http.request(request)
puts response.read_body{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"intent_status": "requires_confirmation",
"merchant_reference_id": "pay_mbabizu24mvu3mela5njyhpit4"
}{
"error_type": "invalid_request",
"message": "Missing required param: {param}",
"code": "IR_04"
}Authorizations
Format: api-key=<api_key>
Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.
Body
application/json
Show child attributes
Show child attributes
Billing connector id to update the invoices.
Example:
"mca_1234567890"
Payments connector id to update the invoices.
Example:
"mca_1234567890"
The status of the attempt
Available options:
started, authentication_failed, router_declined, authentication_pending, authentication_successful, authorized, authorization_failed, charged, authorizing, cod_initiated, voided, voided_post_charge, void_initiated, capture_initiated, capture_failed, void_failed, auto_refunded, partial_charged, partially_authorized, partial_charged_and_chargeable, unresolved, pending, failure, payment_method_awaited, confirmation_awaited, device_data_collection_pending, integrity_failure, expired, capture_review Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.
Available options:
ach, affirm, afterpay_clearpay, alfamart, ali_pay, ali_pay_hk, alma, amazon_pay, paysera, apple_pay, atome, bacs, bancontact_card, becs, benefit, bizum, blik, bluecode, boleto, bca_bank_transfer, bni_va, breadpay, bri_va, bhn_card_network, card_redirect, cimb_va, classic, credit, crypto_currency, cashapp, dana, danamon_va, debit, duit_now, efecty, eft, eft_debit_order, eps, flexiti, fps, evoucher, giropay, givex, google_pay, go_pay, gcash, ideal, interac, indomaret, klarna, kakao_pay, local_bank_redirect, mandiri_va, knet, mb_way, mobile_pay, momo, momo_atm, multibanco, online_banking_thailand, online_banking_czech_republic, online_banking_finland, online_banking_fpx, online_banking_poland, online_banking_slovakia, oxxo, pago_efectivo, permata_bank_transfer, open_banking_uk, pay_bright, payjustnow, paypal, paze, pix, pix_key, pix_emv, pix_qr, pix_automatico_qr, pix_automatico_push, pay_safe_card, przelewy24, prompt_pay, pse, qris, red_compra, red_pagos, samsung_pay, sepa, sepa_bank_transfer, sepa_guarenteed_debit, skrill, sofort, swish, touch_n_go, trustly, twint, upi_collect, upi_intent, upi_qr, vipps, viet_qr, venmo, walley, we_chat_pay, seven_eleven, lawson, mini_stop, family_mart, seicomart, pay_easy, local_bank_transfer, mifinity, open_banking_pis, direct_carrier_billing, instant_bank_transfer, instant_bank_transfer_finland, instant_bank_transfer_poland, revolut_pay, indonesian_bank_transfer, open_banking, network_token, payshap, payshap_proxy customer id at payment connector for which mandate is attached.
Example:
"cust_12345"
Show child attributes
Show child attributes
type of action that needs to taken after consuming recovery payload
Available options:
cancel_invoice, schedule_failed_payment, success_payment_external, pending_payment, no_action, invalid_action The invoice identifier from the merchant's billing system that this payment attempt is being recorded against. This ensures idempotency when the same invoice is reported more than once.
Required string length:
30Example:
"invoice_mbabizu24mvu3mela5njyh"
Error details for the payment
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The time at which payment attempt was created.
Example:
"2022-09-10T10:11:12Z"
Indicates the type of payment method. Eg: 'card', 'wallet', etc.
Available options:
card, card_redirect, pay_later, wallet, bank_redirect, bank_transfer, crypto, bank_debit, reward, real_time_payment, upi, voucher, gift_card, open_banking, mobile_payment, network_token Invoice billing started at billing connector end.
Example:
"2022-09-10T10:11:12Z"
A unique identifier for a payment provided by the payment connector
Example:
"993672945374576J"
Allow partial authorization for this payment
You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.
Response
Revenue Recovery Payment Recorded Successfully
Unique identifier for the payment.
Required string length:
30Example:
"pay_mbabizu24mvu3mela5njyhpit4"
Represents the overall status of a payment intent. The status transitions through various states depending on the payment method, confirmation, capture method, and any subsequent actions (like customer authentication or manual capture).
Available options:
succeeded, failed, cancelled, cancelled_post_capture, processing, requires_customer_action, requires_merchant_action, requires_payment_method, requires_confirmation, requires_capture, partially_captured, partially_captured_and_capturable, partially_authorized_and_requires_capture, partially_captured_and_processing, conflicted, expired, review Unique identifier for the payment. This ensures idempotency for multiple payments that have been done by a single merchant.
Required string length:
30Example:
"pay_mbabizu24mvu3mela5njyhpit4"
Was this page helpful?