Plastic Card Preorder

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

   Obtain KYC through SumSub. 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:

3. JSON

   {
        "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.
      }
   

3. Enter Details: First Name and Last Name

• To update the cardholder name for a card request, the endpoint PUT /v2/card/card-requests/{cardRequestId}/cardholder-name is used. This endpoint allows the user to input or modify the first and last name that will appear on the card.

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).

4. 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

   • The system calculates the shipping cost based on the selected shipping country. This is done using the endpoint GET /v2/card/card-requests/country/plastic-delivery.

   Example Response:

   JSON

   {
     "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

   • Create a payment offer for the order using the endpoint POST /v2/card/card-requests/{id}/payment-offer/{currency}.
   • Note: id is the cardRequestId obtained from the endpoint POST /v2/card/card-requests.
   • Currency Options: The currency parameter can be one of the following values: BTC, ETH, USDT, or USDC.

4. Pay the Offer

   • Pay the offer using the endpoint POST /v2/card/card-requests/payment-offer/{id}/confirm.
   • Ensure that there are sufficient funds in your wallet.

     ❗️

     Note: {id} refers to the request ID you received from the POST /v2/card/card-requests endpoint.

5. Complete the Preorder

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