Banking API

The Sandbox gives you an opportunity to test some basic card management functions of SmartVista suite — register customers, create accounts, issue virtual cards, set card limits, transfer funds, etc. The first steps in the banking Sandbox should be:

  1. Register a new customer with registerCustomer request. This request also creates an account for the customer. You can create as many customers as you want. But only one account per customer can be created in the Sandbox — this restriction is added to simplify the Sandbox logic. In a real project you would be able to create as many accounts per customer as required for your business.
  2. Issue a new virtual card with createVirtualCard for a customer’s accounts. You can issue as many cards as you want. The Sandbox cards are issued in active state and are instantly ready for use.

Now you can test the following features (in no particular order):

  • block and unblock the issued cards with blockCard and changeCardState request
  • deposit funds on issued cards with creditCard request
  • make P2P card transfers with p2pTransfer request (create at least two cards to transfer funds between them)
  • manage card limits with getCardLimits and changeCardLimit requests
  • get card data with getCardData request
  • get card transaction history with getTransactions request (generate some transactions first)

You can download Postman collection of API requests, to test some basic card management functions of SmartVista suite

Please check the information for each request below, including examples with short descriptions of what should be changed to make these requests yourself. Use links to detailed documentation for additional information.

Credentials

Use credentials from a Sandboxes page to make API calls.

Common characteristics

All requests are HTTP POST requests.

Content type for both requests and responses is application/json

Banking Scenario

Create Customer

Documentation

https://dev.bpcbt.com/v1/apigate/ws/rest/registerCustomer

This is where the Sandbox process begins. registerCustomer registers a new customer in SmartVista and creates an account.


The following parameters with their values should be transferred for a customer creation in the Sandbox:

  • institutionId you got the value in the e-mail after the registration
  • agent_number same as institutionId
  • customer_number any text. Have to be unique in your sandbox project.
  • product_id you got the value in the e-mail after the registration
  • start_date any date in the past. «YYYY-MM-DD» format
  • service_id_acc you got the value in the e-mail after the registration
  • surname firstName secondName email mobile_phone region city street house apartment Customer data parameters. Can be any text
  • country_code ISO 3166-1 numeric country code

Request


    {
      "productName": "CRCU1001",
      "parameters":  [
          {
            "name": "institutionId",
            "value": "3006"
          },
          {
            "name": "agent_number",
            "value": "3006"
          },
          {
            "name": "customer_number",
            "value": "3006P_0000003"
          },
          {
            "name": "product_id",
            "value": "70000304"
          },
          {
            "name": "start_date",
            "value": "2021-09-06"
          },
          {
            "name": "service_id_acc",
            "value": "70000305"
          },
          {
            "name": "surname",
            "value": "Smith"
          },
          {
            "name": "firstName",
            "value": "John"
          },
          {
            "name": "secondName",
            "value": "A."
          },
          {
            "name": "email",
            "value": "johnsmith@email.com"
          },
          {
            "name": "mobile_phone",
            "value": "319220977338"
          },
          {
            "name": "country_code",
            "value": "528"
          },
          {
            "name": "region",
            "value": "BJ"
          },
          {
            "name": "city",
            "value": "Utrecht"
          },
          {
            "name": "street",
            "value": "Papendorpseweg"
          },
          {
            "name": "house",
            "value": "99"
          },
          {
            "name": "apartament",
            "value": "1"
          },
		      {
            "name": "postal_code",
            "value": "3528"
          }
        ]
    }
    

    curl --location --request POST 'https://dev.bpcbt.com/v1/apigate/ws/rest/registerCustomer' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic ZXVnZW5lMTIxMzEyMDp0dGhtdldcNg==' \
    --data-raw '{
      "productName": "CRCU1001",
      "parameters":  [
          {
            "name": "institutionId",
            "value": "3006"
          },
          {
            "name": "agent_number",
            "value": "3006"
          },
          {
            "name": "customer_number",
            "value": "3006P_0000002"
          },
          {
            "name": "product_id",
            "value": "70000304"
          },
          {
            "name": "start_date",
            "value": "2021-09-06"
          },
          {
            "name": "service_id_acc",
            "value": "70000305"
          },
          {
            "name": "surname",
            "value": "Smith"
          },
          {
            "name": "firstName",
            "value": "John"
          },
          {
            "name": "secondName",
            "value": "A."
          },
          {
            "name": "email",
            "value": "johnsmith@email.com"
          },
          {
            "name": "mobile_phone",
            "value": "319220977338"
          },
          {
            "name": "country_code",
            "value": "528"
          },
          {
            "name": "region",
            "value": "BJ"
          },
          {
            "name": "city",
            "value": "Utrecht"
          },
          {
            "name": "street",
            "value": "Papendorpseweg"
          },
          {
            "name": "house",
            "value": "99"
          },
          {
            "name": "apartament",
            "value": "1"
          },
		      {
            "name": "postal_code",
            "value": "3528"
          }
        ]
    }'
    

