Guides

Plastic Card Preorder

Suggest Edits

Stage 1: Sign-In and Navigation

  1. User Registration

    Send a request to register using the endpoint POST /v2/mobile/signup.

  2. Confirm Registration and Obtain Access Token

    Confirm registration by sending a request to the endpoint POST /v2/mobile/phone/confirm.

  3. Add Email

    Add an email by sending a request to the endpoint PUT /v2/mobile/email/add.

  4. Obtain KYC 0

    Obtain KYC 0 by sending a request to the endpoint PATCH /v2/customer/profile.

  5. Create Wallet

    Create a wallet using the endpoint POST /v2/wallets, selecting one of the following currencies:

    • BTC
    • ETH
    • USDT
    • USDC

  6. Top Up Cryptocurrency Wallet

    To top up your cryptocurrency wallet, contact technical support with the following information:

    • Phone Number: Your registered phone number.
    • Currency: Specify the cryptocurrency you wish to top up.
    • Amount Needed: Specify the amount you wish to deposit.

  7. Obtain KYC 1

    Obtain KYC 1 through Ondato. More details can be found here.

  8. Check Available Card Designs

    Determine which card designs are available to your merchant using the endpoint GET /v2/card/prices. This endpoint also provides information about the price of each card design.

    Additionally, check the availability of delivery to different countries and the associated shipping costs using the endpoint GET /v2/card/card-requests/country/plastic-delivery. This step is crucial for ensuring that card delivery can be made to the desired country.

  9. Request a New Card

    Create a request for a new card using the endpoint POST /v2/card/card-requests, selecting an available design and card type PLASTIC.

Stage 2: Data Entry

  1. Navigate to Data Entry Screen for Plastic Card

    The user is directed to the screen where they need to enter personal details for ordering the plastic card.

  2. Provide Additional Personal Information

    Provide additional personal information using the endpoint POST /v3/card/additional-personal-info. The following parameters are required:

  1. {
     "taxId": "string", // tax identification number. a unique number used for tax purposes in the country of tax residence.
     "taxCountry": "string", // country associated with the tax number. specified in ISO 3166-1 alpha-3 format, e.g., "USA" for the United States or "GBR" for the United Kingdom.
     "dataCorrectnessConfirmation": true, // confirmation of data accuracy. a value of `true` indicates that the user confirms the correctness of the provided data.
     "isUsRelated": true, // US-related status. a value of `true` indicates a connection with the US, such as an American tax number or activity in the US.
   }

When providing the taxCountry parameter, it's essential to ensure that the country specified is valid for plastic card issuance. Follow these steps to validate and ensure the accuracy of the taxCountry parameter:

  1. Check Valid Countries:

    To verify which countries are acceptable for the taxCountry parameter, use the endpoint GET /v1/catalog/countries with the filter REAP_PLASTIC_ALLOWED. This endpoint will return a list of countries approved for plastic card issuance.

    Example Request:

    GET https://crpt-backend-main-service.dev.testessential.net/v1/catalog/countries?type=REAP_PLASTIC_ALLOWED
  1. Enter Details: First Name and Last Name

Data Validation: First Name and Last Name

When entering the first and last name for creating or updating a cardholder's profile, the following validation rules are applied:

1. Character Length Validation:

  • Virtual Card: The combined length of the first and last name must not exceed 27 characters (including spaces).
  • Plastic Card: Each input field (first name and last name) must not exceed 13 characters (including spaces).

