UfitPay Virtual Card API is designed for developers and fintechs to easily issue and manage NGN and USD virtual cards for their users from any application using any software programing technology or development platform
Access to this API is available to all registered UfitPay wallets and merchants. A UfitPay wallet must be connected to your merchant account for billing purposes in order to access this API as a merchant. You will likely need access to a web developer or programmer (if you’re not one) to get the most use out of UfitPay API.
All requests to this API require HTTP Header Authentication over TLS (HTTPS).
To authenticate your request, you need to pass the following parameters as part of your HTTP request headers;
Api-Key: Your merchant or wallet API key
API-Token: Your merchant or wallet API token
Note! When using merchant credentials, the merchant account must be connected to a UfitPay wallet before it can interact with our cards API. Check Our API Introductory Section for more information on how to link a wallet to your merchant account
The following API Credentials can be used for development and test purpose only. Transactions done using these credentials are not treated as live
Test API Key: VENDWCB5TO5RfJFCNkwSX8z0F8ZwD91
Test API Token: VENDuEwtekJEcWiwzC1gDdiDzKcJFk1
When interacting with our card APIs, the funds as well as any applicable issuing fees will be debited from your UfitPay balance. If you are using merchant API credentials, the billing wallet connected to your merchant account would be debited. Check Our Pricing Section for more information about our card charges and rates
Our Naira MasterCard and VISA 3d Dollar cards are accepted on almost every platform that supports a virtual card, while our regular VISA cards are accepted on over 4,000 platforms and website around the world. We have compiled a long list of platforms our Regular VISA card has been tested on; here.
UfitPay cards can be used to make payments in any country. However, we can only issue our cards to users from the following countries;
- Nigeria
- Kenya
- Ghana
- Ivory Coast
- South Africa
- Sierra Leone
- Togo
- Senegal
- Cameroon
- India
- United States
- United Kindom
- Algeria
- Netherland
- Brazil
- Morocco
This API allows you to retrieve the current exchange rate from UfitPay server. This endpoint is accessed by making an HTTP POST request to
| Request Body Parameters | |
| currency (string) | (required) This is the currency to get exchange rate in naira for. Supported values are USD and EUR only |
Sample success response (json)
{
"resource": "get_exchange_rate",
"status":"success",
"data": {
"currency":"USD",
"exchange_rate": "412.00"
}
}
This API allows you create a new card holder's account. This endpoint is accessed by making an HTTP POST request to
| Request Body Parameters | |
| first_name (string) | (required) This is the card holder's first name |
| last_name (string) | (required) This is the card holder's last name |
| email (string) | (required) This is the card holder's email address (This will be used for OTP delivery is supported) |
| phone (string) | (required) This is the card holder's mobile phone number (This will be used for OTP delivery is supported) |
| address (string) | (required) This is the card holder's street address |
| state (string) | (required) This is the card holder's state (e.g. New York, Lagos, etc) |
| country (string) | (required) This is the card holder's country (e.g. Nigeria, United State, etc) |
| postal_code (string) | (required) This is the card holder's valid ZIP or Postal code for the state. You can use our ZIP / Postal Code Lookup API to get this value |
| kyc_method (string) | (required) This is the prefered method to use for the card-holder's identity verification. Supported values are SELFIE_IMAGE (Nigeria only), NIGERIAN_NIN, NIGERIAN_INTERNATIONAL_PASSPORT, NIGERIAN_PVC, NIGERIAN_DRIVERS_LICENSE, KENYAN_PASSPORT, KENYAN_NATIONAL_ID, INDIA_NATIONAL_ID, TOGO_NATIONAL_ID, KENYAN_NATIONAL_ID, CAMEROON_NATIONAL_ID, CAMEROON_PASSPORT, TOGO_PASSPORT, SIERRA_LEONE_NATIONAL_ID, SIERRA_LEONE_PASSPORT, SENEGAL_ECOWAS_ID, INDIA_PASSPORT, BRAZIL_PASSPORT, UNITED_STATES_INTERNATIONAL_PASSPORT, UNITED_STATES_RESIDENCE_CARD, UNITED_KINGDOM_INTERNATIONAL_PASSPORT, ALGERIA_PASSPORT, GHANIAN_INTERNATIONAL_PASSPORT, IVORYCOAST_PASSPORT, SOUTHAFRICAN_PASSPORT, MOROCCO_PASSPORT, NETHERLAND_PASSPORT |
| bvn (string) | (required only if kyc_method is either "NIGERIAN_DRIVERS_LICENSE", "NIGERIAN_PVC", "NIGERIAN_INTERNATIONAL_PASSPORT", "NIGERIAN_NIN" or "SELFIE_IMAGE") This is the card holder's BVN |
| selfie_image (string) | (required only if kyc_method is SELFIE_IMAGE) This is the remote URL to the card holder's Pasport-sized Photo or selfie clearly showing the card holder's face. The image shoiuld be captured with a camera under bright condition. Only PNG and JPG images are allowed |
| id_image (string) | (required for every other kyc_method except for SELFIE_IMAGE) This is the remote image URL to the card-holder's ID card. Only PNG and JPG images are allowed |
| back_id_image (string) | (required only if kyc_method is either KENYAN_NATIONAL_ID, UNITED_STATES_RESIDENCE_CARD, INDIA_NATIONAL_ID, TOGO_NATIONAL_ID, KENYAN_NATIONAL_ID, CAMEROON_NATIONAL_ID, SIERRA_LEONE_NATIONAL_ID or SENEGAL_ECOWAS_ID) This is the remote image URL to the back of the card-holder's ID card. Only PNG and JPG images are allowed |
| id_number (string) | (required for every other kyc_method except for SELFIE_IMAGE) This is the card holder's ID Number. |
Note: ID images must be neatly captured with all text clearly readable. All file URL must be accessible via https and on a publicly domain on the internet
Sample success response (json)
{
"resource": "create_card_holder",
"status":"success",
"data": {
"card_holder_id":"GupJFog3iyv32fsu22uc282",
"first_name": "John",
"last_name": "Doe",
"status": "active"
}
}
This API allows you delete a card holder's account. This endpoint is accessed by making an HTTP POST request to
Note: You can only delete a card holder when there are no active cards under it's account
| Request Body Parameters | |
| card_holder_id (string) | (required) This is the card_holder_id of the card holder to be deleted |
Sample success response (json)
{
"resource": "delete_card_holder",
"status":"success",
"data": {
"card_holder_id":"GupJFog3iyv32fsu22uc282",
"status": "deleted"
}
}
This API allows you issue a new virtual NGN or USD card to your customer. This endpoint is accessed by making an HTTP POST request to
Note: You are now required to create a card holder for the user first (if you haven't done so already), then pass the card holder's ID under card_holder_id
| Request Body Parameters | |
| card_brand (string) | (required) This is the brand of virtual card you wish to create. Supported values are "mastercard" and "visa" only |
| card_currency (string) | (required) This is the currency for the new card. Supported values are "NGN" and "USD" only. |
| amount (string) | (optional) This is the amount to be prefunded in the card's currency (eg. amount in NGN for naira cards or amount in USD for dollar cards). This should be above 2000 for NGN and 5 for USD cards |
| funding_currency (string) | (required if amount is set) This is the currency code of the wallet to be debited for the transaction. Supported values are "NGN" for naira wallet and "USD" for dollar wallet |
| card_holder_id (string) | (required) Pass a valid card holder's card_holder_id here to create a card under the card holder's profile |
| callback_url (string) | (optional) This is a custom URL you would like us to send all event related to this card to. Refer to Webhook Documentation for more |
Note: We currently support only NGN for Mastercard and USD for VISA card
Sample success response (json)
{
"resource": "create_virtual_card",
"status":"success",
"data": {
"id":"GupJFog3iyv32fsu22uc282",
"card_holder_id":"73cdudc9wfdoavcyqisb",
"currency": "NGN",
"brand": "VISA",
"type": "3D Secured Virtual Card",
"pan": "4177-****-****-7075",
"name_on_card": "STEVEN JOBS",
"card_number": "4177009811117075",
"expiry_month": "12",
"expiry_year": "27",
"cvv": "876",
"pin": "1234",
"address_street": "123 Johnson Street",
"address_city": "Wuse",
"address_country": "Nigeria",
"postal_code": "910002",
"status": "active"
}
}
Note: UfitPay send Transaction and OTP Notifications via webhook events for cards created via API. Refer to the Webhook Section for more information on how to handle these events.
This API allows you search for an existing card holder using either BVN, email or phone. This endpoint is accessed by making an HTTP POST request to
| Request Body Parameters | |
| search_by (string) | (required) This is the filed you wish to search in. This can be either email, bvn or phone |
| search_word (string) | (required) This is the esact card holder's BVN, email or phone number to search. This must be exactkly what you paswed while creating the card holder |
Sample success response (json)
{
"resource": "search_card_holder",
"status":"success",
"data": {
"id":"GupJFog3iyv32fsu22uc282",
"first_name":"John",
"last_name": "Doe",
"kyc_method": "NIGERIA_BVN",
"status": "active"
}
}
This API allows you fetch a list of all virtual cards under your account. This endpoint is accessed by making an HTTP POST request to
| Request Body Parameters | |
| card_currency (string) | (optional) Pass a valid currency code here to limit the returned records to cards issued in this currency. Supported values are "NGN", "USD" and "EUR" |
Sample success response (json)
{
"resource": "list_virtual_cards",
"status":"success",
"data": [{
"id":"hek73Fl387Ltu9834bsanb",
"name_on_card":"JOHN DOE"
"balance":"21000.00",
"currency":"NGN",
"pan": "5102-****-****-4115",
"brand": "Mastercard"
},
{
"id":"GupJFog3iyv32fsu22uc282",
"name_on_card":"STEVE JOBS"
"balance":"1280.00",
"currency":"USD",
"pan": "4177-****-****-7075",
"brand": "VISA"
}]
}
This API allows you retrieve details of a virtual card. This endpoint is accessed by making an HTTP POST request to
| Request Body Parameters | |
| id (string) | (required) This is the unique ID of the card to get details for |
Sample success response (json)
{
"resource": "get_virtual_card",
"status":"success",
"data": {
"id":"GupJFog3iyv32fsu22uc282",
"balance": "12800.00",
"currency": "NGN",
"brand": "VISA",
"type": "Regular Virtual Card",
"pan": "4177-****-****-7075",
"name_on_card": "STEVEN JOBS",
"card_number": "4177009811117075",
"expiry_month": "12",
"expiry_year": "27",
"cvv": "876",
"pin": "1234",
"address_street": "123 Johnson Street",
"address_city": "Wuse",
"address_country": "Nigeria",
"postal_code": "910002",
"status": "active"
}
}
This API allows you add funds from your wallet to a virtual card. This endpoint is accessed by making an HTTP POST request to
| Request Body Parameters | |
| id (string) | (required) This is the unique ID of the card to be funded |
| amount (string) | (required) This is the amount to be funded in the card's currency (eg. amount in NGN for naira cards or amount in USD for dollar cards) |
| funding_currency (string) | (required) This is the currency code of the wallet to be debited for the transaction. Supported values are "NGN" for naira wallet and "USD" for dollar wallet |
Sample success response (json)
{
"resource": "fund_virtual_card",
"status":"success",
"data": {
"id":"GupJFog3iyv32fsu22uc282",
"balance": "21000.00"
}
}
This API allows you withdraw funds from your virtual card to your wallet. This endpoint is accessed by making an HTTP POST request to
Note: On successful withdrawal, the funds withdrawn will be deposited into corresponding UfitPay balance by default. Thus, withdrawals from Naira cards will be deposited into your UfitPay NGN balance while withdrawals from Dollar cards will be deposited into your UfitPay USD balance
| Request Body Parameters | |
| id (string) | (required) This is the unique ID of the card to be withdrawn from |
| amount (string) | (required) This is the amount to be withdrawn in the card's currency (eg. amount in NGN for naira cards or amount in USD for dollar cards) |
| withdrawal_currency (string) | (optional) This is the currency code of the wallet to be credited for the withdrawal. Supported values are "NGN" for naira wallet and "USD" for dollar wallet |
Sample success response (json)
{
"resource": "withdraw_virtual_card_balance",
"status":"success",
"data": {
"id":"GupJFog3iyv32fsu22uc282",
"balance": "16000.00"
}
}
This API allows you block or unblock a virtual card. This endpoint is accessed by making an HTTP POST request to
| Request Body Parameters | |
| id (string) | (required) This is the unique ID of the card to update |
| status (string) | (required) This is the new status to set on the card. Supported values are "active" and "inactive" only |
Sample success response (json)
{
"resource": "update_card_status",
"status":"success",
"data": {
"id":"GupJFog3iyv32fsu22uc282",
"new_status": "inactive"
}
}
This API allows you update the callback URL set on a virtual card. This endpoint is accessed by making an HTTP POST request to
| Request Body Parameters | |
| id (string) | (required) This is the unique ID of the card to update |
| callback_url (string) | (optional) Pass a valid URL here to update the webhook URL for the card |
Sample success response (json)
{
"resource": "update_card_status",
"status":"success",
"data": {
"id":"GupJFog3iyv32fsu22uc282",
}
}
This API allows you retrieve all transactions that occured on a virtual card. This endpoint is accessed by making an HTTP POST request to
| Request Body Parameters | |
| id (string) | (required) This is the unique ID of the card to return transactions for |
| limit_datetime (string) | (optional) Pass a value here to limit the returned records to those that occured after this date and time. Supported data format is "YYYY-MM-DD HH:MM:SS" (eg. 2022-02-23 11:54:00) |
Sample success response (json)
{
"resource": "get_card_transactions",
"status":"success",
"data": [{
"datetime":"2022-12-25 11:34:12",
"narration":"WEBPOS/ABC SHOP-83893"
"type":"debit",
"currency":"NGN",
"amount": "-2600"
},
{
"datetime":"2022-11-02 05:14:08",
"narration":"Card funding"
"type":"credit",
"currency":"NGN",
"amount": "10000"
}]
}
This API allows you generate a new PIN for a virtual card. This endpoint is accessed by making an HTTP POST request to
| Request Body Parameters | |
| id (string) | (required) This is the unique ID of the card to change PIN for |
Sample success response (json)
{
"resource": "change_card_pin",
"status":"success",
"data": {
"id":"GupJFog3iyv32fsu22uc282",
"new_pin": "12345678"
}
}
This API allows you permanently delete a virtual card. This endpoint is accessed by making an HTTP POST request to
| Request Body Parameters | |
| id (string) | (required) This is the unique ID of the card to terminate |
Sample success response (json)
{
"resource": "delete_card",
"status":"success",
"data": {
"id":"GupJFog3iyv32fsu22uc282",
"new_status": "terminated"
}
}
Copyright @2024 Ynet Technology Ltd. All Rights Reserved