Create a Paymentcard

This endpoint allows you to generate a payment link. With this link, you can receive deposits from other TropiPay accounts or external sources in a simple way. You can share your payment links and manage your charges efficiently.

POST <base url>/api/v3/paymentcards

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer {user-token}
Content-Type	string	Yes	application/json

Example Request

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

Example Response

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

Fields

Field	Type	Description
reference	string	Used for tracking orders within your application. This value will be returned in notifications and webhooks.
concept	string	A brief title or concept for the payment.
favorite	boolean	Mark this payment card as a favorite.
description	string	Detailed description of what the payment is for.
amount	number	Payment amount in cents (e.g., 10.55 EUR should be sent as 1055).
currency	string	Currency code (e.g., "EUR").
singleUse	boolean	Whether the payment link can be used only once.
reasonId	number	Reason identifier for the payment.
accountId	number	The unique identifier of the account for which the payment card will be created. IMPORTANT: Determines where the fund will be settled. If omited the configured default account by the user will be used
reasonDes	string	Text for the reason if reason is 9 (see below for a comprehensive list of reasons).
expirationDays	number	Funds will be pending in until this number of days after payment
lang	string	Language code (e.g., "es" for Spanish).
urlSuccess	string	URL where users will be redirected after successful payment.
urlFailed	string	URL where users will be redirected if payment fails.
urlNotification	string	POST endpoint that will receive payment notifications. Must be accessible to TropiPay servers. For testing, you can use services like ngrok or webhook.site.
expirationDate	string	Date until the paymentcard will be available ISO8601 format including variants allowing timezone
termsAndConditions	boolean	Acceptance of terms and conditions.

Client Information (Required)

tip

The client object, if present, must include ALL the following fields (pass null to let Tropipay request the client data in the payment card):

Field	Type	Description
name	string	Client's first name.
lastName	string	Client's last name.
address	string	Client's address.
phone	string	Client's phone number.
email	string	Client's email address.
city	string	Client's city.
postCode	string	Client's zip code or postal code.
dateOfBirth	string	Client's birth date. Format: yyyy-mm-dd.
termsAndConditions	string	Acceptance of terms and conditions.

Optional Fields

Field	Type	Description
countryId	number	Country identifier. Not required if countryIso is provided.
countryIso	string	Country ISO code (e.g., "ES", "US"). Not required if countryId is provided.
paymentMethods	array[string]	Specifies available payment methods. Options include 'EXT' (external cards like Visa, Mastercard) and 'TPP' (TropiPay balance). If omitted, all payment methods will be available.
saveToken	boolean	Save payment token for future use. Defaults to false.
imageBase	string	Base64 string format of an image (JPG, PNG, etc.). Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAKQAAACkHYTCA...

Code Examples

cURL

curl --request POST \
  --url https://tropipay-dev.herokuapp.com/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

<?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://tropipay-dev.herokuapp.com/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;

Java

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://tropipay-dev.herokuapp.com/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();
        }
    }
}

C#

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://tropipay-dev.herokuapp.com/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);
    }
}

Go

package main

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

func main() {
	url := "https://tropipay-dev.herokuapp.com/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)
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the payment card.
reference	string	Your provided reference.
concept	string	Payment concept.
description	string	Payment description.
amount	number	Payment amount in cents.
accountId	number	The unique identifier of the account for which the payment card was created.
currency	string	Currency code.
singleUse	boolean	Whether the payment link can be used only once.
favorite	boolean	Whether the payment card is marked as favorite.
reasonId	number	Reason identifier.
reasonDes	string	Reason description (may be null).
expirationDays	number	Days until expiration.
userId	string	User ID of the payment card creator.
lang	string	Language code.
state	number	Payment state.
urlSuccess	string	Success URL.
urlFailed	string	Failed URL.
urlNotification	string	Notification URL for webhooks.
expirationDate	string	Expiration date (may be null).
serviceDate	string	Service date (may be null).
hasClient	boolean	Whether client information is included.
updatedAt	string	Last update timestamp.
createdAt	string	Creation timestamp.
qrImage	string	Base64-encoded QR code image for the payment.
shortUrl	string	Short URL to access the payment.

Implementation Notes

• For testing webhook notifications locally, consider using services like ngrok or webhook.site
• The amount field is always an integer in cents (e.g., 10.55 EUR should be represented as 1055)
• You can specify payment methods to limit how users can pay (external cards, TropiPay balance, or both)
• The QR image is returned as a base64 string, which can be displayed directly on your website