Endpoint specification

Data API allows partners to retrieve information about your users and any orders associated with your Partner ID. It also includes support for direct user creation if enabled for your Partner ID.

Endpoint URLs:

Endpoint	URL	Method
Orders	`https://partner-sandbox.wert.io/api/external/orders`	`GET`
Users	`https://partner-sandbox.wert.io/api/external/users`	`GET`
User Create	`https://partner-sandbox.wert.io/api/external/users/create`	`POST`
Card Register	`https://cards-reg-iframe-sandbox.wert.io/api/v1/partner/register`	`POST`

Authentication

To authenticate your requests, include your API key in the HTTP header of every request.

Header Key	Value
`X-Api-Key`	`your-unique-api-key`

⚠️
Your API key carries many privileges, so keep it secure.
Your API key is provided exclusively by Wert during onboarding. Store it safely in your backend.
Never share your key. If you suspect a compromise, contact us immediately to issue a new one.
Note: Sandbox and Production keys are unique to their respective environments and are not interchangeable.

API Reference

Get orders

Get detailed orders data associated with your partner account.

Request Details

Endpoint: `GET /api/external/orders`

👉 Refer to endpoints table for a full link.

Parameters

Configure your request using the parameters below to search and filter order results.

Parameter	Description	Possible Values
`limit`	The number of orders you want to retrieve. Defaults to `10`.	`0` to `20`
`cursor_id`	Fetches the next page of results using the `next_cursor_id` from a previous response. Defaults to an empty string.	`01KAQWBNWWGG06HR5T9Z35A3WD`
`search_by`	Allows setting `order_id`, `click_id`, or `external_order_id` to find specific orders.	Comma-separated order IDs, click IDs, or external order IDs, for example `2FX6Yz`.
`order_by`	Sets the order as ascending or descending. Defaults to `desc`.	`asc` / `desc`
`start_date`	Filters orders with `created_at` after this timestamp.	`YYYY-MM-DDTHH:MM:SSZ`, for example `2025-11-19T23:59:59.00Z`.
`end_date`	Filters orders with `created_at` up to this timestamp.	`YYYY-MM-DDTHH:MM:SSZ`

💡
Date filtering reference

Use start_date and end_date together to return orders for a specific period.

Use a narrow time range if you have a high volume of orders. The maximum is 20 orders per request.

Example Requests

# 1. Get the 10 most recent orders (default)
curl -X GET 'https://partner-sandbox.wert.io/api/external/orders' \
  -H 'X-Api-Key: your-unique-api-key'

# 2. Retrieve 20 orders using a cursor and ascending order
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/orders' \
  -H 'X-Api-Key: your-unique-api-key' \
  -d 'limit=20' \
  -d 'cursor_id=01KAQWBNWWGG06HR5T9Z35A3WD' \
  -d 'order_by=asc'

# 3. Search for orders using a single click_id
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/orders' \
  -H 'X-Api-Key: your-unique-api-key' \
  -d 'search_by=click_id'

# 4. Search for orders using a single external_order_id
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/orders' \
  -H 'X-Api-Key: your-unique-api-key' \
  -d 'search_by=2FX6Yz'

# 5. Search using multiple click_ids and order_ids
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/orders' \
  -H 'X-Api-Key: your-unique-api-key' \
  -d 'search_by=click_id1,click_id2,order_id1,order_id2'

# 6. Filter orders by status
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/orders' \
  -H 'X-Api-Key: your-unique-api-key' \
  -d 'status=failed'

# 7. Filter orders by date range
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/orders' \
  -H 'X-Api-Key: your-unique-api-key' \
  -d 'start_date=2025-11-19T00:00:00Z' \
  -d 'end_date=2025-11-19T23:59:59Z'

# 8. Filter orders by status and commodity
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/orders' \
  -H 'X-Api-Key: your-unique-api-key' \
  -d 'status=failed' \
  -d 'commodity=tt_amoy.erc-20.polygon'

Response Details

Orders Response

Upon a successful request, the response includes the following fields:

Variable	Description
`success`	Indicates if the request was successfully processed.
`data`	An array containing the retrieved order objects. See order object.
`next_cursor_id`	The cursor string used to fetch the next page of results.
`total`	The total count of orders matching the search criteria.

