Xelf Solutions API Reference (v1.0)

Your guide to integrating with the Xelf Solutions REST API. Find everything you need to build powerful payment solutions.

← Back to Developer Hub

Introduction

Welcome to the Xelf Solutions API v1.0.

The Xelf Solutions API is organized around REST. 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.xelf.solutions/v1

Authentication

How to authenticate your API requests.

Xelf Solutions 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 Solutions 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 Solutions 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'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 Solutions 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 payments, 10 at a time:

curl https://api.xelf.solutions/v1/payments \
  -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.

Core Resources

Payments

The Payments API is central to Xelf Solutions, allowing you to create and manage payment transactions. This includes one-time payments, pre-authorizations, captures, refunds, and voids. Xelf intelligently routes these operations to your configured providers like Stripe, Adyen, Braintree, or Chase, based on your orchestration rules.

POST /v1/payments

Creates a new payment intent. You can specify the desired PSP or let Xelf's routing engine decide.

Request Body:
{
  "amount": 1000,
  "currency": "usd",
  "payment_method_id": "pm_1KGqR42eZvKYlo2CluPjZtq7",
  "customer_id": "cus_K7gL2X5hZLzW9Y",
  "description": "Order #12345",
  "capture_method": "automatic",
  "metadata": {
    "order_id": "12345"
  },
  "routing_preferences": {
    "preferred_psp": "stripe",
    "fallback_psps": ["adyen", "braintree"]
  }
}
Example cURL:
curl https://api.xelf.solutions/v1/payments \
  -u YOUR_SECRET_API_KEY: \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique_key_for_this_request>" \
  -d '{
        "amount": 1000,
        "currency": "usd",
        "payment_method_id": "pm_1KGqR42eZvKYlo2CluPjZtq7",
        "description": "New T-Shirt Order"
      }'
Response Body (Success 201):
{
  "id": "pi_3KGqR42eZvKYlo2C1n2q3Q4r",
  "object": "payment_intent",
  "amount": 1000,
  "currency": "usd",
  "status": "requires_capture",
  "client_secret": "pi_3KGqR42eZvKYlo2C1n2q3Q4r_secret_L8XqPZ...",
  "created": 1678886400,
  "livemode": false,
  "payment_method_id": "pm_1KGqR42eZvKYlo2CluPjZtq7",
  "psp_used": "stripe",
  "psp_response": {
    "stripe_charge_id": "ch_3KGqR42eZvKYlo2C..."
  }
}

GET /v1/payments/{payment_id}

Retrieves the details of an existing payment by its unique identifier.

Example cURL:
curl https://api.xelf.solutions/v1/payments/pi_3KGqR42eZvKYlo2C1n2q3Q4r \
  -u YOUR_SECRET_API_KEY:
Response Body (Success 200):
{
  "id": "pi_3KGqR42eZvKYlo2C1n2q3Q4r",
  "object": "payment_intent",
  "amount": 1000,
  "currency": "usd",
  "status": "requires_capture", 
  "client_secret": "pi_3KGqR42eZvKYlo2C1n2q3Q4r_secret_L8XqPZ...",
  "created": 1678886400,
  "livemode": false,
  "payment_method_id": "pm_1KGqR42eZvKYlo2CluPjZtq7",
  "psp_used": "stripe",
  "psp_response": {
    "stripe_charge_id": "ch_3KGqR42eZvKYlo2C..."
  }
}

POST /v1/payments/{payment_id}/capture

Captures the funds of an existing uncaptured PaymentIntent. This is only applicable for payments created with capture_method: "manual".

Request Body (Optional):
{
  "amount_to_capture": 1000 
}
Example cURL:
curl https://api.xelf.solutions/v1/payments/pi_3KGqR42eZvKYlo2C1n2q3Q4r/capture \
  -u YOUR_SECRET_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{ "amount_to_capture": 1000 }'
Response Body (Success 200):
{
  "id": "pi_3KGqR42eZvKYlo2C1n2q3Q4r",
  "object": "payment_intent",
  "status": "succeeded",
  "amount_captured": 1000,
  "psp_used": "stripe",
  "psp_response": {
    "stripe_charge_id": "ch_3KGqR42eZvKYlo2C...",
    "captured_at": 1678886500
  }
  // ... other payment intent fields
}

POST /v1/payments/{payment_id}/refund

Refunds a captured payment, either partially or in full. Xelf will attempt to process the refund via the original PSP (e.g., Adyen, Worldpay).

