Card Register

Register a user's payment card directly from your backend to pre-populate their profile ahead of checkout. By combining this endpoint with the Create User endpoint, end-users can open the widget with their card already saved on file; eliminating manual card entry, reducing checkout friction, and increasing conversion rates.

EnvironmentMethodEndpoint
SandboxPOSThttps://cards-reg-iframe-sandbox.wert.io/api/v1/partner/register
ProductionPOSThttps://cards.wert.io/api/v1/partner/register

Limits


⚠️

Important!

  • PCI DSS Compliance Required: Access to this endpoint requires valid PCI DSS certification. Please contact the Wert team to enable this feature for your Partner ID.
  • User must agree to sharing their card details with Wert.
  • Only works for user profiles created via the Create User API using your own partner account. You cannot register cards on behalf of users created by a different partner account.

Body


card_number
string Required

The user's payment card number.

Possible values: 12–19 characters, numbers only.


exp_month
string Required

The expiration month of the card.

Possible values: 2 digits, numbers only (e.g., 01 to 12).


exp_year
string Required

The expiration year of the card.

Possible values: 4 digits, numbers only (e.g., 2029).


user_id
string Required

The unique identifier of the user in Wert's database. Must match an existing user created via the API.


billing_address
object Required

The billing address associated with the card.

Show child attributes
billing_address.country string Required

The billing country code in alpha-2 format.

Possible values: Click to see alpha-2 country code, for example DE, US, RU.


billing_address.state string Conditional

The billing state or province code in alpha-2 format. Required for USA and Canada only; optional for other countries.

Possible values: Click to see US/CANADA alpha-2 state codes, (US territories are excluded and should be passed in the country field instead). for example AZ, UT, FL.


billing_address.postal_code string Required

The billing postal or ZIP code. Must be 2–10 characters matching ^[a-zA-Z0-9[:space:]-]* (hyphens - and spaces are allowed).


billing_address.city string Required

The billing city name. Must be 2–25 characters (A–Z, a–z, 0–9); no special or non-English characters; cannot be all numeric.


billing_address.street string Required

The billing street address. Must be 2–35 characters (A–Z, a–z, 0–9, and spaces); no special or non-English characters; cannot be all numeric.


Example Request


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": "01KT3R3BQ2ZRBHZN58E6VVY5F3",
    "billing_address": {
      "country": "AD",
      "postal_code": "11111",
      "city": "City",
      "street": "Street house number 6"
    }
  }'

Response


body
object
Show child attributes
body.card_id string

The unique identifier for the registered payment card in Wert's database.


status
string

Indicates the status of the request (e.g., "ok").

Example Response


{
  "body": {
    "card_id": "01KADXN9TN3QEMG9DHWX6G7Y0S"
  },
  "status": "ok"
}

References


Card Registration Errors

Card details validation

{
  "status": "error",
  "error_description": "Invalid card"
}
{
  "status": "error",
  "error_description": "Invalid exp month"
}
{
  "status": "error",
  "error_description": "Invalid year"
}
{
  "status": "error",
  "error_description": "Card expired"
}

Billing address & business validation

{
  "code": 121,
  "status": "error",
  "error_description": "invalid billing address information",
  "request_id": "string"
}
{
  "code": 109,
  "status": "error",
  "error_description": "attempt to register more cards than allowed"
}
{
  "code": 113,
  "status": "error",
  "error_description": "card already registered"
}
{
  "code": 309,
  "status": "error",
  "error_description": "user not found"
}
{
  "code": 310,
  "status": "error",
  "error_description": "user banned"
}

Did this page help you?