Order Object

💡
The following fields represent the schema for each order in the data array. Parameters marked as filterable can be used to customize your queries by using the filter name shown in the table.

Variable	Description	Filterable	Filter Name
`order_id`	The unique identifier for the order in Wert's database.	Yes	`search_by`
`click_id`	The identifier you pass to Wert when you initialise the widget.	Yes	`search_by`
`currency`	The base currency for the order.	No	-
`currency_amount`	The value of the order in the base currency.	No	-
`external_order_id`	The unique identifier for an order. Used in partner dashboard and customer emails.	Yes	`search_by`
`crypto`	The crypto asset purchased or sent to the smart contract.	Yes	`commodity`
`crypto_amount`	The amount of the crypto asset purchased or sent to the smart contract.	No	-
`user_id`	The unique identifier for the user in Wert's database.	Yes	`user_ids`
`status`	The status of the order. See statuses.	Yes	`status`
`card_id`	The unique identifier for the card used in Wert's database.	Yes	`card_id`
`created_at`	Timestamp of when the order was created (UTC).	No	-
`changed_at`	Timestamp of when the order was last updated (UTC).	No	-
`partner_fee`	The USD amount of fees collected as partner revenue.	No	-
`partner_fee_percent`	The percentage of fees collected as partner revenue.	No	-
`wert_fee`	The USD amount of fees collected as Wert revenue.	No	-
`wert_fee_percent`	The percentage of fees collected as Wert revenue.	No	-
`tx_id`	Blockchain transaction hash.	Yes	`tx_id`
`processed_through`	The acquirer who processed the card payment.	No	-
`card_brand`	Visa or Mastercard.	No	-
`fail_reason`	Payment error code. Refer to error code descriptions.	Yes	`fail_reason`
`payment_type`	Authentication method of the payment, for example `3ds_v2`.	Yes	`payment_type`
`additional_data`	Additional information.	No	-
`address`	The address specified for the order.	No	-
`sc_input_data`	Smart contract input data sent in the transaction.	No	-

Example Response

{
    "success": true,
    "data": [
        {
            "order_id": "01HNWX0HSK85WW9W5A3RZS1BBH",
            "click_id": "82960ad6-e52c-48b1-9293-5658709da384",
            "currency": "usd",
            "currency_amount": 1.07,
            "crypto": "matic.simple.polygon",
            "crypto_amount": 1.28928444,
            "external_order_id": "62no2X",
            "user_id": "01HNWWXZ8FQ9FSH08A8ACHH7K1",
            "status": "success",
            "card_id": "01HNWWZ6E1T0BJT46H35M42JT7",
            "created_at": "2024-02-05 15:08:29",
            "changed_at": "2024-02-05 15:08:32",
            "tx_id": "0xbef4262a7c56f64423b80e4342ee4309595dcdb78d8c201fd752dc1d9c29c19e",
            "processed_through": "safecharge",
            "card_brand": "VISA",
            "fail_reason": "",
            "payment_type": "non_3ds",
            "additional_data": null,
            "address": "0xAA453aD5c9CF7F04bFe0DfdD12b27504AFdb800b"
        },
        {
            "order_id": "01HMXQ6AN3XKQAZHPRSM13ED3X",
            "click_id": "click_id",
            "currency": "usd",
            "currency_amount": 5,
            "crypto": "tt_goerli.erc-20.ethereum",
            "crypto_amount": 4.36051815,
            "external_order_id": "62no2X",
            "user_id": "01HMVWY6V7B9ZHA6P2C48AP5C7",
            "status": "failed",
            "card_id": "01HMVX1NJB6QDW5YKXA13HB2CG",
            "created_at": "2024-01-24 12:30:20",
            "changed_at": "2024-01-24 12:30:27",
            "tx_id": "",
            "card_brand": "VISA",
            "fail_reason": "4007",
            "payment_type": "unknown",
            "additional_data": null,
            "address": "0xAA453aD5c9CF7F04bFe0DfdD12b27504AFdb800b"
        }
    ],
    "next_cursor_id": "01KAQWBNWWGG06HR5T9Z35A3WD",
    "total": 2
}

