How to validate buyer fields before purchase

For direct_top_up products, buyers must provide account details (for example a player ID). Use POST /orders/validate-fields to check that required fields are present and optionally confirm the account before checkout.

When to use this

• Product product_type is direct_top_up and the catalog row has a non-empty required_fields array.
• Before the customer pays — show a confirmation step or inline validation on your product page.
• Not for gift-card / code products (game_card, gift_card, etc.) — those do not use this endpoint.

POST /orders/check does not accept fields in v1. Use this dedicated endpoint for field validation.

Step 1: Read required_fields from the catalog

Each direct_top_up SKU lists the inputs you must collect:

{
  "item_code": "PUBG-60UC-TOPUP-XXXX",
  "product_type": "direct_top_up",
  "required_fields": [
    { "key": "player_id", "label": "Player ID", "type": "string", "required": true, "max_length": 64 },
    { "key": "server_id", "label": "Server", "type": "string", "required": false, "max_length": 32 }
  ]
}

Build your form from required_fields[].key and label. See display products for the full catalog field list.

Step 2: Send the validation request

Endpoint: POST https://api.cardpluspay.com/v1/orders/validate-fields

Body (JSON):

• item_code or item_id (required) — Same SKU identifier as on other endpoints.
• fields (required) — Object mapping each catalog key to a string value. Required keys must be non-empty after trimming.

Example request

curl -X POST "https://api.cardpluspay.com/v1/orders/validate-fields" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "item_code": "PUBG-60UC-TOPUP-XXXX",
    "fields": {
      "player_id": "5123456789"
    }
  }'

Step 3: Handle the response

On success:

{
  "success": true,
  "message": "Fields are valid.",
  "data": {
    "valid": true,
    "display_name": "ExamplePlayer"
  }
}

• valid — Always true on HTTP 200 success.
• display_name — Optional human-readable account label when CardPlusPay can verify the account live (for example a game nickname). May be null when live verification is not available for that SKU — a null display name does not mean the fields are invalid.

CardPlusPay does not echo your fields back in the response (PII minimization). Store them in your session until purchase.

Error handling

• 422 — missing_fields — A required catalog field is missing or empty. Check data.field for the key name.
• 422 — invalid_fields — Unknown key, value too long, or account could not be verified.
• 422 — validation_error — Wrong product type (endpoint applies only to direct_top_up) or malformed body.
• 404 — Product not found or inactive.
• 401 — Invalid or missing API key.

Example:

{
  "success": false,
  "message": "player_id is required for this product.",
  "data": {
    "state": "missing_fields",
    "field": "player_id"
  }
}

Next step

After validation and payment, create the order with the same fields values. See create a direct top-up order.

← Display products · Integration Guide · Direct top-up order →