Response


    {
      "customerNumber": "3006P_0000003",
      "accountNumber": "3006978700000000108"
    }
    

Create Virtual Card

Documentation

https://dev.bpcbt.com/v1/apigate/ws/rest/createVirtualCard

Request

Creates a virtual card for a registered customer. Use registerCustomer to create a customer and an account if you haven’t done it yet.
Replace first 6 digits in cardIdentification.cardNumber with Visa BIN from an email you got after the registration. Use customerId you provided to registerCustomer request and accountNumber you got in registerCustomer response.


    {
        "cardIdentification": {
          "cardNumber": 4140050000000000,
          "phoneNumber": "319220977337",
          "customerId": "3006P_0000002"
        },
        "virtualCardIdentification": {
          "expDate": 202201,
          "productType": "5A"
        },
        "amount": 0,
        "currency": 978,
        "accountNumber": "3006978700000000108",
        "deliveryMethod": "WS"
    }
    

    curl --location --request POST 'https://dev.bpcbt.com/v1/apigate/ws/rest/createVirtualCard' \
	--header 'Content-Type: application/json' \
	--header 'Authorization: Basic ZXVnZW5lMTIxMzEyMDp0dGhtdldcNg==' \
	--data-raw ' {
        "cardIdentification": {
          "cardNumber": 4140050000000000,
          "phoneNumber": "319220977337",
          "customerId": "3006P_0000002"
        },
        "virtualCardIdentification": {
          "expDate": 202201,
          "productType": "5A"
        },
        "amount": 0,
        "currency": 978,
        "accountNumber": "3006978700000000108",
        "deliveryMethod": "WS"
    }'
    

Response


    {
	    "virtualCardIdentification": {
	        "cardNumber": "4140050021658271",
	        "cardId": "100000000873",
	        "expDate": "202301",
	        "productType": "5A"
	    }
	}
    

Get Card Limits

Documentation

https://dev.bpcbt.com/v1/apigate/ws/rest/getCardLimits

Get limits for a specific card. The limits set is defined for the card product and is predefined in the Sandbox. Initially the limits for a specific card are inherited from the product setting. You can change the limit values for a specific card with changeCardLimit
Take cardId from createVirtualCard response.

Request


    {
        "cardIdentification": {
          "cardId": 100000000873
        }
    }
    

    curl --location --request POST 'https://dev.bpcbt.com/v1/apigate/ws/rest/getCardLimits' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic ZXVnZW5lMTIxMzEyMDp0dGhtdldcNg==' \
    --data-raw '{
        "cardIdentification": {
          "cardId": 100000000873
        }
    }'
    

Response


    {
        "limits": [
            {
                "name": "LMTP0111",
                "value": 999999999999,
                "cycleType": 0,
                "cycleLength": 1,
                "currency": 978,
                "currentValue": 0,
                "limitExceptions": []
            },
            {
                "name": "LMTP0112",
                "value": 999999999999,
                "cycleType": 3,
                "cycleLength": 1,
                "currency": 978,
                "currentValue": 0,
                "limitExceptions": []
            },
            {
                "name": "LMTP0108",
                "value": 999999999999,
                "cycleType": 3,
                "cycleLength": 1,
                "currency": 978,
                "currentValue": 0,
                "limitExceptions": []
            },
            {
                "name": "LMTP0110",
                "value": 999999999999,
                "cycleType": 3,
                "cycleLength": 1,
                "currency": 978,
                "currentValue": 0,
                "limitExceptions": []
            },
            {
                "name": "LMTP0109",
                "value": 999999999999,
                "cycleType": 0,
                "cycleLength": 1,
                "currency": 978,
                "currentValue": 0,
                "limitExceptions": []
            },
            {
                "name": "LMTP0107",
                "value": 999999999999,
                "cycleType": 0,
                "cycleLength": 1,
                "currency": 978,
                "currentValue": 0,
                "limitExceptions": []
            }
        ]
    }
    

Change Card Limit

Documentation

https://dev.bpcbt.com/v1/apigate/ws/rest/changeCardLimit

Change the limit values for a specific card. The limits set is defined for the card product and is predefined in the Sandbox. Initially the limits for a specific card are inherited from the product setting. Use getCardLimits to get limits names.
Take cardId from createVirtualCard response and limit.name from getCardLimits response.

