# Welcome πŸ₯³ We are happy you chose us as your magic wand πŸͺ„ In this documentation, we will introduce you to how to use Bridgecard's issuing APIs to issue physical and virtual cards to your customers. Next ⏭\ Let’s spin this up in 3 hours ⏰ # Introduction πŸš€ Bridgecard Issuing has two types of environments, a production and sandbox environment. Here’s the difference between both environments. **ENVIRONMENTS USE** **Production:** This environment is for live apps, they issue real cards that can be used online. baseURL: `https://issuecards.api.bridgecard.co/v1/issuing` **Sandbox:** Use this environment while you are still developing, they are free to call, provide you with live-like data and they have the same implementation as the production environment so you don’t have to write two different codes. baseURL: `https://issuecards.api.bridgecard.co/v1/issuing/sandbox` For each of the environments on Bridgecard Issuing you will require an access token and a secret key. To get these you will have to [create an account](https://bridgecard.cards/register) with us. Nice now that you have an account up and running, you can get your access token and secret key for both the sandbox or production environments by clicking the API Keys tab on your dashboard homepage. For the sake of this test we will be setting up this application in a sandbox environment and so we will be using our sandbox keys. Sandbox keys usually start with β€œtest” keyword and are free to use. We currently support only the issuing of virtual dollar cards ## Get your API keys Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error. You can generate an API key from your [Dashboard](https://bridgecard.co/dashboard) at any time. # Definitions πŸ”– Here are a few words you'll hear us use frequently in this documentation when describing how the APIs work, feel free to come back here if you don't know what a term means. {% hint style="success" %} Card Holder πŸ™β€β™‚οΈ: A Cardholder is an individual who you want to issue a card. {% endhint %} {% hint style="success" %} Card πŸ’³ : This is a card issued to a cardholder, this card can be a physical or a virtual card. {% endhint %} {% hint style="success" %} Issuing Wallet πŸ’³ : This is a float wallet where your business stores the funds you need to credit your user's cards. {% endhint %} # Card Products We have a couple of card products currently available and we're currently working on rolling out more of them.
Card SchemeCard TypeCurrencyAvailabilityLimit
MastercardPhysicalMulticurrency (NGN and USD)βœ…$1,500 monthly and N1,000,000 daily
MastercardVirtualMulticurrency (NGN and USD)βœ…$1,500 monthly and N1,000,000 daily
MastercardVirtualUSDβœ…$5,000 OR $10,000 monthly
MastercardVirtualUSDβœ…$5,000 OR $10,000 monthly
# Integration Guide βš™οΈ Step by Step guide Here is a step-by-step guide on how to use our APIs to issue cards to your users. * [ ] [Register your business](https://bridgecard.cards/register) on our administrator dashboard to get access to a production and sandbox token to authenticate your API calls. Also don't forget to set up a webhook URL. * [ ] You'll have to register your user as a cardholder on our platform, you can do this either synchronously using this [endpoint](/reference/api-reference/cardholder#register-a-cardholder-synchronously) or asynchronously using this [endpoint](https://docs.bridgecard.co/introduction/pages/e5ROtsej1SMpZ3kUCRAm#register-a-cardholder.) * [ ] If you registered the cardholder synchronously you'll get a response immediately but this API call can take up to 45sec to return a response because the verification is done on the fly, so remember to set your request timeout to about 45sec if you have to. \ If you used the asynchronous API to register the cardholder, we will verify the cardholder's ID and other details in the background and send you a [successful](https://docs.bridgecard.co/introduction/pages/MZdzG9LSiDrdbNFKhcny#cardholder_verification.successful) or [failed](https://docs.bridgecard.co/introduction/pages/MZdzG9LSiDrdbNFKhcny#cardholder_verification.failed) webhook event to let you know the verification result. Cardholder verification takes about 2 minutes after account creation. * [ ] You'll need to fund your issuing wallet with some test funds so you can create a card and also fund one. You can use this [API](/reference/api-reference/misc#fund-issuing-wallet) to do this. * [ ] After the cardholder has been successfully verified, you can then go ahead and request a card for this cardholder using this [endpoint](/reference/api-reference/usd-cards#create-a-card). * [ ] Call the [get user card details endpoint](/reference/api-reference/usd-cards#get-card-details) to reveal the user's card details. This information is usually encrypted because it contains sensitive information but you can change the API baseURL to the relay endpoint URLs below to decrypt the card details. **RELAY URLS**\ `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` **Note:** We strongly suggest that you don't save card details except your PCI-DSS compliant, you can always call this endpoint whenever you need to fetch the card details. * [ ] Now that you have created a card, you can now fund the card using this [endpoint](/reference/api-reference/usd-cards#fund-card). * [ ] You can also check the balance on the card using this [endpoint](/reference/api-reference/usd-cards#get-card-balance). * [ ] We also have an API to withdraw some funds from the card, if this fits your use case you can try out the feature using this [endpoint](/reference/api-reference/usd-cards#unload-a-card). * [ ] You can also mock a sample debit transaction on a card with this [endpoint](/reference/api-reference/usd-cards#mock-a-debit-transaction) * [ ] Now that you've done a couple of transactions on the card, you can call this endpoint to [view the cards transaction history](/reference/api-reference/usd-cards#get-card-transactions) * [ ] You can also explore the [other APIs here](/reference/api-reference/usd-cards) to manage your issued cards # API Reference Dive into the specifics of each API endpoint by checking out our complete documentation. ## Managing Cardholders All the APIs to manage a cardholder {% content-ref url="/pages/e5ROtsej1SMpZ3kUCRAm" %} [Cardholder](/reference/api-reference/cardholder) {% endcontent-ref %} ## All the APIs to manage an issued card All the APIs to manage an issued card {% content-ref url="/pages/0tMyylwkhXcdXzvSCSfZ" %} [USD Cards](/reference/api-reference/usd-cards) {% endcontent-ref %} ## Webhook Events All of our webhook events {% content-ref url="/pages/MZdzG9LSiDrdbNFKhcny" %} [Webhook events](/reference/api-reference/webhook-events) {% endcontent-ref %} # Cardholder All the APIs to manage cardholder ## Register a cardholder synchronously Use this endpoint to register your user as a cardholder on our platform. The cardholder's Identity verification is done on the fly, so the response might take about 45 seconds and you might want to increase the seconds it takes for your requests to timeout. This endpoint is rate limited per minute which means a cardholder can only retry his KYC once every minute(register\_cardholder) Please note: phone must be E.164 (+ + country code + number) {% tabs %} {% tab title="cURL" %} ``` curl --location --request POST 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder_synchronously' \ --header 'token: Bearer xxxxx' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_name": "John", "last_name": "Doe", "address": { "address": "9 Jibowu Street", "city": "Aba North", "state": "Abia", "country": "Nigeria", "postal_code": "1000242", "house_no": "13" }, "phone": "+2348122277789", "email_address": "testingboy@gmail.com", "identity": { "id_type": "NIGERIAN_BVN_VERIFICATION", "bvn": "22222222222222", "selfie_image": "https://image.com" }, "meta_data":{"any_key": "any_value"} }' ``` {% endtab %} {% tab title="Python" %} ```python import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder_synchronously" payload = json.dumps({ "first_name": "John", "last_name": "Doe", "address": { "address": "9 Jibowu Street", "city": "Aba North", "state": "Abia", "country": "Nigeria", "postal_code": "1000242", "house_no": "13" }, "phone": "+2348122277789", "email_address": "testingboy@gmail.com", "identity": { "id_type": "NIGERIAN_BVN_VERIFICATION", "bvn": "22222222222222", "selfie_image": "https://image.com" }, "meta_data":{"any_key": "any_value"} ) headers = { 'token': 'Bearer xxxxx', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'POST', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder_synchronously', 'headers': { 'token': 'Bearer xxxxx', 'Content-Type': 'application/json' }, body: JSON.stringify({ "first_name": "John", "last_name": "Doe", "address": { "address": "9 Jibowu Street", "city": "Aba North", "state": "Abia", "country": "Nigeria", "postal_code": "1000242", "house_no": "13" }, "phone": "+2348122277789", "email_address": "testingboy@gmail.com", "identity": { "id_type": "NIGERIAN_BVN_VERIFICATION", "bvn": "22222222222222", "selfie_image": "https://image.com" }, "meta_data":{"any_key": "any_value"} ) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder_synchronously'); $request->setMethod(HTTP_Request2::METHOD_POST); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer xxxxx', 'Content-Type' => 'application/json' )); $request->setBody('{\n "first_name": "John",\n "last_name": "Doe",\n \n "address": {\n "address": "9 Jibowu Street",\n "city": "Aba North",\n "state": "Abia",\n "country": "Nigeria",\n "postal_code": "1000242",\n "house_no": "13"\n },\n "phone": "+2348122277789",\n "email_address": "testingboy@gmail.com",\n "meta_data":{ \n "any_key": "any_value"}, \n "identity": {\n "id_type": "NIGERIAN_BVN",\n "bvn": "32747711121",\n "selfie_image": "https://id_image"\n},\n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder_synchronously" method := "POST" payload := strings.NewReader(`{ "first_name": "John", "last_name": "Doe", "address": { "address": "9 Jibowu Street", "city": "Aba North", "state": "Abia", "country": "Nigeria", "postal_code": "1000242", "house_no": "13" }, "phone": "+2348122277789", "email_address":"testingboy@gmail.com", "identity": { "id_type": "NIGERIAN_BVN_VERIFICATION", "bvn": "22222222222222", "selfie_image": "https://image.com" }, "meta_data":{"any_key": "any_value"} }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer xxxxx") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Body * `first_name : String *required` * `last_name : String *required` * `address : CardHolderAdress *required` \ \ CardHolderAdress Object ``` { "address": "9 Jibowu Street", "city": "Aba North", "state": "Abia", "country": "Nigeria", "postal_code": "1000242", "house_no": "13" } ``` You can use these endpoints to get a list of [all the states ](/reference/api-reference/misc#get-all-states) * `phone : String *required` * `identity: There are 4 types of identity objects depending on the country of the user you're onboarding.` If you need to onboard users outside these countries please check this [link](/reference/api-reference/kyc-requirements-for-all-countries) for the KYC requirements. **Nigerian Cardholder Identity Request** **Object** ``` { "id_type": "NIGERIAN_BVN_VERIFICATION", "bvn": "22222222222222", "selfie_image": "https://image.com" } OR USE ANY OTHER GOVERNMENT ISSUED ID { "id_type": "NIGERIAN_NIN" or "NIGERIAN_INTERNATIONAL_PASSPORT" or "NIGERIAN_PVC" or "NIGERIAN_DRIVERS_LICENSE", "id_no": "32747711121", "id_image": "https://id_image", "bvn": "2222222222222" } ``` **Ghanian Cardholder Identity Request** **Object** ``` { "id_type": "GHANIAN_SSNIT" or "GHANIAN_VOTERS_ID" or "GHANIAN_DRIVERS_LICENSE" or "GHANIAN_INTERNATIONAL_PASSPORT" or "GHANIAN_GHANA_CARD", "id_no": "32747711121", "id_image": "https://immage.com", "selfie_image": "https://image.com" } ``` **Ugandan Cardholder Identity Request** **Object** ``` { "id_type": "UGANDA_VOTERS_ID" or "UGANDA_PASSPORT" or "UGANDA_NATIONAL_ID" or "UGANDA_DRIVERS_LICENSE", "id_no": "32747711121", "first_name": "John", "last_name": "Doe", "middle_name": "Moe", "date_of_birth": "1990-12-02", #yyyy-mm-dd "gender": "male" or "female", "selfie_image": "https://image.com" } ``` **Kenyan Cardholder Identity Request** **Object** ``` { "id_type": "KENYAN_VOTERS_ID" "id_no": "32747711121" "first_name": "John" "last_name": "Doe" "middle_name": "Moe" "date_of_birth": "1990-12-02" #yyyy-mm-dd "gender": "male" or "female" "selfie_image": "https://image.com" } ``` * `meta_data: Use this to store any other data you want to use to recognise this cardholder from your system *optional`
Responses 🟒 **201**: cardholder successfully created ``` { "status": "success", "message": "cardholder created successfully.", "data": { "cardholder_id": "e416a9a188af40b78b8afd740e835d699" } } ``` πŸ”΄ 400: Invalid Firstname Error ``` { "message": "Invalid firstname, a valid name should have a minimum of 3 letters" } ``` πŸ”΄ 400: Invalid Lastname Error ``` { "message":"Invalid lastname, a valid name should have a minimum of 3 letters" } ``` πŸ”΄ 400: Invalid BVN Error ``` { "message": "Invalid BVN, a valid BVN is 12 digits long" } ``` πŸ”΄ 400: BVN already exists error ``` { "message": "A cardholder already exists with this BVN" } ``` πŸ”΄ 400: Issuing not supported in Country Error ``` { "message":"Our card Issuing doesn't support this country, we only support ["Nigeria", "Ghana", "Uganda", "Kenya"]" } ``` πŸ”΄ 400: Invalid Address Error ``` { "message": "Invalid address, a valid address should have a minimum of 3 letters" } ``` πŸ”΄ 400: Invalid Postal code ``` { "message": "Invalid postalcode, please check the get_all_lga API to see the list of valid postalcodes and LGAs" } ``` πŸ”΄ 400: Invalid House Number Error ``` { "message": "Invalid house no, please enter a house or apartment number" } ``` πŸ”΄ 400: Invalid Local Government Error ``` { "message": "Invalid LGA, please check the get_all_lga API to see the list of valid LGAs" } ``` πŸ”΄ 400: Invalid Phone Number ``` { "message": "Invalid phoneno." } ``` πŸ”΄ 400: Phone Number already exists ``` { "message": "A cardholder already exists with this phoneno" } ``` πŸ”΄ 400: Invalid ID url ``` { "message": "Invalid ID url" } ``` πŸ”΄ 400: Invalid ID Number ``` { "message": "Invalid ID number" } ``` πŸ”΄ 403: Client account missing Address ``` { "message": "Your issuing account wasn't setup properly, we don't have your company's official address or utility bill, please contact support" } ``` πŸ”΄ 400: invalid DOB ``` { "message": "Invalid Date of Birth format, please send in yyyy-mm-dd e.g 2021-12-31" } ``` πŸ”΄ 400: Unable to verify BVN Error ``` { "message": "Oops.. we couldn't verify your BVN, please confirm the BVN and try again.", } ``` πŸ”΄ 400: Blacklisted BVN Profile ``` { "message": "Oops.. your BVN might have been associated with some fraud or bad record recently so we couldn't enroll you. please contact your bank." } ``` πŸ”΄ 400: ID number does not match the uploaded ID ``` { "message": "Oops.. The uploaded ID number doesn't match the ID uploaded, please try again." } ``` πŸ”΄ 400: Invalid State Error ``` { "message": "Invalid state, please check the get_all_states API to see the list of valid states" } ``` πŸ”΄ 400: BVN Name does not match ID ``` { "message": "Oops.. The uploaded ID name doesn't match the name on his BVN, please try again." } ``` πŸ”΄ 400: Could not verify ID error ``` { "message": "Oops.. we couldn't verify your ID, please try again." } ``` πŸ”΄ 400: Cardholder's name does not match name on BVN ``` { "message": "The cardholders name doesn't match the name on the BVN provided" } ``` πŸ”΄ 400: Could not send OTP ``` { "message": "We ran into an error sending you an OTP, please contact support." } ``` πŸ”΄ 400: BVN Phone number Fraud Suspected ``` { "message": "Oops.. we suspect fraud, this phone no is tied to multiple BVNs." } ``` πŸ”΄ 451: Customer has been blacklisted due to fraud ``` { "message": "This individual has been blacklisted on our platform due to fraudulent activities, please contact support." } ```
## Register a cardholder asynchronously (Recommended) Use this endpoint to register your user as a cardholder on our platform. If the user passes the KYC verification we will send you a [success webhook](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#cardholder_verification.successful). However, we have a human-in-the-loop process where if a user fails a KYC verification we might pass it to a human being to do a manual verification just to double check that the automated KYC verification system didn't flag the user's KYC unnecessarily. In the case that a users KYC is being sent for manual review you will be sent a [manual review webhook](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#cardholder_verification.manual_review). The manual review process by our compliance team usually takes between 1 - 24hrs and after this, we will send you either the cardholder [success](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#cardholder_verification.successful) or [failure](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#cardholder_verification.failed) webhook verification response depending on the final decision. Please note: phone must be E.164 (+ + country code + number) {% tabs %} {% tab title="cURL" %} 
curl --location --request POST 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder' \
--header 'token: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "first_name": "John",
  "last_name": "Doe",
  "address": {
    "address": "9 Jibowu Street",
    "city": "Aba North",
    "state": "Abia",
    "country": "Nigeria",
    "postal_code": "1000242",
    "house_no": "13"
  },
  "phone": "+2348122277789",
  "email_address": "testingboy@gmail.com",
  "identity": {
    "id_type": "NIGERIAN_BVN_VERIFICATION",
    "bvn": "22222222222222",
    "selfie_image": "https://image.com" 
  },
  "meta_data":{"any_key": "any_value"}
}'
{% endtab %} {% tab title="Python" %} ```python import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder" payload = json.dumps({ "first_name": "John", "last_name": "Doe", "address": { "address": "9 Jibowu Street", "city": "Aba North", "state": "Abia", "country": "Nigeria", "postal_code": "1000242", "house_no": "13" }, "phone": "+2348122277789", "email_address": "testingboy@gmail.com", "identity": { "id_type": "NIGERIAN_BVN_VERIFICATION", "bvn": "22222222222222", "selfie_image": "https://image.com" }, "meta_data":{"any_key": "any_value"} ) headers = { 'token': 'Bearer xxxxx', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'POST', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder', 'headers': { 'token': 'Bearer xxxxx', 'Content-Type': 'application/json' }, body: JSON.stringify({ "first_name": "John", "last_name": "Doe", "address": { "address": "9 Jibowu Street", "city": "Aba North", "state": "Abia", "country": "Nigeria", "postal_code": "1000242", "house_no": "13" }, "phone": "+2348122277789", "email_address": "testingboy@gmail.com", "identity": { "id_type": "NIGERIAN_BVN_VERIFICATION", "bvn": "22222222222222", "selfie_image": "https://image.com" }, "meta_data":{"any_key": "any_value"} ) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder'); $request->setMethod(HTTP_Request2::METHOD_POST); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer xxxxx', 'Content-Type' => 'application/json' )); $request->setBody('{\n "first_name": "John",\n "last_name": "Doe",\n \n "address": {\n "address": "9 Jibowu Street",\n "city": "Aba North",\n "state": "Abia",\n "country": "Nigeria",\n "postal_code": "1000242",\n "house_no": "13"\n },\n "phone": "+2348122277789",\n "email_address": "testingboy@gmail.com",\n "meta_data":{ \n "any_key": "any_value"}, \n "identity": {\n "id_type": "NIGERIAN_BVN",\n "bvn": "32747711121",\n "selfie_image": "https://id_image",\n},\n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder" method := "POST" payload := strings.NewReader(`{ "first_name": "John", "last_name": "Doe", "address": { "address": "9 Jibowu Street", "city": "Aba North", "state": "Abia", "country": "Nigeria", "postal_code": "1000242", "house_no": "13" }, "phone": "+2348122277789", "email_address":"testingboy@gmail.com", "identity": { "id_type: "NIGERIAN_NIN" or "NIGERIAN_INTERNATIONAL_PASSPORT" or "NIGERIAN_PVC" or "NIGERIAN_DRIVERS_LICENSE" "id_no": "11111111111", "id_image": "", "bvn": "2222222222" }, "meta_data":{"any_key": "any_value"} }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer xxxxx") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Body * `first_name : String *required` * `last_name : String *required` * `address : CardHolderAdress *required` \ \ CardHolderAdress Object ``` { "address": "9 Jibowu Street", "city": "Aba North", "state": "Abia", "country": "Nigeria", "postal_code": "1000242", "house_no": "13" } ``` You can use these endpoints to get a list of [all the states](broken://pages/geZb1adfGPcwMXg4cNJs#get-all-states) and their [lgas & postalcodes](broken://pages/geZb1adfGPcwMXg4cNJs#get-all-lgas-and-their-postal-codes) * `phone : String *required` * `identity: There are 4 types of identity objects depending on the country of the user you're onboarding.` \ \ If you need to onboard users outside these countries please check this [link](/reference/api-reference/kyc-requirements-for-all-countries) for the KYC requirements. **Nigerian Cardholder Identity Request** **Object** ``` { "id_type": "NIGERIAN_BVN_VERIFICATION", "bvn": "22222222222222", "selfie_image": "https://image.com" } OR USE ANY OTHER GOVERNMENT ISSUED ID { "id_type": "NIGERIAN_NIN" or "NIGERIAN_INTERNATIONAL_PASSPORT" or "NIGERIAN_PVC" or "NIGERIAN_DRIVERS_LICENSE", "id_no": "32747711121", "id_image": "https://id_image", "bvn": "2222222222222" } ``` **Ghanian Cardholder Identity Request** **Object** ``` { "id_type": "GHANIAN_SSNIT" or "GHANIAN_VOTERS_ID" or "GHANIAN_DRIVERS_LICENSE" or "GHANIAN_INTERNATIONAL_PASSPORT" or "GHANIAN_GHANA_CARD", "id_no": "32747711121", "id_image": "https://immage.com", "selfie_image": "https://image.com" } ``` **Ugandan Cardholder Identity Request** **Object** ``` { "id_type": "UGANDA_VOTERS_ID" or "UGANDA_PASSPORT" or "UGANDA_NATIONAL_ID" or "UGANDA_DRIVERS_LICENSE", "id_no": "32747711121", "first_name": "John", "last_name": "Doe", "middle_name": "Moe", "date_of_birth": "1990-12-02", #yyyy-mm-dd "gender": "male" or "female", "selfie_image": "https://image.com" } ``` **Kenyan Cardholder Identity Request** **Object** ``` { "id_type": "KENYAN_VOTERS_ID" "id_no": "32747711121" "first_name": "John" "last_name": "Doe" "middle_name": "Moe" "date_of_birth": "1990-12-02" #yyyy-mm-dd "gender": "male" or "female" "selfie_image": "https://image.com" } ``` * `meta_data: Use this to store any other data you want to use to recognise this cardholder from your system *optional`
Responses 🟒 **201**: cardholder successfully created ``` { "status": "success", "message": "cardholder created successfully, you\'ll recieve a webhook event when this user\'s identity has been verified.", "data": { "cardholder_id": "e416a9a188af40b78b8afd740e835d699" } } ``` πŸ”΄ 400: Invalid Firstname Error ``` { "message": "Invalid firstname, a valid name should have a minimum of 3 letters" } ``` πŸ”΄ 400: Invalid Lastname Error ``` { "message":"Invalid lastname, a valid name should have a minimum of 3 letters" } ``` πŸ”΄ 400: Invalid BVN Error ``` { "message": "Invalid BVN, a valid BVN is 12 digits long" } ``` πŸ”΄ 400: BVN already exists error ``` { "message": "A cardholder already exists with this BVN" } ``` πŸ”΄ 400: Issuing not supported in Country Error ``` { "message":"Our card Issuing doesn't support this country, we only support ["Nigeria", "Ghana", "Uganda", "Kenya"]" } ``` πŸ”΄ 400: Invalid Address Error ``` { "message": "Invalid address, a valid address should have a minimum of 3 letters" } ``` πŸ”΄ 400: Invalid Postal code ``` { "message": "Invalid postalcode, please check the get_all_lga API to see the list of valid postalcodes and LGAs" } ``` πŸ”΄ 400: Invalid House Number Error ``` { "message": "Invalid house no, please enter a house or apartment number" } ``` πŸ”΄ 400: Invalid Local Government Error ``` { "message": "Invalid LGA, please check the get_all_lga API to see the list of valid LGAs" } ``` πŸ”΄ 400: Invalid Phone Number ``` { "message": "Invalid phoneno." } ``` πŸ”΄ 400: Phone Number already exists ``` { "message": "A cardholder already exists with this phoneno" } ``` πŸ”΄ 400: Invalid ID url ``` { "message": "Invalid ID url" } ``` πŸ”΄ 400: Invalid ID Number ``` { "message": "Invalid ID number" } ``` πŸ”΄ 403: Client account missing Address ``` { "message": "Your issuing account wasn't setup properly, we don't have your company's official address or utility bill, please contact support" } ``` πŸ”΄ 400: Invalid Utility Bill URL ``` { "message": "Invalid utility bill url" } ``` πŸ”΄ 400: invalid DOB ``` { "message": "Invalid Date of Birth format, please send in yyyy-mm-dd e.g 2021-12-31" } ``` πŸ”΄ 400: Unable to verify BVN Error ``` { "message": "Oops.. we couldn't verify your BVN, please confirm the BVN and try again.", } ``` πŸ”΄ 400: Blacklisted BVN Profile ``` { "message": "Oops.. your BVN might have been associated with some fraud or bad record recently so we couldn't enroll you. please contact your bank." } ``` πŸ”΄ 400: ID number does not match the uploaded ID ``` { "message": "Oops.. The uploaded ID number doesn't match the ID uploaded, please try again." } ``` πŸ”΄ 400: Invalid State Error ``` { "message": "Invalid state, please check the get_all_states API to see the list of valid states" } ``` πŸ”΄ 400: BVN Name does not match ID ``` { "message": "Oops.. The uploaded ID name doesn't match the name on his BVN, please try again." } ``` πŸ”΄ 400: Could not verify ID error ``` { "message": "Oops.. we couldn't verify your ID, please try again." } ``` πŸ”΄ 400: Cardholder's name does not match name on BVN ``` { "message": "The cardholders name doesn't match the name on the BVN provided" } ``` πŸ”΄ 400: Could not send OTP ``` { "message": "We ran into an error sending you an OTP, please contact support." } ``` πŸ”΄ 400: BVN Phone number Fraud Suspected ``` { "message": "Oops.. we suspect fraud, this phone no is tied to multiple BVNs." } ``` πŸ”΄ 451: Customer has been blacklisted due to fraud ``` { "message": "This individual has been blacklisted on our platform due to fraudulent activities, please contact support." } ```
## Update cardholder details. Use this endpoint to update some information on an already created cardholder. Please note that this will not trigger a re-validation and should be done on an already validated cardholder. {% tabs %} {% tab title="cURL" %} ``` curl --location --request PATCH 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/update_cardholder' \ --header 'token: Bearer xxxxx' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_name": "John", "last_name": "Doe", "cardholder_id": "5ce48a0b4292499bbe3d23441a2a2d06" "address": { "address": "9 Jibowu Street", "city": "Aba North", "state": "Abia", "country": "Nigeria", "postal_code": "1000242", "house_no": "13" }, "phone": "+2348122277789", "identity": { "id_type": "NIGERIAN_BVN_VERIFICATION", "bvn": "22222222222222", "selfie_image": "https://image.com" }, "meta_data":{"any_key": "any_value"} }' ``` {% endtab %} {% tab title="Python" %} ```python import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/update_cardholder" headers = { "token": "Bearer xxxxx", "Content-Type": "application/json" } payload = { "first_name": "John", "last_name": "Doe", "cardholder_id": "5ce48a0b4292499bbe3d23441a2a2d06", "address": { "address": "9 Jibowu Street", "city": "Aba North", "state": "Abia", "country": "Nigeria", "postal_code": "1000242", "house_no": "13" }, "phone": "+2348122277789", "identity": { "id_type": "NIGERIAN_BVN_VERIFICATION", "bvn": "22222222222222", "selfie_image": "https://image.com" }, "meta_data": {"any_key": "any_value"} } response = requests.patch(url, headers=headers, data=json.dumps(payload)) print(response.status_code) print(response.json()) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript const axios = require('axios'); const url = 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/update_cardholder'; const payload = { first_name: "John", last_name: "Doe", cardholder_id: "5ce48a0b4292499bbe3d23441a2a2d06", address: { address: "9 Jibowu Street", city: "Aba North", state: "Abia", country: "Nigeria", postal_code: "1000242", house_no: "13" }, phone: "+2348122277789", identity: { id_type: "NIGERIAN_BVN_VERIFICATION", bvn: "22222222222222", selfie_image: "https://image.com" }, meta_data: { any_key: "any_value" } }; axios.patch(url, payload, { headers: { 'token': 'Bearer xxxxx', 'Content-Type': 'application/json' } }) .then(response => { console.log(response.status); console.log(response.data); }) .catch(error => { console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="PHP" %} ```php "John", "last_name" => "Doe", "cardholder_id" => "5ce48a0b4292499bbe3d23441a2a2d06", "address" => [ "address" => "9 Jibowu Street", "city" => "Aba North", "state" => "Abia", "country" => "Nigeria", "postal_code" => "1000242", "house_no" => "13" ], "phone" => "+2348122277789", "identity" => [ "id_type" => "NIGERIAN_BVN_VERIFICATION", "bvn" => "22222222222222", "selfie_image" => "https://image.com" ], "meta_data" => ["any_key" => "any_value"] ]); $ch = curl_init($url); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH"); curl_setopt($ch, CURLOPT_POSTFIELDS, $payload); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, [ "token: Bearer xxxxx", "Content-Type: application/json" ]); $response = curl_exec($ch); $httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); echo "Status Code: $httpcode\n"; echo "Response: $response\n"; ?> ``` {% endtab %} {% tab title="Go" %} ``` package main import ( "bytes" "fmt" "io/ioutil" "net/http" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/update_cardholder" payload := []byte(`{ "first_name": "John", "last_name": "Doe", "cardholder_id": "5ce48a0b4292499bbe3d23441a2a2d06", "address": { "address": "9 Jibowu Street", "city": "Aba North", "state": "Abia", "country": "Nigeria", "postal_code": "1000242", "house_no": "13" }, "phone": "+2348122277789", "identity": { "id_type": "NIGERIAN_BVN_VERIFICATION", "bvn": "22222222222222", "selfie_image": "https://image.com" }, "meta_data": {"any_key": "any_value"} }`) req, err := http.NewRequest(http.MethodPatch, url, bytes.NewBuffer(payload)) if err != nil { panic(err) } req.Header.Set("token", "Bearer xxxxx") req.Header.Set("Content-Type", "application/json") client := &http.Client{} resp, err := client.Do(req) if err != nil { panic(err) } defer resp.Body.Close() body, _ := ioutil.ReadAll(resp.Body) fmt.Println("Status Code:", resp.StatusCode) fmt.Println("Response:", string(body)) } ``` {% endtab %} {% endtabs %} ## Get cardholder details. Use this API to view a cardholder's profile. {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/get_cardholder?cardholder_id=e416a9a188af40b78b8afd740e835d68' \ --header 'token: Bearer xxxxx' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/get_cardholder?cardholder_id=e416a9a188af40b78b8afd740e835d68" payload={} headers = { 'token': 'Bearer xxxxx' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/get_cardholder?cardholder_id=e416a9a188af40b78b8afd740e835d68', 'headers': { 'token': 'Bearer xxxxx' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/get_cardholder?cardholder_id=e416a9a188af40b78b8afd740e835d68'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer xxxxx' )); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/get_cardholder?cardholder_id=e416a9a188af40b78b8afd740e835d68" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer xxxxx") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 200: cardholder details fetched successfully. ``` { "status": "success", "message": "cardholder details fecthed successfully.", "data": { "address": { "address": "9 Jibowu Street", "city": "Aba North", "country": "nigeria", "house_no": "13", "lga": "Aba North", "postal_code": "1000242", "state": "Abia" }, "cardholder_id": "d0658fedf8284207866d961e83fa", "created_at": 1659726281, "email_address": "testingboy@gmail.com", "first_name": "John", "identity_details": { "blacklisted": false, "date_of_birth": "1999-02-04", "first_name": "John", "gender": "Male", "id_no": "22222222222", "id_type": "NIGERIAN_NIN", "last_name": "Doe", "phone": "08123456789" }, "is_active": true, "is_id_verified": true, "issuing_app_id": "842352f4-8a6f-4a19-89c6-", "last_name": "Doe", "phone": "2348189691071" }, "meta_data":{"user_id" : "zzz001658fedf8284207866d961e83fa"} } ``` * *is\_active (bool) : When this value is `True` this means the cardholder can be issued a card.* * *is\_id\_verified (bool) : Shows you whether the user has passed ID verification* if the user failed the ID verification step, `is_active` and `is_id_verified` will be set to `False` and you cannot issue the user a card*.* πŸ”΄ 400: Invalid Cardholder ID ``` { "message": "Invalid cardholder ID, there's no cardholder with this ID." } ```
## Delete cardholder Use this API to delete a cardholder {% tabs %} {% tab title="cURL" %} ``` curl --location --request DELETE 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/delete_cardholder/e416a9a188af40b78b8afd740e835d68' \ --header 'token: Bearer xxxxx' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/delete_cardholder/e416a9a188af40b78b8afd740e835d68" payload={} headers = { 'token': 'Bearer xxxxx' } response = requests.request("DELETE", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'DELETE', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/delete_cardholder/e416a9a188af40b78b8afd740e835d68', 'headers': { 'token': 'Bearer xxxxx' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/delete_cardholder/e416a9a188af40b78b8afd740e835d68'); $request->setMethod(HTTP_Request2::METHOD_DELETE); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer xxxxx' )); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/delete_cardholder/e416a9a188af40b78b8afd740e838" method := "DELETE" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer xxxxx") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 200: cardholder details deleted successfully. ``` { "status": "success", "message": "cardholder has been deleted successfully.", "data": {} } ``` πŸ”΄ 400: Invalid Cardholder ID ``` { "message": "Invalid cardholder ID, there's no cardholder with this ID." } ```
# USD Cards All the APIs to issue and manage a card This documentation explains how you can issue USD cards to your customers, your customers can make payments worth $5,000 or $10,000 monthly (depending on the card's limit) using this card. We'll also be assuming that you have finished the integration process of [creating a cardholder](/reference/api-reference/cardholder) to continue this implementation. ## Create a card Use this endpoint to create a card for a verified cardholder. In the sandbox environment, you'll need to fund your sandbox-issuing wallet before you'll be able to create a card or fund one. You can use [this endpoint](/reference/api-reference/misc#fund-issuing-wallet) to fund your issuing wallet with some large amount that can cover you through your test. ### Mastercard Cards The Mastercard product also has two card limits, $5,000 and $10,000. To create a card with a $5,000 limit you must pre-fund the card at creation with at least $3 and to create a card with a limit of $10,000 you'll need to fund the card with at least $4 at creation. These minimum funds are held down and will be used to pay the card's Monthly maintenance fee in subsequent months. If the customer doesn't doesn't do a transaction for three months the [card eventually gets deleted](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#card_delete_event.successful) and the get card details data carries an `is_deleted` value of `true`. Before a card gets deleted we send a [webhook notification](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#card_delete_event.notification) some days before to remind the user to fund his card to avoid deletion The cards are also PIN-secured cards, so the user has to select a PIN on their card at the point of card creation. If you send an empty pin field the card's pin is defaulted to the 7th and 10th digit of the card PAN number. The pin value in the create card payload must be 4 digits and encrypted before passing it as a parameter to call the API, we use an open-source package called [AES-Anywhere](https://github.com/mervick/aes-everywhere) 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 {% tabs %} {% tab title="Python" %} ``` $ pip install aes-everywhere from AesEverywhere import aes256 # encryption encrypted = aes256.encrypt('4 digit pin', 'Bridgecard Secret Key') encrypted = encrypted.decode() print(encrypted) ``` {% endtab %} {% tab title="Nodejs" %} ``` $ npm install aes-everywhere var AES256 = require('aes-everywhere'); // or // import AES256 from 'aes-everywhere'; // encryption var encrypted = AES256.encrypt('4 digit pin', 'Bridgecard Secret Key') console.log(encrypted); ``` {% endtab %} {% tab title="PHP" %} ``` $ composer require mervick/aes-everywhere require '../../vendor/mervick/aes-everywhere/php/src/AES256.php'; use mervick\aesEverywhere\AES256; $encrypt = AES256::encrypt('4 digit pin', 'Bridgecard Secret Key') ``` {% endtab %} {% tab title="Go" %} ``` import "github.com/mervick/aes-everywhere/go/aes256" // encryption encrypted := aes256.Encrypt("4 digit pin", "Bridgecard Secret Key") ``` {% endtab %} {% endtabs %} Now that you have the encrypted PIN you can go ahead to call the API below {% tabs %} {% tab title="cURL" %} ``` curl --location --request POST 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/create_card' \ --header 'token: Bearer *****' \ --header 'Content-Type: application/json' \ --data-raw '{ "cardholder_id": "d0658fedf8284207866d96183fa", "card_type": "virtual" || "physical", "card_brand": "Mastercard", "card_currency": "USD", "card_limit": "500000" || "1000000", "transaction_reference:"", "funding_amount": "300", "pin" : "39sksksie3902023020dj03020203039", "meta_data": {"user_id": "d0658fedf828420786e4a7083fa"} }' ``` {% endtab %} {% tab title="Python" %} ```python import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/create_card" payload = json.dumps({ "cardholder_id": "d0658fedf8284207866d96183fa", "card_type": "virtual", "card_brand": "Mastercard", "card_currency": "USD", "card_limit": "500000" || "1000000", "funding_amount": "300", "pin" : "39sksksie3902023020dj03020203039", "transaction_reference":"", "meta_data": { "user_id": "d0658fedf828420786e4a7083fa" } }) headers = { 'token': 'Bearer *****', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'POST', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/create_card', 'headers': { 'token': 'Bearer *****', 'Content-Type': 'application/json' }, body: JSON.stringify({ "cardholder_id": "d0658fedf8284207866d96183fa", "card_type": "virtual", "card_brand": "Mastercard", "card_currency": "USD", "card_limit": "500000" || "1000000", "transaction_reference":"", "funding_amount": "300", "pin" : "39sksksie3902023020dj03020203039", "meta_data": { "user_id": "d0658fedf828420786e4a7083fa" } }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/create_card'); $request->setMethod(HTTP_Request2::METHOD_POST); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****', 'Content-Type' => 'application/json' )); $request->setBody('{\n "cardholder_id": "d0658fedf8284207866d96183fa",\n "card_type": "virtual",\n "card_brand": "Mastercard",\n "card_currency": "USD",\n "card_limit": "500000" || "1000000",\n "pin" : "39sksksie3902023020dj03020203039",\n "funding_amount": "300",\n "meta_data": {"user_id": "d0658fedf828420786e4a7083fa"}\n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/create_card" method := "POST" payload := strings.NewReader(`{ "cardholder_id": "d0658fedf8284207866d96183fa", "card_type": "virtual", "card_brand": "Mastercard", "card_currency": "USD", "card_limit": "500000" || "1000000", "funding_amount": "300", "transaction_reference":"", "pin" : "39sksksie3902023020dj03020203039", "meta_data": {"user_id": "d0658fedf828420786e4a7083fa"} }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Body * ``` cardholder_id : String *required ``` * ``` card_type (can either be "virtual" or "physical") : String *required ``` * ``` card_brand (can either be "Mastercard") : String *required ``` * ``` card_currency (can either be "USD") : String *required ``` * ``` card_limit (can either be $5,000 i.e "500000" or $10,000 i.e "1000000") : String *required ``` * ``` transaction_reference: *Optional ``` * ``` funding_amount (a minimum of $3 i.e "300" for cards with a spending limit of $5,000 and $4 i.e "400" for a card with a spending limit of $10,000) : String *required ``` * ``` pin (AES 256 encrypted 4 digit pin): string *required ``` * ``` meta_data : Dictionary *Optional ```
Response 🟒 200 : card creation is successful. ``` { "status": "success", "message": "The Mastercard USD card was created successfully", "data": { "card_id": "216ef11a58bf468baeb9cdbb94765865", "currency": "USD" } } ``` πŸ”΄ 400: Invalid Cardholder ID ``` { "message": "Invalid cardholder ID, there's no cardholder with this ID." } ``` πŸ”΄ 401: Cardholder has been deactivated ``` { "message": "This cardholder has been deactivated please contact admin before requesting a card." } ``` πŸ”΄ 401: Cardholder didn't pass ID verification and so can't be issued a card ``` { "message": "This cardholder has not had their ID verified yet and so cannot be issued a card." } ``` πŸ”΄ 401: Insufficient balance in your issuing wallet ``` { "message": "Please top up your USD issuing wallet, you have insufficient balance to perform this operation" } ``` πŸ”΄ 400: The requested card type is currently unavailable ``` { "message": "This card type is currently unavailable, but we're working on it." } ``` πŸ”΄ 504: We ran into an error creating the card ``` { "message": "We ran into an error running this operation, please try again." } ```
## Activate Physical Dollar Card Note: Only for physical USD cards. Use this endpoint to activate a physical card for a verified cardholder. {% tabs %} {% tab title="cURL" %} ``` curl --location --request POST 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/activate_physical_card' \ --header 'token: Bearer *****' \ --header 'Content-Type: application/json' \ --data-raw '{ "cardholder_id": "37383839939030", "card_type": "physical", "card_brand": "Mastercard", "card_currency": "USD", "card_token_number": "37383839939030", "meta_data": {} }' ``` {% endtab %} {% tab title="Python" %} ```python import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/activate_physical_card" payload = json.dumps({ "cardholder_id": "37383839939030", "card_type": "physical", "card_brand": "Mastercard", "card_currency": "USD", "card_token_number": "37383839939030", "meta_data": {} }) headers = { 'token': 'Bearer *****', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```python var request = require('request'); var options = { 'method': 'POST', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/activate_physical_card', 'headers': { 'token': 'Bearer *****', 'Content-Type': 'application/json' }, body: JSON.stringify({ "cardholder_id": "37383839939030", "card_type": "physical", "card_brand": "Mastercard", "card_currency": "USD", "card_token_number": "37383839939030", "meta_data": {} }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); pyth ``` {% endtab %} {% tab title="PHP" %} ```python setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/activate_physical_card'); $request->setMethod(HTTP_Request2::METHOD_POST); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****', 'Content-Type' => 'application/json' )); $request->setBody('{\n "cardholder_id": "d0658fedf8284207866d96183fa",\n "card_type": "physical",\n "card_brand": "Mastercard",\n "card_currency": "USD",\n "card_token_number: "38393030303030" \n"meta_data": {"user_id": "d0658fedf828420786e4a7083fa"}\n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/activate_physical_card" method := "POST" payload := strings.NewReader(`{ "cardholder_id": "37383839939030", "card_type": "physical", "card_brand": "Mastercard", "card_currency": "USD", " ": "37383839939030", "meta_data": {} }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Body * ``` cardholder_id : String *required ``` * ``` card_type (can either be "virtual" or "physical") : String *required ``` * ``` card_brand (can either be "Mastercard") : String *required ``` * ``` card_currency (can either be "USD") : String *required ``` * ``` card_token_number: 13 digit number attached to card envelope. ``` * ``` meta_data : Dictionary *Optional ```
Response 🟒 200 : card creation is in done, listen to [the webhook event](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#card_creation_event.successful) ``` { "status": "success", "message": "The Mastercard USD card creation is currently being processed, please listen to the webhook notification.", "data": { "card_id": "216ef11a58bf468baeb9cdbb94765865", "currency": "USD" } } ``` πŸ”΄ 400: Invalid Cardholder ID ``` { "message": "Invalid cardholder ID, there's no cardholder with this ID." } ``` πŸ”΄ 401: Cardholder has been deactivated ``` { "message": "This cardholder has been deactivated please contact admin before requesting a card." } ``` πŸ”΄ 401: Cardholder didn't pass ID verification and so can't be issued a card ``` { "message": "This cardholder has not had their ID verified yet and so cannot be issued a card." } ``` πŸ”΄ 401: Insufficient balance in your issuing wallet ``` { "message": "Please top up your USD issuing wallet, you have insufficient balance to perform this operation" } ``` πŸ”΄ 400: The requested card type is currently unavailable ``` { "message": "This card type is currently unavailable, but we're working on it." } ``` πŸ”΄ 504: We ran into an error creating the card ``` { "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` 2. 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`
We rate limit this endpoint once every 3 seconds for a specific card\_id(get\_card\_details) {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_details?card_id=216ef11a58bf468baeb9cdbb97777777' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_details?card_id=216ef11a58bf468baeb9cdbb97777777" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_details?card_id=216ef11a58bf468baeb9cdbb97777777', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_details?card_id=216ef11a58bf468baeb9cdbb97777777'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_details?card_id=216ef11a58bf468baeb9cdbb97777777" method := "GET" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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": "Mastercard", "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, "is_deleted": false, "issuing_app_id": "842352f4-8a6f-4a19-89c6-4e8a240a2355", "last_4": "8649", "livemode": false, "meta_data": { "user_id": "d0658fedf8284207866d961e4a7083fa" }, "balance": "900", "available_balance": "600", "book_balance": "900" "blocked_due_to_fraud": false, "pin_3ds_activated": true } } ``` πŸ”΄ 400: Invalid card ID ``` { "message": "Invalid card ID, there's no card 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 Use this API to fetch the balance of a card. We provide you with 3 balances for each card when you call this API. \ \ A. Balance: This is the total amount on a card, which includes the maintenance fee held and the amount available to spend for transactions. \ B. Book Balance: This balance is the same as the "BALANCE" field explained above. \ c. Available Balance: This is the total amount available for the user to spend and also unload from their card, it's the "BALANCE" minus the card's monthly maintenance fee held. We rate limit this endpoint once every 3 seconds for a specific card\_id(get\_card\_balance) {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_balance?card_id=216ef11a999f468baeb9cdbb94765865' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_balance?card_id=216ef11a58bf468baeb9cdbb94765865" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_balance?card_id=216ef11a58bf468baeb9cdbb94765865', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_balance?card_id=216ef11a58bf468baeb9cdbb94765865'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_balance?card_id=216ef11a58bf468baeb9cdbb94765865" method := "GET" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 200: card balance fetched successfully. ``` { "status": "success", "message": "Card balance was fetched successfully", "data": { "card_id": "216ef11a58bf468baeb9cdbb94765865", "balance": "900", "settled_available_balance": "800", "settled_book_balance": "900" } } ``` πŸ”΄ 400: Invalid Cardholder ID ``` { "message": "Invalid cardholder ID, there's no cardholder with this ID." } ``` πŸ”΄ 504: We ran into an error fetching card balance ``` { "message": "We ran into an error running this operation, please try again." ```
## Fund card You can use this endpoint to fund a card. \ PS: In the sandbox environment, you'll need to fund your sandbox-issuing wallet before you can create a card or fund one. You can use [this endpoint](/reference/api-reference/misc#fund-issuing-wallet) to fund your issuing wallet with some large amount that can cover you through your test. We rate limit this endpoint once every 5 mins for a specific card\_id(fund\_card) {% tabs %} {% tab title="cURL" %} ``` curl --location --request PATCH 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/fund_card_asynchronously' \ --header 'token: Bearer *****' \ --header 'Content-Type: application/json' \ --data-raw '{ "card_id": "216ef11a58bf468baeb9cdbb94765865", "amount": "100", "transaction_reference": "216ef11a58bf468baeb9cdbb94765865", "currency": "USD" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/fund_card_asynchronously" payload = json.dumps({ "card_id": "216ef11a58bf468baeb9cdbb94765865", "amount": "100", "transaction_reference": "216ef11a58bf468baeb9cdbb94765865", "currency": "USD" }) headers = { 'token': 'Bearer *****', 'Content-Type': 'application/json' } response = requests.request("PATCH", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'PATCH', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/fund_card_asynchronously', 'headers': { 'token': 'Bearer *****', 'Content-Type': 'application/json' }, body: JSON.stringify({ "card_id": "216ef11a58bf468baeb9cdbb94765865", "amount": "100", "transaction_reference": "216ef11a58bf468baeb9cdbb94765865", "currency": "USD" }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/fund_card_asynchronously'); $request->setMethod('PATCH'); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****', 'Content-Type' => 'application/json' )); $request->setBody('{\n "card_id": "216ef11a58bf468baeb9cdbb94765865",\n "amount": "100",\n "transaction_reference": "216ef11a58bf468baeb9cdbb94765865",\n "currency": "USD"\n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/fund_card_asynchronously" method := "PATCH" payload := strings.NewReader(`{ "card_id": "216ef11a58bf468baeb9cdbb94765865", "amount": "100", "transaction_reference": "216ef11a58bf468baeb9cdbb94765865", "currency": "USD" }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Body 
card_id : String *required
``` amount(in cents) : String *required ``` ``` transaction_reference (must be unique) : String *required ``` ``` currency: can be either "USD" String *required ```
Response 🟑 202: card funding in progress. ``` { "status": "success", "message": "Card funding in progress", "data": { "card_id": "216ef11a58bf468baeb9cdbb94765865", "transaction_reference": "216ef11a58bf468baeb9cdbb94765865" } } ``` You'll have to listen to the [success](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#card_credit_event.successful) or [failed](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#card_credit_event.failed) webhook event to know if the card was successfully funded. πŸ”΄ 420: Funding rate limit exceeded ``` { "message": "You can only fund a card once every 5 minutes, please try again later." } ``` πŸ”΄ 400: Invalid Cardholder ID ``` { "message": "Invalid cardholder ID, there's no cardholder with this ID." } ``` πŸ”΄ 400: Funding Limit Exceeded 
{
    "message": "This card can only hold a maximum balance of 5000 USD at a time."
}
πŸ”΄ 400: Transaction reference already exists ``` { "message": "This transaction reference exists please enter another reference" } ``` πŸ”΄ 401: Insufficient balance in your issuing wallet ``` { "message": "Please top up your USD issuing wallet, you have insufficient balance to perform this operation" } ``` πŸ”΄ 504: We ran into an error funding the card ``` { "message": "We ran into an error running this operation, please try again. ```
## Unload a card This endpoint allows you to withdraw funds from a card. We rate limit this endpoint once every 5 mins for a specific card\_id(unload\_card) {% tabs %} {% tab title="cURL" %} ``` curl --location --request PATCH 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/unload_card_asynchronously' \ --header 'token: Bearer ****' \ --header 'Content-Type: application/json' \ --data-raw '{ "card_id": "216ef11a58bf468baeb9cdbb965", "amount": "0", "transaction_reference": "216ef11a58bf468baeb9cdbb965", "currency": "USD" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/unload_card_asynchronously" payload = json.dumps({ "card_id": "216ef11a58bf468baeb9cdbb965", "amount": "0", "transaction_reference": "216ef11a58bf468baeb9cdbb965", "currency": "USD" }) headers = { 'token': 'Bearer *****', 'Content-Type': 'application/json' } response = requests.request("PATCH", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'PATCH', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/unload_card_asynchronously', 'headers': { 'token': 'Bearer *****', 'Content-Type': 'application/json' }, body: JSON.stringify({ "card_id": "216ef11a58bf468baeb9cdbb94765865", "amount": "0", "transaction_reference": "216ef11a58bf468baeb9cdbb94765111", "currency": "USD" }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/unload_card_asynchronously'); $request->setMethod('PATCH'); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****', 'Content-Type' => 'application/json' )); $request->setBody('{\n "card_id": "216ef11a58bf468baeb9cdbb999030",\n "amount": "0",\n "transaction_reference": "216ef11a58bf468baeb9cdbb94765111",\n "currency": "USD"\n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/unload_card_asynchronously" method := "PATCH" payload := strings.NewReader(`{ "card_id": "216ef11a58bf468baeb9cdbb94765865", "amount": "100", "transaction_reference": "216ef11a58bf468baeb9cdbb94765865", "currency": "USD" }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Body 
card_id : String *required
``` amount(in cents) : String *required ``` ``` transaction_reference (must be unique) : String *required ``` ``` currency: can be either "USD" or "NGN" String *required ```
Response 🟑 202: card unloading in progress. ``` { "status": "success", "message": "Card unloading in progress", "data": { "card_id": "b7fc2c83e96144489bdffa1f2249e2ff", "transaction_reference": "b7fc2c83e96144489bdffa1f2249e2ff0000111999111" } } ``` You'll have to listen to the [success](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#card_unload_event.successful) or [failed](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#card_unload_event.failed) webhook event to know if the card was successfully funded. πŸ”΄ 420: Withdrawal rate limit exceeded ``` { "message": "You can only withdraw from a card once every 5 minutes, please try again later." } ``` πŸ”΄ 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. } ```
## 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. {% tabs %} {% tab title="cURL" %} ``` curl --location --request PATCH 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/mock_debit_transaction' \ --header 'token: Bearer ****' \ --header 'Content-Type: application/json' \ --data-raw '{ "card_id": "216ef11a58bf468baeb9cdbb965" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/mock_debit_transaction" payload = json.dumps({ "card_id": "216ef11a58bf468baeb9cdbb965" }) headers = { 'token': 'Bearer *****', 'Content-Type': 'application/json' } response = requests.request("PATCH", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'PATCH', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/mock_debit_transaction', 'headers': { 'token': 'Bearer *****', 'Content-Type': 'application/json' }, body: JSON.stringify({ "card_id": "216ef11a58bf468baeb9cdbb94765865" }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/mock_debit_transaction'); $request->setMethod('PATCH'); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****', 'Content-Type' => 'application/json' )); $request->setBody('{\n "card_id": "216ef11a58bf468baeb9cdbb999030"\n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/mock_debit_transaction" method := "PATCH" payload := strings.NewReader(`{ "card_id": "216ef11a58bf468baeb9cdbb94765865" }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Body 
card_id : String *required
Response 🟒 200: card was funded successfully. ``` { "status": "success", "message": "Debit transaction was done Successfully", "data": { "card_id": "216ef11a58bf468baeb9cdbb94765865", "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. } ```
## Get card transactions Use this endpoint to get all the transactions on a card. 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. {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transactions?card_id=70b34986c13c4026a9c1607e27eabc49&page=1' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transactions?card_id=70b34986c13c4026a9c1607e27eabc49&page=1" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transactions?card_id=70b34986c13c4026a9c1607e27eabc49&page=1', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transactions?card_id=70b34986c13c4026a9c1607e27eabc49&page=1'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transactions?card_id=70b34986c13c4026a9c1607e27eabc49&page=1" method := "GET" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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" }, "partner_interchange_fee": "100", "interchange_revenue": "100", "partner_interchange_fee_refund": "100", "interchange_revenue_refund": "100" }, { "amount": "100", "bridgecard_transaction_reference": "370a5e491c20434dbb7dccdf1fafb9d2", "card_id": "70b34986c13c4026a9c1607e27eabc49", "card_transaction_type": "CREDIT", "cardholder_id": "d0658fedf8284207866d961e4a7083fa", "client_transaction_reference": "0906c4b453a745b8abbcf8b77b846ddd", "currency": "USD", "description": "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. We rate limit this endpoint once every 3 seconds for a specific card\_id and a unique page(get\_card\_transaction\_history) ## Get card transaction by transaction ID You can use this endpoint to get a specific transaction by the `client_transaction_reference` from a list of transactions on a card. If the transaction reference originates from Bridgecard (for example in the case of a debit transactions), you can use the `bridgecard_transaction_reference` instead. {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transaction_by_id?card_id=70b34986c13c4026a9c1607e27eabc49&client_transaction_reference=a7887279b' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transaction_by_id?card_id=70b34986c13c4026a9c1607e27eabc49&client_transaction_reference=a7887279b" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transaction_by_id?card_id=70b34986c13c4026a9c1607e27eabc49&client_transaction_reference=a7887279b', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transaction_by_id?card_id=70b34986c13c4026a9c1607e27eabc49&client_transaction_reference=a7887279b'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transaction_by_id?card_id=70b34986c13c4026a9c1607e27eabc49&client_transaction_reference=a7887279b" method := "GET" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 200: card transactions fetched successfully. ``` { "status": "success", "message": "Card transaction history was fetched successfully", "data": { "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 } } } ``` πŸ”΄ 400: Invalid card ID ``` { "message": "Invalid card ID, there's no card with this ID." } ```
## Get card transaction status You can use this endpoint to verify the status of a transaction whether funding or unloading. This way you can know if the transaction is still pending or is successful. {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transaction_status?card_id=70b34986c13c4026a9c1607e27eabc49&client_transaction_reference=a7887279b' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transaction_status?card_id=70b34986c13c4026a9c1607e27eabc49&client_transaction_reference=a7887279b" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transaction_status?card_id=70b34986c13c4026a9c1607e27eabc49&client_transaction_reference=a7887279b', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transaction_status?card_id=70b34986c13c4026a9c1607e27eabc49&client_transaction_reference=a7887279b'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_transaction_status?card_id=70b34986c13c4026a9c1607e27eabc49&client_transaction_reference=a7887279b" method := "GET" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 200: Transaction is still pending. ``` { "status": "success", "message": "Transaction status fetched successfully", "data": { "transaction_status": "PENDING" } } ``` 🟒 200: Transaction is successful. ``` { "status": "success", "message": "Transaction status fetched successfully", "data": { "transaction_status": "SUCCESSFUL" } } ``` πŸ”΄ 400: Invalid card ID ``` { "message": "Invalid transaction ID, there's no transaction with this ID or this transaction might have failed previously." } ```
## 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`. {% tabs %} {% tab title="cURL" %} ``` curl --location --request PATCH 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/freeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/freeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("PATCH", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'PATCH', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/freeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/freeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b'); $request->setMethod('PATCH'); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/freeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b" method := "PATCH" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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`. {% tabs %} {% tab title="cURL" %} ``` curl --location --request PATCH 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/unfreeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/unfreeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("PATCH", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'PATCH', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/unfreeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/unfreeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b'); $request->setMethod('PATCH'); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/unfreeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b" method := "PATCH" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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 all cardholder cards This endpoint returns all the cards assigned to a cardholder in a list. {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cardholder_cards?cardholder_id=d0658fedf82861e4a7083fa' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cardholder_cards?cardholder_id=d0658fedf82861e4a7083fa" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cardholder_cards?cardholder_id=d0658fedf82861e4a7083fa', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cardholder_cards?cardholder_id=d0658fedf82861e4a7083fa'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cardholder_cards?cardholder_id=d0658fedf82861e4a7083fa" method := "GET" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 200: All the cards the cardholder has have been fetched successfully. ``` { "status": "success", "message": "All the cards for this cardholder have been fetched successfully", "data": { "cards": [ { "billing_address": { "billing_address1": "256 Chapman Road STE 105-4", "billing_city": "Newark", "billing_country": "US", "billing_zip_code": "19702", "country_code": "US" }, "brand": "Mastercard", "card_currency": "USD", "card_id": "5334986c13c4026a9c160eabc49", "card_name": "John Doe", "card_number": "ev:RFVC:/k2ywhfd6puozkZx:A23n3EoM5dZwHG24zaS+meBBIbgJ03OCfO6GnFSPl5tS:1BLgOZHre56P9DPkhqHJJaifHnlvzGzQ5sSrn+xWcT8:$", "card_type": "virtual", "cardholder_id": "d0658fedf828420761e4a7083fa", "created_at": 1659826136, "cvv": "ev:RFVC:5ek3QdaiLFvaL4md:A23n3EoM5dZwHG24zaS+meBBIbgJ03OCfO6GnFSPl5tS:aI3XxL+A54ZITT9/zPjV11J0yA:$", "expiry_month": "ev:RFVC:gDwn8Kqsg9rmVSeK:A23n3EoM5dZwHG24zaS+meBBIbgJ03OCfO6GnFSPl5tS:QpMwLxi1g+uVpB88+XKtg6Dp:$", "expiry_year": "ev:RFVC:bOzx6EkH6brriobW:A23n3EoM5dZwHG24zaS+meBBIbgJ03OCfO6GnFSPl5tS:mKtDnYDJ9pdoa2Pz01gl4qEDLB4:$", "is_active": true, "issuing_app_id": "842352f4-8a6f-4a19-89c6-40a2355", "last_4": "8623", "livemode": false }, { "billing_address": { "billing_address1": "256 Chapman Road STE 105-4", "billing_city": "Newark", "billing_country": "US", "billing_zip_code": "19702", "country_code": "US" }, "brand": "Mastercard", "card_currency": "USD", "card_id": "216ef11a58bf468bdbb94765865", "card_name": "John Doe", "card_number": "ev:RFVC:x9Fyh+9rI0BekZ5i:AgQHRjIQa7BzqhGXYuZwV/lXqiTb8Uq07nBYWWbuu46I:XXbJWyrBwDicifdA3exFewXRLSnR71whuMYKMhj5FVA:$", "card_type": "virtual", "cardholder_id": "d0658fedf828420761e4a7083fa", "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-40a2355", "last_4": "8649", "livemode": false } ], "total": 2 } } ``` πŸ”΄ 400: Invalid Cardholder ID ``` { "message": "Invalid cardholder ID, there's no cardholder with this ID." } ```
## Delete a card This endpoint allows you to delete a card and unassign it from a cardholder. \ \ Please note that before you delete a card you'll need to unload the card first so that you don't lose the funds on the card. {% tabs %} {% tab title="cURL" %} ``` curl --location --request DELETE 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/delete_card/44faae6059834696b2ad9eecc94ca955' \ --header 'accept: application/json' \ --header 'token: Bearer at_live_***' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/delete_card/44faae6059834696b2ad9eecc94ca955" payload = {} headers = { 'accept': 'application/json', 'token': 'Bearer at_live_***' } response = requests.request("DELETE", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'DELETE', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/delete_card/44faae6059834696b2ad9eecc94ca955', 'headers': { 'accept': 'application/json', 'token': 'Bearer at_live_***' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/delete_card/44faae6059834696b2ad9eecc94ca955'); $request->setMethod(HTTP_Request2::METHOD_DELETE); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'accept' => 'application/json', 'token' => 'Bearer at_live_***' )); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/delete_card/44faae6059834696b2ad9eecc94ca955" method := "DELETE" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } req.Header.Add("accept", "application/json") req.Header.Add("token", "Bearer at_live_***") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 200: card was deleted successfully. ``` { "status": "success", "message": "This card has been deleted successfully", "data": {} } ``` πŸ”΄ 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." } ```
## Migrate a card (Deprecated ) This endpoint allows you to migrate a card across our supported card brands i.e from Visa to Mastercard. We automatically default your users card pin to the 7th to 10th characters of your their card number if you don't send a PIN field in the API call. {% tabs %} {% tab title="cURL" %} ``` curl --location --request POST 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/migrate_card' \ --header 'token: Bearer *****' \ --header 'Content-Type: application/json' \ --data-raw '{ "cardholder_id": "d0658fedf8284207866d96183fa", "card_id": "d0658feddddf8284207866d96183fa", "card_type": "virtual" || "physical", "target_card_brand": "Mastercard", "target_card_currency": "USD", "card_limit": "500000" || "1000000", "pin" : "39sksksie3902023020dj03020203039", }' ``` {% endtab %} {% tab title="Python" %} ```python import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/migrate_card" payload = json.dumps({ "cardholder_id": "d0658fedf8284207866d96183fa", "card_id": "d0658fedf8284207866d96183fa", "card_type": "virtual", "target_card_brand": "Mastercard", "target_card_currency": "USD", "card_limit": "500000" || "1000000", "pin" : "39sksksie3902023020dj03020203039", }) headers = { 'token': 'Bearer *****', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'POST', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/migrate_card', 'headers': { 'token': 'Bearer *****', 'Content-Type': 'application/json' }, body: JSON.stringify({ "cardholder_id": "d0658fedf8284207866d96183fa", "card_id": "d0658fedf8284207866d96183fa", "card_type": "virtual", "target_card_brand": "Mastercard", "target_card_currency": "USD", "card_limit": "500000" || "1000000", "pin" : "39sksksie3902023020dj03020203039", }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/migrate_card'); $request->setMethod(HTTP_Request2::METHOD_POST); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****', 'Content-Type' => 'application/json' )); $request->setBody('{\n "cardholder_id": "d0658fedf8284207866d96183fa",\n "card_id": "d0658fedf8284207866d96183fa",\n "card_type": "virtual",\n "target_card_brand": "Mastercard",\n "target_card_currency": "USD",\n "pin" : "39sksksie3902023020dj03020203039",\n}'); try { $response = $request->send(); if ($response->getStatus() == 201) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/create_card" method := "POST" payload := strings.NewReader(`{ "cardholder_id": "d0658fedf8284207866d96183fa", "card_id": "d0658fedf8284207866d96183fa", "card_type": "virtual", "target_card_brand": "Mastercard", "target_card_currency": "USD", "card_limit": "500000" || "1000000", "pin" : "39sksksie3902023020dj03020203039", }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Body * 
cardholder_id : String *required
* 
card_type (can either be "virtual" or "physical") : String *required
* 
target_card_brand (which is "Mastercard") : String *required
* ``` target_card_currency (can either be "USD" or "NGN") : String *required ``` * ``` card_limit (can either be $5,000 i.e "500000" or $10,000 i.e "1000000") : String *required ``` * ``` pin (AES 256 encrypted 4 digit pin): string *required ``` * ``` card_id : String *required ```
Response 🟒 201 : The card migration request is currently processing and you will be notified via webhook ``` { "status": "success", "message": "The card migration request is currently processing and you will be notified via webhook.", "data": {} } ```
## Update card pin Use this endpoint to update the card pin, incase the user wants to change their pin at creation or if they forget it.\ \ The card pin should be encrypted before calling this API, we use an open-source package called [AES-Anywhere](https://github.com/mervick/aes-everywhere) for this.\ \ See Examples Below {% tabs %} {% tab title="Python" %} ``` $ pip install aes-everywhere from AesEverywhere import aes256 # encryption encrypted = aes256.encrypt('3d secure pin', 'Bridgecard Secret Key') encrypted = encrypted.decode() print(encrypted) ``` {% endtab %} {% tab title="Nodejs" %} ``` $ npm install aes-everywhere var AES256 = require('aes-everywhere'); // or // import AES256 from 'aes-everywhere'; // encryption var encrypted = AES256.encrypt('3d secure pin', 'Bridgecard Secret Key') console.log(encrypted); ``` {% endtab %} {% tab title="PHP" %} ``` $ composer require mervick/aes-everywhere require '../../vendor/mervick/aes-everywhere/php/src/AES256.php'; use mervick\aesEverywhere\AES256; $encrypt = AES256::encrypt('3d secure pin', 'Bridgecard Secret Key') ``` {% endtab %} {% tab title="Go" %} ``` import "github.com/mervick/aes-everywhere/go/aes256" // encryption encrypted := aes256.Encrypt("3d secure pin", "Bridgecard Secret Key") ``` {% endtab %} {% endtabs %} Then use the encrypted details to call the API below {% tabs %} {% tab title="cURL" %} ``` curl --location --request POST 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/update_card_pin' \ --header 'token: Bearer *****' \ --header 'Content-Type: application/json' \ --data-raw '{ "card_id": "8389303030030c460e9250", "card_pin": "encrypted pin" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/set_3d_secure_pin" payload = json.dumps({ "card_id": "8389303030030c460e9250", "card_pin": "encrypted pin" }) headers = { 'token': 'Bearer *****', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'POST', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/set_3d_secure_pin', 'headers': { 'token': 'Bearer *****', 'Content-Type': 'application/json' }, body: JSON.stringify({ "card_id": "8389303030030c460e9250", "card_pin": "encrypted pin" }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); p ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/set_3d_secure_pin'); $request->setMethod(HTTP_Request2::METHOD_POST); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****', 'Content-Type' => 'application/json' )); $request->setBody('{\n "card_id": "8389303030030c460e9250",\n "card_pin": "encrypted pin"\n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage( ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/set_3d_secure_pin" method := "POST" payload := strings.NewReader(`{ "card_id": "8389303030030c460e9250", "card_pin": "encrypted pin" }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Body * ``` card_id : String *required ``` * ``` card_pin : 4 digits number *required ```
Response 🟒 201 : 3d secure pin has been updated ``` { "status": "success", "message": "The card pin for this card has been updated successfully", "data": {} } ``` πŸ”΄ 400: Invalid Card ID ``` { "message": "Invalid card ID, there's no card with this ID." } ```
## Managing Declines A card that has up to 15 consecutive declines due to insufficient balance, would be deleted on the 15th decline. For each of the declines, we will send you this [webhook](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#card_debit_event.declined) event and the decline reason (decline\_reason). In the case of these transactions will be "Insufficient balance to pay the merchant charge and transaction fee for this transaction, please top up your card and try again." If a card ends up being deleted because it violated this rule, you'll get this [webhook](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#card_delete_event.successful) event and the number of declines will reset every time the user funds the card. A card that has a negative balance and another merchant or the same merchant processes another negative transaction to that same card, that card would also be deleted as well. If a card ends up being deleted because it violated this rule, you'll get this [webhook](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#card_delete_event.successful) event. # 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](/reference/api-reference/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](https://github.com/mervick/aes-everywhere) 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 {% tabs %} {% tab title="Python" %} ``` $ pip install aes-everywhere from AesEverywhere import aes256 # encryption encrypted = aes256.encrypt('4 digit pin', 'Bridgecard Secret Key') encrypted = encrypted.decode() print(encrypted) ``` {% endtab %} {% tab title="Nodejs" %} ``` $ npm install aes-everywhere var AES256 = require('aes-everywhere'); // or // import AES256 from 'aes-everywhere'; // encryption var encrypted = AES256.encrypt('3d secure pin', 'Bridgecard Secret Key') console.log(encrypted); ``` {% endtab %} {% tab title="PHP" %} ``` $ composer require mervick/aes-everywhere require '../../vendor/mervick/aes-everywhere/php/src/AES256.php'; use mervick\aesEverywhere\AES256; $encrypt = AES256::encrypt('3d secure pin', 'Bridgecard Secret Key') ``` {% endtab %} {% tab title="Go" %} ``` import "github.com/mervick/aes-everywhere/go/aes256" // encryption encrypted := aes256.Encrypt("3d secure pin", "Bridgecard Secret Key") ``` {% endtab %} {% endtabs %} Then use the encrypted details to call the API below {% tabs %} {% tab title="curl" %} 
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"}
}'
{% endtab %} {% tab title="Python" %} ```python import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/create_card" payload = json.dumps({ "cardholder_id": "d0658fedf8284207866d96183fa", "card_type": "virtual" || "physical", "card_brand": "Mastercard", "card_currency": "NGN", "pin" : "39sksksie3902023020dj03020203039", "nin": "22236748901", "meta_data": {"user_id": "d0658fedf828420786e4a7083fa"} }) headers = { 'accept': 'application/json', 'token': 'Bearer ******', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="NodeJS" %} ```javascript var request = require('request'); var options = { 'method': 'POST', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/create_card', 'headers': { 'accept': 'application/json', 'token': 'Bearer ******', 'Content-Type': 'application/json' }, body: JSON.stringify({ "cardholder_id": "d0658fedf8284207866d96183fa", "card_type": "virtual" || "physical", "card_brand": "Mastercard", "card_currency": "NGN", "pin" : "39sksksie3902023020dj03020203039", "nin": "22236748901", "meta_data": {"user_id": "d0658fedf828420786e4a7083fa"} }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/create_card'); $request->setMethod(HTTP_Request2::METHOD_POST); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'accept' => 'application/json', 'token' => 'Bearer ******', 'Content-Type' => 'application/json' )); $request->setBody('{\n "cardholder_id": "d0658fedf8284207866d96183fa",\n "card_type": "virtual" || "physical",\n "card_brand": "Mastercard",\n "card_currency": "NGN",\n "meta_data": {"user_id": "d0658fedf828420786e4a7083fa"}\n}, \n"pin" : "39sksksie3902023020dj03020203039", \n"nin" : "22236748901"'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/create_card" method := "POST" payload := strings.NewReader(`{ "cardholder_id": "d0658fedf8284207866d96183fa", "card_type": "virtual" || "physical", "card_brand": "Mastercard", "card_currency": "NGN", "pin" : "39sksksie3902023020dj03020203039", "nin": "22236748901", "meta_data": {"user_id": "d0658fedf828420786e4a7083fa"} }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("accept", "application/json") req.Header.Add("token", "Bearer ******") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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` 2. 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` {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_details?card_id=216ef11a58bf468baeb9cdbb97777777' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_details?card_id=216ef11a58bf468baeb9cdbb97777777" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_details?card_id=216ef11a58bf468baeb9cdbb97777777', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_details?card_id=216ef11a58bf468baeb9cdbb97777777'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_card_details?card_id=216ef11a58bf468baeb9cdbb97777777" method := "GET" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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. {% tabs %} {% tab title="curl" %} ``` 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 *******' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/get_card_balance?cardholder_id=12jjh2h2bcasdsjhds8s7ssd" payload={} headers = { 'accept': 'application/json', 'token': 'Bearer *******' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="NodeJS" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/get_card_balance?cardholder_id=12jjh2h2bcasdsjhds8s7ssd', 'headers': { 'accept': 'application/json', 'token': 'Bearer *******' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/get_card_balance?cardholder_id=12jjh2h2bcasdsjhds8s7ssd'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'accept' => 'application/json', 'token' => 'Bearer *******' )); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/get_card_balance?cardholder_id=12jjh2h2bcasdsjhds8s7ssd" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } req.Header.Add("accept", "application/json") req.Header.Add("token", "Bearer *******") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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` {% tabs %} {% tab title="curl" %} ``` 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_****' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/naira_cards/get_otp_message?card_id=f1a33838939393d33939939e5999&amount=1000" payload = {} headers = { 'accept': 'application/json', 'token': 'Bearer at_live_****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="NodeJS" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/naira_cards/get_otp_message?card_id=f1a33838939393d33939939e5999&amount=1000', 'headers': { 'accept': 'application/json', 'token': 'Bearer at_live_****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/naira_cards/get_otp_message?card_id=f1a33838939393d33939939e5999&amount=1000'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'accept' => 'application/json', 'token' => 'Bearer at_live_****' )); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/naira_cards/get_otp_message?card_id=f1a33838939393d33939939e5999&amount=1000" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } req.Header.Add("accept", "application/json") req.Header.Add("token", "Bearer at_live_****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#naira_card_credit_event.successful) or [failed](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#naira_card_credit_event.failed). {% tabs %} {% tab title="curl" %} ``` 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" }' ``` {% endtab %} {% tab title="Python" %} ``` import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/naira_cards/fund_naira_card" payload = json.dumps({ "card_id": "dsjdg7d8s7d78s8auhdskd", "amount": "100", "transaction_reference": "473783839939393030" }) headers = { 'accept': 'application/json', 'token': 'Bearer ********', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="NodeJS" %} ``` var request = require('request'); var options = { 'method': 'POST', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/naira_cards/fund_naira_card', 'headers': { 'accept': 'application/json', 'token': 'sdssda', 'Content-Type': 'application/json' }, body: JSON.stringify({ "card_id": "dsjdg7d8s7d78s8auhdskd", "amount": "100", "transaction_reference": "473783839939393030" }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ``` setUrl('https://issuecards.api.bridgecard.co/v1/issuing/naira_cards/fund_naira_card'); $request->setMethod(HTTP_Request2::METHOD_POST); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'accept' => 'application/json', 'token' => 'sdssda', 'Content-Type' => 'application/json' )); $request->setBody('{ \n "card_id": "dsjdg7d8s7d78s8auhdskd", \n "amount": "100", \n "transaction_reference": "473783839939393030" \n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ``` package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/naira_cards/fund_naira_card" method := "POST" payload := strings.NewReader(`{`+" "+` "card_id": "dsjdg7d8s7d78s8auhdskd",`+" "+` "amount": "100",`+" "+` "transaction_reference": "473783839939393030"`+" "+` }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("accept", "application/json") req.Header.Add("token", "sdssda") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#naira_card_unload_event.successful) or [failed](https://docs.bridgecard.co/reference/api-reference/pages/MZdzG9LSiDrdbNFKhcny#naira_card_credit_event.failed). {% tabs %} {% tab title="curl" %} ``` 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" }' ``` {% endtab %} {% tab title="Python" %} ``` import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/naira_cards/unload_naira_card" payload = json.dumps({ "card_id": "dsjdg7d8s7d78s8auhdskd", "amount": "100", "transaction_reference": "473783839939393030" }) headers = { 'accept': 'application/json', 'token': 'Bearer ********', 'Content-Type': 'application/json' } response = requests.request("PATCH", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="NodeJS" %} ``` var request = require('request'); var options = { 'method': 'PATCH', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/naira_cards/unload_naira_card', 'headers': { 'accept': 'application/json', 'token': 'sdssda', 'Content-Type': 'application/json' }, body: JSON.stringify({ "card_id": "dsjdg7d8s7d78s8auhdskd", "amount": "100", "transaction_reference": "473783839939393030" }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ``` setUrl('https://issuecards.api.bridgecard.co/v1/issuing/naira_cards/unload_naira_card'); $request->setMethod(HTTP_Request2::METHOD_PATCH); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'accept' => 'application/json', 'token' => 'sdssda', 'Content-Type' => 'application/json' )); $request->setBody('{ \n "card_id": "dsjdg7d8s7d78s8auhdskd", \n "amount": "100", \n "transaction_reference": "473783839939393030" \n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ``` package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/naira_cards/unload_naira_card" method := "PATCH" payload := strings.NewReader(`{`+" "+` "card_id": "dsjdg7d8s7d78s8auhdskd",`+" "+` "amount": "100",`+" "+` "transaction_reference": "473783839939393030"`+" "+` }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("accept", "application/json") req.Header.Add("token", "sdssda") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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. {% tabs %} {% tab title="cURL" %} ``` 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" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/mock_debit_naira_card" payload = json.dumps({ "card_id": "216ef11a58bf468baeb9cdbb965", "amount": "0", "transaction_reference": "216ef11a58bf468baeb9cdbb965", "currency": "USD" }) headers = { 'token': 'Bearer *****', 'Content-Type': 'application/json' } response = requests.request("PATCH", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'PATCH', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/mock_debit_naira_card', 'headers': { 'token': 'Bearer *****', 'Content-Type': 'application/json' }, body: JSON.stringify({ "card_id": "216ef11a58bf468baeb9cdbb94765865", "amount": "0", "transaction_reference": "216ef11a58bf468baeb9cdbb94765111", "currency": "USD" }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/mock_debit_naira_card'); $request->setMethod('PATCH'); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****', 'Content-Type' => 'application/json' )); $request->setBody('{\n "card_id": "216ef11a58bf468baeb9cdbb999030",\n "amount": "0",\n "transaction_reference": "216ef11a58bf468baeb9cdbb94765111",\n "currency": "USD"\n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/mock_debit_naira_card" method := "PATCH" payload := strings.NewReader(`{ "card_id": "216ef11a58bf468baeb9cdbb94765865", "amount": "100", "transaction_reference": "216ef11a58bf468baeb9cdbb94765865", "currency": "USD" }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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`. {% tabs %} {% tab title="cURL" %} ``` curl --location --request PATCH 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/freeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/freeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("PATCH", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'PATCH', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/freeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/freeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b'); $request->setMethod('PATCH'); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/freeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b" method := "PATCH" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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`. {% tabs %} {% tab title="cURL" %} ``` curl --location --request PATCH 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/unfreeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/unfreeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("PATCH", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'PATCH', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/unfreeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/unfreeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b'); $request->setMethod('PATCH'); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/naira_cards/unfreeze_card?card_id=3d0220250f6b4addbfef1c5ffa39250b" method := "PATCH" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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. {% tabs %} {% tab title="cURL" %} ``` 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 '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_naira_card_transactions?card_id=70b34986c13c4026a9c1607e27eabc49&page=1" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_naira_card_transactions?card_id=70b34986c13c4026a9c1607e27eabc49&page=1', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_naira_card_transactions?card_id=70b34986c13c4026a9c1607e27eabc49&page=1'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_naira_card_transactions?card_id=70b34986c13c4026a9c1607e27eabc49&page=1" method := "GET" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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. # Misc Miscellaneous APIs that we think you might find useful Get all cardholders You can use this endpoint to get all the cardholders that have been created in your account. {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cardholder?page=1' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cardholder?page=1" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cardholder?page=1', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cardholder?page=1'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cardholder?page=1" method := "GET" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 200: All issued cards have been fetched successfully ``` { "status": "success", "message": "All your cardholders have been fetched successfully", "data": { "cardholders": [ { "address": { "address": "9 Jibowu Street", "city": "Aba North", "country": "nigeria", "house_no": "13", "lga": "Aba North", "postal_code": "1000242", "state": "Abia" }, "cardholder_id": "7da652e1bfc349d996dbfb811e1f3b45", "created_at": 1659921383, "email_address": "festusowumi@gmail.com", "first_name": "John", "identity_details": { "blacklisted": false, "date_of_birth": "1999-02-04", "first_name": "John", "gender": "Male", "id_no": "22222222222", "id_type": "NIGERIAN_NIN", "last_name": "Doe", "phone": "08123456789" }, "is_active": true, "is_id_verified": true, "issuing_app_id": "842352f4-8a6f-4a19-89c6-4e8a240a2355", "last_name": "Doe", "phone": "2348164881733" }, { "address": { "address": "9 Jibowu Street", "city": "Aba North", "country": "nigeria", "house_no": "13", "lga": "Aba North", "postal_code": "1000242", "state": "Abia" }, "cardholder_id": "13404fa9c96a4c43b7f0016b6243ace2", "created_at": 1659920777, "email_address": "festusowumi@gmail.com", "first_name": "John", "identity_details": { "blacklisted": false, "date_of_birth": "1999-02-04", "first_name": "John", "gender": "Male", "id_no": "22222222222", "id_type": "NIGERIAN_NIN", "last_name": "Doe", "phone": "08123456789" }, "is_active": true, "is_id_verified": true, "issuing_app_id": "842352f4-8a6f-4a19-89c6-4e8a240a2355", "last_name": "Doe", "phone": "2348135471627" } ], "meta": { "total": 2, "pages": 1, "previous": null, "next": null } } } ```
## Get all issued cards This endpoint returns a list of all the cards that you have issued on your account {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cards?page=1' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cards?page=1" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cards?page=1', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cards?page=1'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_all_cards?page=1" method := "GET" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 200: All issued cards have been fetched successfully ``` { "status": "success", "message": "All your issued cards have been fetched successfully", "data": { "cards": [ { "billing_address": { "billing_address1": "256 Chapman Road STE 105-4", "billing_city": "Newark", "billing_country": "US", "billing_zip_code": "19702", "country_code": "US" }, "brand": "Mastercard", "card_currency": "USD", "card_id": "70b34986c13c4026a999999e27eabc49", "card_name": "John Doe", "card_number": "ev:RFVC:/k2ywhfd6puozkZx:A23n3EoM5dZwHG24zaS+meBBIbgJ03OCfO6GnFSPl5tS:1BLgOZHre56P9DPkhqHJJaifHnlvzGzQ5sSrn+xWcT8:$", "card_type": "virtual", "cardholder_id": "d0658fedf82866d9699999083fa", "created_at": 1659826136, "cvv": "ev:RFVC:5ek3QdaiLFvaL4md:A23n3EoM5dZwHG24zaS+meBBIbgJ03OCfO6GnFSPl5tS:aI3XxL+A54ZITT9/zPjV11J0yA:$", "expiry_month": "ev:RFVC:gDwn8Kqsg9rmVSeK:A23n3EoM5dZwHG24zaS+meBBIbgJ03OCfO6GnFSPl5tS:QpMwLxi1g+uVpB88+XKtg6Dp:$", "expiry_year": "ev:RFVC:bOzx6EkH6brriobW:A23n3EoM5dZwHG24zaS+meBBIbgJ03OCfO6GnFSPl5tS:mKtDnYDJ9pdoa2Pz01gl4qEDLB4:$", "is_active": true, "issuing_app_id": "842352f4-8a6f-4a19-89c6-999940a2355", "last_4": "8623", "livemode": false, "meta_data": null }, { "billing_address": { "billing_address1": "256 Chapman Road STE 105-4", "billing_city": "Newark", "billing_country": "US", "billing_zip_code": "19702", "country_code": "US" }, "brand": "Mastercard", "card_currency": "USD", "card_id": "581b044df66a4a428bc9999915655e8e", "card_name": "John Doe", "card_number": "ev:RFVC:Gh4YvEoa8/Ua8gtC:AyY2y7CaFrWCiWB7GZKI4+w/b4kLhyQaP4r0/hsVSOB/:dGwEilDdCqrdBKjFyKzkBToxefEpCguuF+rRfFsJfCo:$", "card_type": "virtual", "cardholder_id": "d0658fedf82842079999961e4a7083fa", "created_at": 1659746672, "cvv": "ev:RFVC:3AlzAf1BTFg2SYYG:AyY2y7CaFrWCiWB7GZKI4+w/b4kLhyQaP4r0/hsVSOB/:9O7on5JfbNcyhpo2Ggp97+A8wQ:$", "expiry_month": "ev:RFVC:8m9dVKhiQNVbmJtL:AyY2y7CaFrWCiWB7GZKI4+w/b4kLhyQaP4r0/hsVSOB/:ieCzK8W29dimD8k8aPCC4ama:$", "expiry_year": "ev:RFVC:i1L76Uhr2nicnoRV:AyY2y7CaFrWCiWB7GZKI4+w/b4kLhyQaP4r0/hsVSOB/:39Qlfqi7eQWiqFqMTqfZ8mgzj40:$", "is_active": true, "issuing_app_id": "842352f4-8a6f-4a19-89c6-440a2355", "last_4": "8615", "livemode": false, "meta_data": { "user_id": "d0658fedf8284207866d96083fa" } } ], "meta": { "total": 2, "pages": 1, "previous": null, "next": null } } } ```
## Fund issuing wallet SANDBOX You can use this endpoint to credit your issuing wallet with some fake money in the sandbox environment. {% tabs %} {% tab title="cURL" %} ``` curl --location --request PATCH 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/fund_issuing_wallet?currency=NGNorUSD' \ --header 'token: Bearer *****' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": "0" }' ``` {% endtab %} {% tab title="Python" %} ```python import requests import json url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/fund_issuing_wallet?currency=NGNorUSD" payload = json.dumps({ "amount": "0" }) headers = { 'token': 'Bearer *****', 'Content-Type': 'application/json' } response = requests.request("PATCH", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'PATCH', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/fund_issuing_wallet?currency=NGNorUSD', 'headers': { 'token': 'Bearer *****', 'Content-Type': 'application/json' }, body: JSON.stringify({ "amount": "0", "currency": "NGN or USD" }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/fund_issuing_wallet?currency=NGNorUSD'); $request->setMethod('PATCH'); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****', 'Content-Type' => 'application/json' )); $request->setBody('{\n "amount": "0"\n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/fund_issuing_wallet?currency=NGNorUSD" method := "PATCH" payload := strings.NewReader(`{ "amount": "0" }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") req.Header.Add("Content-Type", "application/json") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Body
Response 🟒 200: card was funded successfully. ``` { "status": "success", "message": "Your issuing wallet was funded successfully", "data": {} } ```
PRODUCTION To begin the process of funding your account in production: 1. Login to your dashboard. 2. Click the + icon on your production wallet on your dashboard to begin the transfer process.
Note: We now support funding your production account automatically in USDT, XAF and UGX. ## Get issuing wallet balance You can use this wallet to fetch the current balance on your issuing wallet. {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_issuing_wallet_balance' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_issuing_wallet_balance" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_issuing_wallet_balance', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_issuing_wallet_balance'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cards/get_issuing_wallet_balance" method := "GET" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 200: Issuing wallet balance has been fetched successfully ``` { "status": "success", "message": "Your issuing wallet balance has been fetched successfully", "data": { "issuing_balance_USD": "23750" } } ```
## Get FX rate This endpoint provides you with the rates at which we perform trades from local currencies to the USD. This endpoint is rate limited once every minute(fx\_rate). {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/cards/fx-rate' \ --header 'accept: application/json' \ --header 'token: Bearer xxxxx' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/cards/fx-rate" payload={} headers = { 'accept': 'application/json', 'token': 'Bearer xxxxx' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/cards/fx-rate', 'headers': { 'accept': 'application/json', 'token': 'Bearer xxxxx' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/cards/fx-rate'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'accept' => 'application/json', 'token' => 'Bearer xxxxx' )); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/cards/fx-rate" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } req.Header.Add("accept", "application/json") req.Header.Add("token", "Bearer xxxxx") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 200 : states fetched successfully ``` { "status": "success", "message": "Rate fetched successfully", "data": { "NGN-USD": 74100 } } ```
## Get all states This endpoint provides you with a list of states under a country. {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/get_all_states?country=Nigeria' \ --header 'accept: application/json' \ --header 'token: Bearer at_live_****' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/get_all_states?country=Nigeria" payload={} headers = { 'accept': 'application/json', 'token': 'Bearer at_live_****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/get_all_states?country=Nigeria', 'headers': { 'accept': 'application/json', 'token': 'Bearer at_live_****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/get_all_states?country=Nigeria'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'accept' => 'application/json', 'token' => 'Bearer at_live_****' )); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/get_all_states?country=Nigeria" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } req.Header.Add("accept", "application/json") req.Header.Add("token", "Bearer at_live_****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 201 : states fetched successfully ``` { "status": "success", "message": "States fetched successfully", "data": { "states": [ "Abuja", "Abia", "Adamawa", "Akwa Ibom", "Anambra", "Bauchi", "Bayelsa", "Benue", "Borno", "Cross River", "Delta", "Ebonyi", "Edo", "Ekiti", "Enugu", "Gombe", "Imo", "Jigawa", "Kaduna", "Kano", "Katsina", "Kebbi", "Kogi", "Kwara", "Lagos", "Nasarawa", "Niger", "Ogun", "Ondo", "Osun", "Oyo", "Plateau", "Rivers", "Sokoto", "Taraba", "Yobe", "Zamfara" ] } } ```
## Get card details using Token You can also generate card details using a secure token and in a PCIDSS-compliant way, so you can stay out of scope and not interface with the user's sensitive card details. Please see the steps below. 1. Your client side application should make a request to your backend asking it for a token that it can use to view the users card details. 2. Your backend will authorize this request and then make an API call to Bridgecard's API to get a onetime token, valid for 5mins to view the card details. Your backend can request for this token from Bridgecard by calling this endpoint. {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/cards/generate_token_for_card_details?card_id=38f18939933303039393' \ --header 'token: Bearer *****' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/cards/generate_token_for_card_details?card_id=38f18939933303039393" payload = "" headers = { 'token': 'Bearer *****' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/cards/generate_token_for_card_details?card_id=38f18939933303039393', 'headers': { 'token': 'Bearer *****' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/cards/generate_token_for_card_details?card_id=38f18939933303039393'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer *****' )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/cards/generate_token_for_card_details?card_id=38f18939933303039393" method := "GET" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer *****") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 200: Card token generated successfully. ``` { "status": "success", "message": "Card token generated successfully, token is only valid for 5 minutes.", "data": { "token": "bd8dc269872144f5b122da743277d470" } } ``` πŸ”΄ 400: Invalid card ID ``` { "message": "Invalid card ID, there's no card with this ID." } ``` πŸ”΄ 504: We ran into an error creating the card ``` { "message": "We ran into an error running this operation, please try again." ```
3. Your backend should send your client-side application this token as a response. 4. Your client side will then make a request to Bridgecard's API to fetch the decrypted details, using the endpoint below. {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/cards/get_card_details_from_token?token=6419a7034aa44f1c886a2ade32a97436' \ --data-raw '' ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/cards/get_card_details_from_token?token=6419a7034aa44f1c886a2ade32a97436" payload = "" response = requests.request("GET", url, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/cards/get_card_details_from_token?token=6419a7034aa44f1c886a2ade32a97436', }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/cards/get_card_details_from_token?token=6419a7034aa44f1c886a2ade32a97436'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setBody(''); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://issuecards-api-bridgecard-co.relay.evervault.com/v1/issuing/cards/get_card_details_from_token?token=6419a7034aa44f1c886a2ade32a97436" method := "GET" payload := strings.NewReader(``) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
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": "Mastercard", "card_currency": "USD", "card_id": "216ef11a58bf468baeb9cdbb947", "card_name": "John Doe", "card_number": "5484383833932345", "card_type": "virtual", "cardholder_id": "d0658fedf8284207866d961e4a7083fa", "created_at": 1659958652, "cvv": "123", "expiry_month": "04", "expiry_year": "2024", "is_active": true, "is_deleted": false, "issuing_app_id": "842352f4-8a6f-4a19-89c6-4e8a240a2355", "last_4": "8649", "livemode": false, "meta_data": { "user_id": "d0658fedf8284207866d961e4a7083fa" }, "balance": "900", "available_balance": "600", "book_balance": "900" "blocked_due_to_fraud": false, "pin_3ds_activated": true } } ``` πŸ”΄ 400: Invalid card ID ``` { "message": "Invalid card ID, there's no card with this ID." } ``` πŸ”΄ 504: We ran into an error creating the card ``` { "message": "We ran into an error running this operation, please try again." ```
# Webhook events ## Webhook authentication We've taken some steps to secure webhook communications, so you can always verify that a webhook event came from us and not from a malicious party. Below are the steps you need to follow to verify that a webhook event came from Bridgecard. STEP 1: Access your webhook secret from your dashboard (live\_webhook\_secret\_key or test\_webhook\_secret\_key depending on the environment)
STEP 2: Whenever you get a webhook event from Bridgecard, extract the x-webhook-signature header and decrypt it using your secret key (live\_secret\_key / test\_secret\_key depending on the environment) {% tabs %} {% tab title="Python" %} ``` $ pip install aes-everywhere from AesEverywhere import aes256 # decryption decrypted = aes256.decrypt('x-webhook-signature value', 'Bridgecard Secret Key') decrypted = decrypted.decode() print(decrypted) ``` {% endtab %} {% tab title="NodeJS" %} ``` $ npm install aes-everywhere var AES256 = require('aes-everywhere'); // or // import AES256 from 'aes-everywhere'; // decryption var decrypted = AES256.decrypt('webhook secret', 'Bridgecard Secret Key') console.log(decrypted); ``` {% endtab %} {% tab title="PHP" %} ``` $ composer require mervick/aes-everywhere require '../../vendor/mervick/aes-everywhere/php/src/AES256.php'; use mervick\aesEverywhere\AES256; $decrypt = AES256::decrypt('webhook secret', 'Bridgecard Secret Key') ``` {% endtab %} {% tab title="Go" %} ``` import "github.com/mervick/aes-everywhere/go/aes256" // decryption decrypted := aes256.Decrypt("webhook secret", "Bridgecard Secret Key") ``` {% endtab %} {% endtabs %} STEP 3: Compare the decrypted string with your webhook secret key from STEP 1. If they are the same, then it is a valid webhook event sent from us. ## All webhook events These are the list of webhook events triggered when you communicate with our APIs. ### cardholder\_verification.successful This webhook event is sent when a user has passed the ID verification process ``` { "event": "cardholder_verification.successful", "data" : { "cardholder_id": "859505050505", "is_active": true, "livemode": false, "issuing_app_id": "9ujinoncpsni3943198393939930ke" } } ``` ### cardholder\_verification.failed This webhook event is sent when a user has failed the ID verification process ``` { "event": "cardholder_verification.failed", "data" : { "cardholder_id": "859505050505", "is_active": true, "livemode": false, "issuing_app_id": "9ujinoncpsni3943198393939930ke", "error_description": "the user passed an invalid ID number" } } ``` ### card\_creation\_event.successful We send this webhook event when a card is successfully created ``` { "event": "card_creation_event.successful", "data" : { "card_id": "859505050505", "cardholder_id": "859505050505", "currency": "USD", "issuing_app_id": "9ujinoncpsni3943198393939930ke", "livemode": True "meta_data": {"user_id": "d0658fedf828420786e4a7083fa"} } } ``` ### card\_creation\_event.failed This webhook event is sent when we can't complete your request to create a card. ``` { "event": "card_creation_event.failed", "data" : { "card_id": "859505050505", "cardholder_id": "859505050505", "currency": "USD", "issuing_app_id": "9ujinoncpsni3943198393939930ke", "livemode": True, "reason": "The user failed our second stage KYC verification for fraud detection, please contact admin." } } ``` ### card\_credit\_event.successful We send this webhook event when a successful credit transaction happens on a USD card. ``` { "event": "card_credit_event.successful", "data" : { "card_id": "859505050505", "cardholder_id": "859505050505", "amount": "100", "currency": "USD", "transaction_reference":"859505050505", "livemode": false, "issuing_app_id": "9ujinoncpsni3943198393939930ke", "card_transaction_type": "CREDIT", "transaction_date": "2022-09-28 23:10:45", "transaction_timestamp": "1664406645", "settled_available_balance":"500", "settled_book_balance":"400" } } ``` ### card\_credit\_event.failed We send this webhook event when a card funding transaction fails on a USD card. ``` { "event": "card_credit_event.failed", "data" : { "card_id": "859505050505", "cardholder_id": "859505050505", "amount": "100", "currency": "USD", "transaction_reference":"859505050505", "livemode": false, "issuing_app_id": "9ujinoncpsni3943198393939930ke", "card_transaction_type": "CREDIT", "transaction_date": "2022-09-28 23:10:45", "transaction_timestamp": "1664406645" } } ``` ### card\_unload\_event.successful You get this webhook event when an unload transaction is successful on a USD card. ``` { "event": "card_unload_event.successful", "data" : { "card_id": "859505050505", "cardholder_id": "859505050505", "amount": "100", "description": "Virtual dollar card unloading", "currency": "USD", "transaction_reference":"859505050505", "livemode": false, "issuing_app_id": "9ujinoncpsni3943198393939930ke", "card_transaction_type": "DEBIT", "transaction_date": "2022-09-28 23:10:45", "transaction_timestamp": "1664406645" } } ``` ### card\_unload\_event.failed You get this webhook event when an unload transaction on a USD card fails. ``` { "event": "card_unload_event.failed", "data" : { "card_id": "859505050505", "cardholder_id": "859505050505", "amount": "100", "description": "Virtual dollar card unloading", "currency": "USD", "transaction_reference":"859505050505", "livemode": false, "issuing_app_id": "9ujinoncpsni3943198393939930ke", "card_transaction_type": "DEBIT", "transaction_date": "2022-09-28 23:10:45", "transaction_timestamp": "1664406645" } } ``` ### card\_debit\_event.successful You get this webhook event when a debit transaction happens on a USD card. ``` { "event": "card_debit_event.successful", "data" : { "card_id": "859505050505", "cardholder_id": "859505050505", "amount": "100", "description": "Amazon US", "currency": "USD", "transaction_reference":"859505050505", "livemode": false, "issuing_app_id": "9ujinoncpsni3943198393939930ke", "card_transaction_type": "DEBIT", "merchant_category_code": "12345 can be None", "transaction_date": "2022-09-28 23:10:45", "transaction_timestamp": "1664406645", "settled_available_balance":"500", "settled_book_balance":"400" } } ``` ### card\_debit\_event.declined We send this webhook event whenever there's a declined transaction on the user's USD card. ``` { "data": { "amount": "100", "card_id": "06246484994004040404efcf", "cardholder_id": "06246484994004040404efcf", "currency": "USD", "decline_reason": "Transaction is not permitted. Please confirm that the billing address you're using is 256 Chapman Road STE 105-4, Newark, 19702, Delaware (DE) and try again. Also confirm from support if our cards work on this platform.", "description": "APPLE ECOM FBILL APPLE ECOM FBILL 866 D712 D7753", "issuing_app_id": "5b29cbe5b29cbe5b29cbe5b29cbe5b29cbe", "livemode": true, "transaction_date": "2024-02-27 19:54:51", "transaction_reference": "3cdee95e5e0c883cdee95e5e0c883cdee95e5e0c883cdee95e5e0c88", "transaction_timestamp": "1709063691" }, "event": "card_debit_event.declined" } ``` ### card\_declined\_transaction\_fee\_charge\_event.successful(Deprecated) We send this webhook event when the declined transaction fee on a user's card has been charged. ``` { 'event': 'card_declined_transaction_fee_charge_event.successful, 'data': { 'card_id': '8eedfssfee443rffd1cb5e', 'cardholder_id': 'bfgg8eedfssfee443rffd1cb5e', 'currency': 'USD', 'amount': '30', 'transaction_date': '2021-11-15 17:13:19', 'transaction_timestamp': '1636996399', 'transaction_reference': '859505050505', 'livemode': True, 'issuing_app_id': 'c6424f3c-1708-4386-9406-b20da7f4d6b9', 'transaction_date': '2022-09-28 23:10:45', 'transaction_timestamp': '1664406645', 'card_transaction_type': 'DEBIT' } } ``` ### card\_reversal\_event.successful This webhook event is triggered whenever a user USD card gets a reversal from a merchant that they previously got debited from. ``` { "event": "card_reversal_event.successful", "data": { "card_id": "a303fb8b7a0e476fbc910671ca952b74", "cardholder_id": "9b78a44ccdf848fd860f75fd5c117d9d", "amount": "100", "currency": "USD", "transaction_reference": "22597F3D-A7A5-4C9B-B9DF-B7D918EE8241_REVERSAL", "transaction_date": "2022-09-28 23:10:45", "transaction_timestamp": "1664406645", "livemode": true, "issuing_app_id": "c6424f3c-1708-4386-9406-b20da7f4d6b9", "card_transaction_type": "CREDIT" } } ``` ### card\_delete\_event.notification This webhook event is triggered to notify a user that he doesn't have enough funds to pay the maintenance fee due in the subsequent month and his card will be automatically deleted in some days. ``` { "event": "card_delete_event.notification", "data" : { "card_id": "859505050505", "cardholder_id": "859505050505", "currency": "USD", "issuing_app_id": "9ujinoncpsni3943198393939930ke", "potential_delete_date": "2022-09-28 23:10:45", "livemode": True } } ``` ### card\_delete\_event.successful This webhook event is triggered whenever a user's USD card gets deleted.\ Note: USD Mastercard gets deleted if a user doesn't have enough balance to pay for the next month's monthly maintenance fee. ``` { "event": "card_delete_event.successful", "data" : { "card_id": "859505050505", "cardholder_id": "859505050505", "currency": "USD", "issuing_app_id": "9ujinoncpsni3943198393939930ke", "livemode": True, "balance": "400", "reason": "" // can be None. } } ``` ### **3d\_secure\_otp\_event.generated** \[Deprecated] This webhook event is sent when a user attempts a transaction online and he's sent an OTP to confirm the transaction. ``` { "event": "3d_secure_otp_event.generated", "data": { "card_id": "86a19202202002020251i292", "cardholder_id": "86a19202202002020251i292", "otp": "430854", "merchant_name": "BRIDGECARD", "amount": "300", "currency": "USD", "last_four_digits": "4804", "issuing_app_id": "198286a192020251i292b01ab", "livemode": true, "transaction_date": "2023-02-02 23:49:00", "transaction_timestamp": "1675381740" } } ``` Note: This API is currently deprecated. To get OTP for transactions on the Mastercard kindly call the transaction history API to fetch the OTP for that current transaction. Here is a sample. In this example, the OTP required for FACEBOOK is CB966S3VM2
### **card\_maintenance\_fee\_debit\_event.successful** We send this webhook event whenever when we deduct the monthly card maintenance fee from the card. ``` { "event": "card_maintenance_fee_debit_event.successful", "data": { "card_id": "38f155a93148", "cardholder_id": "08ceb6a9", "amount": "100", "currency": "USD", "transaction_date": "2023-04-30 11:21:18", "transaction_timestamp": "1682853678", "livemode": true, "issuing_app_id": "e9ab", "card_transaction_type": "DEBIT" } } ``` ### card\_freezed\_due\_to\_30\_days\_inactivity\_event.successful This webhook event is sent when a user's card has been blocked because he hasn't done any transactions in the last 30 days. ``` { "event": "card_freezed_due_to_30_days_inactivity_event.successful", "data": { "card_id": "38f155a9314838f155a93148", "cardholder_id": "08ceb6a908ceb6a908ceb6a9", "livemode": true, "issuing_app_id": "e9ab08ceb6a908ceb6a908ceb6a9", "block_reason": "The user has not made any transactions in the last 30 days." } } ``` ### card\_flagged\_due\_to\_suspiscion\_of\_fraud.activated This webhook event is sent when a user's card has been blocked due to suspicion of fraudulent activity. We'll have to manually review this case and make a final decision, you can reach out to support in this case. ``` { "event": "card_flagged_due_to_suspiscion_of_fraud.activated", "data": { "card_id": "38f155a9314838f155a93148", "cardholder_id": "08ceb6a908ceb6a908ceb6a9", "livemode": true, "issuing_app_id": "e9ab08ceb6a908ceb6a908ceb6a9", "reason": "This card has been flagged due to suspicion of fraudulent transactions." } } ``` ### naira\_card\_credit\_event.successful We send this webhook event when a successful credit transaction happens on a Naira card. ``` { "event":"naira_card_credit_event.successful", "data":{ "card_id":"1104776035", "transaction_reference":"190220249992843051", "cardholder_id":"016ff9d57b314d57aab3cfaf22f53840", "currency":"NGN", "issuing_app_id":"e98260dc-747f-4fa8-8b6c-4704a89b01ab", "livemode":false, "amount":"500", "transaction_reference": "57b314d57aab3016ff9d57b314d57aa", "transaction_type":"CREDIT", "transaction_date": "2022-09-28 23:10:45", "transaction_timestamp": "1664406645" } } ``` ### naira\_card\_credit\_event.failed We send this webhook event when a credit transaction fails on a Naira card. ``` { "event":"naira_card_credit_event.failed", "data":{ "card_id":"1104776035", "transaction_reference":"190220249992843051", "cardholder_id":"016ff9d57b314d57aab3cfaf22f53840", "currency":"NGN", "issuing_app_id":"e98260dc-747f-4fa8-8b6c-4704a89b01ab", "livemode":false, "amount":"500", "transaction_reference": "57b314d57aab3016ff9d57b314d57aa", "transaction_type":"CREDIT", "transaction_date": "2022-09-28 23:10:45", "transaction_timestamp": "1664406645" } } ``` ### naira\_card\_unload\_event.successful You get this webhook event when an unload transaction is successful on a Naira card. ``` { "event":"naira_card_unload_event.successful", "data":{ "card_id":"1104776035", "transaction_reference":"190220249992843051", "cardholder_id":"016ff9d57b314d57aab3cfaf22f53840", "currency":"NGN", "issuing_app_id":"e98260dc-747f-4fa8-8b6c-4704a89b01ab", "livemode":false, "amount":"500", "transaction_reference": "57b314d57aab3016ff9d57b314d57aa", "transaction_type":"DEBIT", "transaction_date": "2022-09-28 23:10:45", "transaction_timestamp": "1664406645" } } ``` ### naira\_card\_unload\_event.failed You get this webhook event when an unload transaction failed on a Naira card. ``` { "event":"naira_card_unload_event.failed", "data":{ "card_id":"1104776035", "transaction_reference":"190220249992843051", "cardholder_id":"016ff9d57b314d57aab3cfaf22f53840", "currency":"NGN", "issuing_app_id":"e98260dc-747f-4fa8-8b6c-4704a89b01ab", "livemode":false, "amount":"500", "transaction_reference": "57b314d57aab3016ff9d57b314d57aa", "transaction_type":"DEBIT", "transaction_date": "2022-09-28 23:10:45", "transaction_timestamp": "1664406645" } } ``` ### naira\_card\_debit\_event.successful You get this webhook event when an debit transaction is successful on a Naira card. ``` { "event":"naira_card_debit_event.successful", "data":{ "cardholder_id":"30429e8efce74ad3a0b2df8bf9189136", "amount":"57272", "currency":"NGN", "is_successful":true, "transaction_type":"DEBIT", "transaction_reference":"0603202499930495", "issuing_app_id":"ef4ad945-e99b-4507-8609-709b144f77d4", "livemode":false, "description":"POINT OF SALE PURCHASE TRANSACTION POS@<99999999> <284118000200925> <520360/129268> ", "transaction_timestamp":1709688060, "is_card":true, "transaction_date":"2024-03-06 02:21:00", "enriched_transaction":{ "transaction_category":"Media", "transaction_group":"Non-Essential Expenses", "merchant_name":"Apple", "merchant_logo":"https://logos.ntropy.com/apple.com", "merchant_website":"apple.com", "merchant_city":"None", "is_recurring":true, "merchant_code":"None" } } } ``` ### naira\_card\_debit\_event.declined You get this webhook event when a debit transaction is declined on a Naira card. ``` { "event":"naira_card_debit_event.declined", "data":{ "cardholder_id":"30429e8efce74ad3a0b2df8bf9189136", "amount":"57272", "currency":"NGN", "is_successful":true, "transaction_type":"DEBIT", "transaction_reference":"0603202499930495", "issuing_app_id":"ef4ad945-e99b-4507-8609-709b144f77d4", "livemode":false, "description":"POINT OF SALE PURCHASE TRANSACTION POS@<99999999> <284118000200925> <520360/129268> ", "transaction_timestamp":1709688060, "is_card":true, "transaction_date":"2024-03-06 02:21:00", "enriched_transaction":{ "transaction_category":"Media", "transaction_group":"Non-Essential Expenses", "merchant_name":"Apple", "merchant_logo":"https://logos.ntropy.com/apple.com", "merchant_website":"apple.com", "merchant_city":"None", "is_recurring":true, "merchant_code":"None" } } } ``` ### naira\_account\_credit\_event.successful This webhook event is sent when a user's naira account is credited ``` { 'event': 'naira_account_credit_event.successful', 'data': { 'transaction_reference': '100720239194959', 'cardholder_id': '019349be694f4daea1a9b04c0', 'currency': 'NGN', 'issuing_app_id': 'e98260dc-sdfdsf-wewcw2-8b6c-4704a89b01ab', 'livemode': False, 'amount': '995000', 'description': 'VPS TRANSFERS TRANSFER FROM JOHN DOE TO BRIDGECARD(Bridgecard) 99**92 Wallet fund ', 'transaction_type': 'CREDIT' } } ``` ### naira\_account\_transfer\_event.successful This webhook event is sent when a user's naira account debit transaction is successful ``` { "event":"naira_account_transfer_event.successful", "data":{ "cardholder_id": "48499494", "amount": "995000", "currency":"NGN", "is_successful": true, "transaction_type": "DEBIT", "recipient_account_number":"5403200440", "recipient_bank_code":"0184", "transaction_reference":"100343243439991194959", "livemode": true, "issuing_app_id":"e982-4fa8-8b6c-47b01ab", } } ``` ### naira\_account\_transfer\_event.failed This webhook event is sent when a user's naira account debit transaction fails ``` { "event":"naira_account_transfer_event.failed", "data":{ "cardholder_id": "48499494", "amount": "995000", "currency":"NGN", "is_successful": true, "transaction_type": "DEBIT", "recipient_account_number":"5403200440", "recipient_bank_code":"0184", "transaction_reference":"100343243439991194959", "livemode": true, "issuing_app_id":"e982-4fa8-8b6c-47b01ab", } } ``` ### rewards\_event.claimed This webhook event is sent when a user claims a reward via the rewards service. ``` { "event": "rewards_event.claimed", "data": { "coupon_code": "25FY1SL4O9DI", "created_on": "19/08/2023", "description": "Women Leggings Black White", "downvotes": 0, "is_available": true, "merchant": "Aliexpress", "reward_id": "JDDDNDNDNDND", "reward_type": "PROMO_CODE", "success_record": 0, "upvotes": 0, "valid_till": 1694818799, "valid_till_date": "15/09/2023", "cardholder_id": "48499494", }, } ``` ### card\_migration\_event.successful (Deprecated) We send this webhook event when a card is successfully migrated ``` { "event": "card_migration_event.successful", "data" : { "card_id": "859505050505", "cardholder_id": "859505050505", "currency": "USD", "issuing_app_id": "9ujinoncpsni3943198393939930ke", "livemode": True } } ``` ### cardholder\_verification.manual\_review This webhook event is sent when a cardholder KYC fails and is subject to manual review within 24 hours. ``` { "event": "cardholder_verification.manual_review", "data" : { "cardholder_id": "859505050505", "is_active": False, "issuing_app_id": "9ujinoncpsni3943198393939930ke", "livemode": True, } } ``` ### card\_migration\_event.failed (Deprecated) This webhook event is sent when we can't complete your request to migrate a card. ``` { "event": "card_creation_event.failed", "data" : { "card_id": "859505050505", "cardholder_id": "859505050505", "currency": "USD", "issuing_app_id": "9ujinoncpsni3943198393939930ke", "livemode": True, "reason": "You don't have sufficient funds to create a card with this limit, you need to fund with up to $3 to create a card with a $5,000 limit and up to $4 for a card with $10,000 limit." } } ``` ### Issuing\_account\_topup.successful This webhook is sent after a successful top-up on your issuing wallet. ``` { "environment": β€œproduction”, "issuing_app_id": β€œ9ujinoncpsni3943198393939930ke”, "data": { "event": "issuing_account_topup.successful", "data": { "amount_topped_up_in_cents": 200 }, }, } ``` ### card\_negative\_balance\_event.notification This webhook is sent when a card recieves a transaction update and the card balance goes into negative. Imagine your card has only a $10 balance. If you book an Uber ride with an estimated cost of $10, the ride cost is authorized and debited from your card right away. However, if an unforeseen event, like an accident, extends the ride and the cost increases to $15, the final amount will be adjusted during the settlement stage (typically within 0-3 days). In this case, the transaction amount will update to $15, resulting in a $5 negative balance on your card. Uber reserves the right to apply this negative balance to the card. ``` { "event": "card_negative_balance_event.notification", "data": { "card_id": "637387383939ee3003838033", "cardholder_id": "637387383939ee3003838033", "currency": "USD", "issuing_app_id": "637387383939ee3003838033", "livemode": true, "merchant_name": "FACEBK *HDB9XEQ9S2 Dublin " } } ``` # Rate Limit To improve clarity on usage limits, we have Rate Limits on some of our endpoint. This section will outline the rate limits applied across our endpoints, detailing the maximum number of requests allowed within specific timeframes (e.g., per minute, hour, or day). Including this information helps you to your users API requests effectively and avoid potential rate limit errors. Additionally, we will add a note under each endpoint in the documentation specifying its rate limits. This ensures that you understand the limits specific to each endpoint at a glance as well. These are the Rate Limits we have: \ **Get\_card\_details**: once every 3 seconds for a specific **Card\_id get\_card\_balance**: once every 3 seconds for a specific **Card\_id get\_card\_transaction\_history**: once every 3 seconds for a specific card\_id and a unique page **Fund\_card:** once every 5 mins for a specific card\_id unload\_card: once every 5 mins for a specific **Card\_id register\_cardholder:** a cardholder can only retry his KYC once every minute **Fx\_rate**: once every minute # KYC requirements for all countries We support the on-boarding of cardholders from multiple countries, below is the list of all the countries we support and what the identity object during cardholder registration should look like, but countries that are not listed should use the rest of the world payload below. ### **Angola** ``` "identity": { "id_type": "Angola_NATIONAL_ID", "id_no": "", "id_image": "", "selfie_image": "", "back_id_image": "" //not required for passports } ``` ### **Ghana** ``` "identity": { "id_type": "GHANIAN_SSNIT" or "GHANIAN_VOTERS_ID" or "GHANIAN_DRIVERS_LICENSE" or "GHANIAN_INTERNATIONAL_PASSPORT" or "GHANIAN_GHANA_CARD", "id_no": "32747711121", "id_image": "https://image.com", "selfie_image": "https://image.com" } ``` ### **Kenya** ``` "identity": { "id_type": "KENYAN_NATIONAL_ID" or "KENYAN_ALIEN_CARD" or "KENYAN_PASSPORT" or "KENYAN_REFUGEE_ID" or "KENYAN_DRIVERS_LICENSE", "id_no": "", "id_image": "", "selfie_image": "", "back_id_image": "" //not required for passports } ``` ### **Nigeria** 
"identity": {
    "id_type": "NIGERIAN_BVN_VERIFICATION",
    "bvn": "22222222222222",
    "selfie_image": "https://image.com"
}

"identity": {
    "id_type": "NIGERIAN_NIN" or β€œNIGERIAN_DRIVERS_LICENSE",
    β€œid_image”: "",
    "bvn": "22222222222222",
    β€œback_id_image”: β€œβ€ // not required for passport 
    "selfie_image": "https://image.com"
    "id_no": "32747711121"
}


PASSPORT VERIFICATION FOR BUSINESS ACCOUNTS

"identity": {    
    "id_type": "NIGERIAN_INTERNATIONAL_PASSPORT",
    "id_no": "32747711121",
    "id_image": "https://id_image",
    "selfie_image": "https://image.com",
    "bvn": "2222222222222"
 }
### **South Africa** ``` "identity": { "id_type": "SOUTHAFRICAN_NATIONAL_ID" or "SOUTHAFRICAN_PASSPORT" or "SOUTHAFRICAN_GREEN_BOOK" or "SOUTHAFRICAN_RESIDENT_CARD" or "SOUTHAFRICAN_DRIVERS_LICENSE", "id_no": "", "id_image": "", "selfie_image": "", "back_id_image": "" //not required for passports } ``` ### Uganda ``` "identity": { "id_type": "UGANDA_VOTERS_ID" or "UGANDA_PASSPORT" or "UGANDA_NATIONAL_ID" or "UGANDA_DRIVERS_LICENSE", "id_no": "", "id_image": "", "selfie_image": "", "back_id_image": "" //not required for passports } ``` ### Zambia ``` "identity": { "id_type": "ZAMBIA_INTERNATIONAL_PASSPORT" or "ZAMBIA_DRIVERS_LICENSE" or "ZAMBIA_RESIDENCE_CARD", "id_no": ", "id_image": "", "selfie_image": "", "back_id_image": "" //not required for passports } ``` ### Zimbabwe ``` "identity": { "id_type": "ZIMBABWE_DRIVERS_LICENSE" or "ZIMBABWE_PASSPORT" or "ZIMBABWE_NATIONAL_ID" or "ZIMBABWE_RESIDENT_CARD" or "ZIMBABWE_VOTER_ID", "id_no": "", "id_image": "", "selfie_image": "", "back_id_image": "" //not required for passports } ``` ### Rest of the World ``` --data-raw '{ "first_name": "John", "last_name": "Doe", "address": { "address": , "city": , "state": || , "country": , "postal_code": "", "house_no": "", "phone": "", "email_address": "" }, "identity": { "id_type": "REST_OF_THE_WORLD_INTERNATIONAL_PASSPORT" or "REST_OF_THE_WORLD_DRIVERS_LICENSE" or "REST_OF_THE_WORLD_NATIONAL_ID", "id_no": ", "id_image": " || ", "selfie_image": " || ", "back_id_image": " ||

Transaction history page revamped using transaction enrichment.

This way your frontend end developer can move your transaction history page from what you currently have to something beautiful and readable like the image above. This can significantly improve your user experience and might be another reason why your customers will pick you instead of a competition. ### **DISPLAYING SPENDING GRAPHS** numbersWouldn't it be great if you could show your users graphs and charts that better interpret their spending to them rather than random numbers flying around. This way your users can know how much they spend on entertainment, food, transportation, etc. We have designed a web page that you can integrate into your mobile app or website as a webview, without having to design a graph yourself. You just have to set up a frame for a webview on your app and render our URL, while we handle displaying the graph to your users, the graphs are also very interactive. Here's how to set it up. **STEP 1:** You'll need to generate a token from your backend using your card\_id and API key, this token is what you'll send to your client-side app (Mobile or Web app). So you'll need to create an endpoint on your backend where what it does is send a token to your client-side when they want to display the graphs to your user. Here's the API to do this {% tabs %} {% tab title="cURL" %} 
curl --location 'https://issuecards.api.bridgecard.co/v1/issuing/cards/generate_token_for_card_details?card_id=b7fc2fa1f2249e2ff' \
--header 'token: Bearer at_live_xxxxx'
{% endtab %} {% tab title="Python" %} ```python import requests url = "https://issuecards.api.bridgecard.co/v1/issuing/cards/generate_token_for_card_details?card_id=b7fc2fa1f2249e2ff" payload = {} headers = { 'token': 'Bearer at_live_xxxxx' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Nodejs" %} ```javascript var request = require('request'); var options = { 'method': 'GET', 'url': 'https://issuecards.api.bridgecard.co/v1/issuing/cards/generate_token_for_card_details?card_id=b7fc2fa1f2249e2ff', 'headers': { 'token': 'Bearer at_live_xxxxx' } }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://issuecards.api.bridgecard.co/v1/issuing/cards/generate_token_for_card_details?card_id=b7fc2fa1f2249e2ff'); $request->setMethod(HTTP_Request2::METHOD_GET); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'token' => 'Bearer at_live_xxxxx' )); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://issuecards.api.bridgecard.co/v1/issuing/cards/generate_token_for_card_details?card_id=b7fc2fa1f2249e2ff" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } req.Header.Add("token", "Bearer at_live_xxxxx") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %}
Response 🟒 200: card token generated successfully. ``` { "status": "success", "message": "Card token generated successfully, token is only valid for 5 minutes.", "data": { "token": "0d225cfe23e8496e84d8caa8c3ac3618" } } ``` πŸ”΄ 400: Invalid card ID ``` { "message": "Invalid card ID, there's no card with this ID." } ```
Note: This token is only valid for 5 minutes and also for one-time use **STEP 2:** Now that your client-side has a valid token they can compose a url using this format [`https://bridgecard.cards/transaction-graphs?card_token=&chart_type=`](https://bridgecard.cards/transaction-graphs/?card_token=%3Ccard%20token%3E\&chart_type=%3Ctype%20of%20chart%3E)and render this url in a webview. The variable `` is where your client-side will use the token they got from the backend in step 1 above and for `` the current valid values are `bar_chart` or `pie_chart` Eventually, you can render graphs looking like this. **Bar Chart**

A bar chart with transactions categorized

Interactive view when you hover around each bar

**Pie Chart**

Pie chart showing transactions categorized

We hope you love this and that your users love it more !!!!. # Potential Spend Notification (Beta) Let's help you predict when next your users will spend! πŸ’° The Potential Spend Notification (PSN) notifies you as a company when your users will spend next after a successful purchase. Using this information, you can deploy various strategies to nudge the user towards spending on your platform and not taking your revenue elsewhere. ## How it works The PSN feature uses a machine learning model applied to your users' transactions to predict when next a user will spend on that card based on previous spending patterns.\ \ After a successful prediction, you will be notified via a webhook of the predictions.\ \ Our model makes the prediction as a probability of the user's next spend falling within either of three categories.\ \ The categories include:\ \ 1\. zero\_class\_prob : This gives a probability that the card will next spend within a week. 2\. first\_class\_prob : This gives a probability that the card will next spend within 7-30 days.\ \ 3\. second\_class\_prob : This gives a probability that the card will next spend after a period of 30 days. ## How can you integrate It's very simple! All you have to do is listen to the webhook below.\ \ \ **potential\_spend\_notification.predicted** ``` { "event": "potential_spend_notification.predicted", "data" : { "card_id": e81a6c7952fb4a90a2f7b13aecc6f010, "first_class_prob": 1.56, "second_class_prob": 70.65, "zero_class_prob": 27.79, "issuing_app_id": b31c7cd1-80c0-451e-845f-20e83bb1307d, } } ``` ## Caveat This feature is still in beta and we currently have an average of 60% accuracy on our predictions. We will however be shipping updates to the feature sequentially to improve the accuracy and experience for you. As such, kindly give us feedback on your preferred communication channel and we'd be glad to review it so that we ultimately make this experience as seamless as possible.\ \ \ Now it's time to chase down those customers for your revenue! Godspeed.