Overview

Introduction

Prepaid cards - pay online, spend abroad, and withdraw cash. The Prepaid card is your balance on the move. Customers of Paysafe Embedded Wallet can create, cancel, activate, and completely manage their cards based on their needs.

Supporting VIRTUAL and PHYSICAL card types, the customers can have both at the same time and use them independently.

Card creation and management are done through REST API calls. Below in this document, a simplified flow will be described for how we could issue a virtual/physical card and what steps are required.

Card Technical Details

note

All requests must contain an Authorization header with the value Bearer {key}, where {key} is the JWT token obtained after login.

Simplified Card Creation Flow

Get Cards

1. To display existing cards, you can make a request to:

GET https://api.paysafe.com/digitalwallets/v1/profile/prepaid/cards

Depending on your needs, you can additionally filter the desired response based on query parameters.

• status - Comma-separated list of card statuses that will returned. By default, all statuses will be returned. For more information, see CardStatus scheme.

• cardType - Get a list of cards by card type (VIRTUAL/PHYSICAL).

• limit - This is the total number of records to return.

• offset - This is the starting position, where 0 is the first record.

• include - Include listed properties in the response.

An example of the response from the request:

Get Cards Endpoint

{
  "cards": [
    {
      "cardId": "f16ba382-eb42-481a-b08f-c57bdc9aae24",
      "status": "ACTIVE",
      "expiry": {
        "month": 3,
        "year": 2028
      },
      "bin": "533944",
      "lastFour": "7009",
      "customerId": "12345678",
      "cardType": "VIRTUAL",
      "programName": "BRAND-VIRTUAL-MC",
      "currency": "EUR",
      "mobile": "+359 888333333",
      "createdDate": "2019-08-24T14:15:22Z",
      "accountId": "127623047"
    }
  ],
  "meta": {
    "numberOfRecords": 1,
    "limit": 10,
    "page": 1
  }
}

Get Programs

2. The program configuration determines the properties of the cards that can be issued within the program. It defines some important parameters like types of cards that can be issued, card currency, etc.

Your onboarding manager will provide comprehensive information regarding the configurable parameters available to you.

Based on the response from Get Cards, we can show the customer information about the available cards.

A simple GET request to the endpoint will return a response with the programs.

GET https://api.paysafe.com/digitalwallets/v1/profile/prepaid/programs

Get Programs Response

{
  "programs": [
    {
      "cardType": "PHYSICAL",
      "scheme": "MC",
      "name": "BRAND-PHYSICAL-MC",
      "currencies": [
        "EUR"
      ],
      "allowableCards": 1,
      "isDigital": true
    },
    {
      "cardType": "VIRTUAL",
      "scheme": "MC",
      "name": "BRAND-VIRTUAL-MC-EEA",
      "currencies": [
        "EUR"
      ],
      "allowableCards": 1,
      "isDigital": false
    }
  ]
}

If the customer is eligible for a Prepaid card, the response will contain a non-empty programs array. The number of cards that can be issued of a given type can be seen in the allowableCards field.

• cardType - indicates the type of the card - PHYSICAL or VIRTUAL
• scheme - indicates the card scheme (VISA / MC Mastercard)
• name - program name contains information about the type of the card, scheme and can contain additional info. The field is used with Create Card and the type of the card is determined by it.
• currencies - list of supported currencies for a given card.
• allowableCards - the number of cards that can be created for the given program. The number of available cards will be reduced with each card issued for the relevant program.
• isDigital - A Digital card is a special type of PHYSICAL card that can be used immediately after it is created.

Create Card

3. Using the information from Get Programs most of the required data will be available to Create a Card.

POST https://api.paysafe.com/digitalwallets/v1/profile/prepaid/cards

Create Card body request

{
  "programName": "BRAND-VIRTUAL-MC-EEA",
  "currency": "EUR",
  "mobile": "+359 888333333",
  "externalId": "a2322550-af91-417f-867e-681efad44b9d",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0"
}

The type of the desired card will be determined by the parameter programName, which can be used together with the currency from the response of the Get Programs endpoint.

• mobile - In case of missing information for the mobile field, the customer's onboarding phone number will be used.
• externalId - a unique card id on the Merchant side associated with the newly created card.
• userAgent - The User Agent used for the request. The field should follow the official specification - User Agent Specification

Some User Agent Examples for the different devices:

Device	Browser/Application	User Agent
Desktop	Chrome	Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36
Phone	Chrome	Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36
Phone	Application	SkrillPaymentsAndroid/3.120.0

Depending on the desired card type, additional properties should be added to the request:

