Search Overlay
Searchbox clear search filters ESC
Filter PreferencesClear

No results found

Overview

asdf

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

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

Prepaid_Cards_Card_Creation.png

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: 

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

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

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

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

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

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

{
  "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 PENDING CANCELLED SUSPENDED APPLIED DIGITAL REJECTED LOCKED EXPIRED ISSUED LOST DAMAGED

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. Other statuses can be applied only to PHYSICAL cards - LOST, DAMAGED, and others.

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.

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

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

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

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

{
  "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 Wallets such as Google Pay, Apple Pay and Samsung Pay

Card tokenization simplified flow

Prepaid_Cards_Card_Tokenization.png

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.

  • Invoking GET request to /digitalwallets/v1/profile/prepaid/cards?include=TOKENIZATIONS or /digitalwallets/v1/profile/prepaid/cards/{cardId}?include=TOKENIZATIONS endpoints. Which will return a response containing:
{
  "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 With request BODY similar to:

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

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

{
  "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 to PATCH /digitalwallets/v1/profile/prepaid/cards/{cardId}/tokenizations

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

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.

On this Page