Cards Management

‍

Follow this Guide to issue your first Card using Inswitch APIs

Suggest Edits

Introduction

Here we describe how to use Inswitch APIs to start issuing prepaid credit cards.

To issue or link a card, an entity and a payment method have to be specified:

• The entity is the natural person or legal entity for wich the card will be assigned.
• The payment method represent an account within an entity's Wallet, and it is used to define from where the funds will be captured during the authorization process.

📘Issuing Cards

• Multiple cards can be linked to a single payment method
• Or each card can be linked to different payment method

Entity and Wallet creation

Authentication API is used to get an access_token required for {entities} and {wallet} APIs.

The Entities API is used to manage all the entities that use the services available in our platform. In Issuing scenarios, entities are used to register the card holders.

Wallets are the stored value accounts. The Wallet API enables you to launch and manage a digital money ecosystem and to support a range of operations. In Issuing scenarios, the Wallet provides the Balance from where the money will be deducted during the authorization process (card usage).

‍

API Examples

Create an entity

POST /entities

{
  "name": {
    "firstName": "Helio",
    "middleName": "Thomas",
    "lastName": "Mora"
  },
  "contact": {
    "phoneNumber": "89083200",
    "email": "test@gmail.com",
    "firstName": "string",
    "lastName": "string",
    "postalAddress": {
      "addressLine1": "string",
      "city": "El Crucero",
      "stateProvince": "Managua",
      "country": "NI"
    }
  },
  "idDocuments": [
    {
      "idType": "nationalId",
      "idNumber": "0012603022205A",
      "issuerCountry": "NI"
    }
  ],
  "dateOfBirth": "2008-09-28T19:49:45",
  "occupation": "string",
  "gender": "m",
  "entityProfileData": [
    {
      "key": "walletType",
      "value": "Normal"
    }
  ],
  "entityType": "naturalPerson"
}

‍

201 - Created

{
  "entityId": "1004",
  "creationDate": "2021-08-19T16:58:38.091Z",
  "users": [],
  "name": {
    "firstName": "Helio",
    "middleName": "Thomas",
    "lastName": "Mora"
  },
  "contact": {
    "phoneNumber": "89083200",
    "email": "test@gmail.com",
    "firstName": "string",
    "lastName": "string",
    "postalAddress": {
      "addressLine1": "string",
      "city": "El Crucero",
      "stateProvince": "Managua",
      "country": "NI"
    }
  },
  "idDocuments": [
    {
      "idType": "nationalId",
      "idNumber": "0012603022205A",
      "issuerCountry": "NI"
    }
  ],
  "dateOfBirth": "2008-09-28T19:49:45",
  "occupation": "string",
  "gender": "m",
  "entityProfileData": [
    {
      "key": "walletType",
      "value": "Normal"
    }
  ],
  "metadata": [],
  "entityType": "naturalPerson",
  "version": 0,
  "parentId": null,
  "entityStatus": "active",
  "lockReason": null
}

‍

Create a Wallet and a Payment Method

POST /wallets

{
  "entityId": "1004",
  "walletStatus": "active",
  "walletProfileData": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "metadata": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

‍

201 - Created

{
    "entityId": "1004",
    "isBatch": false,
    "lockReason": "",
    "metadata": [
        {
            "key": "string",
            "value": "string"
        }
    ],
    "walletId": "1134",
    "walletStatus": "active"
}

‍

POST wallets/{walletId}/paymentmethods

{
    "paymentMethodAlias":"Account Issuing BR",
    "paymentMethodType":"emoney-brl"
}

‍

201 - Created

{
    "paymentMethodAlias": "Account Issuing BR",
    "paymentMethodData": {
        "ACCOUNT_ID": "1000658",
        "CURRENCY": "BRL"
    },
    "paymentMethodId": "3631373033352D313030382D32313032",
    "paymentMethodLinkData": [],
    "paymentMethodType": "emoney-brl",
    "paymentMethodTypeClass": "emoney",
    "paymentMethodTypeCountry": "BR",
    "paymentMethodTypeCurrency": "BRL",
    "paymentMethodTypeDesc": "eMoney BRL",
    "paymentMethodTypeDirection": null,
    "paymentMethodTypeImageUrl": null,
    "paymentMethodTypeStatus": "available",
    "walletId": "1134"
}

‍

Cards lifecycle

This section describes the main operations involved in the Cards issuing process using the Cards API.

Create Card

This operation creates a new card linked to the cardholder user (formally defined as an "entity") and to a wallet (referenced by a Payment Method Reference Id). The wallet is the stored value account for the issued card. {entity} and {paymentMethodReference} shall be created in advance as described in previous topics.

This example represents the creation of a Virtual Card.

‍

Virtual Cards

Virtual Cards are issued in realtime.

POST /cards

{
  "type": "virtual",
  "productId": "Issuing_product_02",
  "entity": "1004",
  "paymentMethodReference": "3330363633312D313030302D31333634",
}

‍

201 - Created

{
    "cardIdentifier": "97e9ed90-8ca0-4e3e-8195-a8fe0bef8e2b",
    "entityId": "1004",
    "status": "assigned",
    "issueDate": "2022-02-03",
    "type": "virtual",
    "productId": "Issuing_product_02",
    "brand": "Mastercard",
    "currency": "BRL",
    "expiry_mm_yyyy": "12/2025",
    "last4": "6691",
    "paymentMethodReference": "3330363633312D313030302D31333634",
    "maskedPan": "231045******6691"
}

‍

‍

When a physical card is requested, the API returns a card Identifier with status: "ordered". There "ordered" status means the personalization is in progress and card details (like PAN) are not assigned yet).