Request Body:
{
  "amount": 500, 
  "reason": "requested_by_customer",
  "metadata": {
    "refund_ticket_id": "REF-001"
  }
}
Example cURL:
curl https://api.xelf.solutions/v1/payments/pi_3KGqR42eZvKYlo2C1n2q3Q4r/refund \
  -u YOUR_SECRET_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500 }'
Response Body (Success 200 - Refund Object):
{
  "id": "re_1KGqT02eZvKYlo2CABCD1234",
  "object": "refund",
  "amount": 500,
  "currency": "usd",
  "payment_intent_id": "pi_3KGqR42eZvKYlo2C1n2q3Q4r",
  "status": "succeeded",
  "reason": "requested_by_customer",
  "created": 1678886600,
  "psp_used": "stripe",
  "psp_response": {
    "stripe_refund_id": "re_3KGqT02eZvKYlo2C..."
  }
}

Customers

The Customers API allows you to create and manage customer objects. You can store customer information, including payment methods (which can be tokenized via providers like Stripe, Adyen, or stored directly with Xelf), to streamline future transactions and manage subscriptions.

POST /v1/customers

Creates a new customer object.

Request Body:
{
  "email": "jenny.rosen@example.com",
  "name": "Jenny Rosen",
  "phone": "+15551234567",
  "description": "Loyal customer since 2023",
  "metadata": {
    "internal_id": "CUST-0042"
  }
}
Response Body (Success 201):
{
  "id": "cus_K7gL2X5hZLzW9Y",
  "object": "customer",
  "email": "jenny.rosen@example.com",
  "name": "Jenny Rosen",
  "phone": "+15551234567",
  "description": "Loyal customer since 2023",
  "livemode": false,
  "created": 1678886400,
  "metadata": {
    "internal_id": "CUST-0042"
  },
  "default_payment_method": null
}

GET /v1/customers/{customer_id}

Retrieves the details of an existing customer by their unique identifier.

Example cURL:
curl https://api.xelf.solutions/v1/customers/cus_K7gL2X5hZLzW9Y \
  -u YOUR_SECRET_API_KEY:
Response Body (Success 200 - matches POST response):
{
  "id": "cus_K7gL2X5hZLzW9Y",
  "object": "customer",
  "email": "jenny.rosen@example.com",
  // ... other customer fields
}

POST /v1/customers/{customer_id}

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request Body:
{
  "email": "jenny.new.email@example.com",
  "metadata": {
    "loyalty_level": "gold"
  }
}
Response Body (Success 200 - updated customer object):
{
  "id": "cus_K7gL2X5hZLzW9Y",
  "object": "customer",
  "email": "jenny.new.email@example.com",
  "metadata": {
    "internal_id": "CUST-0042",
    "loyalty_level": "gold"
  },
  // ... other customer fields
}

DELETE /v1/customers/{customer_id}

Permanently deletes a customer. It cannot be undone. If the customer has active subscriptions, they may need to be canceled first depending on your Xelf configuration and the underlying PSP (e.g., Stripe, Braintree).

Example cURL:
curl -X DELETE https://api.xelf.solutions/v1/customers/cus_K7gL2X5hZLzW9Y \
  -u YOUR_SECRET_API_KEY:
Response Body (Success 200):
{
  "id": "cus_K7gL2X5hZLzW9Y",
  "object": "customer",
  "deleted": true
}

Tokens

Tokens represent sensitive card information or other payment details securely. Xelf allows you to create universal tokens that can be used with multiple downstream providers like Worldpay or Cybersource, or you can create provider-specific tokens. You typically create tokens on the client-side using Xelf.js or our mobile SDKs, and then use these tokens on your server.

POST /v1/tokens

Creates a single-use token that represents debit or credit card details. This token can be used to create a charge or to save the card details to a customer.

Request Body (Example for Card):
{
  "card": {
    "number": "4242424242424242",
    "exp_month": 12,
    "exp_year": 2025,
    "cvc": "123",
    "name": "Jane Doe"
  },
  "type": "card" 
}
Response Body (Success 201):
{
  "id": "tok_1KGqS02eZvKYlo2C5gA7b8C9",
  "object": "token",
  "card": {
    "id": "card_1KGqS02eZvKYlo2C6H7jK8L0",
    "brand": "Visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2025,
    "funding": "credit",
    "country": "US"
  },
  "client_ip": "123.123.123.123",
  "livemode": false,
  "type": "card",
  "used": false,
  "created": 1678886400
}

