Virtual Card API

  • Home
  • Virtual Card API

Introduction

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.

Authentication

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

Test API Credentials

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


Available APIs

Get Exchange Rate POST » /get_exchange_rate

This API allows you to retrieve the current exchange rate from UfitPay server. This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/get_exchange_rate

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" } }

Create Virtual Card POST » /create_virtual_card

This API allows you issue a new virtual card to your customer. This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/create_virtual_card

Request Body Parameters
card_brand (string) (required) This is the brand of virtual card you wish to create. Supported values are "mastercard", "visa" and "verve" only
card_currency (string) (required) This is the currency for the new card. Supported values are "NGN" and "USD" only
amount (string) (required) 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 must be above 2000 for NGN and 10 for USD cards
funding_currency (string) (required) This is the currency code of the wallet to be billed for the transaction. Supported values are "NGN" and "USD" only
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
phone (string) (required) This is the card holder's mobile phone number (This will be used for OTP delivery)
bvn (string) (required) This is the card holder's BVN
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

Sample success response (json)
{ "resource": "create_virtual_card", "status":"success", "data": { "id":"GupJFog3iyv32fsu22uc282", "currency": "NGN", "brand": "VISA", "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" } }

List Virtual Cards POST » list_virtual_cards

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 https://api.ufitpay.com/v1/list_virtual_cards

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": "VERVE" }, { "id":"GupJFog3iyv32fsu22uc282", "name_on_card":"STEVE JOBS" "balance":"1280.00", "currency":"USD", "pan": "4177-****-****-7075", "brand": "VISA" }] }

Get Virtual Card Details POST » get_virtual_card

This API allows you retrieve details of a virtual card. This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/get_virtual_card

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", "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" } }

Fund Virtual Card POST » fund_virtual_card

This API allows you add funds from your wallet to a virtual card. This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/fund_virtual_card

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 billed for the transaction. Supported values are "NGN" and "USD" only
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": "fund_virtual_card", "status":"success", "data": { "id":"GupJFog3iyv32fsu22uc282", "balance": "21000.00" } }

>Block / Unblock Virtual Card POST » update_card_status

This API allows you block or unblock a virtual card. This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/update_card_status

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" } }

Update Virtual Card POST » update_card_details

This API allows you update parameters of a virtual card. This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/update_card_details

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", } }

Fetch Card Transactions POST » get_card_transactions

This API allows you retrieve all transactions that occured on a virtual card. This endpoint is accessed by making an HTTP POST request to https://api.ufitpay.com/v1/get_card_transactions

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": "update_card_status", "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" }] }