Skip to main content

Set up a debit card

The Banqup APIs for setting up a debit card offer the ability to create and manage physical or virtual debit cards directly within an application.
This means users can instantly get a virtual card for online spending or order a physical card for both online and in-store use, while also benefiting from enhanced security and better spending control.



Prerequisites​

  • The customer is onboarded for payments and has a Banqup business account.
  • The user who starts the debit card creation process must be the legal representative of the company. Your default permissions allow you to perform the API call for card creation.
  • The resource IDs necessary to perform the API calls are:

Step 1: Create a debit card

Endpoint: POST/payments/v1/spaces/{spaceId}/paymentAccounts/{paymentAccountId}/cards


Request body: View documentation


Path parameters:

  • spaceId
  • paymentAccountId
curl -L 'https://{{serverURL}}/payments/v1/spaces/:spaceId/paymentAccounts/:paymentAccountId/cards' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
  "card": {
    "country": "Belgium",
    "label": "Office expenses",
    "locale": "fr-BE",
    "type": "PHYSICAL"
  },
  "cardHolderEntityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "deliveryAddress": {
    "buildingName": "Tour Egmont",
    "buildingNumber": "15",
    "city": "Brussels",
    "cityLocationName": "European Quarter",
    "country": "Belgium",
    "countryCode": "BE",
    "department": "Finance",
    "district": "Brussels-Capital",
    "floor": "Ground",
    "house": "15",
    "level": "1",
    "postBox": "1033",
    "postalCode": "1000",
    "postalCodeExtension": "",
    "province": "Brussels-Capital",
    "room": "2.22",
    "state": "",
    "streetName": "Boulevard du Régent",
    "subDepartment": "Accounting",
    "subDistrict": "Brussels"
  }
}'

Successful response:


{
  "accountId": "d44698da-6363-473f-903d-8eb113a2940e",
  "activatedAt": "2024-10-17T20:53:22.315Z",
  "availableOperations": [
    "ACTIVATE_CARD"
  ],
  "createdAt": "2024-10-17T20:53:22.315Z",
  "holder": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "firstName": "John",
    "lastName": "Smith"
  },
  "id": "0639a36a-f5c2-47f8-a2db-2d60d4284362",
  "label": "Office expenses",
  "maskedPan": "8956",
  "pinNeedsToBeSet": true,
  "status": {
    "card": "UNACTIVATED",
    "fulfillment": "ISSUED"
  },
  "type": "PHYSICAL"
}

Step 2: Set the PIN code

If the parameter pinNeedsToBeSet is set to true in the API response from step 1, the cardholder will need to set the PIN code.


Endpoint: POST/payments/v1/spaces/{spaceId}/paymentAccounts/{paymentAccountId}/cards/{cardId}{pin}


Request body: View documentation


Path parameters:

  • spaceId
  • paymentAccountId
  • cardId
curl -L 'https://{{serverURL}}/payments/v1/spaces/:spaceId/paymentAccounts/:paymentAccountId/cards/:cardId:pin' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
  "pin": "4265"
}'

Successful response:


{
  "offlineActivationRequired": true,
  "warningMessage": "string"
}

Hourglass Wait for card arrival

Next, the cardholder must wait for the physical card to be delivered before proceeding with the next steps. Once the card is received, they can continue with the activation process to start using it.

Step 3: Activate the card

To activate the physical debit card, the cardholder must prove that the card is in their possession. This is done by providing the PAN and CVC code in a safe environment.
Follow the instructions below to get an activation URL to integrate into your application to perform card activation.


Endpoint: POST/payments/v1/spaces/{spaceId}/paymentAccounts/{paymentAccountId}/cards/{cardId}{activate}


Request body: View documentation


Path parameters:

  • spaceId
  • paymentAccountId
  • cardId
curl -L 'https://{{serverURL}}/payments/v1/spaces/:spaceId/paymentAccounts/:paymentAccountId/cards/:cardId:activate' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
  "displayHeaders": true,
  "redirectUrl": "https://www.example.com"
}'

Successful response:


{
    "activationUrl": "https://widgets-sandbox.marqeta.com/activate_card?one_time_token=acb564a9-21a4-4bae-b994-f386fe36594f&user_token=8859e4d8-f982-489c-a85d-d4f026d0332e&application_id=unfdpst_sandbox_api_consumer&success_url=https://www.unifiedpost.com&display_headers=true&locale=en-GB"
}

The URL opens the following activation widget:


Activate card

Step 4: View the card details

Once a card has been activated, you can view its details in Banqup.


Endpoint: GET/payments/v1/spaces/{spaceId}/paymentAccounts/{paymentAccountId}/cards/{cardId}


Path parameters: View documentation

  • spaceId
  • paymentAccountId
  • cardId
curl -L 'https://{{serverURL}}/payments/v1/spaces/:spaceId/paymentAccounts/:paymentAccountId/cards/:cardId' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response:


{
  "accountId": "d44698da-6363-473f-903d-8eb113a2940e",
  "activatedAt": "2024-10-17T20:53:22.323Z",
  "availableOperations": [
        "DEACTIVATE_CARD",
        "SUSPEND_CARD"
  ],
  "createdAt": "2024-10-17T20:53:22.323Z",
  "holder": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "firstName": "John",
    "lastName": "Smith"
  },
  "id": "0639a36a-f5c2-47f8-a2db-2d60d4284362",
  "label": "Office expenses",
  "limits": {
    "dailyAtm": {
      "currency": "EUR",
      "currentLimit": 90,
      "currentUsage": 80,
      "expiresAt": "2024-10-17T20:53:22.323Z",
      "maximumLimit": 10
    },
    "weeklyAtm": {
      "currency": "EUR",
      "currentLimit": 90,
      "currentUsage": 80,
      "expiresAt": "2024-10-17T20:53:22.323Z",
      "maximumLimit": 10
    },
    "weeklyPurchase": {
      "currency": "EUR",
      "currentLimit": 90,
      "currentUsage": 80,
      "expiresAt": "2024-10-17T20:53:22.323Z",
      "maximumLimit": 10
    }
  },
  "maskedPan": "8956",
  "pinNeedsToBeSet": true,
  "settings": {
    "contactlessEnabled": true,
    "ecommerceEnabled": true,
    "regions": [
      "BELGIUM"
    ]
  },
  "status": {
    "card": "ACTIVE",
    "fulfillment": "SHIPPED"
  },
  "type": "PHYSICAL"
}