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​


Step 1: Create a debit card

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


Path parameters:

  • spaceId
  • paymentAccountId

Requires a JSON request body.

curl -L -X 'https://{{serverURL}}/payments/cards/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 Regent",
    "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: /payments/cards/v1/spaces/{spaceId}/paymentAccounts/{paymentAccountId}/cards/{cardId}:pin


Path parameters:

  • spaceId
  • paymentAccountId
  • cardId

Requires a JSON request body.

curl -L -X 'https://{{serverURL}}/payments/cards/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: /payments/cards/v1/spaces/{spaceId}/paymentAccounts/{paymentAccountId}/cards/{cardId}:activate


Path parameters:

  • spaceId
  • paymentAccountId
  • cardId

Requires a JSON request body.

curl -L -X 'https://{{serverURL}}/payments/cards/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: /payments/cards/v1/spaces/{spaceId}/paymentAccounts/{paymentAccountId}/cards/{cardId}


Path parameters:

  • spaceId
  • paymentAccountId
  • cardId 
curl -L -X 'https://{{serverURL}}/payments/cards/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"
}