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": 2,
  "recoveryEngineApplied": true,
  "ai": {
    "score": 72.5,
    "confidence": 68,
    "reasoning": "Analysed 142 similar \"do_not_honor\" declines during afternoon hours.",
    "dataSource": "blended"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.revtain.com/llms.txt

Use this file to discover all available pages before exploring further.

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 (e.g., Stripe pm_xxx, tok_xxx, or a Revtain vault token).

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

​
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"

​
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:

2

​
recoveryEngineApplied
boolean
Example:

true

​
ai
object