Tarjetas de pago

La API de Tarjetas de pago te permite gestionar y recuperar detalles sobre tus tarjetas de pago guardadas.

Pruebas en Sandbox

Para simular pagos con tarjetas de crédito/débito de sandbox en diferentes monedas y entidades de pasarela, consulta Pruebas de pagos con tarjeta.

---

El objeto PaymentCard

Un objeto PaymentCard representa una tarjeta de pago almacenada (Paylink). Contiene todos los detalles sobre la solicitud de pago.

Atributos

Atributo	Tipo	Descripción
id	string	Identificador único de la tarjeta de pago.
reference	string	Tu referencia interna para el pago.
concept	string	El concepto o título del pago.
description	string	Una breve descripción del pago.
amount	integer	El monto a pagar, en céntimos.
currency	string	La moneda del pago (por ejemplo, EUR, USD, USDC).
singleUse	boolean	Si es true, el enlace solo puede usarse una vez.
favorite	boolean	Marca la tarjeta de pago como favorita.
state	integer	El estado de la tarjeta de pago (por ejemplo, 1 para activa).
shortUrl	string	La URL corta para la página de pago.
qrImage	string	Una imagen de código QR codificada en base64 para el pago.
urlSuccess	string	URL a la que redirigir al usuario tras un pago exitoso.
urlFailed	string	URL a la que redirigir al usuario tras un pago fallido.
urlNotification	string	URL de webhook para recibir notificaciones del estado del pago.
expirationDate	string	La marca temporal en que el enlace de pago expirará (ISO 8601).
serviceDate	string	La fecha en que se prestó el servicio (ISO 8601).
createdAt	string	La marca temporal de creación de la tarjeta (ISO 8601).
updatedAt	string	La marca temporal de la última actualización de la tarjeta (ISO 8601).
client	object	Opcional. Un objeto que contiene la información del cliente, si se proporcionó durante la creación.

---

Listar tarjetas de pago

GET/paymentcards

Recupera una lista de todas las tarjetas de pago (Paylinks) creadas por el usuario. La lista está paginada y puede filtrarse por estado.

Encabezados

Header	Descripción
Authorization	Requerido. Tu token de acceso Bearer.
Accept	Requerido. Debe ser application/json.

Parámetros de consulta

Parámetro	Tipo	Descripción
limit	integer	Opcional. El número de elementos a devolver por página. Por defecto 10.
offset	integer	Opcional. El número de elementos a omitir para la paginación. Por defecto 0.
state	integer	Opcional. Filtra las tarjetas por estado. 1 para activa, 0 para usada o expirada.

Ejemplo de cURL

curl -X GET "https://sandbox.tropipay.me/api/v3/paymentcards?limit=10&offset=0&state=1" \
  -H "Authorization: Bearer {your-access-token}" \
  -H "Accept: application/json"

Ejemplo de respuesta (200 OK)

La respuesta es un array de objetos PaymentCard.

[
  {
    "id": "758bf1b0-5065-11f0-9095-6392f28119a6",
    "reference": "order-abc-123",
    "concept": "Monthly Subscription",
    "description": "Payment for monthly service renewal",
    "amount": 2500,
    "currency": "EUR",
    "state": 1,
    "shortUrl": "https://tppay.me/mc9gzasb",
    "createdAt": "2025-06-23T19:08:34.252Z",
    "updatedAt": "2025-06-23T19:08:34.626Z"
  }
]

---

Recuperar una tarjeta de pago

GET/paymentcards/{id}

Recupera los detalles de una tarjeta de pago específica por su ID único.

Parámetros de ruta

Parámetro	Tipo	Descripción
id	string	Requerido. El identificador único de la tarjeta de pago.

Encabezados

Header	Descripción
Authorization	Requerido. Tu token de acceso Bearer.
Accept	Requerido. Debe ser application/json.

Ejemplo de cURL

curl -X GET https://sandbox.tropipay.me/api/v3/paymentcards/d08d6f20-6cd1-11f0-b254-3d3d43fd5a7d \
  -H "Authorization: Bearer {your-access-token}" \
  -H "Accept: application/json"

Ejemplo de respuesta (200 OK)

Devuelve un objeto PaymentCard.

{
  "id": "d08d6f20-6cd1-11f0-b254-3d3d43fd5a7d",
  "reference": "order-xyz-789",
  "concept": "E-book Purchase",
  "description": "The Complete Guide to APIs",
  "amount": 1999,
  "currency": "EUR",
  "singleUse": true,
  "favorite": false,
  "state": 1,
  "shortUrl": "https://tppay.me/mdp5mk9t",
  "urlSuccess": "https://example.com/success",
  "urlFailed": "https://example.com/failed",
  "urlNotification": "https://example.com/webhook",
  "expirationDate": "2025-07-30T00:00:00.000Z",
  "serviceDate": "2025-07-29T00:00:00.000Z",
  "createdAt": "2025-07-29T23:14:45.138Z",
  "updatedAt": "2025-07-29T23:14:45.816Z"
}

---

Crear una tarjeta de pago

POST/paymentcards

Crea una nueva tarjeta de pago (Paylink). Una creación exitosa devuelve un objeto PaymentCard.

Encabezados

Header	Descripción
Authorization	Requerido. Tu token de acceso Bearer.
Content-Type	Requerido. Debe ser application/json.
Accept	Requerido. Debe ser application/json.

Parámetros del cuerpo

Parámetro	Tipo	Descripción
concept	string	Requerido. Un título breve para el pago que verá el usuario (máx. 254 caracteres).
description	string	Requerido. Una breve descripción del pago.
amount	integer	Requerido. El monto a pagar, en la unidad más pequeña de la moneda (por ejemplo, céntimos). Debe ser al menos 100.
currency	string	Requerido. El código ISO de tres letras de la moneda: USD, EUR, o USDC.
singleUse	boolean	Requerido. Si es true, el enlace solo puede usarse una vez.
favorite	boolean	Requerido. Marca la tarjeta de pago como favorita para un acceso fácil.
reasonId	integer	Opcional. Un ID numérico que representa la razón del pago. 4 es un valor común para pagos generales.
accountId	integer	Opcional. El identificador único de la cuenta para la cual se creará la tarjeta de pago. Si no se proporciona, se usará la cuenta predeterminada.
reference	string	Opcional. Tu referencia interna única para la transacción. Requerido si singleUse es true.
serviceDate	string	Opcional. La fecha en que se presta el servicio, en formato ISO 8601 (por ejemplo, YYYY-MM-DD). Requerido si singleUse es true.
expirationDate	string	Opcional. La fecha de expiración del enlace de pago en formato ISO 8601.
expirationDays	integer	Opcional. El número de días hasta que el enlace de pago expire.
lang	string	Opcional. El idioma de la página de pago (por ejemplo, es, en). Por defecto es el idioma de la cuenta del usuario.
saveToken	boolean	Opcional. Si es true, guarda el token de pago para uso futuro.
directPayment	boolean	Opcional. Si es true, intenta procesar el pago directamente sin mostrar la página de pago. Por defecto false.
urlSuccess	string	Opcional. URL a la que redirigir al usuario tras un pago exitoso. Debe ser una URL válida.
urlFailed	string	Opcional. URL a la que redirigir al usuario tras un pago fallido. Debe ser una URL válida.
urlNotification	string	Opcional. Una URL de webhook para recibir notificaciones servidor-a-servidor sobre el estado del pago. Debe ser una URL válida.
paymentMethods	array	Opcional. Un array de strings que especifica los métodos de pago permitidos (por ejemplo, ["TPP", "EXT", "CRYPTO"]).
strictPostalCodeCheck	boolean	Opcional. Si es true, fuerza la validación estricta del código postal. Por defecto false.
strictAddressCheck	boolean	Opcional. Si es true, fuerza la validación estricta de la dirección. Por defecto false.
paymentcardType	integer	Opcional. El tipo de tarjeta de pago a crear.
payment3DS	string	Opcional. Configuración 3D Secure: default, force, o bypass. Por defecto default.
client	object	Opcional. Un objeto que contiene la información del cliente final. Requerido si singleUse es true. Ver los detalles del objeto cliente más abajo.

Objeto Client (cuando se proporciona)

Cuando se proporciona el objeto client, singleUse debe ser true y los siguientes campos son requeridos:

Campo	Tipo	Descripción
name	string	Requerido. Nombre del cliente.
lastName	string	Requerido. Apellido del cliente.
email	string	Requerido. Correo electrónico del cliente (debe ser válido).
phone	string	Requerido. Número de teléfono del cliente.
address	string	Requerido. Dirección postal del cliente.
countryId	integer	Requerido* Debe proporcionarse countryId o countryIso. Identificador numérico del país.
countryIso	string	Requerido* Debe proporcionarse countryId o countryIso. Código de país ISO 3166-1 alpha-2.
termsAndConditions	boolean	Requerido. Debe ser true para aceptar los términos y condiciones.
city	string	Opcional. Ciudad del cliente.
postCode	string	Opcional. Código postal/ZIP del cliente.
state	string	Opcional. Estado o provincia del cliente.
dateOfBirth	string	Opcional. Fecha de nacimiento del cliente en formato yyyy-MM-dd.

Ejemplo de cURL

curl -X POST https://sandbox.tropipay.me/api/v3/paymentcards \
  -H "Authorization: Bearer {your-access-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "concept": "E-book Purchase",
    "description": "The Complete Guide to APIs",
    "amount": 1999,
    "currency": "EUR",
    "singleUse": true,
    "favorite": false,
    "reasonId": 4,
    "accountId": 958,
    "reference": "order-xyz-789",
    "serviceDate": "2025-07-29",
    "urlSuccess": "https://example.com/success",
    "urlFailed": "https://example.com/failed",
    "urlNotification": "https://example.com/webhook",
    "client": {
      "name": "John",
      "lastName": "McClane",
      "address": "Ave. Guadí 232, Barcelona, Barcelona",
      "phone": "+34645553333",
      "email": "client@email.com",
      "countryId": 2,
      "termsAndConditions": true,
      "city": "Barcelona",
      "postCode": "78622",
      "dateOfBirth": "1984-08-15"
    }
  }'

Ejemplo de respuesta (200 Created)

{
  "id": "d08d6f20-6cd1-11f0-b254-3d3d43fd5a7d",
  "accountId": 958,
  "reference": "order-xyz-789",
  "concept": "E-book Purchase",
  "description": "The Complete Guide to APIs",
  "amount": 1999,
  "currency": "EUR",
  "singleUse": true,
  "favorite": false,
  "state": 1,
  "shortUrl": "https://tppay.me/mdp5mk9t",
  "qrImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "urlSuccess": "https://example.com/success",
  "urlFailed": "https://example.com/failed",
  "urlNotification": "https://example.com/webhook",
  "expirationDate": "2025-07-30T00:00:00.000Z",
  "serviceDate": "2025-07-29T00:00:00.000Z",
  "createdAt": "2025-07-29T23:14:45.138Z",
  "updatedAt": "2025-07-29T23:14:45.816Z"
}