Order Status

The following order statuses are available:

Status	Description
success	The order was successful and has been sent on the blockchain
failed	The order has failed and will not be sent on the blockchain
cancelled	The payment for the order was processed but the order was later cancelled
pending	The order is being processed but it hasn't been sent on the blockchain
progress	The order is being processed but payment has not yet been completed
created	The order has been created but payment has not yet been processed

Payment Error Codes

The following table identifies the specific cause of transaction failures returned in the fail_reason field in order object. Use these codes to provide accurate troubleshooting steps to your users.

Error Code	Description
`4000`	We weren’t able to charge the user’s card and the order was not completed. The user can try again.
`4001`	The transaction failed due to an incorrect CVV/CVC. The user can try again ensuring they enter the correct CVV/CVC.
`4002` `4010` `4012`	Payment was declined by the card issuer. The user should contact them for further details.
`4003`	Incorrect card details. The user can try again ensuring they enter valid card details.
`4004`	Insufficient balance. The user should add funds to their card and try again.
`4005`	Card limit was exceeded. The user should use a different card to complete their purchase.
`4011`	Card validation failed. The user can add a valid card and try again.
`4013`	Payment was declined due to risk assessment.
`4014`	Name on the bank payment account doesn't match the verified identity. The user should contact support for further assistance.
`4015`	Payment wasn't received within the expected time.
`4016`	Payment was received after the order timeout period. Funds will be refunded shortly.
`4017`	Payment amount doesn't match the order amount.
`4018`	Payment was canceled by the user. No funds were charged.

Get users

Fetch detailed users data you have created or served.

Request Details

Endpoint: `GET /api/external/users`

👉 Refer to endpoints table for a full link.

Parameters

Configure your request using the parameters below to search and filter user results.

Parameter	Description	Possible Values
`limit`	The number of users you want to retrieve.	`0` to `20`
`offset`	Skips the specified number of users. Defaults to `0`.	`10`
`order_by`	Sets the order as ascending or descending. Defaults to `desc`.	`asc` / `desc`
`from`	Filters users with `created_at` after this timestamp.	`YYYY-MM-DDTHH:MM:SSZ`, for example `2025-11-19T23:59:59.00Z`.
`to`	Filters users with `created_at` up to this timestamp.	`YYYY-MM-DDTHH:MM:SSZ`

💡
Date filtering reference

Use from and to together to return users for a specific period.

Use a narrow time range if you have a high number of users. The maximum is 20 users per request.

Example request

### 1. Get the most recent users (Default)
curl -X GET 'https://partner-sandbox.wert.io/api/external/users' \
-H 'X-Api-Key: your-unique-api-key'

### 2. Retrieve 20 users from a specific offset
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/users' \
-H 'X-Api-Key: your-unique-api-key' \
-d 'limit=20' \
-d 'offset=20'

### 3. Search for a specific user by ID
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/users' \
-H 'X-Api-Key: your-unique-api-key' \
-d 'user_ids=user_id'

### 4. Search for multiple users (comma-separated IDs)
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/users' \
-H 'X-Api-Key: your-unique-api-key' \
-d 'user_ids=user_id1,user_id2,user_id3'

### 5. Filter users by KYC status (e.g., success)
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/users' \
-H 'X-Api-Key: your-unique-api-key' \
-d 'lkyc_status=success'

### 6. Filter by date range (When users were created)
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/users' \
-H 'X-Api-Key: your-unique-api-key' \
-H 'Content-Type: application/json' \
-d 'from=2025-11-20T00:00:00.00Z' \
-d 'to=2025-11-20T23:59:59.00Z'

### 7. Filter users by phone country
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/users' \
-H 'X-Api-Key: your-unique-api-key' \
-d 'phone_country=RU'

### 8. Filter users by kyc country
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/users' \
-H 'X-Api-Key: your-unique-api-key' \
-d 'kyc_country=RUS'

Response Details

Users Response

Upon a successful request, the response includes the following fields:

Variable	Description
`success`	Indicates if the request was successfully processed.
`data`	An array containing the retrieved user objects. See user object.
`total`	The total count of users matching the search criteria.

User Object

