Card creation

PEX provides multiple mechanisms to support the creation of cards for remote workforces including plastic cards (with and without EMV) to virtual cards to digital cards (tokens & wallets).

We provide both API endpoints to manage all of your cardholder accounts, as well as webhooks to receive notifications when things change on each account.

Ordering

When a PEX customer wants to create cardholder accounts they place an order. All cardholder accounts are created asynchronously. When an order is placed via the API an ordernumber is returned. This ordernumber can be used for subsequent API calls to obtain the status of the order as accounts are provisioned, as well as when receiving webhooks from PEX. For more information see the API documentation for the /Card/CreateAsync endpoint

Tracking

Orders for plastic cards are fulfilled nightly by PEX embossing partners. When a partner provides PEX with order tracking information a webhook is triggered to update the status of the order in the customer's system.

Activation

Once a card is received by the cardholder it must be activated prior to use. In order to activate the card PEX provides a card activation endpoint on the API. For more information see the API documentation for the /Card/Activate/{id} endpoint

Virtual cards

IMPORTANT: Virtual card support is an advanced feature. PEX must enable this feature for your account before you can use it. If you wish to use this feature, please contact your PEX Account Manager or PEX Client Services for set up.

Along with standard plastic (EMV chip and non-EMV chip) cards PEX also offers virtual cards. Virtual cards are used for online purchases and are very useful in many scenarios.

Note: PEX virtual cards may not be added in digital wallets like Apple Pay

Creation

PEX provides a virtual card creation endpoint that allows customer apps to request a virtual card. Unlike plastic cards when a virtual card is created there is no plastic which is embossed. Virtual cards can be activated immediately. The virtual card endpoint also allows the customer app to specify how much the card should be funded at the moment of creation. For more information see the API documentation for the /VirtualCard/Order endpoint

Receiving card data

PEX allows customers to receive card data for their virtual cards. In order to receive this secure data, the customer app must implement an endpoint to which a webhook will be sent once the virtual card is created.

Tokens and Wallets

IMPORTANT: Tokenization and wallet support is currently in preview. PEX must enable this feature for your account before you can use it. If you wish to use this feature, please contact your PEX Account Manager or PEX Client Services for set up.

PEX offers the ability to issue tokens for cards created on the PEX platform. It is the decision of each business whether a particular cardholder can have a token issued to them. Tokens are used by mobile wallet providers (Apple Pay & Google Pay) to securely store "copies" of a PEX card on a user's device as well as merchants to store cards on file.

There are 2 main scenarios for managing tokens within PEX. A customer can predefine whether a particular cardholder is permitted to tokenize their card or decide in real-time whether a token should be issued (referred to as remote provisioning). If a customer does not want to implement remote provisioning for tokens they must provide PEX with contact information in order to perform additional step-up identity verification of cardholders as required by wallet providers.

Terminology

The following terminology is used within this guide. These terms will help you understand the various components of the tokenization workflow.

Provisioning flow

The diagram below illustrates a high level basic flow of provisioning a token. This flow is for customers who choose to participate in the provisioning process for whom PEX does not have adequate contact information to deliver additional identity verification codes (OTP). This process is known as the remote-provisioning process.

If a customer chooses to participate in the remote provisioning process they must support 3 parts of the process for which PEX will send webhooks and expose an API:

1. Decision to allow a token.
2. Send OTP code to cardholders for step up.
3. Provide a call center where a cardholder can call to identify themselves.

Deciding to allow a token

Request sent by PEX

POST https://api.pexcustomer.com/token/provision

{
    "AcctId": 0,
    "BusinessAcctId": 0,
    "ReferenceId": "DNIT-0013234324325436534",
    "Last4CardNumber": "string",
    "DeviceInfo":{
          "Name":"string"
     }
}

Sample customer response

200=Approve 4XX=Decline

{
  "AcctId": 0,
  "BusinessAcctId": 0,
  "Last4CardNumber": "string",
  "Contacts": [
      {
        "ContactType":"email", //valid values email, call-center, sms
        "ContactId": "string", //This will be sent back on the otp message
        "ContactValue":"string"
      }
    ]
}

Validation: Response models will be validated, if the customer endpoint responds with invalid contact types, PEX will return back to the mobile wallet provider the pre-configured default call center number.

Masking: PEX recommends masking the contact data in the ContactValue attribute, in order to enhance security.

Allowing a cardholder to obtain a token for their card and store the card in their mobile device exposes the business to additional fraud risk, therefore it is important to consider when a token should be issued and when it should not be issued. Allowing a token to be issued can be considered a permission to make a copy of the card. Therefore it may not be desirable under some circumstances to have multiple copies of the card. PEX supports controlling tokenization at the business and individual cardholder levels for a higher level of granularity.