Request


    {
        "cardIdentification": {
          "cardId": 100000000873
        },
        "limit": {
          "name": "LMTP0112",
          "value": 13000000,
          "cycleType": 4,
          "cycleLength": 1
        }
    }
    

    curl --location --request POST 'https://dev.bpcbt.com/v1/apigate/ws/rest/changeCardLimit' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic ZXVnZW5lMTIxMzEyMDp0dGhtdldcNg==' \
    --data-raw '{
        "cardIdentification": {
          "cardId": 100000000873
        },
        "limit": {
          "name": "LMTP0112",
          "value": 13000000,
          "cycleType": 4,
          "cycleLength": 1
        }
    }'
    

Response


    {
        "responseCode": "00",
        "processingCode": "710000",
        "systemTraceAuditNumber": 620394,
        "localTransactionDate": "2021-09-23T14:35:24"
    }
    

Get Card Data

Documentation

https://dev.bpcbt.com/v1/apigate/ws/rest/getCardData

Returns you the detailed info about the cards you created. Can be used after creating a card with createVirtualCard.
Take cardId from createVirtualCard response.

Request


    {
        "cardIdentification": {
          "cardId": 100000000873
        }
    }
    

    curl --location --request POST 'https://dev.bpcbt.com/v1/apigate/ws/rest/getCardData' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic ZXVnZW5lMTIxMzEyMDp0dGhtdldcNg==' \
    --data-raw '{
        "cardIdentification": {
          "cardId": 100000000873
        }
    }'
    

Response


    {
        "cardData": {
            "cardNumber": "4140050021658271",
            "expiryDate": "202301",
            "cardId": "100000000873",
            "hotCardStatus": 0,
            "cardTypeName": "VISA - PLUS",
            "embossedName": "GENERAL POOL",
            "customerId": "3006P_0000003",
            "personId": "3006P_0000002",
            "pinDenialCounter": 0,
            "plasticNumber": 1,
            "hotCardStatusDescription": "VALID CARD",
            "cardIsPrimary": false,
            "cardBindToCustomer": false,
            "customerIsCardholder": false,
            "accounts": [
                {
                    "number": "3006978700000000108",
                    "accountType": 1,
                    "currency": 978,
                    "currencyAlphaCode": "EUR",
                    "balance": 0,
                    "creditLimit": 0,
                    "customerId": "3006P_0000003",
                    "defaultAccount": true
                }
            ],
            "customParameters": []
        }
    }
    

Block Card

Documentation

https://dev.bpcbt.com/v1/apigate/ws/rest/blockCard

Block card. Within the Sandbox a card has to be in active status (status code '0') to be blocked. You can get a card status code with getCardData request.
Take cardId from createVirtualCard response.

Request


    {
        "cardIdentification": {
          "cardId": 100000000873
        },
        "hotCardStatus": 6
    }
    

    curl --location --request POST 'https://dev.bpcbt.com/v1/apigate/ws/rest/blockCard' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic ZXVnZW5lMTIxMzEyMDp0dGhtdldcNg==' \
    --data-raw '{
        "cardIdentification": {
          "cardId": 100000000873
        },
        "hotCardStatus": 6
    }'
    

Response


    {
        "responseCode": "00",
        "processingCode": "910000",
        "systemTraceAuditNumber": 620397,
        "localTransactionDate": "2021-09-23T14:37:36"
    }
    

Change Card Status

Documentation

https://dev.bpcbt.com/v1/apigate/ws/rest/changeCardStatus

Change card status. In the Sandbox you can change card status only for blocked cards (card status code is '6'). You can get the card status code with getCardData request. To change the card status from '0' to '6' (blocked) use blockCard request.
Take cardId from createVirtualCard response.

Request


    {
        "cardIdentification": {
          "cardId": 100000000873
        },
        "hotCardStatus": 0
    }
    

    curl --location --request POST 'https://dev.bpcbt.com/v1/apigate/ws/rest/changeCardStatus' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic ZXVnZW5lMTIxMzEyMDp0dGhtdldcNg==' \
    --data-raw '{
        "cardIdentification": {
          "cardId": 100000000873
        },
        "hotCardStatus": 0
    }'
    

Response


    {
        "responseCode": "00",
        "processingCode": "950000",
        "systemTraceAuditNumber": 620398,
        "localTransactionDate": "2021-09-23T14:38:26"
    }
    

Credit Card

Documentation

https://dev.bpcbt.com/v1/apigate/ws/rest/creditCard