💡
The following fields represent the schema for each user in the data array. Parameters marked as filterable can be used to customize your queries by using the filter name shown in the table.

Variable	Description	Filterable	Filter Name
`user_id`	User's Wert ID.	Yes	`user_ids`
`country`	User's KYC country. alpha3	Yes	`kyc_country`
`phone`	User's masked phone number.	No	-
`phone_country`	User's phone country. alpha2	Yes	`phone_country`
`lkyc_status`	User's non-document verification status.	Yes	`lkyc_status`
`fkyc_status`	User's document verification status.	Yes	`fkyc_status`
`banned`	Indicates whether the user is banned by Wert.	No	-
`created_at`	Date and time of the user's creation (UTC).	Yes	`to` / `from`
`limits.crypto_remaining`	The user's current crypto limit left in USD. Zero if no KYC or active KYC is not success.	No	-
`limits.crypto_spending`	How much in USD the user has already spent from the current crypto limits.	No	-
`limits.digital_goods_remaining`	The user's current NFT limit left in USD. Zero if no KYC or active KYC is not success.	No	-
`limits.digital_goods_spending`	How much in USD the user has already spent from the current NFT limits.	No	-
`linked_payment_methods`	An array of objects representing the user's saved payment options. See linked payment methods object.	No	-

Linked Payment Methods

Variable	Description
`linked_payment_methods.cards[].brand`	Payment method brand.
`linked_payment_methods.cards[].card_id`	Payment method card ID associated with Wert.
`linked_payment_methods.cards[].created_at`	Payment method creation date.
`linked_payment_methods.cards[].last_digits`	Payment method last digits.
`linked_payment_methods.method`	Payment method.

Example Response

{
  "data": [
      {
          "country": "DEU",
          "created_at": "2025-11-19T11:21:48.200421Z",
          "fkyc_status": "retry",
          "limits": {
              "crypto_remaining": "0",
              "crypto_spending": "0",
              "digital_goods_remaining": "0",
              "digital_goods_spending": "0"
          },
          "linked_payment_methods": [
              {
                  "cards": [
                      {
                          "brand": "VISA",
                          "card_id": "01KADXN9TN3QEMG9DHWX6G7Y0S",
                          "created_at": "2025-11-19T11:23:09.526895Z",
                          "last_digits": "1000"
                      }
                  ],
                  "method": "bank_card"
              }
          ],
          "lkyc_status": "failed",
          "phone": "+49*****356",
          "phone_country": "DE",
          "user_id": "01KADXJS47C9B1WG8V3ZNM2SV7"
      },
      {
          "country": "DEU",
          "created_at": "2025-11-19T11:19:44.098153Z",
          "fkyc_status": "not initiated",
          "limits": {
              "crypto_remaining": "6000",
              "crypto_spending": "0",
              "digital_goods_remaining": "6000",
              "digital_goods_spending": "0"
          },
          "linked_payment_methods": [],
          "lkyc_status": "success",
          "phone": "+49*****355",
          "phone_country": "DE",
          "user_id": "01KADXEZZQF8DQEPP4AE28SKBX"
      },
      {
          "country": "DEU",
          "created_at": "2025-11-19T11:14:42.380854Z",
          "fkyc_status": "not initiated",
          "limits": {
              "crypto_remaining": "6000",
              "crypto_spending": "0",
              "digital_goods_remaining": "6000",
              "digital_goods_spending": "0"
          },
          "linked_payment_methods": [],
          "lkyc_status": "success",
          "phone": "+49*****354",
          "phone_country": "DE",
          "user_id": "01KADX5RRHCHDMPFWEEFX2YDS6"
      }
  ],
  "success": true,
  "total": 3
}

Create User

Create users via the API. This will generate a Wert profile for the user and initiate Light KYC on their behalf. If the KYC check is successful, the user will be taken directly to the payment step in the widget. Contact our support team to request this feature for your Partner ID.

Request Details

Endpoint: `POST /api/external/users/create`

👉 Refer to endpoints table for a full link.

❗️
Non-English characters should be standardized to English before passing to API.

Parameters

Configure your request using the parameters below to create user via API.

