Spanish

Virtual Card

Overview

The Virtual Cards API allows you to create and manage virtual cards for your customers. Before using any card functionality, customers must first complete KYC activation.

Base URL

Production base url : https://api.yativo.com/api/v1

Test base url : https://smtp.yativo.com/api/v1

Authentication & Headers

All non-GET requests require an Idempotency-Key header to ensure request uniqueness:

Idempotency-Key: unique-request-identifier
Content-Type: application/json
1

Activate Customer for Virtual Cards

Before creating virtual cards, customers must complete KYC verification.

Endpoint: POST /customer/virtual/cards/activate

Request Body:

request.json
{
  "customer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "customer_address": {
    "city": "New York",
    "state": "New York",
    "zipcode": "10001",
    "street": "123 Main Street Plaza",
    "country": "USA",
    "number": "25"
  },
  "customer_idFront": "https://example.com/path/to/id-front.png",
  "customer_idNumber": "A12345678",
  "date_of_birth": "01-01-1990",
  "user_photo": "https://example.com/path/to/photo.png"
}

Parameters:

  • customer_id (string, required): Unique customer identifier

  • customer_address (object, required): Customer's address information

    • city (string): City name

    • state (string): State/province

    • zipcode (string): Postal/ZIP code

    • street (string): Street address

    • country (string): Country name

    • number (string): House/building number

  • customer_idFront (string, required): URL to front of ID document

  • customer_idNumber (string, required): ID document number

  • date_of_birth (string, required): Date of birth in DD-MM-YYYY format

  • user_photo (string, required): URL to customer photo

2

Create Virtual Card

Create a new virtual card for an activated customer.

Endpoint: POST /customer/virtual/cards/create

Request Body:

request.json
{
  "amount": 300,
  "customer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Parameters:

  • amount (integer, required): Initial card amount in cents (multiples of 100). Minimum $3 fee applies

  • customer_id (string, required): Unique customer identifier

Response:

response.json
{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "card_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "customer_email": "[email protected]",
    "customer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "card_brand": "visa",
    "card_type": "virtual"
  }
}
3

Top Up Card

Add funds to an existing virtual card from the customer's wallet balance.

Endpoint: POST /customer/virtual/cards/topup

Request Body:

request.json
{
  "customer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "cardId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "amount": 1000
}

Parameters:

  • customer_id (string, required): Unique customer identifier

  • cardId (string, required): Card identifier to top up

  • amount (integer, required): Top-up amount in cents (multiples of 100)

4

List All Customer Cards

Retrieve all virtual cards for a customer.

Endpoint: GET /customer/virtual/cards/list

Query Parameters:

  • customer_id (string, required): Customer identifier

5

Get Card Details

Retrieve detailed information for a specific card.

Endpoint: GET /customer/virtual/cards/get/{{cardId}}

Response:

response.json
{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "balance": 300,
    "cardNumber": "4767xxxxxxxxxxxx",
    "last4": "xxxx",
    "cardName": "John Doe",
    "cardType": "virtual",
    "cardBrand": "visa",
    "cvv2": "xxx",
    "expiry": "2028-06-10T00:00:00",
    "valid": "06/2028",
    "billingAddress": {
      "city": "Miami",
      "state": "Florida",
      "street": "3401 N. Miami, Ave. Ste 230",
      "country": "United States",
      "zipCode": "33127",
      "countryCode": "US"
    },
    "airlinePaymentEnabled": "disabled"
  }
}
6

Get Card Transactions

Retrieve transaction history for a specific card.

Endpoint: GET /customer/virtual/cards/transactions/{{cardId}}

Response:

response.json
{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "createdAt": "2025-06-10T13:54:11.594Z",
      "updatedAt": "2025-06-10T13:54:11.730Z",
      "amount": "3",
      "centAmount": "300",
      "cardBalanceAfter": "300",
      "type": "credit",
      "method": "topup",
      "narrative": "Top-up card",
      "status": "success",
      "currency": "usd",
      "reference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "transactionType": null,
      "cardId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "authorizationTransactionId": null,
      "settlementTransactionId": null
    }
  ]
}

Transaction Object Fields:

  • id: Unique transaction identifier

  • createdAt: Transaction creation timestamp

  • updatedAt: Last update timestamp

  • amount: Transaction amount in dollars

  • centAmount: Transaction amount in cents

  • cardBalanceAfter: Card balance after transaction

  • type: Transaction type (credit/debit)

  • method: Transaction method (topup/purchase/etc.)

  • narrative: Human-readable description

  • status: Transaction status

  • currency: Transaction currency (usd)

  • reference: Transaction reference number

7

Freeze/Unfreeze Card

Update the status of a virtual card to freeze or unfreeze it.

Endpoint: PUT /customer/virtual/cards/update/{{cardId}}

Request Body:

request.json
{
  "action": "freeze"
}

Parameters:

  • action (string, required): Action to perform. Valid values: "freeze", "unfreeze"

Important Notes

  • Amount Format: All monetary amounts are specified in cents (e.g., 500 = $5.00)

  • Minimum Requirements: Card creation has a minimum $3 fee

  • Idempotency: All non-GET requests require an Idempotency-Key header

  • KYC Requirement: Customers must complete activation before creating cards

  • Wallet Funding: Top-ups debit from the customer's wallet balance

Error Handling

The API returns standard HTTP status codes. All responses include:

  • status: Success or error indicator

  • status_code: HTTP status code

  • message: Human-readable message

  • data: Response payload (on success)

Security Considerations

  • Always use HTTPS for API requests

  • Store card details securely and comply with PCI DSS requirements

  • Implement proper authentication and authorization

  • Use idempotency keys to prevent duplicate transactions

PreviousWebhookNextLists