Tutorial: Acquiring Cards in MBanq Cloud API

This tutorial provides a step-by-step guide on acquiring cards within MBanq Cloud API. Acquiring cards allows users to link their cards from other financial institutions to their MBanq Cloud account, enabling convenient fund transfers. We'll walk through the process of registering an acquired card, deleting a card, listing registered cards, retrieving card keys, and performing push and pull transfers.

📘

API References for Endpoints in this tutorial:

• Acquiring Cards

Prerequisites

Before getting started, make sure you have the necessary credentials to access MBanq Cloud API.

Step 1: Register an Acquired Card

To register an acquired card, follow these steps:

1. Ensure you have the mandatory information required for registration:

   • clientId: The ID of the client associated with the card.
   • cardData: The encrypted data representing the acquired card.

2. Make a createExternalCard request, providing the necessary parameters:

   • clientId: The ID of the client.
   • cardData: The encrypted data of the acquired card.

   Example Request:

   GraphQL

   mutation {
     createExternalCard(input: {
       clientId: 1,
       cardData: "Iz64n14PAr7QK9U21bsTUODSfxcsj4w................"
     }) {
       officeId
       resourceId
       clientId
     }
   }
   

   Example Response:

   JSON

   {
     "data": {
       "createExternalCard": {
         "officeId": 1,
         "resourceId": 1,
         "clientId": 1
       }
     }
   }
   

Step 2: Delete an Acquired Card

To delete an acquired card, follow these steps:

1. Gather the required information:

   • clientId: The ID of the client associated with the card.
   • externalId: The ID of the acquired card.

2. Send a deleteExternalCard request with the necessary parameters:

   • clientId: The ID of the client.
   • externalId: The ID of the acquired card.

   Example Request:

   GraphQL

   mutation {
     deleteExternalCard(input: {
       clientId: 1,
       externalId: 1
     }) {
       officeId
       clientId
       resourceId
     }
   }
   

   Example Response:

   JSON

   {
     "data": {
       "deleteExternalCard": {
         "officeId": 1,
         "clientId": 1,
         "resourceId": 16
       }
     }
   }
   

Step 3: List Registered Acquired Cards

To list the registered acquired cards, follow these steps:

1. Make a select request to retrieve the list of registered cards.

   Example Request:

   GraphQL

   {
     ExternalCards {
       select {
         id
         clientId
       }
     }
   }
   

   Example Response:

   JSON

   {
     "data": {
       "ExternalCards": {
         "select": [
           {
             "id": 1,
             "clientId": 1
           }
         ]
       }
     }
   }
   

Step 4: Retrieve a Key for an Acquired Card

To retrieve the key associated with an acquired card, follow these steps:

1. Send a getExternalCardKey request.

   Example Request:

   GraphQL

   {
     getExternalCardKey {
       keyID
       key
       expiration
     }
   }
   

   Example Response:

   JSON

   {
     "data": {
       "getExternalCardKey": {
         "keyID": "RcYUPHjCCAomat-B5z54Cw",
         "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwczPOzqW2V1eo5Gqlg7xl0MXPIle5qDYelWgnejLHhENE...............",
         "expiration": "2021-07-17T04:01:27Z"
       }
     }
   }
   

Step 5: Perform a Push Transfer with an Acquired Card

To push funds from your MBanq Cloud account to an external bank card, follow these steps:

1. Build a createAndSubmitTransfer request, specifying the necessary details:

   • type: Transfer type, set to "CREDIT" for a push transfer.
   • paymentType: Payment type, set to "CARD".
   • currency: Currency code, e.g., "USD".
   • amount: Amount to be transferred.
   • creditor: Information about the external card holder, including the identifier and name.
   • debtor: Information about the MBanq Cloud account, including the identifier.

   Example Request:

   GraphQL

   mutation {
     createAndSubmitTransfer(input: {type: "CREDIT",  
          paymentType: "CARD",  
          currency: "USD",  
          amount: 10.00,  
          creditor: {  
            identifier: "EXTERNALCARD:888",  
            name: "alexa"  
          },  
          debtor: {  
            identifier: "ACCOUNT:9510010000009550"  
          },  
          reference: ["External Card PUSH"]  
        }) {  
          id  
        }  
      }
      
   

Example Response:
```json
{
  "data": {
    "createAndSubmitTransfer": {
      "id": "1"
    }
  }
}

Step 6: Perform a Pull Transfer with an Acquired Card

To pull funds from an external bank card into your MBanq Cloud account, follow these steps:

1. Construct a createAndSubmitTransfer request, providing the required parameters:

   • type: Transfer type, set to "DEBIT" for a pull transfer.
   • paymentType: Payment type, set to "CARD".
   • currency: Currency code, e.g., "USD".
   • amount: Amount to be transferred.
   • debtor: Information about the external card holder, including the identifier and name.
   • creditor: Information about the MBanq Cloud account, including the identifier.
   • reference: Additional reference information for the transfer.

   Example Request:

   GraphQL

   mutation {
     createAndSubmitTransfer(input: {
       type: "DEBIT",
       paymentType: "CARD",
       currency: "USD",
       amount: 10.00,
       debtor: {
         identifier: "EXTERNALCARD:888",
         name: "alexa"
       },
       creditor: {
         identifier: "ACCOUNT:9510010000009550"
       },
       reference: ["External Card PULL"]
     }) {
       id
     }
   }
   

   Example Response:

   JSON

   {
     "data": {
       "createAndSubmitTransfer": {
         "id": "1"
       }
     }
   }
   

Congratulations! You have successfully completed the acquiring card tutorial in MBanq Cloud API. You can now register acquired cards, perform push and pull transfers, and manage your funds seamlessly within the MBanq Cloud ecosystem.

Sandbox Card Acquiring Test Cards

PCI requires us and you to use Test Card Numbers when testing. You should never use a real Card Number in the Sandbox Environment. The following Card Numbers were randomly created, if they happen by chance to be a real Card Number, it is purely by coincidence only.