Documentation
  1. Reference

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.

Endpoint URLs:

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.

Limits:

  • Threshold: 10 requests per second.

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 20.		 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 count of orders matching the search criteria. When cursor_id is set, only orders after the cursor are counted.

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_id
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 Partner revenue fee amount in the charged currency. No -
partner_fee_percent The percentage of fees collected as partner revenue. No -
wert_fee Wert revenue fee amount in the charged currency. 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, Mastercard, etc. 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 -
payment_method Available payment methods. Refer to payment methods. No -

Example Response

{
    "success": true,
    "data": [
        {
            "additional_data": null,
            "address": "0x8b444bf218D83Bd567E625383EB2e5A25f707599",
            "card_brand": "VISA",
            "card_id": "01KHB8JNDE3NJ1NG8F1C087X6K",
            "changed_at": "2026-06-02 08:45:44",
            "click_id": "click_id",
            "created_at": "2026-06-02 08:44:43",
            "crypto": "tt.erc-20-sc.base",
            "crypto_amount": 12.92,
            "currency": "USD",
            "currency_amount": 14.25,
            "external_order_id": "zvLHq",
            "fail_reason": "",
            "order_id": "01KT3R3BQ2ZRBHZN58E6VVY5F3",
            "partner_fee": 0.14,
            "partner_fee_percent": 0.01,
            "payment_type": "non_3ds",
            "payment_method": "card",
            "processed_through": "worldpay",
            "sc_input_data": "0x48bc17bf0000000000000000000000008b444bf218d83bd567e625383eb2e5a25f70759900000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000b34d0f8c020c000000000000000000000000000000000000000000000000000000000000000001c20000000000000000000000000000000000000000000000000618a2d524ef00000000000000000000000000000000000000000000000000000000000000000035697066733a2f2f516d574e7a6d5a6b77664531393967386e6b415373583950636d6136796b425747344373734376336b456e764a700000000000000000000000",
            "status": "success",
            "tx_id": "0xe6456e64a1e6d7f226deb7ff344cb5321a3a997165ea24569465493ff7385216",
            "user_id": "01HQRBTDW17YQSZFBWZY7807B1",
            "wert_fee": 1,
            "wert_fee_percent": 0.05
        }
    ],
    "next_cursor_id": "01KAQWBNWWGG06HR5T9Z35A3WD",
    "total": 1
}

Order Status

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

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 offramp orders

Get detailed offramp orders data associated with your partner account. In an offramp order, the user sells USDC for a USD payout to their bank account.

Request Details

Endpoint: GET /api/external/offramp-orders

👉 Refer to endpoints table for a full link.

Parameters

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

Parameter Description Possible Values
limit The number of orders you want to retrieve.

Defaults to 20. Values from 1 to 19 are applied as given. Any other value returns up to 20 orders.		 1 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 Finds orders by one value: an exact order_id, or the beginning of an external_order_id or click_id. Prefix matching is case-insensitive. A single value, for example 2FX6Yz. Comma-separated values are not supported.
status Filters orders by their current status, the same value returned in the status field. See offramp order statuses. One value: created, awaiting_deposit, crypto_received, transfer_pending, completed, failed, expired, on_hold, or cancelled.
start_date Filters orders with created_at at or after this timestamp. YYYY-MM-DDTHH:MM:SSZ, for example 2025-11-19T00:00:00Z.
end_date Filters orders with created_at up to this timestamp. YYYY-MM-DDTHH:MM:SSZ
💡

Pagination reference

  • Orders are returned newest first.
  • Pass the next_cursor_id from the previous response as cursor_id to get the next page. An empty next_cursor_id means there are no more orders.
  • The maximum is 20 orders per request.

Example Requests

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

# 2. Retrieve the next 10 orders using a cursor
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/offramp-orders' \
  -H 'X-Api-Key: your-unique-api-key' \
  -d 'limit=10' \
  -d 'cursor_id=01KAQWBNWWGG06HR5T9Z35A3WD'

# 3. Find an order by its order_id
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/offramp-orders' \
  -H 'X-Api-Key: your-unique-api-key' \
  -d 'search_by=01KAQWBNWWGG06HR5T9Z35A3WD'

# 4. Search by the beginning of an external_order_id or click_id
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/offramp-orders' \
  -H 'X-Api-Key: your-unique-api-key' \
  -d 'search_by=2FX6'

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

# 6. Filter orders by date range
curl -X GET -G 'https://partner-sandbox.wert.io/api/external/offramp-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'
Response Details

Offramp 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 offramp order objects. See offramp order object.
next_cursor_id The cursor string used to fetch the next page of results. An empty string means there are no more orders.
total The count of offramp orders matching the search criteria. The count does not depend on cursor_id.

Offramp 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. Amounts are returned as strings.

Variable Description Filterable Filter Name
order_id The unique identifier for the order in Wert's database. Yes search_by
external_order_id The short identifier for the order. Omitted when the order has none. Yes search_by
click_id The click ID passed when the order was opened. Always present, and can be an empty string. Yes search_by
user_id The unique identifier for the user in Wert's database. No -
status The current status of the order. See statuses. Yes status
created_at Timestamp of when the order was created (UTC), in YYYY-MM-DD HH:MM:SS format. Yes start_date / end_date
changed_at Timestamp of when the order was last updated (UTC), in YYYY-MM-DD HH:MM:SS format. No -
quoted_amount The USDC amount set when the order was created. No -
incoming_amount The USDC amount received from the user. Omitted if no deposit has been recorded. No -
fee_amount The fee deducted from the payout, in USD. Omitted if it has not been calculated. No -
outgoing_amount The amount paid out to the user's bank account, in USD. Omitted if it has not been calculated. No -
tx_id Blockchain transaction hash of the user's deposit. Omitted if no deposit has been recorded. No -
account_number_last4 The last four digits of the bank account the order pays out to. No -
network The blockchain network of the deposit: ethereum, polygon or base. No -
asset The crypto asset sold: USDC. No -

