Xelf Decline Recovery API Reference (v1.0)

Your guide to integrating with the Xelf Processing Decline Recovery API. Find everything you need to programmatically manage failed payments and maximize your revenue recovery.

← Back to Developer Hub

Introduction

Welcome to the Xelf Processing Decline Recovery API v1.0.

The Xelf Processing Decline Recovery API is organized around REST. It allows you to submit declined transaction data, monitor recovery attempts, and access analytics to understand and improve your payment success rates. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Xelf API in test mode, which does not affect your live data or interact with the payment networks. The API key you use to authenticate the request determines whether the request is live mode or test mode.

Base URL for all API requests: https://api.xelfprocessing.com/v1

Authentication

How to authenticate your API requests.

Xelf Processing API uses API keys to authenticate requests. You can view and manage your API keys in the Xelf Dashboard.

Your API keys carry many privileges; be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Bearer Authentication. Provide your API secret key in the Authorization header:

Authorization: Bearer YOUR_SECRET_API_KEY

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Rate Limiting

Understanding API request limits.

To ensure fair usage and stability for all users, the Xelf Processing API implements rate limiting. Limits are applied per API key and are based on the number of requests per second.

Current default limits (subject to change):

  • Test mode: 25 requests per second.
  • Live mode: 100 requests per second.

If you exceed these limits, you will receive an HTTP 429 Too Many Requests error. We recommend implementing a retry mechanism with exponential backoff for handling these errors.

Response headers for rate limiting include:

  • X-RateLimit-Limit: The maximum number of requests allowed in the current window.
  • X-RateLimit-Remaining: The number of requests remaining in the current window.
  • X-RateLimit-Reset: The UTC epoch seconds when the current window resets.

Error Handling

Common error codes and responses.

Xelf Processing uses conventional HTTP response codes to indicate the success or failure of an API request.

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.).
  • Codes in the 5xx range indicate an error with Xelf's servers (these are rare).

When an API request fails, the response body will be JSON and contain an error object with the following attributes:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required param: amount.",
    "param": "amount",
    "code": "parameter_missing"
  }
}

Common error types include:

  • api_error: An issue on Xelf Processing's end.
  • authentication_error: Invalid or missing API key.
  • card_error: A problem with the card being charged.
  • idempotency_error: An issue with an idempotency key.
  • invalid_request_error: Invalid parameters in the request.
  • rate_limit_error: Too many requests too quickly.

Versioning

API versions and how to use them.

The Xelf Processing API is versioned to allow for backward-compatible changes and new features. The current version is v1.0.

API versions are specified in the URL path: /v1/...

When we release breaking changes, we will release a new API version. We aim to provide ample notice and migration paths for any new versions.

All top-level API resources that return a list of objects support pagination. List API methods share a common structure, taking at least these two parameters: limit and starting_after or ending_before.

Example: Fetching a list of submitted declines, 10 at a time:

curl https://api.xelfprocessing.com/v1/declines \
  -u YOUR_SECRET_API_KEY: \
  -d limit=10

The response will include a has_more boolean flag and a next_page_token (or similar) if more results are available. Use this token in the starting_after parameter for the next request.

Idempotency

Ensuring safe retries.

To perform an idempotent request, provide an additional Idempotency-Key: YOUR_UNIQUE_KEY header to the request. An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request.

We recommend using V4 UUIDs for idempotency keys. If a request with an idempotency key fails due to a network error, you can safely retry the request with the same key without risking duplicate operations.

Decline Recovery Resources

Declines

The Declines API allows you to submit information about a failed transaction to Xelf Processing for analysis and potential recovery. This is the primary object for initiating the decline recovery process.

POST /v1/declines

Submits a new declined transaction for recovery processing.

Request Body:
{
  "amount": 1000,
  "currency": "usd",
  "original_transaction_id": "ch_123abcxyz",
  "original_psp": "stripe",
  "decline_code": "05",
  "decline_message": "Do not honor",
  "payment_method_details": { // Could be token, raw card, etc. depending on your setup
    "type": "card_token",
    "token": "tok_abcdef12345" 
  },
  "customer_details": {
    "id": "cus_K7gL2X5hZLzW9Y",
    "email": "jenny.rosen@example.com"
  },
  "metadata": {
    "order_id": "ORDER-XYZ-789",
    "product_sku": "SKU-123"
  }
}
Example cURL:
curl https://api.xelfprocessing.com/v1/declines \
  -u YOUR_SECRET_API_KEY: \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique_key_for_this_request>" \
  -d '{
        "amount": 1000,
        "currency": "usd",
        "original_transaction_id": "ch_123abcxyz",
        "decline_code": "05",
        "payment_method_details": { "type": "card_token", "token": "tok_abcdef12345" }
      }'
Response Body (Success 201):
{
  "id": "decl_abcdef123456",
  "object": "decline",
  "amount": 1000,
  "currency": "usd",
  "status": "submitted_for_recovery",
  "original_transaction_id": "ch_123abcxyz",
  "decline_code": "05",
  "decline_message": "Do not honor",
  "psp_used_for_original_attempt": "stripe",
  "created": 1678886400,
  "livemode": false,
  "metadata": {
    "order_id": "ORDER-XYZ-789"
  }
}

GET /v1/declines/{decline_id}

Retrieves the details of a submitted decline, including its current recovery status and any recovery attempts made.

Example cURL:
curl https://api.xelfprocessing.com/v1/declines/decl_abcdef123456 \
  -u YOUR_SECRET_API_KEY:
