Create card
API Documentation: Create Virtual Card
Endpoint
POST {{baseUrl}}/customer/virtual/cards/create
Description
This endpoint allows you to create a new virtual card for a customer. The customer must already be registered and activated for virtual card services.
Card Issuing Fees
These fees apply to both MasterCard and Visa Virtual USD cards.
Card Creation
$2 for every newly issued card
Top Up
1.5% charges on virtual card funding
Chargeback
$80 flat rate for Visa Card
Termination
no fee is charged for the termination of cards, you get back the balance on the card
Cross Border Fees
2.5% + $0.5 per transaction settled outside the USA
Card Declined
$1 for automatic termination after 3 Insufficient funds Transactions
Headers
No specific headers are required for this endpoint, but typically, you might need to include authorization tokens or other headers as per your API's authentication requirements.
Request Body
The request body must include the following fields:
customer_id: (string) The unique identifier of the customer.
amount: (string) The initial amount to be loaded onto the virtual card.
Create Card
StartFragment
To create a card, a user has to be registered as a card user in our card section; this requires basic KYC details of your users.
We support all countries and have different IDType for certain countries; here is the list;
| Countries | Accepted Documents |
|---|---|
| Nigeria | [vNIN, PASSPORT, DRIVERS_LICENSE, PVC] |
| Ghana | [PASSPORT, DRIVERS_LICENSE, VOTERS_ID] |
| Kenya | [PASSPORT, NATIONAL_ID] |
| Senegal | [NATIONAL_ID, ECOWAS_ID] |
| Other Countries | [NATIONAL_ID] |
This endpoint is used to create a new card.
Request Body
amount(number, required): The amount to be associated with the new card.
Response
The response will contain the details of the newly created card.
{"amount":200,"customer_id":"c50b72fe-611d-4ede-b6a7-ecf4cbdb1441"}POST /api/v1/customer/virtual/cards/create HTTP/1.1
Host: smtp.yativo.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 67
{
"amount": 200,
"customer_id": "c50b72fe-611d-4ede-b6a7-ecf4cbdb1441"
}No content
Example Request Body
{
"customer_id": "4e6e40e8-c148-4eea-9332-76ec98ecb165",
"amount": "5"
}Response
The response will include the status of the request, a relevant message, and details of the newly created virtual card if the request is successful. If the request is invalid, an error message will be returned.
Successful Response
{
"status": "success",
"status_code": 200,
"message": "Virtual card created successfully",
"data": {
"id": "8d5b43bb-683b-45b3-9d1d-f64d5d75ee97",
"balance": 5,
"cardNumber": "4040381842044628",
"last4": "4628",
"cardName": "John Doe",
"cardType": "virtual",
"cardBrand": "visa",
"cvv2": "849",
"expiry": "2027-05-29T00:00:00",
"valid": "05/2027",
"billingAddress": {
"city": "Miami",
"state": "Florida",
"street": "3401 N. Miami, Ave. Ste 230",
"country": "United States",
"zipCode": "33127",
"countryCode": "US"
}
}
}Error Response
If the request is invalid or there are issues processing the request, the following error response will be returned:
{
"error": "Invalid request"
}Fields in Successful Response
status: Indicates the success status of the request (e.g., "success").
status_code: HTTP status code of the response (e.g., 200 for success).
message: A message describing the result of the request (e.g., "Virtual card created successfully").
data: Contains the details of the newly created virtual card.
id: Unique identifier of the virtual card.
balance: Initial balance loaded onto the virtual card.
cardNumber: Full number of the virtual card.
last4: Last four digits of the card number.
cardName: Name on the virtual card.
cardType: Type of the card (e.g., "virtual").
cardBrand: Brand of the card (e.g., "visa").
cvv2: CVV2 code of the virtual card.
expiry: Expiry date and time of the card in ISO 8601 format.
valid: Validity of the card in MM/YYYY format.
billingAddress: Billing address associated with the virtual card.
city: City of the billing address.
state: State of the billing address.
street: Street address.
country: Country of the billing address.
zipCode: Postal code of the billing address.
countryCode: Country code of the billing address.
By following the above details, you can successfully create a new virtual card for a customer.
Last updated