Example Response

{
    "success": true,
    "data": [
        {
            "account_number_last4": "6789",
            "asset": "USDC",
            "changed_at": "2026-06-02 09:12:05",
            "click_id": "click_id",
            "created_at": "2026-06-02 08:44:43",
            "external_order_id": "zvLHq",
            "fee_amount": "1.5",
            "incoming_amount": "100",
            "network": "ethereum",
            "order_id": "01KT3R3BQ2ZRBHZN58E6VVY5F3",
            "outgoing_amount": "98.5",
            "quoted_amount": "100",
            "status": "completed",
            "tx_id": "0xe6456e64a1e6d7f226deb7ff344cb5321a3a997165ea24569465493ff7385216",
            "user_id": "01HQRBTDW17YQSZFBWZY7807B1"
        }
    ],
    "next_cursor_id": "",
    "total": 1
}

Offramp Order Status

The status field and the status filter use the following values:

  • created
  • awaiting_deposit
  • crypto_received
  • transfer_pending
  • completed
  • failed
  • expired
  • on_hold
  • cancelled

If Wert support overrides the status of an order, status returns the overridden value and the status filter matches it.

Offramp Order Errors

Possible error responses from the Offramp Orders endpoint.

{
    "message": "search_by accepts one order id or external id prefix"
}
{
    "message": "unknown offramp order status"
}

A missing X-Api-Key header, or a parameter in the wrong format (for example, a non-numeric limit or a malformed date), also returns 400, with the reason in a msg field.


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.

Limits:

  • Threshold: 10 requests per second.

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' \
-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.

PropertyRequiredValidation
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_nameOptional2–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;
tinOptionalFor USA, a Social Security number: dashes and spaces are ignored, and exactly 9 digits are stored as 000-00-0000. For any other country, the trimmed value is stored as given. A blank value is rejected. The value is not returned.

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",
   "tin": "000-00-0000"
 }'
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.

Create offramp bank account

Add a US bank account to an existing user for offramp payouts. The user must be one you have created or served, and offramp must be available for your Partner ID.

Request Details

Endpoint: POST /api/external/offramp/users/USER_ID/bank-accounts

👉 Refer to endpoints table for a full link.

Limits:

  • Requests are rate limited per partner. When the limit is reached, the API returns 429 with a Retry-After header.
  • A user can have up to 3 active bank accounts.
  • If the user already has an active bank account with the same routing_number and account_number, the API returns 409 with the existing bank_account_id.

Parameters

Replace USER_ID in the path with the user's Wert ID, and configure the request body using the parameters below.

PropertyRequiredValidation
account_holder_name✅1–128 characters; leading and trailing spaces are removed
account_number✅4–17 digits, only numbers
routing_number✅9 digits, only numbers; must be a valid ABA routing number
account_type✅possible values: checking, savings
aliasOptionalUp to 64 characters; leading and trailing spaces are removed. If omitted or empty, the alias is four middle dots, a space, and the last four digits of the account number, for example ···· 6789
emailOptionalA valid email address. Omit it or send null to use the email on the user's offramp profile, or the user's email if the profile has none

Example request

# 1. Create a bank account with the required fields only
curl -X POST 'https://partner-sandbox.wert.io/api/external/offramp/users/USER_ID/bank-accounts' \
  -H 'X-Api-Key: your-unique-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_holder_name": "Jane Doe",
    "account_number": "123456789",
    "routing_number": "021000021",
    "account_type": "checking"
  }'

# 2. Create a bank account with an alias and an email
curl -X POST 'https://partner-sandbox.wert.io/api/external/offramp/users/USER_ID/bank-accounts' \
  -H 'X-Api-Key: your-unique-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_holder_name": "Jane Doe",
    "account_number": "123456789",
    "routing_number": "021000021",
    "account_type": "savings",
    "alias": "Main savings",
    "email": "[email protected]"
  }'
Response Details

Possible responses from the Offramp Bank Account Create endpoint. Refer to offramp bank account error codes for more details.

{
    "account_number_last4": "6789",
    "account_type": "checking",
    "alias": "···· 6789",
    "bank_account_id": "01KB2YQ8V7C3N4M5P6R7S8T9VW",
    "created_at": "2026-10-29T12:34:56.789123Z"
}

Offramp Bank Account Error Codes

Error code Description
400 Bad request. The errors array lists each field that failed validation. A body that is not valid JSON, a field of the wrong type, or an email that is not a valid address returns 400 with an empty body. A missing X-Api-Key header returns 400 with the reason in a msg field.
401 Unauthorized. Check your API key or contact support.
403 Forbidden. The user is banned, or offramp is not available for your Partner ID.
404 Not found. The user does not exist or is not one of your users.
409 Conflict. The user already has 3 active bank accounts (code is BANK_LIMIT), or already has an active bank account with the same routing and account number (bank_account_id is the existing account).
429 Too Many Requests. Retry after the number of seconds in the Retry-After header.
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.

PropertyRequiredValidation
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.stateConditionalRequired 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.

{
  "body": {
    "card_id": "string"
  },
  "status": "ok"
}

Updated 1 day ago

Documentation related to this page

Did this page help you?