Cards Management
Follow this Guide to issue your first Card using Inswitch APIs
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
{
"name": {
"firstName": "Helio",
"middleName": "Thomas",
"lastName": "Mora"
},
"contact": {
"phoneNumber": "89083200",
"email": "[email protected]",
"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"
}
{
"entityId": "1004",
"creationDate": "2021-08-19T16:58:38.091Z",
"users": [],
"name": {
"firstName": "Helio",
"middleName": "Thomas",
"lastName": "Mora"
},
"contact": {
"phoneNumber": "89083200",
"email": "[email protected]",
"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
{
"entityId": "1004",
"walletStatus": "active",
"walletProfileData": [
{
"key": "string",
"value": "string"
}
],
"metadata": [
{
"key": "string",
"value": "string"
}
]
}
{
"entityId": "1004",
"isBatch": false,
"lockReason": "",
"metadata": [
{
"key": "string",
"value": "string"
}
],
"walletId": "1134",
"walletStatus": "active"
}
{
"paymentMethodAlias":"Account Issuing BR",
"paymentMethodType":"emoney-brl"
}
{
"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.
{
"type": "virtual",
"productId": "Issuing_product_02",
"entity": "1004",
"paymentMethodReference": "3330363633312D313030302D31333634",
}
{
"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"
}
Named Physical Cards
Similar to Virtual Cards, a personalized (named) physical Cards is ordered using the POST /cards API by including some special fields into the request:
| Field | Description | Mandatory | Value |
|---|---|---|---|
| cardholderName | Name to be printed in the card | Yes | alphabetic (min 2 char, max 20 chars) |
| initialPin | Used in markets where offline PIN is applicable (like in Mexico) | Yes | 4 digits. - Repeating or Sequential Digits are not allowed (i.e. "2345","7777", "6543", etc.) |
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".
{
"type": "physical",
"productId": "NominatedCard",
"entity": "205",
"paymentMethodReference": "3435353335372D313033322D32303033",
"initialPin":"3108",
"cardholderName":"Juan Perez"
}
{
"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.
curl --location --request GET '{{baseUrl}/issuing/cards/{{cardReference}}/' \
--header 'accept: application/json' \
--header 'apikey: {{apikey}}' \
--header 'X-User-Bearer: Bearer {{access_token}}' \
{
"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).
curl --location --request GET '{{virtualCardsUrl}/issuing/cards/{{cardReference}}/' \
--header 'accept: application/json' \
--header 'apikey: {{apikey}}' \
--header 'X-Expand: card' \
{
"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.
| Field | Description | Mandatory | Value |
|---|---|---|---|
| pin | New pin to be set cardholders for their physical cards. | Yes | 4 digits. - Repeating or Sequential Digits are not allowed (i.e. "2345","7777", "6543", etc.) |
{
"pin": "1008"
}
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:
| Blocking reasonId | Description |
|---|---|
| 1 | Card lost |
| 2 | Card stolen |
| 3 | Pending Query |
| 5 | Card Inactive |
| 7 | Suspected Fraud |
| 8 | Card replaced |
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:
| Unblocking reasonId | Description |
|---|---|
| 1 | Requested by User |
| 2 | Requested by Issuer |
Disable a Card
The disableCard operation is used to disable a card definitely (it is not reversible).
Updated almost 2 years ago