Test card payments

Use the Centrobill staging environment to generate synthetic card credentials and simulate different payment outcomes before going live. You can create and manage test cards either through the Merchant Portal or the Test Data API.

📘
Note
Test payments can be created only for the Parent merchant account but are visible across all daughter accounts. Make sure you are logged in as the Parent merchant before creating test data.

Step 1: Create a test card

Via the Merchant Portal

Log in to the Merchant Portal.
In the main menu, under Merchant, click Test payments.
Click Create test payment.
Fill in the following fields:

Field	Description
Merchant	Select the Parent merchant account
Type	Select the card type to generate (for example, Visa or Mastercard)
Balance	Set the available balance on the test card. Controls whether charges succeed or are declined
Currency	Select the currency for the test card balance
Allowed IPs	Enter the IP address of the server that will send payment requests using this card
Emulate 3DS	Toggle on to simulate the 3DS challenge flow for this card
Is blocked	Toggle on to simulate a blocked card — all charges will be declined
Comment	Optional. Add a note for your own reference

Click Create. You are redirected to the Test payments page where your new card number appears.
Use Ctrl+F to search by IP address to locate the card you just created.

Via the API

Send a POST request to /testPaymentData on the staging endpoint:

curl --request POST \
  --url https://api-stage.centrobill.com/testPaymentData \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "visa",
    "emulate3ds": false,
    "balance": 100,
    "currency": "USD"
  }'

A successful response returns the test card object including the generated card number and id:

{
  "id": 1234,
  "type": "visa",
  "emulate3ds": false,
  "number": "4024007179366348",
  "balance": 100,
  "blocked": false,
  "allowedIps": [],
  "createdAt": "2022-01-27 10:11:39",
  "updatedAt": "2022-01-27 10:11:39"
}

📘
Note
The type field accepts the same card type values available in the Type dropdown in the Merchant Portal. Contact Merchant Support to confirm the full list of supported values.

Step 2: Run a test payment

Use the generated card number in a payment request exactly as you would in production. Pass the card number directly in paymentSource for the direct card flow.

Step 3: Simulate different outcomes

Successful charge

Set balance to a positive value equal to or greater than the charge amount. The payment will be approved.

Insufficient funds decline

Set balance to 0. The next charge attempt will be declined due to insufficient funds.

Via the Merchant Portal: click Edit next to the card entry and update the balance field.

Via the API:

curl --request PUT \
  --url https://api-stage.centrobill.com/testPaymentData/{id}/balance \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"balance": 0}'

Blocked card decline

Via the Merchant Portal: toggle Is blocked on when creating or editing a card.

Via the API:

curl --request POST \
  --url https://api-stage.centrobill.com/testPaymentData/{id}/block \
  --header 'Authorization: YOUR_API_KEY'

All charges against a blocked card are declined regardless of balance. To unblock:

curl --request POST \
  --url https://api-stage.centrobill.com/testPaymentData/{id}/unblock \
  --header 'Authorization: YOUR_API_KEY'

3DS challenge flow

Via the Merchant Portal: toggle Emulate 3DS on when creating or editing a card.

Via the API:

curl --request POST \
  --url https://api-stage.centrobill.com/testPaymentData/{id}/emulate3ds \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"emulate3ds": true}'

To simulate the frictionless flow instead (no redirect required):

curl --request POST \
  --url https://api-stage.centrobill.com/testPaymentData/{id}/notEmulate3ds \
  --header 'Authorization: YOUR_API_KEY'

See Test 3DS in the staging environment for how to handle each flow in your integration.

Step 4: Verify IPN delivery

After each test payment, confirm that Centrobill delivers an IPN to your configured ipnUrl and that your server responds with 200, 201, or 202. Check payment.code and payment.status in the payload to confirm the expected outcome was delivered.

If a callback doesn't arrive, verify that Centrobill's IP addresses are allowlisted on your server. See IPN reference for the full retry schedule and validation details.

Step 5: Manage test cards

Edit or delete a card

Via the Merchant Portal: click Edit or Delete next to the card entry on the Test payments page.

Via the API:

curl --request DELETE \
  --url https://api-stage.centrobill.com/testPaymentData/{id} \
  --header 'Authorization: YOUR_API_KEY'