Testing

Testing & Sandbox

Test your integration safely before going live with our sandbox environment.

Sandbox Environment

The sandbox environment allows you to test all API features without processing real payments. All test transactions are simulated and no real money is processed.

Safe Testing

No real money is processed

Test Scenarios

Simulate success, failures, and edge cases

Same API

Identical endpoints to production

Sandbox Base URL

Use the same base URL for sandbox: https://cashier.flowpayment.net. The environment is determined by your API key prefix.

Test API Keys

Your API key prefix determines whether you're using sandbox or production:

Prefix	Environment	Description
`sk_test_`	Sandbox	Use for development and testing
`sk_live_`	Production	Use for real transactions

Getting Test Keys

Go to Configuration → API Keys

Copy your Test API Key (starts with sk_test_)

Use this key for all sandbox testing

Test Cards (Izipay)

Use these test card numbers to simulate different payment scenarios:

Card Type	Number	Result
Visa Approved	`4970 1000 0000 0014`	`Success`
Visa 3DS	`4970 1000 0000 0063`	`3DS Flow`
Visa Declined	`4970 1000 0000 0022`	`Declined`
Mastercard	`5200 0000 0000 0007`	`Success`

Test Card Details

CVV

Any 3 digits

e.g., 123

Expiry Date

Any future date

e.g., 12/2028

Cardholder Name

Any name

e.g., John Doe

Test PIX (SFP)

PIX payments in sandbox mode work with any valid CPF format:

CPF Format

Any valid CPF format works (11 digits)

Instant Approval

All PIX payments approved instantly in sandbox

QR Code in Sandbox

The QR code generated in sandbox mode is valid for display testing but will not process actual payments when scanned. The payment is automatically approved after a few seconds.

Test CPF Numbers

test-cpfs.txt

# Any of these CPF formats work in sandbox:
123.456.789-09
12345678909
000.000.000-00

# The API validates the format but doesn't verify against real databases

Test Payouts

Payout testing in sandbox validates the format of PIX keys and bank details without executing real transfers:

Payout Type	Validation	Sandbox Behavior
PIX Key	Format validated	Not executed (simulated success)
CLABE (Mexico)	18-digit format	Not executed (simulated success)
CVU (Argentina)	22-digit format	Not executed (simulated success)

Instant Processing

All payouts in sandbox are processed instantly and marked as successful. No actual transfers are made.

Mock Provider

Control test outcomes using special amount values. The decimal portion determines the result:

Amount Ending	Result	Example
`.01`	`Approved`	`100.01`, `50.01`
`.02`	`Declined`	`100.02`, `75.02`
`.03`	`Pending`	`100.03`, `200.03`
Any other	`Approved`	`100.00`, `50.99`

Example: Testing Declined Payment

test-decline.sh

curl -X POST "https://cashier.flowpayment.net/api/v1/checkout" \
  -H "X-API-Key: sk_test_your_test_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.02,
    "currency": "BRL",
    "country": "BRA",
    "success_url": "https://your-site.com/success",
    "cancel_url": "https://your-site.com/cancel"
  }'

# This will result in a declined payment when processed

Webhook Testing

Test your webhook integration using these recommended tools:

webhook.site

Get a unique URL instantly to receive and inspect webhooks. Perfect for quick testing.

ngrok

Expose your local server to the internet. Ideal for local development and debugging.

Using ngrok

ngrok-setup.sh

# Install ngrok (macOS)
brew install ngrok

# Start a tunnel to your local server
ngrok http 3000

# Use the generated URL as your notification_url
# Example: https://abc123.ngrok.io/webhooks/cashier

Dashboard Webhook Logs

View all webhook attempts and their responses in your dashboard:

Go to Configuration → Webhooks

View the webhook delivery history

Inspect request payloads and response codes

Retry failed webhooks manually

Testing Checklist

Before going to production, ensure you've tested all these scenarios:

Integration Checklist

Create checkout session

POST /api/v1/checkout

Process PIX payment

Display QR code and copy-paste code

Process card payment

Test with approved and declined cards

Handle 3DS redirect

Complete 3D Secure authentication flow

Receive webhooks

Verify signature and process events

Create payout

Test PIX key and bank account payouts

Handle errors

Test validation errors and edge cases

Session expiration

Verify expired session handling

Idempotency

Test duplicate request handling

Going to Production

When you're ready to go live, follow these steps:

Replace API Keys

Change from sk_test_ to sk_live_ in your application

Update Webhook URLs

Point to your production webhook endpoints (not webhook.site or ngrok)

Enable Provider Credentials

Ensure your PSP credentials (SFP, Izipay) are configured for production

Remove Test Amount Logic

Stop using special amounts (.01, .02, .03) for controlling results

Monitor First Transactions

Watch the dashboard closely for the first few production transactions

Production Ready

Once you've completed all checklist items and made the changes above, you're ready to process real payments!

Common Test Scenarios

Test Successful PIX Payment

test-pix-success.sh

