Data API

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 Ordershttps://partner-sandbox.wert.io/api/external/orders
Partner's User Creationhttps://partner-sandbox.wert.io/api/external/users/create
Partner's Usershttps://partner-sandbox.wert.io/api/external/users
Production:Endpoint
Partner's Ordershttps://partner.wert.io/api/external/orders
Partner's User Creationhttps://partner.wert.io/api/external/users/create
Partner's Usershttps://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:

ParameterData TypeDescription
limitNumberThe number of orders you want to retrieve. Defaults to 10.
offsetNumberSkips specified number of orders. Defaults to 0.
search_byString with order or click IDAllows setting an order or click ID to find a specific order.
order_byasc / descAllows 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:

VariableDescription
successWhether the request was successfully processed and produced a result
dataAn object with the orders which were retrieved from the API
totalThe 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",
            "partner_fee": 0,
            "partner_fee_percent": 0,
            "wert_fee": 0.04,
            "wert_fee_percent": 0.04,
            "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",
            "partner_fee": 0,
            "partner_fee_percent": 0,
            "wert_fee": 0.19,
            "wert_fee_percent": 0.04,
            "tx_id": "",
            "processed_through": "safecharge",
            "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:

VariableDescriptionFilterableFilter name
order_idThe unique identifier for the order in Wert's databaseYessearch_by
click_idThe identifier you pass to Wert when you initialise the widgetYessearch_by
currencyThe base currency for the orderNo
currency_amountThe value of the order in the base currencyNo
cryptoThe crypto asset which was purchased or sent to the smart contractYescommodity
crypto_amountThe amount of the crypto asset which was purchased or sent to the smart contractNo
user_idThe unique identifier for the user in Wert's databaseYesuser_ids
statusThe status of the orderYesstatus
card_idThe unique identifier for the card which was used in Wert's databaseYescard_id
created_atTimestamp of when the order was created (UTC)No
changed_atTimestamp of when the order was last updated (UTC)No
partner_feeThe USD amount of fees which were collected as partner revenueNo
partner_fee_percentThe percentage of fees which were collected as partner revenueNo
wert_feeThe USD amount of fees which were collected as Wert revenueNo
wert_fee_percentThe percentage of fees which were collected as Wert revenueNo
tx_idBlockchain transaction hashYestx_id
processed_throughThe acquirer who processed the card paymentNo
card_brandVisa or MastercardNo
fail_reasonPayment error code, refer to description of error code.Yesfail_reason
payment_typeThe authentication method of the payment, e.g "3ds_v2"Yes
additional_dataAdditional informationNo
sc_input_dataSmart contract Input data that was sent in the transactionNo

The following order statuses are available:

StatusDescription
successThe order was successful and has been sent on the blockchain
failedThe order has failed and will not be sent on the blockchain
cancelledThe payment for the order was processed but the order was later cancelled
pendingThe order is being processed but it hasn't been sent on the blockchain
progressThe order is being processed but payment has not yet been completed
createdThe 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:

PropertyRequiredValidation
has_accepted_terms_of_servicepossible values: true, false
phone+1234567890
email[email protected]
first_name2–30 characters; A-Z, a-z, 0-9; Cannot contain special characters (?, @, #, $, &, *, etc.) and non-English letters; Cannot be all numeric
middle_nameOptional2–30 characters; A-Z, a-z, 0-9; Cannot contain special characters (?, @, #, $, &, *, etc.) and non-English letters; Cannot be all numeric
last_name2–30 characters; A-Z, a-z, 0-9; Cannot contain special characters (?, @, #, $, &, *, etc.) and non-English letters; Cannot be all numeric
date_of_birthformat: YYYY-MM-DD
country_of_residencealpha-3 country code; Must be on our list in the countries table
state_of_residencealpha-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

VariableDescriptionFilterableFilter name
user_idUser's Wert IDYesuser_ids
countryUser's KYC countryYeskyc_country
phone_countryUsers phone countryYesphone_country
lkyc_statusUsers non-document verification statusYeslkyc_status
fkyc_statusUsers document verification statusYesfkyc_status
bannedIs the user banned by WertNo
created_atdate and time of the user's creationNo
limits.digital_goods_remainingHow 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_methodsAvailable payment methods for the user (based on the KYC country or state for US) with the list of bank card dataNo

Documentation related to this page