2. Allowed Characters:

  • Only Latin letters (A-Z), digits (0-9), spaces, and hyphens (-) are allowed.
  • Regional characters (e.g., ě, ć) and any other non-standard Latin characters are not permitted.
  • Special characters such as ;:!?<>~\%^@{}|[]”_` are not allowed and will not appear when entered.

3. Validation Example:

  • Valid Input: "JOHN DOE"
  • Invalid Input: "JOHN! DOE@" — the characters ! and @ will not be accepted.
  • Exceeding Character Limit: Entering "CHRISTOPHER" for the first name and "JONATHANSON" for the last name for a plastic card will trigger an error because each field exceeds the 13-character limit.

These validation rules ensure consistency and readability of the name on cards and prevent errors during card creation and usage.

📘

The backend imposes a total limit of 27 characters. One character is used for the separator that will be inserted between the first and last names (e.g., a period). The remaining 26 characters are divided between the first and last name fields, typically 13 characters each. However, partners have the flexibility to adjust this division, such as allocating 1 character for the first name and 25 for the last name.

Combining First Name and Last Name into a Single Field

Now, a separate endpoint is used for transmitting the combined first and last name. The process includes the following steps:

  1. Data Collection: Capture the first and last name entered by the user.
  2. Combining: Concatenate the first and last names using a separator (presumably, this will be a period).
  3. Sending to Backend: Submit the combined value through the new endpoint to the backend.

This new endpoint accepts a single field containing the combined first and last name, ensuring compliance with the 27-character maximum length rule (including the separator).

  1. Enter Shipping Address and Billing Address

    To update the shipping and billing addresses, use the endpoint PUT /v3/card/card-requests/{cardRequestId}/address.

    Request Parameters:

    • cardRequestId (integer, path): Card request identifier.

    • cp (string, query): Values: CP_1, CP_2.

      Request Body Example:

{
  "billingAddress": {
    "country": "string", // ISO 3166-1 alpha-3 country code for the billing address. must be a country whose documents are valid for plastic card issuance.
    "city": "string", // city for the billing address.
    "state": "string", // state or region for the billing address. (optional)
    "address": "string", // address for the billing address.
    "address2": "string", // additional address for the billing address. (optional)
    "postalCode": "string" // postal code for the billing address. (optional)
  },
  "shippingAddress": {
    "country": "string", // ISO 3166-1 alpha-3 country code for the shipping address. only countries where card delivery is supported are allowed. an error will be returned if a restricted country is selected: "we currently do not ship to your selected country. please select a different one or check back later."
    "city": "string", // city for the shipping address.
    "state": "string", // state or region for the shipping address. (optional)
    "address": "string", // address for the shipping address.
    "address2": "string", // additional address for the shipping address. (optional)
    "postalCode": "string", // postal code for the shipping address.
    "firstName": "string", // recipient's first name for the shipping address.
    "lastName": "string", // recipient's last name for the shipping address.
    "phone": "string" // recipient's phone number for the shipping address.
  }
}

📘

For virtual card orders, the shippingAddress array becomes optional since physical delivery is not required for virtual cards

Additional Information

Optional Fields

  • billingAddress:

    • state and postalCode fields are now optional.
    • address2 field is optional. If it is empty, a space will be used in its place on the backend.

  • shippingAddress:

    • state field is optional.
    • address2 field is optional. If it is empty, a space will be used in its place on the backend.

Country Restrictions

  • For shippingAddress:

    • Only countries where card delivery is supported can be used.
    • The list of allowed countries for shippingAddress can be retrieved via the following endpoint: 
      https://crpt-backend-main-service.dev.testessential.net/v1/catalog/countries?type=REAP_PLASTIC_ALLOWED
    • If a country outside this list is provided, the following error message will be returned: 
      We currently do not ship to your selected country. Please select a different one or check back later.

  • For billingAddress:

    • Only countries whose documents are valid for plastic card issuance can be used.
    • The list of allowed countries for billingAddress can be retrieved via the following endpoint: 
      https://crpt-backend-main-service.dev.testessential.net/v1/catalog/countries?type=REAP_VIRTUAL_ALLOWED
    • If a restricted country is selected, the following error message will be returned: 
      The selected country is currently restricted for card issuing.

Shipping Address Requirements

  • The shippingAddress field is subject to more stringent requirements as it is reviewed by the issuing partner (RIP).
  • Incorrect or incomplete data might lead to the rejection of the application.
  • Unlike the shippingAddress, the billingAddress only requires the country to be in the correct ISO 3166-1 alpha-3 format, without further validation criteria.

Stage 3: Confirmation and Payment

  1. Data Verification

    • The user reviews the entered data on the confirmation screen.

  2. Cost Calculation

    Example Response:

    {
  "countries": [
    {
      "countryIsoCode": "string", // ISO 3166-1 alpha-3 format.
      "countryIsoCode2": "string", // ISO 3166-1 alpha-2 format.
      "countryName": "string", // country name.
      "price": {
        "value": 0, // shipping cost.
        "currency": "string" // currency code.
      }
    }
  ]
}

  3. Create a Payment Offer

  4. Pay the Offer

  5. Complete the Preorder

    • After successful payment, the user receives preorder confirmation.
    • The application is saved in the system with the status PREORDERED.

Updated 21 days ago