Overview

This guide provides the technical requirements for building a Reset Fee Payment API on your WordPress/WooCommerce platform. When set-up correctly, this API will allow our system to generate payment links for users who need to pay reset fees for their trading accounts by using this API.

The integration is straightforward: our backend will send a request to your API endpoint with user and product information, and your API should return a secure, one-time payment link that the user can use to complete their payment, that expires in a short timeframe if not used.

How the Integration Works

Here's the overall flow of how the reset fee payment process works:

User requests an account reset — When a user's trading account fails or gets blocked and they're eligible for a reset, they initiate a reset request from their user dashboard.
Our system calls your API — Our backend sends a POST request to your Reset Fee API endpoint with all the necessary information including user billing details, the product they need to pay for, and a reference to their account.
Your API creates an order — Your WordPress system receives this request, validates it, creates a WooCommerce order in "pending payment" status, and generates a secure payment link.
Your API returns the payment link — Your API responds with the order ID and the payment URL that the user will redirect users to.
User completes payment — The user is redirected to the payment link where they complete their payment through your configured payment gateways.
Webhook notification — Once the payment is completed, your WooCommerce system sends an order completion webhook to our backend, which triggers the account reset process on our end.

WooCommerce Product Setup

Create a single Variable Product (e.g., "Account Reset Fee") with variations for each combination of challenge type and account size.

How It Works

Each variation represents a unique pairing of:

Challenge Type (e.g., "1 Step", "2 Step")

Account Size (e.g., $10,000, $50,000, $100,000, $200,000, $300,000)

Example: If you have 4 challenge types with 3 account sizes each, you'll need 12 variations.

Setup Steps

Create a Variable Product in WooCommerce
Add two attributes (both marked as "Used for variations"):
1. Challenge Type — with all your challenge names
2. Account Size — with all your account sizes
Generate variations for each combination
Set the appropriate price for each variation

Sharing the Product IDs

Once created, send us a mapping of all variations:

Variation ID	Challenge Type	Account Size
#72238	1 Step	$100,000
#72250	2 Step	$100,000
#72254	1 Step	$200,000
...etc	...	...

We'll configure this mapping on our end so the correct product_id is sent with each API request.

Note: Do not delete or recreate variations after we've configured the mapping — coordinate with us first if changes are needed.

API Endpoint Requirements

Endpoint Configuration

You will need to create a custom REST API endpoint on your WordPress installation. The endpoint should be accessible at a URL path of your choosing. We recommend something like:

POST /wp-json/your-namespace/v1/reset-fee

The endpoint must:

Accept POST requests
Accept and parse JSON request bodies
Return JSON responses
Be accessible over HTTPS only (SSL is mandatory)

Request Format

When our system calls your API, we will send a POST request with the following JSON structure in the request body:

Request Headers

Content-Type: application/json

Request Body Fields

{
    "billing_details": {
        "first_name": "John",                    // Customer's first name
        "last_name": "Smith",                    // Customer's last name
        "address_1": "123 Main Street",          // Primary address line
        "address_2": "Apt 4B",                   // Secondary address
        "city": "New York",                      // City name
        "postcode": "10001",                     // Postal/ZIP code
        "country": "US",                         // 2 letter country code
        "email": "[email protected]",       // Email (required)
        "phone": "+1234567890"                   // Customer's phone
    },
    "product_id": 72238,                         // WooCommerce product ID
    "secret_key": "your_shared_secret_key",      // Pre-shared secret key
    "account_id": "12345"                        // Tech's Account ID
}

secret_key (string): A pre-shared secret key that you should validate on every request. This ensures the request is genuinely coming from our system and not from an unauthorized source. We will send out the provided secret key, and you can reject requests that do not include the correct key.
product_id (integer) — The WooCommerce product ID for the specific reset fee product. This corresponds to products you have already set up in your WooCommerce store for each account size and challenge type.
account_id (string) — A unique identifier for the user's account in our system. This should be stored in the order metadata as it will be used to link the payment back to the correct account when processing the webhook.

Response Format

Your API must return a JSON response. The structure should differ based on whether the operation was successful or not.

Successful Response

When the order is created successfully, return an HTTP 200 status code with the following JSON structure:

{
    "success": true,
    "order_id": 98765,  // WooCommerce order ID that was created
    "payment_url": "https://yoursite.com/checkout/order-pay/98765/?pay_for_order=true&key=wc_order_abc123xyz"  // One-time payment URL (expires in 5-10 minutes)
}

Error Response

When something goes wrong, return an appropriate HTTP error status code (400 for bad requests, 401 for authentication failures, 500 for server errors) with the following JSON structure:

{
    "success": false,  // Boolean indicating the operation failed
    "message": "Invalid secret key provided"  // Human-readable error
}

Critical Requirement: One-Time, Time-Limited Payment Links

This is extremely important for security.

The payment URL you return must meet these security requirements:

One-Time Use

The payment link should be valid for a single use only. Once the user visits the payment page (whether they complete the payment or not), the link should become invalid. If someone tries to access the same link again, they should receive an error or be redirected to an appropriate page.

Time-Limited Expiration

The payment link must expire within 5 to 10 minutes of being generated. If the user does not access the link within this timeframe, the link should become invalid. Our tech will request for a new link as and when the user requests another reset.

Webhook Configuration

For the integration to work end-to-end, your WooCommerce installation must be configured to send order webhooks to our system. Please use the default built in WooCommerce webhooks (https://woocommerce.com/document/webhooks/), and enable the order.updated event to trigger to our tech's webhook URL (request your dedicated project manager for this URL)

Summary of Deliverables

To complete this integration, please provide us with the following:

WooCommerce Reset Product ID mappings
REST API endpoint that accepts our POST requests, and returns a one-time, short-lived payment link.
Secret Key for the Endpoint
Request samples, if possible.

Account Reset Fee Payment API Setup Guide