Once the card details are defined by Inswitch and the order sent to the manufacturer, the card information will be set and the status updated to "assigned".

POST /cards

{
    "type": "physical",
    "productId": "NominatedCard",
    "entity": "205",
    "paymentMethodReference": "3435353335372D313033322D32303033",
    "initialPin":"3108",
    "cardholderName":"Juan Perez"   
}

‍

201 - Created

{
    "cardIdentifier": "1fe4d55b-8c6c-4de9-8ec9-7d953934865c",
    "entityId": "205",
    "status": "ordered",
    "issueDate": "2022-08-31",
    "type": "physical",
    "productId": "NominatedCard",
    "brand": "mastercard",
    "currency": "MXN",
    "paymentMethodReference": "3435353335372D313033322D32303033"
}

‍

Activate a Card

By default, the cards are not created in "Active" status. The activeCard operation is required to enable a card for usage and, in case of virtual cards, to be able to retrieve the expanded card details (like PAM and CVV).

‍

Retrieve the Card Details

The Query Card operation is used to retrieve card details.

‍

GET /cards/{cardReference}/

curl --location --request GET '{{baseUrl}/issuing/cards/{{cardReference}}/' \
--header 'accept: application/json' \
--header 'apikey: {{apikey}}' \
--header 'X-User-Bearer: Bearer {{access_token}}' \

‍

200 OK

{
    "cardIdentifier": "508fba61-a402-48f6-8d7c-bbb6d840b5d6",
    "entityId": "642",
    "status": "active",
    "issueDate": "2022-06-20",
    "type": "virtual",
    "productId": "VirtualCard",
    "brand": "mastercard",
    "currency": "MXN",
    "expiry_mm_yyyy": "07/2023",
    "last4": "5405",
    "paymentMethodReference": "3737323937312D313030302D31303030",
    "maskedPan": "523857******5405"
}

‍

Virtual Cards

In case of Virtual Cards, a separated endpoint is offered to allow client to retrieve sensitive card details on behalf of cardholders, to display its PAN and CVV in a secured channel (i.e. Mobile Wallet).

GET /cards/{cardReference}/

curl --location --request GET '{{virtualCardsUrl}/issuing/cards/{{cardReference}}/' \
--header 'accept: application/json' \
--header 'apikey: {{apikey}}' \
--header 'X-Expand: card' \

‍

200 OK

{
    "cardIdentifier": "508fba61-a402-48f6-8d7c-bbb6d840b5d6",
    "entityId": "642",
    "status": "active",
    "issueDate": "2022-06-20",
    "type": "virtual",
    "productId": "VirtualCard",
    "brand": "mastercard",
    "currency": "MXN",
    "expiry_mm_yyyy": "07/2023",
    "last4": "5405",
    "paymentMethodReference": "3737323937312D313030302D31303030",
    "maskedPan": "523857******5405",
    "expanded_card_info": {
        "cardInfoEncrypted": false,
        "pan": "5238571111115405",
        "cvv": "123"
    }
}

‍

Card Security Management

Virtual Cards: Regenerate CVV

This feature allows customers to add an extra level of security to Virtual Cards by generating a new CVV code. When this operations is called, Iswitch will generate a new CVV invalidating the previous one. The new CVV will not be returned by this operation; the only available option for retrieving the updated CVV is by calling the Query operation (where the full card details are returned).

‍

Physical Cards: set PIN

This feature allows customers set/update the PIN at any time for Physical Cards.

‍

‍

PUT /cards/{cardReference]/pin

{
 "pin": "1008"
}

‍

204 - No content

Block/unBlock a Card

Block and Unblock operations are useful to reject or pause the authorizations temporally. The blocked status is reversible by using the unblock operation.

Card blocking operation supports a pre-defined list of reason Codes to allow both user or issuer bloking requests:

📘When a Card is blocked

• Status "blocked" and blocking details are returned in the query card details endpoint.
• The operation is reversible by calling the unBlock endpoint.

In the unBlock operation an unbloking reason code is also supported, in order to specify who is requesting the operation:

‍

‍

Disable a Card

The disableCard operation is used to disable a card definitely (it is not reversible).

‍

‍

‍

‍