Naira Cards

All endpoints for Naira cards

This documentation explains how you can issue Naira cards (Mastercard) to your customers, your customers can make global payments worth $1,500 monthly using this card. We'll also be assuming that you have finished the integration process of creating a cardholder to continue this implementation.

Create Card

This API allows you to create an NGN virtual card for an already verified cardholder.

The card pin should be 4 digits and encrypted before passing it as a parameter to call the API to create a card, we use an open-source package called AES-Anywhere for this. The encryption key is the live or test secret key for your account, you can find these keys on the homepage of your dashboard. See Examples Below

$ pip install aes-everywhere

from AesEverywhere import aes256

# encryption
encrypted = aes256.encrypt('4 digit pin', 'Bridgecard Secret Key')
encrypted = encrypted.decode()
print(encrypted)

Then use the encrypted details to call the API below

curl -X 'POST' \
'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/create_card' \
  -H 'accept: application/json' \
  -H 'token: Bearer ******' \
  -H 'Content-Type: application/json' \
  -d '{
  "cardholder_id": "d0658fedf8284207866d96183fa",
  "card_type": "virtual" || "physical",
  "card_brand": "Mastercard",
  "card_currency": "NGN",
  "pin" : "39sksksie3902023020dj03020203039",
  "nin": "22236748901",
  "meta_data": {"user_id": "d0658fedf828420786e4a7083fa"}
}'
Body
  • cardholder_id : string *required

  • card_type (can either be "virtual" or "physical") : String *required 
  • card_brand ("Mastercard") : String *required
  • card_currency ("NGN") : String *required
  • pin (AES 256 encrypted 4 digit pin): string *required
  • meta_data : Dictionary *Optional
Response

🟢 200

{
  "status": "success",
  "message": "The Mastercard NGN card was created successfully",
  "data": {
    "card_id": "216ef11a58bf468baeb9cdbb94765865",
    "currency": "NGN"
  }
}

🔴 400: Invalid Cardholder ID

{
    "message": "Invalid cardholder ID, there's no cardholder with this ID."
}

🔴 504: ErrorPerfromingOperation

{
"message": "We ran into an error running this operation, please try again.
}

Get Card Details

Use this endpoint to fetch the details for a card you created.

Because a card's data contains sensitive information like the card number, CVV, and expiry date the details are encrypted when they're sent over to you but are decrypted automatically when they get to your server.

We strongly advise that you do not store the card data on your server except if you're PCI-DSS certified.

We have provided you with two endpoints to keep you compliant.

  1. Use these endpoints below when the user doesn't really need to see the card details, for example in a screen where you show them the list of cards they have, or where you display general information about the card like the last 4 digits etc.

sandbox: http://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_details

production: http://issuecards.api.bridgecard.co/v1/issuing/cards/get_card_details

  1. You can also use this other endpoint when you need to display the card details to the user may be at the point when they need to make a payment or when they click the view card details button on your app

sandbox: https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/sandbox/cards/get_card_details

production: https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/cards/get_card_details

curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_details?card_id=216ef11a58bf468baeb9cdbb97777777' \
--header 'token: Bearer *****' \
--data-raw ''
Response

🟢 200: card details fetched successfully.

{
    "status": "success",
    "message": "Card details was fetched successfully",
    "data": {
        "billing_address": {
            "billing_address1": "256 Chapman Road STE 105-4",
            "billing_city": "Newark",
            "billing_country": "US",
            "billing_zip_code": "19702",
            "country_code": "US",
            "state": "Delaware",
            "state_code": "DE"
        },
        "brand": "Visa",
        "card_currency": "USD",
        "card_id": "216ef11a58bf468baeb9cdbb947",
        "card_name": "John Doe",
        "card_number": "ev:RFVC:x9Fyh+9rI0BekZ5i:AgQHRjIQa7BzqhGXYuZwV/lXqiTb8Uq07nBYWWbuu46I:XXbJWyrBwDicifdA3exFewXRLSnR71whuMYKMhj5FVA:$",
        "card_type": "virtual",
        "cardholder_id": "d0658fedf8284207866d961e4a7083fa",
        "created_at": 1659958652,
        "cvv": "ev:RFVC:b9Qu3KGE+LBIhZEo:AgQHRjIQa7BzqhGXYuZwV/lXqiTb8Uq07nBYWWbuu46I:BJhJBGa/87QT8YCCLoCWvh9STg:$",
        "expiry_month": "ev:RFVC:f24e5mMw/sVAQxtl:AgQHRjIQa7BzqhGXYuZwV/lXqiTb8Uq07nBYWWbuu46I:i05HSrBrHf2hKfn0cUDTcYnX:$",
        "expiry_year": "ev:RFVC:2b0lTiBTfLcht3ju:AgQHRjIQa7BzqhGXYuZwV/lXqiTb8Uq07nBYWWbuu46I:JtZ1xVK3hJnFrW+sMjC1P7BP2LY:$",
        "is_active": true,
        "issuing_app_id": "842352f4-8a6f-4a19-89c6-4e8a240a2355",
        "last_4": "8649",
        "livemode": false,
        "meta_data": {
            "user_id": "d0658fedf8284207866d961e4a7083fa"
        },
        "balance": "0",
        "blocked_due_to_fraud": false,
        "pin_3ds_activated": true
    }
}