• cardPin - The field can be used when creating a physical card in the EU.
• deliveryAddress - It is a required property when the request is for PHYSICAL card. For VIRTUAL card type this property is not needed.
• termsAndConditionsAccepted - The field must be present for US customers.
• eDisclosureAccepted - The field must be present for US customers.

The response from the endpoint will contain as follows:

Create Card Response

{
  "programName": "BRAND-VIRTUAL-MC-EEA",
  "currency": "EUR",
  "mobile": "+359 888333333",
  "cardId": "f16ba382-eb42-481a-b08f-c57bdc9aae24",
  "status": "ACTIVE",
  "expiry": {
    "expiryMonth": "2",
    "expiryYear": "26"
  },
  "bin": "533944",
  "lastFour": "7009",
  "cardType": "VIRTUAL",
  "customerId": "12345678",
  "scheme": "VISA",
  "createdDate": "2019-08-24T14:15:22Z",
  "accountId": "127623047"
}

During the creation of the card, some exceptions may arise. One example of such is the missing programName property:

HTTP STATUS - 400 Bad Request

Missing programName Exception

{
  "error": {
    "code": "5068",
    "message": "Field error(s)",
    "details": [
      "Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected."
    ],
    "fieldErrors": [
      {
        "field": "programName",
        "error": "must not be null"
      }
    ]
  }
}

For other types of errors that may occur, please visit the Error Handling section.

Get Card Sensitive Details

note

To use this endpoint, you must have a valid and current PCI-DSS certification, backed by the ROC report.

4. Card sensitive information can be retrieved via endpoint:

GET https://api.paysafe.com/digitalwallets/v1/profile/prepaid/cards/{cardId}/details

Card Sensitive Details

{
  "pan": "4748365822915043",
  "cvv": "233",
  "expiry": {
    "month": 3,
    "year": 2028
  },
  "cardHolderName": "Mollie Bazhaev"
}

Update Card

Given Card can be in one of the following statuses:

• ACTIVE - Card can be used for payments.
• PENDING - Intermediate status before issuing a card, while performing additional validations.
• CANCELLED - The card is canceled and can't be used for any kind of operation. The status is (IRREVERSIBLE).
• SUSPENDED - The status is changed from CS (Customer Service) representative or due to customer actions like (wrong activation info).
• APPLIED - Intermediate status for a card that is stuck due to technical reasons.
• DIGITAL - PHYSICAL card that is active and can be used for online payments only, but it is not yet delivered to the client, and it is not activated.
• REJECTED - Card is rejected due to technical / validation reasons.
• LOCKED - Card is locked by the customer and can't be used for payments.
• EXPIRED - Card is expired.
• ISSUED - The status indicates that the customer has successfully applied for a PHYSICAL card, but the card is not yet activated and can't be used for payments.

note

Not all the mentioned statuses can be changed by the Customer. Statuses like EXPIRED REJECTED and SUSPENDED are internal statuses. The list of card statuses can be extended and new statuses added.

Some of them are called IRREVERSIBLE and they are final. Such statuses cannot be changed. CANCELLED and REJECTED are some examples of such kind of statuses.

The status of the card is flexible and can be changed at the customer's request, as long as the new status is compatible with the current status. In the table below, you can find information about the statuses that the user can change.

From \ To	ACTIVE	CANCELLED	LOCKED	DIGITAL
ACTIVE	-	✅	✅	❌
CANCELLED	❌	-	❌	❌
LOCKED	✅	✅	-	❌
DIGITAL	✅ (By PIN & CHIP)	✅	✅	-

We can change the Card Status from ACTIVE to LOCKED with request:

PATCH https://api.paysafe.com/digitalwallets/v1/profile/prepaid/cards/{cardId}

Change Card Status Request

{
  "status": "LOCKED",
  "statusReason": "Card status changed from ACTIVE to LOCKED",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0"
}

The response from the successfully applied status will be:

Change Card Status Response

{
  "cardId": "f16ba382-eb42-481a-b08f-c57bdc9aae24",
  "status": "LOCKED",
  "expiry": {
    "month": 3,
    "year": 2028
  },
  "bin": "533944",
  "lastFour": "7009",
  "customerId": "12345678",
  "cardType": "VIRTUAL",
  "programName": "BRAND-VIRTUAL-MC-EEA",
  "currency": "EUR",
  "mobile": "+359 888333333",
  "createdDate": "2019-08-24T14:15:22Z",
  "accountId": "127623047",
  "scheme": "VISA",
  "activationDate": "2019-08-24T14:15:22Z",
  "isPinSet": false,
  "externalId": "a2322550-af91-417f-867e-681efad44b9d"
}

