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 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",
"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:
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 |
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 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 |
Updated 12 days ago