GET /v1/tokens/{token_id}

Retrieves the token with the given ID. This is useful for checking if a token has been used, or to see its details if you only stored the ID.

Example cURL:
curl https://api.xelf.solutions/v1/tokens/tok_1KGqS02eZvKYlo2C5gA7b8C9 \
  -u YOUR_SECRET_API_KEY:
Response Body (Success 200 - matches POST response):
{
  "id": "tok_1KGqS02eZvKYlo2C5gA7b8C9",
  "object": "token",
  "card": {
    "id": "card_1KGqS02eZvKYlo2C6H7jK8L0",
    "brand": "Visa",
    "last4": "4242",
    // ... other card details
  },
  "used": false, // Will be true if used
  // ... other token fields
}

Payment Methods

Payment Methods represent a customer's payment instrument, such as a credit card, bank account, or digital wallet (e.g., Apple Pay via Stripe, Google Pay via Braintree). They can be attached to Customers for repeat use and are designed to be long-lived. Xelf can help manage these across different providers.

POST /v1/payment_methods

Creates a PaymentMethod object.

Request Body (Example for Card):
{
  "type": "card",
  "card": {
    "token": "tok_1KGqS02eZvKYlo2C5gA7b8C9" 
  },
  "billing_details": {
    "name": "Jenny Rosen",
    "email": "jenny.rosen@example.com",
    "address": {
      "line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94107",
      "country": "US"
    }
  },
  "metadata": {
    "preferred_for_subscriptions": "true"
  }
}
Response Body (Success 201):
{
  "id": "pm_1KGqR42eZvKYlo2CluPjZtq7",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "123 Main Street",
      "line2": null,
      "postal_code": "94107",
      "state": "CA"
    },
    "email": "jenny.rosen@example.com",
    "name": "Jenny Rosen",
    "phone": null
  },
  "card": {
    "brand": "visa",
    "checks": {
      "address_line1_check": "pass",
      "address_postal_code_check": "pass",
      "cvc_check": "pass"
    },
    "country": "US",
    "exp_month": 12,
    "exp_year": 2025,
    "funding": "credit",
    "last4": "4242",
    "networks": {
      "available": ["visa"],
      "preferred": null
    },
    "three_d_secure_usage": {
      "supported": true
    }
  },
  "created": 1678886400,
  "customer": null,
  "livemode": false,
  "metadata": {
    "preferred_for_subscriptions": "true"
  },
  "type": "card"
}

GET /v1/payment_methods/{payment_method_id}

Retrieves a PaymentMethod object by its ID.

Example cURL:
curl https://api.xelf.solutions/v1/payment_methods/pm_1KGqR42eZvKYlo2CluPjZtq7 \
  -u YOUR_SECRET_API_KEY:
Response Body (Success 200 - matches POST response):
{
  "id": "pm_1KGqR42eZvKYlo2CluPjZtq7",
  "object": "payment_method",
  "type": "card",
  // ... other payment method fields
}

POST /v1/payment_methods/{payment_method_id}/attach

Attaches a PaymentMethod object to a Customer.

Request Body:
{
  "customer": "cus_K7gL2X5hZLzW9Y"
}
Example cURL:
curl https://api.xelf.solutions/v1/payment_methods/pm_1KGqR42eZvKYlo2CluPjZtq7/attach \
  -u YOUR_SECRET_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{ "customer": "cus_K7gL2X5hZLzW9Y" }'
Response Body (Success 200 - updated PaymentMethod):
{
  "id": "pm_1KGqR42eZvKYlo2CluPjZtq7",
  "object": "payment_method",
  "customer": "cus_K7gL2X5hZLzW9Y", // Now attached
  // ... other payment method fields
}

POST /v1/payment_methods/{payment_method_id}/detach

Detaches a PaymentMethod object from a Customer. The PaymentMethod is not deleted and can be re-attached later or attached to a different Customer.

Example cURL:
curl https://api.xelf.solutions/v1/payment_methods/pm_1KGqR42eZvKYlo2CluPjZtq7/detach \
  -u YOUR_SECRET_API_KEY: \
  -X POST
Response Body (Success 200 - updated PaymentMethod):
{
  "id": "pm_1KGqR42eZvKYlo2CluPjZtq7",
  "object": "payment_method",
  "customer": null, // Now detached
  // ... other payment method fields
}