If you try to change an irreversible status to a reversible one, you will get an error of type.

HTTP STATUS - 400 Bad Request

Card Sensitive Details

{
  "error": {
    "code": "DW-PREPAID-CARDS-STATUS-IRREVERSIBLE",
    "message": "Current card status is irreversible.",
    "details": [
      "Current card status is irreversible."
    ],
    "fieldErrors": []
  }
}

Mobile Wallets Card Tokenization

Card tokenization is a multistep process that involves various parties to ensure the security and integrity of customer payment information. Some specific steps may vary depending on the implementation.

Card tokenization process described and illustrated in this section is mainly focused on adding a Prepaid Card to a Mobile Wallet such as Google Pay, Apple Pay and Samsung Pay.

Card tokenization simplified flow

Check for cards that are already tokenized (Added to a mobile wallet)

The first step in digitizing a card is to check whether it has already been tokenized for the corresponding device and wallet. Depending on the user flow, two methods are available to check if the given card is already tokenized.

• GET /digitalwallets/v1/profile/prepaid/cards?include=TOKENIZATIONS
• GET /digitalwallets/v1/profile/prepaid/cards/{cardId}?include=TOKENIZATIONS

Either request will return a response containing:

Cards with tokenizations

{
  "cards": [
    {
      "cardId": "f16ba382-eb42-481a-b08f-c57bdc9aae24",
      "status": "ACTIVE",
      "expiry": {
        "month": 3,
        "year": 2028
      },
      "bin": "533944",
      "lastFour": "7009",
      "customerId": "12345678",
      "cardType": "VIRTUAL",
      "programName": "BRAND-VIRTUAL-MC",
      "currency": "EUR",
      "mobile": "+359 888333333",
      "createdDate": "2019-08-24T14:15:22Z",
      "accountId": "127623047",
      "scheme": "MC",
      "activationDate": "2019-08-24T14:15:22Z",
      "isPinSet": true,
      "tokenizations": {
        "mobileWalletTokenizations": [
          {
            "dpanRef": "DAPLMC00002125433c0c34a2821f4f86866e7886963baf8b",
            "walletId": "NMZlGi8-DezZZKaR06orvl0f",
            "walletType": "GOOGLE_PAY",
            "status": "COMPLETED"
          }
        ]
      }
    }
  ],
  "meta": {
    "numberOfRecords": 1,
    "limit": 10,
    "page": 1
  }
}

$.tokenizations.mobileWalletTokenizations[] field contains the necessary information needed for cross-checking with the Mobile Wallet SDK for an already added card.

Start card tokenization flow

To start the tokenization flow, the client should make a request:

POST /digitalwallets/v1/profile/prepaid/cards/{cardId}/tokenizations

Start card tokenization request

{
  "walletType": "GOOGLE_PAY",
  "clientDeviceId": "WNkcsfZPiKfa5PrH3jilkQYT",
  "clientWalletAccountId": "40exmLiWV1iV55ZVstOAiMf7"
}

note

Please keep in mind that not all fields are necessary for the different Mobile Wallets. For more information about the required fields for specific Mobile Wallets, please refer to the API documentation.

The response from the request will contain the needed information that should be provided to the Mobile Wallet SDK

Card tokenization response

{
  "opaquePaymentCard": "eyJhbGciOiJBMjU2R0NNS1ciLCJjaGFub...(Base64 encoded data)",
  "cardNetwork": "CARD_NETWORK_VISA",
  "tokenProvider": "TOKEN_PROVIDER_VISA",
  "customer": {
    "address1": "Tsarigradsko Shose 73",
    "city": "Sofia",
    "countryCode": "BG",
    "postalCode": "1000",
    "name": "John Roger Smith",
    "mobile": "+1 1234567896"
  },
  "cardLastDigits": "4234"
}

After completion of the steps provided by the Mobile Wallet SDK, the client should receive information about the DPAN reference as a response as well as some additional information that needs to be provided back to Paysafe via request:

PATCH /digitalwallets/v1/profile/prepaid/cards/{cardId}/tokenizations

Complete card tokenization request

{
  "dpanRef": "DAPLMC00002125433c0c34a2821f4f86866e7576963baf8b",
  "walletId": "NMZlGi8-DezZZKaU06orvl0f",
  "walletType": "GOOGLE_PAY",
  "status": "COMPLETED"
}

warning

Due to the overall complexity of the process, some of the prerequisite steps for tokenizing a prepaid card in a mobile wallet were omitted. Тhey may include issuing and maintaining certificates, opening accounts, and more.