Skip to main content
POST
/
api
/
recovery
/
execute
curl --request POST \
  --url https://api.revtain.com/api/recovery/execute \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "paymentMethodToken": "pm_1234567890",
  "amount": 5000,
  "currency": "USD",
  "originalDeclineCode": "do_not_honor",
  "idempotencyKey": "order_12345_retry_1"
}
'
{
  "success": true,
  "message": "Revenue Recovered",
  "error": null,
  "transactionId": "01KKZ14FEZK152ZBXEM2XK1B0C",
  "strategyUsed": "primary",
  "gatewaysAttempted": 1,
  "recoveryEngineApplied": true,
  "ai": {
    "score": 72.5,
    "confidence": 68,
    "reasoning": "Analysed 142 similar \"do_not_honor\" declines during afternoon hours.",
    "dataSource": "blended"
  }
}

Authorizations

​
X-API-KEY
string
header
required

Your Revtain API key (format: rev_xxx). Provided during onboarding.

Body

application/json
​
paymentMethodToken
string
required

Your gateway's payment token. Format varies per gateway — see the full per-gateway token-format table at Supported Gateways.

Common examples:

  • Stripe: pm_xxx (PaymentMethod ID) — works for cards, Apple Pay, Google Pay
  • Checkout.com: src_xxx (saved instrument token)
  • Adyen: <merchantAccount>|<storedPaymentMethodId>|<shopperReference>
  • Braintree: <paymentMethodToken>|<customerId>
  • GoCardless: <mandateId> (MD-xxx)
  • PayPal: billing-agreement|<BA-token> or reference|<previous-payment-id>

Apple Pay and Google Pay tokens issued by your gateway work the same way as card tokens — pass them as the underlying gateway token, and set paymentMethodType to identify the wallet.

Example:

"pm_1234567890"

​
amount
integer
required

Amount in the smallest currency unit (e.g., 5000 = $50.00 USD). For zero-decimal currencies (JPY, KRW, VND), pass the whole amount.

Required range: 50 <= x <= 100000000
Example:

5000

​
fallbackPaymentMethodTokens
string[]

Optional list of alternative payment tokens for the same customer (for example, a backup card-on-file when the primary is a wallet). When the primary token's gateway cascade exhausts on a recoverable decline (insufficient funds, do not honor, gateway timeout, and similar), Revtain automatically tries each fallback token in order — no orchestration code on your side.

Tokens that fail with hard cardholder-state declines (lost, stolen, fraud, expired) skip the fallback step, because the issuer's flag applies to the cardholder rather than the individual token.

Pass the tokens in priority order. Up to 5 supported.

Maximum array length: 5
Example:
[
  "pm_card_backup_5678",
  "pm_secondary_card_9012"
]
​
currency
string
default:USD

3-letter ISO 4217 currency code.

Example:

"USD"

​
originalDeclineCode
string

The decline code from your processor. Dramatically improves recovery rate.

Example:

"do_not_honor"

​
cardOrigin
string

2-letter ISO country code of the card issuer. Enables geographic routing optimisation.

Example:

"US"

​
idempotencyKey
string

Unique key to prevent duplicate recovery attempts. Strongly recommended for production.

Maximum string length: 128
Example:

"order_12345_retry_1"

​
binPrefix
string

First 6 digits of the card (BIN). Enables issuer-level analytics and smarter routing.

Example:

"411111"

​
customerEmail
string<email>

The end customer's email address. Required if dunning is enabled.

Example:

"customer@example.com"

​
paymentMethodType
enum<string>
default:card

How the customer originally paid. Lets Revtain apply the right recovery strategy per rail — wallets get a higher predicted-recovery score and skip cascades to gateways that don't support recurring wallet charges.

Defaults to card when omitted. Always pass this if the failed payment originated via Apple Pay, Google Pay, PayPal, or Venmo — recovery rates are materially higher when set correctly.

Available options:
card,
apple_pay,
google_pay,
paypal,
venmo
Example:

"apple_pay"

​
isTrialConversion
boolean
default:false

Set to true if this failure occurred on the customer's first paid charge after a free trial. Trial-conversion failures get prioritised in the cascade (effective priority bumps to critical) — losing the customer at the trial-to-paid moment is the highest-cost churn event a subscription business faces.

Example:

true

​
simulateOutcome
enum<string>

Sandbox only. Force a specific outcome for testing. Only honoured when primary gateway is a Test Gateway.

Available options:
success,
failed,
blocked

Response

Recovery attempt completed (check success field for outcome)

​
success
boolean
Example:

true

​
message
string
Example:

"Revenue Recovered"

​
error
string | null
Example:

null

​
transactionId
string
Example:

"01KKZ14FEZK152ZBXEM2XK1B0C"

​
strategyUsed
string
Example:

"primary"

​
gatewaysAttempted
integer
Example:

1

​
recoveryEngineApplied
boolean
Example:

true

​
ai
object