Deposit funds to the card.
Take cardIdentification.cardNumber from createVirtualCard response.

Request


    {
        "cardIdentification": {
            "cardNumber": 4140050021658271,
            "expDate": 202201
        },
        "amount": 10000,
        "currency": 978
    }
    

    curl --location --request POST 'https://dev.bpcbt.com/v1/apigate/ws/rest/creditCard' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic ZXVnZW5lMTIxMzEyMDp0dGhtdldcNg==' \
    --data-raw '{
        "cardIdentification": {
            "cardNumber": 4140050021658271,
            "expDate": 202201
        },
        "amount": 10000,
        "currency": 978
    }'
    

Response


    {
        "responseCode": "00",
        "processingCode": "270000",
        "systemTraceAuditNumber": 620399,
        "localTransactionDate": "2021-09-23T14:39:15",
        "rrn": "000000154798",
        "authorizationIdResponse": "154798",
        "paymentSpecificData": {}
    }
    

P2P Transfer

Documentation

https://dev.bpcbt.com/v1/apigate/ws/rest/p2pTransfer

p2pTransfer from a card to a card. Both cards must be created in the Sandbox before using the request.
Take sourceCardIdentification.cardNumber and destinationCardIdentification.cardNumber from createVirtualCard response.

Request


    {
        "sourceCardIdentification": {
          "cardNumber": 4140050021658271,
          "expDate": 202201
        },
        "destinationCardIdentification": {
          "cardNumber": 4123940050955625
        },
        "amount": 1000,
        "currency": 978,
        "senderReceiverInfo": {
          "senderName": "Tor, John",
          "senderAddress": "New York, USA"
        },
        "pointOfServiceDataCode": 810
    }
    

    curl --location --request POST 'https://dev.bpcbt.com/v1/apigate/ws/rest/p2pTransfer' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic ZXVnZW5lMTIxMzEyMDp0dGhtdldcNg==' \
    --data-raw '{
        "sourceCardIdentification": {
          "cardNumber": 4140050021658271,
          "expDate": 202201
        },
        "destinationCardIdentification": {
          "cardNumber": 4123940050955625
        },
        "amount": 1000,
        "currency": 978,
        "senderReceiverInfo": {
          "senderName": "Tor, John",
          "senderAddress": "New York, USA"
        },
        "pointOfServiceDataCode": 810
    }'
    

Response


    {
        "responseCode": "00",
        "processingCode": "490000",
        "systemTraceAuditNumber": 620400,
        "localTransactionDate": "2021-09-23T14:40:05",
        "rrn": "000000154799",
        "authorizationIdResponse": "154801",
        "paymentSpecificData": {}
    }
    

Get Transactions

Documentation

https://dev.bpcbt.com/v1/apigate/ws/rest/getTransactions

Get transactions history for the specific card.
Take cardId from createVirtualCard response.

Request


    {
        "cardIdentification": {
          "cardId": 100000000873
        },
        "period": {
              "start": "2020-04-01",
              "end": "2022-05-01"
            }
    }
    

    curl --location --request POST 'https://dev.bpcbt.com/v1/apigate/ws/rest/getTransactions' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic ZXVnZW5lMTIxMzEyMDp0dGhtdldcNg==' \
    --data-raw '{
        "cardIdentification": {
          "cardId": 100000000873
        },
        "period": {
              "start": "2020-04-01",
              "end": "2022-05-01"
            }
    }'
    

