> ## Documentation Index > Fetch the complete documentation index at: https://api-reference.hyperswitch.io/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml post /v2/payments/recovery openapi: 3.0.3 info: title: Hyperswitch - API Documentation description: > ## Get started Hyperswitch provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using your favorite HTTP/REST library. We have a testing environment referred to "sandbox", which you can setup to test API calls without affecting production data. Currently, our sandbox environment is live while our production environment is under development and will be available soon. You can sign up on our Dashboard to get API keys to access Hyperswitch API. ### Environment Use the following base URLs when making requests to the APIs: | Environment | Base URL | |---------------|------------------------------------| | Sandbox | | | Production | | ## Authentication When you sign up on our [dashboard](https://app.hyperswitch.io) and create a merchant account, you are given a secret key (also referred as api-key) and a publishable key. You may authenticate all API requests with Hyperswitch server by providing the appropriate key in the request Authorization header. | Key | Description | |-----------------|-----------------------------------------------------------------------------------------------| | api-key | Private key. Used to authenticate all API requests from your merchant server | | publishable key | Unique identifier for your account. Used to authenticate API requests from your app's client | Never share your secret api keys. Keep them guarded and secure. contact: name: Hyperswitch Support url: https://hyperswitch.io email: support.global@juspay.io license: name: Apache-2.0 version: 0.1.0 servers: - url: https://sandbox.hyperswitch.io description: Sandbox Environment security: [] tags: - name: Merchant Account description: Create and manage merchant accounts - name: Profile description: Create and manage profiles - name: Merchant Connector Account description: Create and manage merchant connector accounts - name: Payments description: Create and manage one-time payments, recurring payments and mandates - name: Refunds description: Create and manage refunds for successful payments - name: Mandates description: Manage mandates - name: Customers description: Create and manage customers - name: Payment Methods description: Create and manage payment methods of customers - name: Disputes description: Manage disputes - name: API Key description: Create and manage API Keys - name: Payouts description: Create and manage payouts - name: payment link description: Create payment link - name: Routing description: Create and manage routing configurations - name: Event description: Manage events paths: /v2/payments/recovery: post: tags: - Revenue Recovery summary: Revenue Recovery - Create description: >- 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. operationId: Create a Revenue Recovery Payment requestBody: content: application/json: schema: $ref: '#/components/schemas/RecoveryPaymentsCreate' examples: Record a failed payment attempt and schedule a retry: value: 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 required: true responses: '200': description: Revenue Recovery Payment Recorded Successfully content: application/json: schema: $ref: '#/components/schemas/RecoveryPaymentsResponse' '400': description: Missing mandatory fields content: application/json: schema: $ref: '#/components/schemas/GenericErrorResponseOpenApi' '404': description: Resource missing '500': description: Internal server error security: - api_key: [] components: schemas: RecoveryPaymentsCreate: type: object required: - amount_details - billing_merchant_connector_id - payment_merchant_connector_id - transaction_status - payment_method_sub_type - connector_customer_id - payment_method_data - action properties: amount_details: $ref: '#/components/schemas/AmountDetails' merchant_reference_id: type: string description: >- 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. example: invoice_mbabizu24mvu3mela5njyh nullable: true maxLength: 30 minLength: 30 error: allOf: - $ref: '#/components/schemas/ErrorDetails' nullable: true billing_merchant_connector_id: type: string description: Billing connector id to update the invoices. example: mca_1234567890 payment_merchant_connector_id: type: string description: Payments connector id to update the invoices. example: mca_1234567890 transaction_status: $ref: '#/components/schemas/AttemptStatus' billing: allOf: - $ref: '#/components/schemas/Address' nullable: true payment_method_sub_type: $ref: '#/components/schemas/PaymentMethodType' transaction_created_at: type: string format: date-time description: The time at which payment attempt was created. example: '2022-09-10T10:11:12Z' nullable: true payment_method_type: allOf: - $ref: '#/components/schemas/PaymentMethod' nullable: true connector_customer_id: type: string description: customer id at payment connector for which mandate is attached. example: cust_12345 billing_started_at: type: string format: date-time description: Invoice billing started at billing connector end. example: '2022-09-10T10:11:12Z' nullable: true connector_transaction_id: type: string description: A unique identifier for a payment provided by the payment connector example: 993672945374576J nullable: true payment_method_data: $ref: '#/components/schemas/CustomRecoveryPaymentMethodData' action: $ref: '#/components/schemas/RecoveryAction' enable_partial_authorization: type: boolean description: Allow partial authorization for this payment default: false nullable: true metadata: type: object description: >- 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. nullable: true additionalProperties: false RecoveryPaymentsResponse: type: object required: - id - intent_status properties: id: type: string description: Unique identifier for the payment. example: pay_mbabizu24mvu3mela5njyhpit4 maxLength: 30 minLength: 30 intent_status: allOf: - $ref: '#/components/schemas/IntentStatus' default: requires_confirmation merchant_reference_id: type: string description: >- Unique identifier for the payment. This ensures idempotency for multiple payments that have been done by a single merchant. example: pay_mbabizu24mvu3mela5njyhpit4 nullable: true maxLength: 30 minLength: 30 GenericErrorResponseOpenApi: type: object required: - error_type - message - code properties: error_type: type: string example: invalid_request message: type: string example: 'Missing required param: {param}' code: type: string example: IR_04 AmountDetails: type: object required: - currency properties: order_amount: type: integer format: int64 description: >- The payment amount. Amount for the payment in the lowest denomination of the currency, (i.e) in cents for USD denomination, in yen for JPY denomination etc. E.g., Pass 100 to charge $1.00 and 1 for 1¥ since ¥ is a zero-decimal currency. Read more about [the Decimal and Non-Decimal Currencies](https://github.com/juspay/hyperswitch/wiki/Decimal-and-Non%E2%80%90Decimal-Currencies) example: 6540 minimum: 0 currency: $ref: '#/components/schemas/Currency' shipping_cost: allOf: - $ref: '#/components/schemas/MinorUnit' nullable: true order_tax_amount: allOf: - $ref: '#/components/schemas/MinorUnit' nullable: true skip_external_tax_calculation: $ref: '#/components/schemas/TaxCalculationOverride' skip_surcharge_calculation: $ref: '#/components/schemas/SurchargeCalculationOverride' surcharge_amount: allOf: - $ref: '#/components/schemas/MinorUnit' nullable: true tax_on_surcharge: allOf: - $ref: '#/components/schemas/MinorUnit' nullable: true ErrorDetails: type: object description: Error details for the payment required: - code - message properties: code: type: string description: The error code example: card_declined message: type: string description: The error message example: The card was declined. reason: type: string description: The detailed error reason that was returned by the connector. example: The card was declined. nullable: true unified_code: type: string description: |- The unified error code across all connectors. This can be relied upon for taking decisions based on the error. example: card_declined nullable: true unified_message: type: string description: >- The unified error message across all connectors. If there is a translation available, this will have the translated message example: The card was declined. nullable: true network_advice_code: type: string description: >- This field can be returned for both approved and refused Mastercard payments. This code provides additional information about the type of transaction or the reason why the payment failed. If the payment failed, the network advice code gives guidance on if and when you can retry the payment. example: '01' nullable: true network_decline_code: type: string description: >- For card errors resulting from a card issuer decline, a brand specific 2, 3, or 4 digit code which indicates the reason the authorization failed. example: '05' nullable: true network_error_message: type: string description: >- A string indicating how to proceed with an network error if payment gateway provide one. This is used to understand the network error code better. example: Do not retry nullable: true AttemptStatus: type: string description: The status of the attempt enum: - 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 Address: type: object properties: address: allOf: - $ref: '#/components/schemas/AddressDetails' nullable: true phone: allOf: - $ref: '#/components/schemas/PhoneDetails' nullable: true email: type: string nullable: true PaymentMethodType: type: string description: >- Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets. enum: - 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 PaymentMethod: type: string description: 'Indicates the type of payment method. Eg: ''card'', ''wallet'', etc.' enum: - 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 CustomRecoveryPaymentMethodData: type: object required: - primary_processor_payment_method_token - payment_method_metadata properties: primary_processor_payment_method_token: type: string description: Primary payment method token at payment processor end. example: token_1234 payment_method_metadata: $ref: '#/components/schemas/AdditionalCardInfo' RecoveryAction: type: string description: type of action that needs to taken after consuming recovery payload enum: - cancel_invoice - schedule_failed_payment - success_payment_external - pending_payment - no_action - invalid_action IntentStatus: type: string description: >- 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). enum: - 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 Currency: type: string description: >- The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment. enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHF - CLF - CLP - CNY - COP - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLE - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL MinorUnit: type: integer format: int64 description: This Unit struct represents MinorUnit in which core amount works TaxCalculationOverride: type: string enum: - skip - calculate SurchargeCalculationOverride: type: string enum: - skip - calculate AddressDetails: type: object description: Address details properties: city: type: string description: The city, district, suburb, town, or village of the address. example: New York nullable: true maxLength: 50 country: allOf: - $ref: '#/components/schemas/CountryAlpha2' nullable: true line1: type: string description: The first line of the street address or P.O. Box. example: 123, King Street nullable: true maxLength: 200 line2: type: string description: >- The second line of the street address or P.O. Box (e.g., apartment, suite, unit, or building). example: Powelson Avenue nullable: true maxLength: 50 line3: type: string description: The third line of the street address, if applicable. example: Bridgewater nullable: true maxLength: 50 zip: type: string description: The zip/postal code for the address example: '08807' nullable: true maxLength: 50 state: type: string description: The address state example: New York nullable: true first_name: type: string description: The first name for the address example: John nullable: true maxLength: 255 last_name: type: string description: The last name for the address example: Doe nullable: true maxLength: 255 origin_zip: type: string description: The zip/postal code of the origin example: '08807' nullable: true maxLength: 50 PhoneDetails: type: object properties: number: type: string description: The contact number example: '9123456789' nullable: true country_code: type: string description: The country code attached to the number example: '+1' nullable: true AdditionalCardInfo: type: object properties: card_issuer: type: string description: The name of issuer of the card nullable: true card_network: allOf: - $ref: '#/components/schemas/CardNetwork' nullable: true card_type: type: string description: Card type, can be either `credit` or `debit` nullable: true card_issuing_country: type: string nullable: true card_issuing_country_code: type: string nullable: true bank_code: type: string nullable: true last4: type: string description: Last 4 digits of the card number nullable: true card_isin: type: string description: The ISIN of the card nullable: true card_extended_bin: type: string description: Extended bin of card, contains the first 8 digits of card number nullable: true card_exp_month: type: string example: '01' nullable: true card_exp_year: type: string example: '2026' nullable: true card_holder_name: type: string example: John Doe nullable: true payment_checks: description: >- Additional payment checks done on the cvv and billing address by the processors. This is a free form field and the structure varies from processor to processor nullable: true authentication_data: description: >- Details about the threeds environment. This is a free form field and the structure varies from processor to processor nullable: true is_regulated: type: boolean description: >- Indicates if the card issuer is regulated under government-imposed interchange fee caps. In the United States, this includes debit cards that fall under the Durbin Amendment, which imposes capped interchange fees. nullable: true signature_network: allOf: - $ref: '#/components/schemas/CardNetwork' nullable: true auth_code: type: string description: Unique authorisation code generated for the payment. nullable: true CountryAlpha2: type: string enum: - AF - AX - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - KH - CM - CA - CV - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MK - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SZ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW - US CardNetwork: type: string description: Indicates the card network. enum: - Visa - Mastercard - AmericanExpress - JCB - DinersClub - Discover - CartesBancaires - UnionPay - Interac - RuPay - Maestro - Star - Pulse - Accel - Nyce - Prop - PrivateLabel - Dinacard securitySchemes: api_key: type: apiKey in: header name: Authorization description: >- Format: `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. ````