Crear tarjeta

Documentación de API: Crear Tarjeta Virtual

Endpoint

POST {{baseUrl}}/customer/virtual/cards/create

Descripción

Este endpoint permite crear una nueva tarjeta virtual para un cliente. El cliente debe estar registrado y activado para los servicios de tarjeta virtual.

Tarifas de Emisión de Tarjetas

Estas tarifas se aplican tanto a las tarjetas Virtuales USD MasterCard como Visa.

Acción	Costo
Creación de Tarjeta	$2 por cada tarjeta emitida
Recarga	Cargo del 1.5% sobre la financiación de la tarjeta virtual
Contracargo	Tarifa fija de $80 para tarjetas Visa
Terminación	No se cobra tarifa por la terminación de tarjetas, se devuelve el saldo en la tarjeta
Tarifas Transfronterizas	2.5% + $0.5 por transacción liquidada fuera de EE. UU.
Tarjeta Rechazada	$1 por terminación automática después de 3 transacciones con fondos insuficientes

Headers

No se requieren encabezados específicos para este endpoint, pero típicamente, puede necesitar incluir tokens de autorización u otros encabezados según los requisitos de autenticación de su API.

Cuerpo de la Solicitud

El cuerpo de la solicitud debe incluir los siguientes campos:

• customer_id: (string) El identificador único del cliente.

• amount: (string) La cantidad inicial que se cargará en la tarjeta virtual.

Ejemplo de Cuerpo de Solicitud

{
    "customer_id": "4e6e40e8-c148-4eea-9332-76ec98ecb165",
    "amount": "5"
}

Respuesta

La respuesta incluirá el estado de la solicitud, un mensaje relevante y los detalles de la nueva tarjeta virtual si la solicitud es exitosa. Si la solicitud es inválida, se devolverá un mensaje de error.

Respuesta Exitosa

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

Respuesta de Error

Si la solicitud es inválida o hay problemas para procesarla, se devolverá la siguiente respuesta de error:

{
    "error": "Invalid request"
}

Campos en la Respuesta Exitosa

• status: Indica el estado de éxito de la solicitud (e.g., "success").

• status_code: Código de estado HTTP de la respuesta (e.g., 200 para éxito).

• message: Un mensaje que describe el resultado de la solicitud (e.g., "Virtual card created successfully").

• data: Contiene los detalles de la nueva tarjeta virtual.

  • id: Identificador único de la tarjeta virtual.

  • balance: Saldo inicial cargado en la tarjeta virtual.

  • cardNumber: Número completo de la tarjeta virtual.

  • last4: Últimos cuatro dígitos del número de la tarjeta.

  • cardName: Nombre en la tarjeta virtual.

  • cardType: Tipo de la tarjeta (e.g., "virtual").

  • cardBrand: Marca de la tarjeta (e.g., "visa").

  • cvv2: Código CVV2 de la tarjeta virtual.

  • expiry: Fecha y hora de expiración de la tarjeta en formato ISO 8601.

  • valid: Validez de la tarjeta en formato MM/AAAA.

  • billingAddress: Dirección de facturación asociada con la tarjeta virtual.

    • city: Ciudad de la dirección de facturación.

    • state: Estado de la dirección de facturación.

    • street: Dirección.

    • country: País de la dirección de facturación.

    • zipCode: Código postal de la dirección de facturación.

    • countryCode: Código del país de la dirección de facturación.

Siguiendo los detalles anteriores, puede crear exitosamente una nueva tarjeta virtual para un cliente.