1 # 1. Create checkout session
2 curl -X POST "https://cashier.flowpayment.net/api/v1/checkout" \
3   -H "X-API-Key: sk_test_your_key" \
4   -H "Content-Type: application/json" \
5   -d '{
6     "amount": 100.01,
7     "currency": "BRL",
8     "country": "BRA",
9     "success_url": "https://example.com/success",
10     "cancel_url": "https://example.com/cancel",
11     "notification_url": "https://your-webhook.site/test"
12   }'
13 
14 # Response: { "checkout_url": "https://...", "session_id": "cs_xxx" }
15 
16 # 2. Process PIX payment (done by checkout frontend)
17 curl -X POST "https://cashier.flowpayment.net/api/v1/checkout/process" \
18   -H "Content-Type: application/json" \
19   -d '{
20     "session_id": "cs_xxx",
21     "method_code": "s-interio-mt-1",
22     "customer": {
23       "name": "Test User",
24       "email": "test@example.com",
25       "document": "12345678909"
26     }
27   }'
28 
29 # Response: { "pix_code": "00020126...", "status": "pending" }
30 # In sandbox, payment auto-approves after a few seconds

Test Card Payment with 3DS

test-card-3ds.sh

1 # Process card payment with 3DS test card
2 curl -X POST "https://cashier.flowpayment.net/api/v1/checkout/process" \
3   -H "Content-Type: application/json" \
4   -d '{
5     "session_id": "cs_xxx",
6     "method_code": "s-interio-mt-2",
7     "customer": {
8       "name": "Test User",
9       "email": "test@example.com",
10       "document": "12345678909"
11     },
12     "card": {
13       "number": "4970100000000063",
14       "holder_name": "TEST USER",
15       "expiry_month": "12",
16       "expiry_year": "2028",
17       "cvv": "123"
18     }
19   }'
20 
21 # Response includes redirect_url for 3DS authentication
22 # { "redirect_url": "https://3ds.provider.com/auth/xxx", "status": "processing" }

Test Declined Card

test-card-decline.sh

1 # Process card payment with declined test card
2 curl -X POST "https://cashier.flowpayment.net/api/v1/checkout/process" \
3   -H "Content-Type: application/json" \
4   -d '{
5     "session_id": "cs_xxx",
6     "method_code": "s-interio-mt-2",
7     "customer": {
8       "name": "Test User",
9       "email": "test@example.com",
10       "document": "12345678909"
11     },
12     "card": {
13       "number": "4970100000000022",
14       "holder_name": "TEST USER",
15       "expiry_month": "12",
16       "expiry_year": "2028",
17       "cvv": "123"
18     }
19   }'
20 
21 # Response: { "success": false, "status": "failed", "error_message": "Card declined" }

1	# 1. Create checkout session
2	curl -X POST "https://cashier.flowpayment.net/api/v1/checkout" \
3	-H "X-API-Key: sk_test_your_key" \
4	-H "Content-Type: application/json" \
5	-d '{
6	"amount": 100.01,
7	"currency": "BRL",
8	"country": "BRA",
9	"success_url": "https://example.com/success",
10	"cancel_url": "https://example.com/cancel",
11	"notification_url": "https://your-webhook.site/test"
12	}'
13
14	# Response: { "checkout_url": "https://...", "session_id": "cs_xxx" }
15
16	# 2. Process PIX payment (done by checkout frontend)
17	curl -X POST "https://cashier.flowpayment.net/api/v1/checkout/process" \
18	-H "Content-Type: application/json" \
19	-d '{
20	"session_id": "cs_xxx",
21	"method_code": "s-interio-mt-1",
22	"customer": {
23	"name": "Test User",
24	"email": "test@example.com",
25	"document": "12345678909"
26	}
27	}'
28
29	# Response: { "pix_code": "00020126...", "status": "pending" }
30	# In sandbox, payment auto-approves after a few seconds

1	# Process card payment with 3DS test card
2	curl -X POST "https://cashier.flowpayment.net/api/v1/checkout/process" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"session_id": "cs_xxx",
6	"method_code": "s-interio-mt-2",
7	"customer": {
8	"name": "Test User",
9	"email": "test@example.com",
10	"document": "12345678909"
11	},
12	"card": {
13	"number": "4970100000000063",
14	"holder_name": "TEST USER",
15	"expiry_month": "12",
16	"expiry_year": "2028",
17	"cvv": "123"
18	}
19	}'
20
21	# Response includes redirect_url for 3DS authentication
22	# { "redirect_url": "https://3ds.provider.com/auth/xxx", "status": "processing" }

1	# Process card payment with declined test card
2	curl -X POST "https://cashier.flowpayment.net/api/v1/checkout/process" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"session_id": "cs_xxx",
6	"method_code": "s-interio-mt-2",
7	"customer": {
8	"name": "Test User",
9	"email": "test@example.com",
10	"document": "12345678909"
11	},
12	"card": {
13	"number": "4970100000000022",
14	"holder_name": "TEST USER",
15	"expiry_month": "12",
16	"expiry_year": "2028",
17	"cvv": "123"
18	}
19	}'
20
21	# Response: { "success": false, "status": "failed", "error_message": "Card declined" }