🔴 400: Invalid Cardholder ID

{
    "message": "Invalid cardholder ID, there's no cardholder with this ID."
}

🔴 504: We ran into an error creating the card

{
    "message": "We ran into an error running this operation, please try again."

Get Card Balance

This endpoint can be used to get the balance on the Naira card.

curl  -X 'GET'  'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/get_card_balance?cardholder_id=12jjh2h2bcasdsjhds8s7ssd' \
--header 'accept: application/json' \
--header 'token: Bearer *******'
Response

🟢 200

{
  "status": "success",
  "message": "Account balance fetched successfully",
  "data": {
    "available_balance": "0"
  }

🔴 400: Invalid Cardholder ID

{
    "message": "Invalid cardholder ID, there's no cardholder with this ID."
}

🔴 504: ErrorPerfromingOperation

{
"message": "We ran into an error running this operation, please try again.
}

Get Transaction OTP

A merchant might trigger the 3DS process on a user's card when they try to make a purchase, by asking them to provide an OTP to confirm a transaction. This endpoint allows your users to generate an OTP for a pending amount on their card. All the user has to do is enter the amount and we'll provide them with an OTP if there's a pending transaction on the card for that amount.

The amount should be passed to the API in Kobo and to test the 400 error response you can pass 0 as the amount.

Use these endpoint URLs to fetch the OTP in order to ensure secure transmission of the OTP sandbox: https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/sandbox/naira_cards/get_otp_message

production: https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/naira_cards/get_otp_message

curl --location --request GET 'https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/naira_cards/get_otp_message?card_id=f1a33838939393d33939939e5999&amount=1000' \
--header 'accept: application/json' \
--header 'token: Bearer at_live_****'
Response

🟢 200

{
    "status": "success",
    "message": "otp fetched successfully.",
    "data": {
        "otp": "632433"
    }
}

🔴 400: No pending OTP

{
  "message": "You do not have a pending OTP for this amount on your card, Please confirm the amount you entered is correct and try generating another OTP from the merchant.",
  "status": false
}

Fund Naira Card

This endpoint allows you to fund a naira Card from the NGN issuing wallet. Please listen to this webhook event to know whether the card funding was successful or failed.

curl -X 'POST' \
  'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/fund_naira_card' \
  -H 'accept: application/json' \
  -H 'token: Bearer *********' \
  -H 'Content-Type: application/json' \
  -d '{
  "card_id": "dsjdg7d8s7d78s8auhdskd",
  "amount": "100",
  "transaction_reference": "473783839939393030"
}'
Body
  • card_id: string *required

  • amount : string *required

  • transaction_reference : string *required

Response

🟢 202

{
  "status": "success",
  "message": "Transaction is processing",
  "data": {
    "transaction_reference": "7e409b3ec10f4ea99fd5bd0a77d07eab"
  }
}

🔴 504: ErrorPerfromingOperation

{
"message": "We ran into an error running this operation, please try again.
}

Unload Naira Card

This endpoint allows you to unload funds from a naira card and the funds go back into your NGN issuing wallet. Please listen to this webhook event to know whether the card funding was successful or failed.

curl -X 'PATCH' \
  'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/unload_naira_card' \
  -H 'accept: application/json' \
  -H 'token: Bearer *********' \
  -H 'Content-Type: application/json' \
  -d '{
  "card_id": "dsjdg7d8s7d78s8auhdskd",
  "amount": "100",
  "transaction_reference": "473783839939393030"
}'
Body
  • card_id: string *required

  • amount : string *required

  • transaction_reference : string *required

Response

🟢 202

{
  "status": "success",
  "message": "Transaction is processing",
  "data": {
    "transaction_reference": "7e409b3ec10f4ea99fd5bd0a77d07eab"
  }
}

🔴 504: ErrorPerfromingOperation

{
"message": "We ran into an error running this operation, please try again.
}

Mock a debit transaction

You can use this endpoint to create a debit transaction on a card in the sandbox environment to see how a purchase will look.

curl --location --request PATCH 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/mock_debit_naira_card' \
--header 'token: Bearer ****' \
--header 'Content-Type: application/json' \
--data-raw '{
    "card_id": "216ef11a58bf468baeb9cdbb965"
}'
Body
card_id : String *required
Response

🟢 200: card was funded successfully.

{
    "status": "success",
    "message": "Debit transaction was done Successfully",
    "data": {
        "transaction_reference": "216ef11a58bf468baeb9cdbb94765865"
    }
}

🔴 400: Invalid Cardholder ID

{
    "message": "Invalid cardholder ID, there's no cardholder with this ID."
}

🔴 400: Transaction reference already exists

{
    "message": "This transaction reference exists please enter another reference"
}

🔴 401: Insufficient balance on the card

{
    "message": "This card doesn\'t have enough funds to sufficient balance to perform this operation"
}

🔴 504: We ran into an error unloading the card

{
    "message": "We ran into an error running this operation, please try again.
}

Freeze Card

