Payment Cards

The Payment Cards API allows you to manage and retrieve details about your saved payment cards.

The Payment Card Object

A PaymentCard object represents a stored payment card (Paylink). It contains all the details about the payment request.

Attributes

Attribute	Type	Description
`id`	string	Unique identifier for the payment card.
`reference`	string	Your internal reference for the payment.
`concept`	string	The concept or title of the payment.
`description`	string	A short description of the payment.
`amount`	integer	The amount to be paid, in cents.
`currency`	string	The currency of the payment (e.g., `EUR`, `USD`, `USDC`).
`singleUse`	boolean	If `true`, the link can only be used once.
`favorite`	boolean	Marks the payment card as a favorite.
`state`	integer	The state of the payment card (e.g., `1` for active).
`shortUrl`	string	The short URL for the payment page.
`qrImage`	string	A base64-encoded QR code image for the payment.
`urlSuccess`	string	URL to redirect the user to after a successful payment.
`urlFailed`	string	URL to redirect the user to after a failed payment.
`urlNotification`	string	Webhook URL to receive payment status notifications.
`expirationDate`	string	The timestamp when the payment link will expire (ISO 8601).
`serviceDate`	string	The date the service was rendered (ISO 8601).
`createdAt`	string	The timestamp when the card was created (ISO 8601).
`updatedAt`	string	The timestamp when the card was last updated (ISO 8601).
`client`	object	Optional. An object containing the client's information, if provided during creation.

List Payment Cards

GET/paymentcards

Retrieves a list of all payment cards (Paylinks) created by the user. The list is paginated and can be filtered by state.

Headers

Header	Description
`Authorization`	Required. Your `Bearer` access token.
`Accept`	Required. Must be `application/json`.

Query Parameters

Parameter	Type	Description
`limit`	integer	Optional. The number of items to return per page. Defaults to `10`.
`offset`	integer	Optional. The number of items to skip for pagination. Defaults to `0`.
`state`	integer	Optional. Filters cards by state. `1` for active, `0` for used or expired.

cURL Example

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"

Response Example (200 OK)

The response is an array of PaymentCard objects.

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

Retrieve a Payment Card

GET/paymentcards/{id}

Retrieves the details of a specific payment card by its unique ID.

Path Parameters

Parameter	Type	Description
`id`	string	Required. The unique identifier of the payment card.

Headers

Header	Description
`Authorization`	Required. Your `Bearer` access token.
`Accept`	Required. Must be `application/json`.

cURL Example

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"

Response Example (200 OK)

Returns a PaymentCard object.

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

Create a Payment Card

POST/paymentcards

Creates a new payment card (Paylink). A successful creation returns a PaymentCard object.

Headers

Header	Description
`Authorization`	Required. Your `Bearer` access token.
`Content-Type`	Required. Must be `application/json`.
`Accept`	Required. Must be `application/json`.

Body Parameters

Parameter	Type	Description
`concept`	string	Required. A brief title for the payment that the user will see (max 254 characters).
`description`	string	Required. A short description of the payment.
`amount`	integer	Required. The amount to be paid, in the smallest currency unit (e.g., cents). Must be at least 100.
`currency`	string	Required. The three-letter ISO currency code: `USD`, `EUR`, or `USDC`.
`singleUse`	boolean	Required. If `true`, the link can only be used once.
`favorite`	boolean	Required. Marks the payment card as a favorite for easy access.
`reasonId`	integer	Optional. A numeric ID representing the reason for the payment. `4` is a common value for general payments.
`accountId`	integer	Optional. The unique identifier of the account for which the payment card will be created. If not provided, the default account will be used.
`reference`	string	Optional. Your unique internal reference for the transaction. Required if `singleUse` is `true`.
`serviceDate`	string	Optional. The date the service is rendered, in ISO 8601 format (e.g., `YYYY-MM-DD`). Required if `singleUse` is `true`.
`expirationDate`	string	Optional. The expiration date for the payment link in ISO 8601 format.
`expirationDays`	integer	Optional. The number of days until the payment link expires.
`lang`	string	Optional. The language for the payment page (e.g., `es`, `en`). Defaults to the user's account language.
`saveToken`	boolean	Optional. If `true`, saves the payment token for future use.
`directPayment`	boolean	Optional. If `true`, attempts to process the payment directly without showing the payment page. Defaults to `false`.
`urlSuccess`	string	Optional. URL to redirect the user to after a successful payment. Must be a valid URL.
`urlFailed`	string	Optional. URL to redirect the user to after a failed payment. Must be a valid URL.
`urlNotification`	string	Optional. A webhook URL to receive server-to-server notifications about the payment status. Must be a valid URL.
`paymentMethods`	array	Optional. An array of strings specifying allowed payment methods (e.g., `["TPP", "EXT"]`).
`strictPostalCodeCheck`	boolean	Optional. If `true`, enforces strict postal code validation. Defaults to `false`.
`strictAddressCheck`	boolean	Optional. If `true`, enforces strict address validation. Defaults to `false`.
`paymentcardType`	integer	Optional. The type of payment card to create.
`payment3DS`	string	Optional. 3D Secure configuration: `default`, `force`, or `bypass`. Defaults to `default`.
`client`	object	Optional. An object containing the end client's information. Required if `singleUse` is `true`. See client object details below.

Client Object (when provided)

When the client object is provided, singleUse must be true and the following fields are required:

Field	Type	Description
`name`	string	Required. Client's first name.
`lastName`	string	Required. Client's last name.
`email`	string	Required. Client's email address (must be valid).
`phone`	string	Required. Client's phone number.
`address`	string	Required. Client's street address.
`countryId`	integer	Required* Either `countryId` or `countryIso` must be provided. Numeric country identifier.
`countryIso`	string	Required* Either `countryId` or `countryIso` must be provided. ISO 3166-1 alpha-2 country code.
`termsAndConditions`	boolean	Required. Must be `true` to accept terms and conditions.
`city`	string	Optional. Client's city.
`postCode`	string	Optional. Client's postal/ZIP code.
`state`	string	Optional. Client's state or province.
`dateOfBirth`	string	Optional. Client's date of birth in `yyyy-MM-dd` format.

cURL Example

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

Response Example (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"
}

The Payment Card Object​

Attributes​

List Payment Cards​

Headers​

Query Parameters​

cURL Example​

Response Example (200 OK)​

Retrieve a Payment Card​

Path Parameters​

Headers​

cURL Example​

Response Example (200 OK)​

Create a Payment Card​

Headers​

Body Parameters​

Client Object (when provided)​

cURL Example​

Response Example (200 Created)​

The Payment Card Object

Attributes

List Payment Cards

Headers

Query Parameters

cURL Example

Response Example (200 OK)

Retrieve a Payment Card

Path Parameters

Headers

cURL Example

Response Example (200 OK)

Create a Payment Card

Headers

Body Parameters

Client Object (when provided)

cURL Example

Response Example (200 Created)