Response Body (Success 200):
{
  "id": "decl_abcdef123456",
  "object": "decline",
  "amount": 1000,
  "currency": "usd",
  "status": "recovery_attempted_successful", 
  "original_transaction_id": "ch_123abcxyz",
  "decline_code": "05",
  "decline_message": "Do not honor",
  "psp_used_for_original_attempt": "stripe",
  "created": 1678886400,
  "livemode": false,
  "metadata": {
    "order_id": "ORDER-XYZ-789"
  },
  "recovery_attempts": [
    {
      "id": "ra_123",
      "status": "successful",
      "recovered_amount": 1000,
      "psp_used": "adyen", 
      "timestamp": 1678887000
    }
  ]
}

Recovery Attempts

Recovery Attempts represent the actions Xelf Processing takes to try and recover a declined transaction. You can list recovery attempts for a specific decline to understand the strategies employed and their outcomes.

GET /v1/declines/{decline_id}/recovery_attempts

Lists all recovery attempts made for a specific decline.

Example cURL:
curl https://api.xelfprocessing.com/v1/declines/decl_abcdef123456/recovery_attempts \
  -u YOUR_SECRET_API_KEY:
Response Body (Success 200 - List of Recovery Attempt Objects):
{
  "object": "list",
  "data": [
    {
      "id": "ra_123",
      "object": "recovery_attempt",
      "decline_id": "decl_abcdef123456",
      "status": "successful", // "failed", "pending"
      "strategy_used": "intelligent_retry_adyen_eur",
      "psp_used": "adyen",
      "psp_response_code": "00",
      "psp_response_message": "Approved",
      "recovered_amount": 1000,
      "currency": "usd",
      "created": 1678887000
    },
    {
      "id": "ra_456",
      "object": "recovery_attempt",
      "decline_id": "decl_abcdef123456",
      "status": "failed",
      "strategy_used": "intelligent_retry_stripe_usd",
      "psp_used": "stripe",
      "psp_response_code": "05",
      "psp_response_message": "Do not honor",
      "recovered_amount": 0,
      "currency": "usd",
      "created": 1678886800
    }
  ],
  "has_more": false,
  "url": "/v1/declines/decl_abcdef123456/recovery_attempts"
}

GET /v1/recovery_attempts/{recovery_attempt_id}

Retrieves the details of a specific recovery attempt.

Example cURL:
curl https://api.xelfprocessing.com/v1/recovery_attempts/ra_123 \
  -u YOUR_SECRET_API_KEY:
Response Body (Success 200):
{
  "id": "ra_123",
  "object": "recovery_attempt",
  "decline_id": "decl_abcdef123456",
  "status": "successful",
  "strategy_used": "intelligent_retry_adyen_eur",
  "psp_used": "adyen",
  "psp_response_code": "00",
  "psp_response_message": "Approved",
  "recovered_amount": 1000,
  "currency": "usd",
  "created": 1678887000
}

Decline Analytics

Gain insights into your payment decline patterns and recovery performance. The Decline Analytics API provides aggregated data to help you understand trends, identify common failure reasons, and measure the effectiveness of recovery strategies.

GET /v1/analytics/declines/summary

Retrieves a summary of decline statistics over a specified period.

Query Parameters:
  • start_date (date, required): Start of the reporting period (YYYY-MM-DD).
  • end_date (date, required): End of the reporting period (YYYY-MM-DD).
  • group_by (string, optional): Dimension to group results by (e.g., psp, decline_code, currency).
Example cURL:
curl "https://api.xelfprocessing.com/v1/analytics/declines/summary?start_date=2023-01-01&end_date=2023-01-31&group_by=decline_code" \
  -u YOUR_SECRET_API_KEY:
Response Body (Success 200):
{
  "object": "list",
  "data": [
    {
      "group_key": "do_not_honor",
      "total_declines": 150,
      "total_amount_declined": 750000, // in cents
      "currency": "usd",
      "recovery_rate": 0.25, // 25%
      "recovered_amount": 187500 // in cents
    },
    {
      "group_key": "insufficient_funds",
      "total_declines": 120,
      "total_amount_declined": 600000,
      "currency": "usd",
      "recovery_rate": 0.40, // 40%
      "recovered_amount": 240000
    }
    // ... other groups
  ],
  "summary": {
    "total_declines_period": 500,
    "total_amount_declined_period": 2500000,
    "overall_recovery_rate": 0.30,
    "total_recovered_amount_period": 750000
  },
  "period_start": "2023-01-01T00:00:00Z",
  "period_end": "2023-01-31T23:59:59Z"
}

GET /v1/analytics/declines/time_series

Provides a time series breakdown of decline and recovery metrics.

Query Parameters:
  • start_date (date, required): Start of the reporting period (YYYY-MM-DD).
  • end_date (date, required): End of the reporting period (YYYY-MM-DD).
  • interval (string, required): Time interval for data points (e.g., day, week, month).
Example cURL:
curl "https://api.xelfprocessing.com/v1/analytics/declines/time_series?start_date=2023-01-01&end_date=2023-01-07&interval=day" \
  -u YOUR_SECRET_API_KEY:
Response Body (Success 200):
{
  "object": "list",
  "data": [
    {
      "timestamp": "2023-01-01T00:00:00Z",
      "total_declines": 20,
      "total_amount_declined": 100000,
      "recovered_amount": 30000,
      "recovery_rate": 0.30
    },
    {
      "timestamp": "2023-01-02T00:00:00Z",
      "total_declines": 25,
      "total_amount_declined": 125000,
      "recovered_amount": 40000,
      "recovery_rate": 0.32
    }
    // ... other data points for the series
  ],
  "interval": "day",
  "currency": "usd" 
}