This endpoint allows your users to freeze their card. After freezing a card the is_active field in the get card details endpoint is immediately updated to False.

curl --location --request PATCH 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/freeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b' \
--header 'token: Bearer *****' \
--data-raw ''
Response

🟢 200: card was frozen successfully.

{
    "status": "success",
    "message": "This card has been frozen successfully",
    "data": {
        "card_id": "3d0220250f6b4addbfef1c5ffa39250b"
    }
}

🔴 400: Invalid Cardholder ID

{
    "message": "Invalid cardholder ID, there's no cardholder with this ID."
}

🔴 504: We ran into an error unfreezing the card

{
    "message": "We ran into an error running this operation, please try again."
}

Unfreeze Card

This endpoint allows your users to unfreeze their card. When you unfreeze a card the is_active field in the get card details endpoint is immediately updated to True.

curl --location --request PATCH 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/unfreeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b' \
--header 'token: Bearer *****' \
--data-raw ''
Response

🟢 200: card was unfrozen successfully.

{
    "status": "success",
    "message": "This card has been unfrozen successfully",
    "data": {
        "card_id": "3d0220250f6b4addbfef1c5ffa39250b"
    }
}

🔴 400: Invalid Cardholder ID

{
    "message": "Invalid cardholder ID, there's no cardholder with this ID."
}

🔴 504: We ran into an error unfreezing the card

{
    "message": "We ran into an error running this operation, please try again."
}

Get Card Transactions

Use this endpoint to get all the transactions on a nairacard.

Please note that all transactions are reported in the GMT time zone and you'll need to convert it to your own time zone if this is not your time zone.

curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_naira_card_transactions?card_id=70b34986c13c4026a9c1607e27eabc49&page=1' \
--header 'token: Bearer *****' \
--data-raw ''
Body

We allow you query this endpoint with some options.

card_id: The id of the card you want to pull transactions for *this field is compulsory
page: Transactions from this endpoint are paginated and each page contains at least 20 transactions *this field is compulsory
start_date (format 2023-03-01 12:10:00): Allows you to limit the transaction to a particular start date #this field is optional but you must always send it with an end_date param.
end_date (format 2023-03-01 12:10:00): Allows you to limit the transaction to a particular end date #this field is optional but you must always send it with a start_date param.
Response

🟢 200: card transactions fetched successfully.

{
    "status": "success",
    "message": "Card transaction history was fetched successfully",
    "data": {
        "transactions": [
            {
                "amount": "0",
                "bridgecard_transaction_reference": "7832a4d6371e4643aba4aa1f3c7030ab",
                "card_id": "70b34986c13c4026a9c1607e27eabc49",
                "card_transaction_type": "DEBIT",
                "cardholder_id": "d0658fedf8284207866d961e4a7083fa",
                "client_transaction_reference": "5c3598c8152446ba8093d058d8b59a1e",
                "currency": "USD",
                "description": "Apple Inc. US",
                "issuing_app_id": "842352f4-8a6f-4a19-89c6-4e8a240a2355",
                "livemode": false,
                "transaction_date": "2022-08-08 02:48:15",
                "transaction_timestamp": 1659923295,
                "merchant_category_code": "123478" || can be None,
                "enriched_data": {
                    "is_recurring": true,
                    "merchant_city": "California",
                    "merchant_code": "123478",
                    "merchant_logo": "https://logos.ntropy.com/apple.com",
                    "merchant_name": "Apple",
                    "merchant_website": "apple.com",
                    "transaction_category": "Others",
                    "transaction_group": "Other Outgoing Transactions"
                }
            },
            {
                "amount": "100",
                "bridgecard_transaction_reference": "370a5e491c20434dbb7dccdf1fafb9d2",
                "card_id": "70b34986c13c4026a9c1607e27eabc49",
                "card_transaction_type": "CREDIT",
                "cardholder_id": "d0658fedf8284207866d961e4a7083fa",
                "client_transaction_reference": "0906c4b453a745b8abbcf8b77b846ddd",
                "currency": "USD",
                "description": "Visa Virtual dollar card funding",
                "issuing_app_id": "842352f4-8a6f-4a19-89c6-4e8a240a2355",
                "livemode": false,
                "transaction_date": "2022-08-08 02:17:14",
                "transaction_timestamp": 1659921434,
                "enriched_data": {
                    "is_recurring": false,
                    "merchant_city": None,
                    "merchant_code": None,
                    "merchant_logo": "https://logos.ntropy.com/consumer_icons-ATM_bank_deposit",
                    "merchant_name": None,
                    "merchant_website": None,
                    "transaction_category": None,
                    "transaction_group": "Other Incoming Transactions"
                }
            }
        ],
        "meta": {
            "total": 2,
            "pages": 1,
            "previous": null,
            "next": "http://api.bridgecard.co/v1/issuing/cards/sandbox/get_card_transactions?card_id=70b34986c13c4026a9c1607e9&page=2"
        }
    }
}

🔴 400: Invalid card ID

{
    "message": "Invalid card ID, there's no card with this ID."
}

We provide transaction enrichment for all card transactions, you can use this feature to improve the user experience on your app. Read more here.

Last updated