Property	Required	Validation
has_accepted_terms_of_service	✅	possible values: `true`, `false`
phone	✅	+1234567890
email	✅	[email protected]
first_name	✅	2–30 characters; A-Z, a-z, 0-9; No special characters (?, @, #, $, etc.); Cannot be all numeric
middle_name	Optional	2–30 characters; A-Z, a-z, 0-9; No special characters (?, @, #, $, etc.); Cannot be all numeric
last_name	✅	2–30 characters; A-Z, a-z, 0-9; No special characters (?, @, #, $, etc.); Cannot be all numeric
date_of_birth	✅	format: `YYYY-MM-DD`
country_of_residence	✅	alpha3 country code;
state_of_residence	✅	alpha2 US state code;

Example request

Example of user data to create a user with Wert and initiate an automatic LKYC.

curl -X POST 'https://partner.wert.io/api/external/users/create' \
 -H 'X-Api-Key: your-unique-api-key' \
 -H 'Content-Type: application/json' \
 -d '{
   "has_accepted_terms_of_service": true,
   "phone": "+1234567890",
   "email": "[email protected]",
   "first_name": "John",
   "middle_name": "Paul",
   "last_name": "Doe",
   "date_of_birth": "1990-01-01",
   "country_of_residence": "USA",
   "state_of_residence": "CA"
 }'

Response Details

Possible response from User Creation endpoint. Refer to user creation error codes for more details.

   {
       "created_at": "string",
       "user_id": "string",
   }

User Creation Error Codes

Error code	Description
`400`	Bad request. Ensure all required fields are present and meet validation criteria.
`401`	Unauthorized. Check your API key or contact support.
`403`	Forbidden. Ensure the user is 18+ years old, country and state are supported, and the user has accepted the terms and conditions.
`409`	Conflict. A user with the same phone number may already exist.
`429`	Too Many Requests. Retry later.
`500`	Internal Server Error.

Card Register

Allows you to register users cards directly from your backend. This requires PCI DSS certification, please get in touch with Wert team to request this feature for your Partner ID. Only works for users who have been created by the user creation API above.

Request Details

Endpoint: `POST /api/v1/partner/register`

👉 Refer to endpoints table for a full link.

Parameters

Configure your request using the parameters below to register a card for an existing user.

Property	Required	Validation
card_number	✅	String, 12–19
exp_month	✅	2 digits, only numbers
exp_year	✅	4 digits, only numbers
user_id	✅	Must match an existing user in database
billing_address.country	✅	alpha2 country code
billing_address.state	Conditional	Required for USA & Canada only; Not required for other countries; alpha2 state code
billing_address.postal_code	✅	2–10 characters; `^[a-zA-Z0-9[:space:]-]*`; Character “-” is allowed
billing_address.city	✅	String, 2–25 characters; A–Z, a–z, 0–9; No special or non-English characters; Cannot be all numeric
billing_address.street	✅	String, 2–35 characters; A–Z, a–z, 0–9; No special or non-English characters; Cannot be all numeric; Spaces allowed

Example request

Example of card data registered on behalf of an existing user.

curl --location 'https://cards.wert.io/api/v1/partner/register' \
  --header 'x-api-key: your-unique-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "card_number": "4001590000000001",
    "exp_month": "01",
    "exp_year": "2029",
    "user_id": "USER_ID",
    "billing_address": {
      "country": "AD",
      "postal_code": "11111",
      "city": "City",
      "street": "Street house number 6"
    }
  }'

Response Details

Possible responses from Card Register endpoint.

   {
     "card_id": "string"
   }

Endpoint specification

Authentication

API Reference

Get orders

Endpoint: GET /api/external/orders

Parameters

Example Requests

Orders Response

Order Object

Example Response

Order Status

Payment Error Codes

Get users

Endpoint: GET /api/external/users

Parameters

Example request

Users Response

User Object

Linked Payment Methods

Example Response

Create User

Endpoint: POST /api/external/users/create

Parameters

Example request

User Creation Error Codes

Card Register

Endpoint: POST /api/v1/partner/register

Parameters

Example request

Endpoint: `GET /api/external/orders`

Endpoint: `GET /api/external/users`

Endpoint: `POST /api/external/users/create`

Endpoint: `POST /api/v1/partner/register`