Test token payments

Use the Centrobill staging environment to test the full tokenization flow — from generating a synthetic card to tokenizing it and making a payment using the token. All staging requests go to https://api-stage.centrobill.com.

Step 1: Create a test card

Generate a synthetic card using the Test Data API:

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 card number you will tokenize in the next step:

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

For the full range of simulation options (balance control, blocked card, 3DS emulation), see Test card payments.

Step 2: Tokenize the card

Pass the card number from Step 1 to POST /tokenize. This exchanges the raw card number for a short-lived token:

curl --request POST \
  --url https://api-stage.centrobill.com/tokenize \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "4024007179366348",
    "expirationMonth": "12",
    "expirationYear": "30",
    "cvv": "123",
    "cardHolder": "TEST USER"
  }'

A successful response returns the token:

{
  "token": "YOUR_TOKEN",
  "expireAt": 1711735028
}

Save the token value — you will use it in the payment request. Note that expireAt is a Unix timestamp after which the token is no longer valid.

Step 3: Make a payment using the token

Use the token from Step 2 in a POST /payment request. Set paymentSource.type to token and paymentSource.value to the token:

curl --request POST \
  --url https://api-stage.centrobill.com/payment \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'X-Request-ID: YOUR_UNIQUE_REQUEST_ID' \
  --data '{
    "paymentSource": {
      "type": "token",
      "value": "YOUR_TOKEN",
      "cvv": "123"
    },
    "consumer": {
      "email": "[email protected]"
    },
    "sku": {
      "siteId": "YOUR_SITE_ID",
      "sku": "YOUR_SKU_ID"
    },
    "url": {
      "ipnUrl": "https://your-server.example.com/ipn",
      "redirectUrl": "https://your-server.example.com/return"
    }
  }'

Step 4: Verify IPN delivery

After the payment request, 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.

Simulate different outcomes

The token inherits the behaviour of the underlying test card. To simulate a specific outcome, update the test card before tokenizing: