Crear una tarjeta de pago

Este endpoint te permite generar un enlace de pago. Con este enlace, puedes recibir depósitos de otras cuentas de TropiPay o de fuentes externas de forma sencilla. Puedes compartir tus enlaces de pago y gestionar tus cobros de manera eficiente.

POST <base url>/api/v3/paymentcards

Encabezados

Nombre	Tipo	Requerido	Descripción
`Authorization`	string	Sí	Bearer {user-token}
`Content-Type`	string	Sí	application/json

Ejemplo de solicitud

{
    "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"
  },
  "reference": "my-reference",
  "concept": "Bicycle",
  "favorite": "true",
  "description": "Two wheels",
  "amount": 100,
  "currency": "EUR",
  "singleUse": "true",
  "reasonId": 4,
  "accountId": 9,
  "expirationDays": 1,
  "lang": "es",
  "urlSuccess": "https://my-business.com/payment-ok",
  "urlFailed": "https://my-business.com/payment-ko",
  "urlNotification": "https://my-business.com/payment-callback",
  "directPayment": "false",
  "paymentMethods": [
    "EXT",
    "TPP",
    "TPP_GIFTCARD",
    "CRYPTO"
  ]
}

Ejemplo de respuesta

{
	"id": "1178ee20-fd00-11ef-a2a1-395c2db61965",
	"saveToken": false,
	"accountId": 9,
	"reference": "my-reference",
	"concept": "Bicycle",
	"description": "Two wheels",
	"amount": 100,
	"currency": "EUR",
	"singleUse": true,
	"favorite": true,
	"reasonId": 4,
	"reasonDes": null,
	"expirationDays": 0,
	"userId": "5b78aed0-70d7-11ef-8e71-afa4d9a6153a",
	"lang": "es",
	"imageBase": null,
	"state": 1,
	"urlSuccess": "https://my-business.com/payment-ok",
	"urlFailed": "https://my-business.com/payment-ko",
	"urlNotification": "https://my-business.com/payment-callback",
	"expirationDate": null,
	"serviceDate": null,
	"hasClient": true,
	"credentialId": 10,
	"force3ds": false,
	"origin": 2,
	"paymentcardType": 1,
	"strictPostalCodeCheck": false,
	"strictAddressCheck": false,
	"updatedAt": "2025-03-09T16:03:41.486Z",
	"createdAt": "2025-03-09T16:03:40.675Z",
	"qrImage": "data:image/png;base64,iVBORw0KGgoA...",
	"shortUrl": "https://tppay.me/m81tp753",
	"paymentUrl": null,
	"bankOrderCode": "439900781291",
	"rawUrlPayment": null,
	"giftcard": null
}

Campos

Campo	Tipo	Descripción
`reference`	string	Se usa para rastrear pedidos dentro de tu aplicación. Este valor se devolverá en notificaciones y webhooks.
`concept`	string	Un título o concepto breve para el pago.
`favorite`	boolean	Marca esta tarjeta de pago como favorita.
`description`	string	Descripción detallada de para qué es el pago.
`amount`	number	Monto del pago en céntimos (por ejemplo, 10.55 EUR debe enviarse como 1055).
`currency`	string	Código de moneda (por ejemplo, "EUR").
`singleUse`	boolean	Indica si el enlace de pago puede usarse solo una vez.
`reasonId`	number	Identificador del motivo del pago.
`accountId`	number	El identificador único de la cuenta para la cual se creará la tarjeta de pago. IMPORTANTE: Determina dónde se liquidarán los fondos. Si se omite, se usará la cuenta predeterminada configurada por el usuario.
`reasonDes`	string	Texto del motivo si el motivo es 9 (ver más abajo la lista completa de motivos).
`expirationDays`	number	Los fondos permanecerán pendientes de entrada hasta este número de días después del pago.
`lang`	string	Código de idioma (por ejemplo, "es" para español).
`urlSuccess`	string	URL a la que se redirigirá al usuario tras un pago exitoso.
`urlFailed`	string	URL a la que se redirigirá al usuario si el pago falla.
`urlNotification`	string	Endpoint POST que recibirá las notificaciones de pago. Debe ser accesible para los servidores de TropiPay. Para pruebas, puedes usar servicios como ngrok o webhook.site.
`expirationDate`	string	Fecha hasta la cual estará disponible la tarjeta de pago, en formato ISO8601 incluyendo variantes que permiten zona horaria.
`termsAndConditions`	boolean	Aceptación de términos y condiciones.

Información del cliente (Requerida)

tip

El objeto client, si está presente, debe incluir TODOS los siguientes campos (pasa null para que Tropipay solicite los datos del cliente en la tarjeta de pago):

Campo	Tipo	Descripción
`name`	string	Nombre del cliente.
`lastName`	string	Apellido del cliente.
`address`	string	Dirección del cliente.
`phone`	string	Número de teléfono del cliente.
`email`	string	Correo electrónico del cliente.
`city`	string	Ciudad del cliente.
`postCode`	string	Código postal o ZIP del cliente.
`dateOfBirth`	string	Fecha de nacimiento del cliente. Formato: yyyy-mm-dd.
`termsAndConditions`	string	Aceptación de términos y condiciones.

Campos opcionales

Campo	Tipo	Descripción
`countryId`	number	Identificador del país. No es requerido si se proporciona `countryIso`.
`countryIso`	string	Código ISO del país (por ejemplo, "ES", "US"). No es requerido si se proporciona `countryId`.
`paymentMethods`	array[string]	Especifica los métodos de pago disponibles. Las opciones incluyen 'EXT' (tarjetas externas como Visa, Mastercard) y 'TPP' (saldo de TropiPay). 'CRYPTO' (criptomonedas). Si se omite, todos los métodos de pago estarán disponibles.
`saveToken`	boolean	Guarda el token de pago para uso futuro. Por defecto `false`.
`imageBase`	string	Cadena en formato Base64 de una imagen (JPG, PNG, etc.). Ejemplo: `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAKQAAACkHYTCA...`

Ejemplos de código

cURL
PHP
Java
C#
Go

curl --request POST \
  --url https://sandbox.tropipay.me/api/v3/paymentcards \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {your-token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "reference": "my-reference",
    "concept": "Bicycle",
    "favorite": true,
    "description": "Two wheels",
    "accountId": 9,
    "amount": 100000,
    "currency": "EUR",
    "singleUse": true,
    "reasonId": 4,
    "expirationDays": 1,
    "lang": "es",
    "urlSuccess": "https://my-business.com/payment-ok",
    "urlFailed": "https://my-business.com/payment-ko",
    "urlNotification": "https://my-business.com/payment-callback",
    "serviceDate": "2021-08-20",
    "client": {
      "name": "John",
      "lastName": "McClane",
      "address": "Ave. Guadí 232, Barcelona, Barcelona",
      "phone": "+34645553333",
      "email": "client@email.com",
      "countryId": 1,
      "termsAndConditions": "true",
      "city": "Barcelona",
      "postCode": "78622",
      "dateOfBirth": "1984-08-15"
    },
    "directPayment": true,
    "paymentMethods": [
      "EXT",
      "TPP"
    ]
  }'

<?php

$curl = curl_init();

$data = [
    "reference" => "my-reference",
    "concept" => "Bicycle",
    "favorite" => true,
    "description" => "Two wheels",
    "accountId" => 9,
    "amount" => 100000,
    "currency" => "EUR",
    "singleUse" => true,
    "reasonId" => 4,
    "expirationDays" => 1,
    "lang" => "es",
    "urlSuccess" => "https://my-business.com/payment-ok",
    "urlFailed" => "https://my-business.com/payment-ko",
    "urlNotification" => "https://my-business.com/payment-callback",
    "serviceDate" => "2021-08-20",
    "client" => [
        "name" => "John",
        "lastName" => "McClane",
        "address" => "Ave. Guadí 232, Barcelona, Barcelona",
        "phone" => "+34645553333",
        "email" => "client@email.com",
        "countryId" => 1,
        "termsAndConditions" => "true",
        "city" => "Barcelona",
        "postCode" => "78622",
        "dateOfBirth" => "1984-08-15"
    ],
    "directPayment" => true,
    "paymentMethods" => ["EXT", "TPP"]
];

curl_setopt_array($curl, [
    CURLOPT_URL => "https://sandbox.tropipay.me/api/v3/paymentcards",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Accept: application/json",
        "Content-Type: application/json",
        "Authorization: Bearer {your-token}"
    ],
    CURLOPT_POSTFIELDS => json_encode($data)
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;

public class PaymentCard {
    public static void main(String[] args) {
        try {
            URL url = new URL("https://sandbox.tropipay.me/api/v3/paymentcards");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Authorization", "Bearer {your-token}");
            conn.setDoOutput(true);

            String jsonInputString = "{ \"reference\": \"my-reference\", \"concept\": \"Bicycle\", \"accountId\": 9, \"amount\": 100000 }";
            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }

            InputStream responseStream = conn.getInputStream();
            responseStream.transferTo(System.out);
            conn.disconnect();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program {
    static async Task Main() {
        using var client = new HttpClient();
        var url = "https://sandbox.tropipay.me/api/v3/paymentcards";

        var json = "{ \"reference\": \"my-reference\", \"concept\": \"Bicycle\", \"accountId\": 9, \"amount\": 100000 }";
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        client.DefaultRequestHeaders.Add("Authorization", "Bearer {your-token}");
        var response = await client.PostAsync(url, content);

        var responseString = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseString);
    }
}

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://sandbox.tropipay.me/api/v3/paymentcards"

	data := map[string]interface{}{
		"reference": "my-reference",
		"concept":   "Bicycle",
		"accountId": 9,
		"amount":    100000,
	}

	jsonData, _ := json.Marshal(data)

	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer {your-token}")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Error:", err)
		return
	}
	defer resp.Body.Close()

	var res map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&res)
	fmt.Println(res)
}

Campos de la respuesta

Campo	Tipo	Descripción
`id`	string	Identificador único de la tarjeta de pago.
`reference`	string	La referencia proporcionada.
`concept`	string	Concepto del pago.
`description`	string	Descripción del pago.
`amount`	number	Monto del pago en céntimos.
`accountId`	number	El identificador único de la cuenta para la cual se creó la tarjeta de pago.
`currency`	string	Código de moneda.
`singleUse`	boolean	Indica si el enlace de pago puede usarse solo una vez.
`favorite`	boolean	Indica si la tarjeta de pago está marcada como favorita.
`reasonId`	number	Identificador del motivo.
`reasonDes`	string	Descripción del motivo (puede ser null).
`expirationDays`	number	Días hasta la expiración.
`userId`	string	ID del usuario que creó la tarjeta de pago.
`lang`	string	Código de idioma.
`state`	number	Estado del pago.
`urlSuccess`	string	URL de éxito.
`urlFailed`	string	URL de fallo.
`urlNotification`	string	URL de notificación para webhooks.
`expirationDate`	string	Fecha de expiración (puede ser null).
`serviceDate`	string	Fecha del servicio (puede ser null).
`hasClient`	boolean	Indica si se incluye información del cliente.
`updatedAt`	string	Marca temporal de la última actualización.
`createdAt`	string	Marca temporal de creación.
`qrImage`	string	Imagen del código QR codificada en Base64 para el pago.
`shortUrl`	string	URL corta para acceder al pago.

Notas de implementación

Para probar tarjetas de pago y simular transacciones exitosas o fallidas en Sandbox, consulta la referencia Pruebas de pagos con tarjeta.
Para probar notificaciones webhook de forma local, considera usar servicios como ngrok o webhook.site.
El campo amount siempre es un entero en céntimos (por ejemplo, 10.55 EUR debe representarse como 1055).
Puedes especificar métodos de pago para limitar cómo pueden pagar los usuarios (tarjetas externas, saldo de TropiPay, o ambos).
La imagen QR se devuelve como una cadena base64, que puede mostrarse directamente en tu sitio web.

Encabezados​

Ejemplo de solicitud​

Ejemplo de respuesta​

Campos​

Información del cliente (Requerida)​

Campos opcionales​

Ejemplos de código​

Campos de la respuesta​

Notas de implementación​