Testing Card Payments

When integrating payment flows in the TropiPay Sandbox environment (https://sandbox.tropipay.me), you must use dedicated test payment cards to simulate transaction lifecycles, authentications, and error scenarios.

Environment Restrictions

• Real cards will NOT work in the Sandbox environment.
• Sandbox test cards will NOT work in Production.
• Never attempt to process real cardholder data or live credit/debit cards in Sandbox.

---

Currency & Gateway (TPV) Routing

TropiPay routes transactions dynamically through multiple payment gateways (TPVs) based on several factors, including:

• Account Currency: EUR accounts, USD accounts, or crypto/stablecoin-denominated accounts (USDT / USDC).
• Merchant Gateway Assignment (TPV): Determined by the assigned paymentEntity for your processing account.

Payment Entity & Set Mapping

Card Set	Primary Account Currencies	paymentEntity	Notes
Set #1	EUR accounts	1	Multi-brand 3DS authentication gateway
Set #2	Multi-currency accounts	2, 4	Dual-scenario Visa/Mastercard processing
Set #3	Multi-currency accounts	1, 3	Standard simulator & error scenarios

Because payment processing rules and gateway configurations can vary or change dynamically, if a card from one set does not process as expected in your sandbox setup, try a card from another set.

General Sandbox Card Guidelines

Unless specified otherwise in a test scenario:

• Cardholder Name: Any name (e.g., John Doe).
• Expiration Date: Any valid future date (e.g., 12/30).
• Security Code (CVV / CVC): Any 3-digit number (e.g., 123), or 4 digits for American Express (e.g., 1234).
• 3D Secure (3DS) OTP: When prompted for SMS/OTP verification in Sandbox, use 123456.

---

Test Card Sets

Set #1: Multi-Brand Gateway Testing (paymentEntity: 1, EUR accounts)

This set is mostly used in EUR accounts with paymentEntity: 1 and allows testing standard 3D Secure / authentication lifecycles across major card networks.

Successful Authentication

Brand	Card Number	Expected Status
American Express (AMEX)	340000000004001	Successful (Authentication OK)
Discover	6573700000000009	Successful (Authentication OK)
Mastercard	5591390000000504	Successful (Authentication OK)
Visa	4900490000000501	Successful (Authentication OK)

Simulated Errors (Authentication Unsuccessful)

Brand	Card Number	Scenario / Result
American Express (AMEX)	340000000004019	Status: N (Authentication unsuccessful / 3DS query failed)
Discover	6599999900000313	Status: N (Authentication unsuccessful)
Mastercard	5591390000000520	Status: N (Authentication unsuccessful)
Visa	4900490000000519	Status: N (Authentication unsuccessful)

---

Set #2: Dual-Scenario Gateway Testing (paymentEntity: 2 and 4)

Use this set when testing accounts configured with paymentEntity: 2 and paymentEntity: 4.

Brand	Scenario	Card Number
Visa	Successful	4000000000002503
Mastercard	Successful	5200000000002151
Visa	Failed	4000000000002420
Mastercard	Failed	5200000000002664

---

Set #3: Standard Simulator & Specific Error Scenarios (paymentEntity: 1 and 3)

Use this set when testing accounts configured with paymentEntity: 1 and paymentEntity: 3 to test edge cases such as general card declines, insufficient funds, and card expiration.

Successful Transactions

Brand	Card Number
Visa	4111111111111111
Mastercard	5555555555555555
Maestro	6771290000000001

Simulating Error Scenarios

Scenario	Card Number / Condition	Details
Declined Card (General)	4000000000000002	Simulates a generic issuer decline.
Insufficient Funds	4111111111111002	Simulates a transaction declined due to insufficient balance.
Expired Card	Any valid test card number	Enter an expiration date in a past month/year (e.g., 01/20).

---

Handling Callbacks & Webhook Events

Testing Tip

You do not need to trigger every possible payment error permutation (e.g., insufficient funds, authorization error, 3DS challenge timeout) individually. Instead, ensure your callback and webhook handlers correctly process the standard payload schemas for completed and failed states.

When a card payment state changes or fails, TropiPay dispatches a callback event to your configured endpoint (notificationUrl or subscribed webhook target).

Example: Payment State Change / Failed Callback

Below is an example of the callback event received when a card payment state transition occurs or fails:

{
  "signature": "b2740b505314ef1577235b5c8d484e312b64ed3fade27324fe23ef1bb1f8f4cd",
  "event_name": "payment_in_state_change",
  "userId": "10951e80-6218-11ef-9e2f-7f00b2bfc1f3",
  "date": 1786830266966,
  "uuid": "ae4c6fdf-449d-496a-9622-03b863e366e6",
  "data": {
    "stateStr": "processing",
    "state": 1,
    "id": 5091118,
    "reference": "TAB1508260286",
    "bankOrderCode": "636452502154",
    "conceptTransfer": null,
    "service": 2,
    "movementType": 2,
    "destinationAmount": "4976"
  }
}

Callback Payload Attributes

Field	Type	Description
signature	string	HMAC-SHA256 signature to verify that the payload originated from TropiPay.
event_name	string	Name of the dispatched event (e.g., payment_in_state_change).
userId	string	Unique identifier of the TropiPay merchant user.
date	number	Unix timestamp (in milliseconds) of when the callback was dispatched.
uuid	string	Unique notification tracking UUID.
data.id	number	Internal ID of the transaction/booking.
data.reference	string	Your internal order reference provided during payment creation.
data.bankOrderCode	string	TropiPay bank order tracking code.
data.state	number	Numeric state of the transaction.
data.stateStr	string	Human-readable state string (e.g., processing, completed, failed).
data.destinationAmount	string	Transaction amount settled.

Best Practices for Testing

1. Always Return HTTP 200 Immediately: Your webhook receiver endpoint must respond with an HTTP 200 OK status immediately upon receipt to acknowledge delivery.
2. Process Asynchronously: Defer database updates, order fulfillments, and external API calls to background queues after returning the 200 response.
3. Validate Signatures: Always compute and verify the payload signature using your secret key to prevent spoofing.
4. Use Webhook Inspection Tools: Tools like Webhook.site or ngrok make it easy to inspect payloads and debug callbacks during sandbox testing.