If a customer chooses to participate in remote provisioning, they must provide PEX with a remote provisioning endpoint. This endpoint will ingest token provisioning data and will return step-up options for a particular cardholder. This endpoint must be provided to PEX when the account is being configured for remote provisioning.

The following data is sent to the remote provisioning endpoint by PEX. This data should be used by the customer endpoint to determine whether the cardholder should be issued a token or not.

Token Provisioning Request Model

Token Provisioning Response Model

Step up

POST Request sent by PEX to deliver OTP

POST https://api.pexcustomer.com/token/otp-code
Authorization: {shared secret}

{
    "AcctId": 0,
    "BusinessAcctId": 0,
    "Last4CardNumber": "string",
    "ContactId":"string", //this id was provided by the customer's provisioning endpoint
    "Passcode": "string",
    "Expiration": "yyyy-mm-ddThh:mm:ss" //this is an optional field, and may not be sent by token service provider
}

Step up is the the process used by wallet providers to perform additional identity verification on the cardholder attempting to obtain a token. The step-up may be requested by the wallet service provider, or by PEX. In either case the customer app must return an enumeration of contact information to be presented to the cardholder. The cardholder will then choose from the options provided. A call center phone number must be provided in order to give the cardholder an option to call for their token activation.

If the cardholder chooses the email step-up mechanism PEX will send the Token Service Provider (VISA) generated One Time Passcode to the customer app's specified endpoint. Therefore the customer must provide PEX with an endpoint capable of ingesting the OTP data and sending that data to the cardholder.

In order to properly identify which contact method was selected the customer can specify an id to each of the available contact methods when responding to the remote provisioning call. PEX will then send the same id to indicate the cardholder selection.

Call center

POST https://coreapi.pexcard.com/v4/TokenProvisioning/{AcctId}/Activation
Authorization: token {token}

{
    "ReferenceId":"DNIT-0013234324325436534",
    "ActivationNote":"verified via call center"
}

When participating in remote provisioning flows the customer must provide a call center option for their cardholders to verify their identity on the phone. If a cardholder calls to verify their identity and the customer call center decides that a token should be issued for the cardholder, the call center app will need to notify PEX of that decision by calling the PEX token activation API endpoint. This endpoint will queue the token for activation, and the token will be activated within the Token Service Provider (VISA) within 24 hours.

Token Activation Request Model

PEX Verifications

Prior to calling the customer remote provisioning endpoint PEX will validate the following information:

• Valid card number, which will be used to look up the acctId
• Valid expiration date
• Valid CVV2 code
• The business must have tokenization enabled

If any of the above validations fails PEX will not call the customer endpoint.

Token related webhooks

POST POST https://api.pexcustomer.com/token/callback
Authorization: {shared secret}

{
  "CallbackTime": "2020-08-22T12:20:53.7335395+03:00",
  "Data": {
    "AcctId": 123213234,
    "CardId": 123456,
    "ReferenceId": "DNIT-0013234324325436534",
    "Last4CardNumber": "1212",
    "Last4TokenNumber": "5523",
    "TokenExpirationDate": "2020-08-22",
    "DeviceName": "Joe's iPhone",
    "WalletName": "Apple Pay"
  }
}

In order to notify the customers apps of changes to their cardholder tokens PEX provides token related webhooks. For general information on webhooks, please see the the webhooks section.

Customers must subscribe to the card status webhooks in order to be notified when a card is tokenized.

Since call-center based token activation does not occur in real-time this webhook can be used by the customer app to notify their cardholder that their token is ready to be used at a merchant terminal.

Failure handling

PEX handles customer failures in he following situations:

• If the customer does not respond to the remote provisioning call within 2,000 milliseconds PEX will use the rules configured at the business and the cardholder to approve/decline the token provisioning request
• If the customer send-otp endpoint does not respond within 10,000 milliseconds PEX will make 3 attempts to deliver the OTP after which point we will not make any further attempts.

In order to provide a reliable fallback mechanism customers can configure their desired outcomes in the event that they do not respond to a remote provisioning request.

PEX provides 3 settings which can be set the business and cardholder accounts to determine the appropriate action in the even that the customer remote decisioning endpoint does not respond. The following diagram helps to clarify the final outcome of the provisioning request to the token service provider under various failure scenarios:

Frequently asked questions

For more information on managing your digital wallets please also refer to the digital wallet section of the admin guide.