Response


    {
        "transactions": [
            {
                "authorizationDate": "2021-09-23T14:35:24",
                "transactionType": "578",
                "operationDirection": "NOOP",
                "amount": 0,
                "currency": 0,
                "amountInAccountCurrency": 0,
                "utrnno": 154793,
                "transactionDescription": "Change limit",
                "feeDirection": "DEBIT",
                "acquireFeeAmount": 0,
                "feIssuerFeeAmount": 0,
                "mcc": 6012,
                "merchantCountry": "NLD",
                "merchantCity": "BPC TEST ADDRESS N 2",
                "merchantName": "Test Mobile Bank",
                "merchantId": "TEST__MB",
                "terminalAddress": "APIGATE  FE  TEST BPC TEST ADDRESS N 1",
                "posDataCode": "600550U00110",
                "reversal": false,
                "requestAmount": 0,
                "terminalId": "TEST__MB",
                "internalResponseCode": -1
            },
            {
                "authorizationDate": "2021-09-23T14:37:36",
                "transactionType": "493",
                "operationDirection": "NOOP",
                "amount": 0,
                "currency": 0,
                "amountInAccountCurrency": 0,
                "utrnno": 154796,
                "transactionDescription": "Card blocking",
                "feeDirection": "DEBIT",
                "acquireFeeAmount": 0,
                "feIssuerFeeAmount": 0,
                "mcc": 6012,
                "merchantCountry": "NLD",
                "merchantCity": "BPC TEST ADDRESS N 2",
                "merchantName": "Test Mobile Bank",
                "merchantId": "TEST__MB",
                "terminalAddress": "APIGATE  FE  TEST BPC TEST ADDRESS N 1",
                "posDataCode": "600550U00110",
                "authorizationIdResponse": "154796",
                "reversal": false,
                "requestAmount": 0,
                "terminalId": "TEST__MB",
                "internalResponseCode": -1
            },
            {
                "authorizationDate": "2021-09-23T14:38:26",
                "transactionType": "672",
                "operationDirection": "NOOP",
                "amount": 0,
                "currency": 0,
                "amountInAccountCurrency": 0,
                "utrnno": 154797,
                "transactionDescription": "Card status change",
                "feeDirection": "DEBIT",
                "acquireFeeAmount": 0,
                "feIssuerFeeAmount": 0,
                "mcc": 6012,
                "merchantCountry": "NLD",
                "merchantCity": "BPC TEST ADDRESS N 2",
                "merchantName": "Test Mobile Bank",
                "merchantId": "TEST__MB",
                "terminalAddress": "APIGATE  FE  TEST BPC TEST ADDRESS N 1",
                "posDataCode": "600550U00110",
                "authorizationIdResponse": "154797",
                "reversal": false,
                "requestAmount": 0,
                "terminalId": "TEST__MB",
                "internalResponseCode": -1
            },
            {
                "authorizationDate": "2021-09-23T14:39:15",
                "transactionType": "760",
                "operationDirection": "CREDIT",
                "amount": 10000,
                "currency": 978,
                "amountInAccountCurrency": 10000,
                "utrnno": 154798,
                "transactionDescription": "Credit account presentment",
                "feeDirection": "CREDIT",
                "acquireFeeAmount": 0,
                "feIssuerFeeAmount": 0,
                "mcc": 6012,
                "merchantCountry": "NLD",
                "merchantCity": "BPC TEST ADDRESS N 2",
                "merchantName": "Test Mobile Bank",
                "merchantId": "TEST__MB",
                "terminalAddress": "APIGATE  FE  TEST BPC TEST ADDRESS N 1",
                "posDataCode": "600550U00110",
                "authorizationIdResponse": "154798",
                "reversal": false,
                "requestAmount": 10000,
                "terminalId": "TEST__MB",
                "internalResponseCode": -1
            },
            {
                "authorizationDate": "2021-09-23T14:40:05",
                "transactionType": "781",
                "operationDirection": "DEBIT",
                "amount": 1000,
                "currency": 978,
                "amountInAccountCurrency": 1000,
                "utrnno": 154800,
                "transactionDescription": "P2P Debit part",
                "feeDirection": "DEBIT",
                "acquireFeeAmount": 0,
                "feIssuerFeeAmount": 0,
                "mcc": 6012,
                "merchantCountry": "NLD",
                "merchantCity": "BPC TEST ADDRESS N 2",
                "merchantName": "Test Mobile Bank",
                "merchantId": "TEST__MB",
                "terminalAddress": "APIGATE  FE  TEST BPC TEST ADDRESS N 1",
                "posDataCode": "600550U00110",
                "authorizationIdResponse": "154800",
                "reversal": false,
                "requestAmount": 1000,
                "terminalId": "TEST__MB",
                "internalResponseCode": -1
            },
            {
                "authorizationDate": "2021-09-23T14:40:05",
                "transactionType": "689",
                "operationDirection": "NOOP",
                "amount": 1000,
                "currency": 978,
                "amountInAccountCurrency": 1000,
                "utrnno": 154799,
                "transactionDescription": "Card-to-Card money transfer",
                "feeDirection": "DEBIT",
                "acquireFeeAmount": 0,
                "feIssuerFeeAmount": 0,
                "mcc": 6012,
                "merchantCountry": "NLD",
                "merchantCity": "BPC TEST ADDRESS N 2",
                "merchantName": "Test Mobile Bank",
                "merchantId": "TEST__MB",
                "terminalAddress": "APIGATE  FE  TEST BPC TEST ADDRESS N 1",
                "posDataCode": "600550U00110",
                "authorizationIdResponse": "154801",
                "reversal": false,
                "requestAmount": 1000,
                "terminalId": "TEST__MB",
                "internalResponseCode": -1
            }
        ]
    }