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.

Request method: GET | POST

Endpoint URL:

Sandbox:	Endpoint
Partner's Orders	`https://partner-sandbox.wert.io/api/external/orders`
Partner's User Creation	`https://partner-sandbox.wert.io/api/external/users/create`
Partner's Users	`https://partner-sandbox.wert.io/api/external/users`

Production:	Endpoint
Partner's Orders	`https://partner.wert.io/api/external/orders`
Partner's User Creation	`https://partner.wert.io/api/external/users/create`
Partner's Users	`https://partner.wert.io/api/external/users`

Headers:

Key: X-API-KEY
Value:your-unique-api-key

ℹ️
You must replace 'your-unique-api-key' with your personal API key. You can request this by contacting our partner support.

Order Request

The Data API can make use of the following parameters:

Parameter	Data Type	Description
limit	Number	The number of orders you want to retrieve. Defaults to 10.
offset	Number	Skips specified number of orders. Defaults to 0.
search_by	String with order or click ID	Allows setting an order or click ID to find a specific order.
order_by	asc / desc	Allows setting the order as ascending or descending. Defaults to desc.

Examples Of Request

Retrieving the ten most recent orders:

curl -X GET 'https://partner.wert.io/api/external/orders' \
-H 'X-API-KEY: your-unique-api-key'

Retrieving the 20 orders which were made after the first 10 orders:

curl -X GET -G 'https://partner.wert.io/api/external/orders' \
-H 'X-API-KEY: your-unique-api-key'\ 
-d 'limit=20' \
-d 'offset=10' \
-d 'order_by=asc'

Retrieving an order using the click ID:

curl -X GET -G 'https://partner.wert.io/api/external/orders' \
-H 'X-API-KEY: your-unique-api-key'\ 
-d 'search_by=click_id'

Order Response

The response contains the following:

Variable	Description
success	Whether the request was successfully processed and produced a result
data	An object with the orders which were retrieved from the API
total	The total number of orders which match the criteria for the search

Example Of Response

Response from Orders endpoint:

{
    "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,
            "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
        },
        {
            "order_id": "01HMXQ6AN3XKQAZHPRSM13ED3X",
            "click_id": "click_id",
            "currency": "usd",
            "currency_amount": 5,
            "crypto": "tt_goerli.erc-20.ethereum",
            "crypto_amount": 4.36051815,
            "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
        }
    ],
    "total": 2
}

Order Variables

Each order in the data object will include the following:

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
crypto	The crypto asset which was purchased or sent to the smart contract	Yes	commodity
crypto_amount	The amount of the crypto asset which was 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	Yes	status
card_id	The unique identifier for the card which was 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 which were collected as partner revenue	No
partner_fee_percent	The percentage of fees which were collected as partner revenue	No
wert_fee	The USD amount of fees which were collected as Wert revenue	No
wert_fee_percent	The percentage of fees which were 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 description of error code.	Yes	fail_reason
payment_type	The authentication method of the payment, e.g "3ds_v2"	Yes
additional_data	Additional information	No
sc_input_data	Smart contract Input data that was sent in the transaction	No

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

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	We weren’t able to charge the user’s card and the order was not completed. The user should contact support for further assistance.

User Creation

Allows you to create users directly from your backend. Contact our support team to request this feature for your Partner ID.

Parameters to pass for user creation:

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; Cannot contain special characters (?, @, #, $, &, *, etc.) and non-English letters; Cannot be all numeric
middle_name	Optional	2–30 characters; A-Z, a-z, 0-9; Cannot contain special characters (?, @, #, $, &, *, etc.) and non-English letters; Cannot be all numeric
last_name	✅	2–30 characters; A-Z, a-z, 0-9; Cannot contain special characters (?, @, #, $, &, *, etc.) and non-English letters; Cannot be all numeric
date_of_birth	✅	format: YYYY-MM-DD
country_of_residence	✅	alpha-3 country code; Must be on our list in the countries table
state_of_residence	✅	alpha-2 US state code; Must be on our list in the states table

Example Of Request

Example of user data to be sent to the /api/external/users/create endpoint 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"
  }'

Example Of Response

Response from User Creation endpoint:

201 Created

{
  "user_id": "01HPPKVTKC3VKXC95ADA8M5JTA",
  "created_at": "2024-05-15T12:30:45Z"
}

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 user has accepted 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

Get User Data

Allows you to fetch detailed user data for users you have created or served.

Example Of Request

Request to the Users endpoint

curl -X GET 'https://partner.wert.io/api/external/users?user_ids=01JP7C3WV0BXEWP5ZF2Q8MQ7P0' \
  -H 'X-Api-Key: your-unique-api-key' \
  -H 'Content-Type: application/json'

Example Of Response

Response from the Users endpoint

{
    "data": [
        {
          "user_id": "01HPPKVTKC3VKXC95ADA8M5JTA",
          "created_at": "2019-05-15T12:30:45Z",
          "country": "US", // do not send if empty
          "state": "CA", // do not send if empty
          "phone": "+1*****345",
          "phone_country": "US",
          "banned": "", // Present only if user is banned
          "lkyc_status": "success",
          "fkyc_status": "not initiated",
          "limits": { 
            "crypto_spending": 1000.07,
            "crypto_remaining": 500.03,
            "digital_goods_spending": 0,
            "digital_goods_remaining": 1500
           },
				"linked_payment_methods": [
					  {
					    "method": "bank_card",
					    "cards": [
					      {
					        "card_id": "01HPPKVTHGGHHDA8M5JTA",
					        "brand": "Visa",
					        "last_digits": "4242",
					        "created_at": "2024-05-01T10:30:00Z"
					      },
					      {
					        "card_id": "01HPPKVTKC3VKXJBBBJ76",
					        "brand": "Mastercard",
					        "last_digits": "1111",
					        "created_at": "2024-05-10T14:20:00Z"
					      }
					    ]
					  }
					]
        }
    ],
    "success": true,
    "total": 1
}

Response Variables

Variable	Description	Filterable	Filter name
user_id	User's Wert ID	Yes	user_ids
country	User's KYC country	Yes	kyc_country
phone_country	Users phone country	Yes	phone_country
lkyc_status	Users non-document verification status	Yes	lkyc_status
fkyc_status	Users document verification status	Yes	fkyc_status
banned	Is the user banned by Wert	No
created_at	date and time of the user's creation	No
limits.digital_goods_remaining	How much in USD of the user's current NFT limits is left. Send zero limits if the user has not started any KYC yet or if his active KYC is not in success status.	No
linked_payment_methods	Available payment methods for the user (based on the KYC country or state for US) with the list of bank card data	No