Testing Guide

Overview

This guide provides comprehensive testing scenarios for KOIN payment integration. All examples use the sandbox environment where no real money is processed.

Sandbox Environment

Base URL: https://api.firstoken-staging.co/v1/payments/
Environment: Complete simulation of production KOIN processing
Test Cards: Any valid card format works in sandbox
Real-time Testing: All flows work exactly like production

Test Card Numbers

For KOIN testing, you can use any valid card number format. The payment processing is simulated based on other request parameters.

Test Card Numbers

For KOIN testing, you can use any valid card number format. The system will simulate the payment flow:

Card Brand

Number

CVV

Notes

Visa

4111 1111 1111 1111

Any 3-digit

Standard test

Mastercard

5555 5555 5555 4444

Any 3-digit

Standard test

American Express

3782 8224 6310 005

Any 4-digit

Requires 4-digit CVV

Important Notes:

Use any expiration date in the future (MM/YYYY format)
Cardholder name can be any valid name format
All cards work in sandbox for testing different scenarios

Amount-Based Testing

Control transaction outcomes by using specific amounts in your test requests. KOIN uses transaction amounts to simulate different scenarios:

Amount Range (cents)

Initial Status

Final Status

Description

1 - 5000

Authorized

Success

5001 - 10000

Authorized

Failed

InsufficientFunds

10001 - 15000

Authorized

Failed

InvalidCard

15001 - 20000

Authorized

Failed

ExpiredCard

20001 - 25000

Authorized

Failed

StolenCard

25001 - 30000

Authorized

Failed

ProcessingError

30001 - 35000

Failed

Rejected

40001 - 45000

Pending

Authorized

Antifraud approved after review

45001 - 50000

Pending

Failed

Antifraud rejected

50001 - 55000

Pending

Authorized

Manual review - approved

55001 - 60000

Pending

Failed

Manual review - rejected

100000+

Authorized

High-value success

Example: To test a successful payment, use amount 15 (R$ 15). To test antifraud review, use amount 420 (R$ 420).

Document Testing

Valid CPF Numbers for Testing

CPF

Use Case

12345678901

Standard valid CPF

11144477735

Alternative valid CPF

54672396002

KOIN documentation example

Invalid CPF for Error Testing

CPF

Expected Error

00000000000

Invalid CPF format

11111111111

Invalid CPF format

123

Invalid CPF length

Complete Test Scenarios

1. Successful Payment Flow

curl -X POST https://api.firstoken.co/v1/payments/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_info": {
      "type": "payment",
      "reference_code": "test_ref_' $(date +%s) '"
    },
    "card": {
      "number": "4111111111111111",
      "expiration_date": "12/2030",
      "security_code": "123",
      "holder": "João Silva"
    },
    "order_info": {
      "amount_details": {
        "total_amount": 1500,
        "currency": "BRL",
        "items_amount": 1500
      },
      "installments": 1,
      "descriptor": "Teste Payment"
    },
    "cardholder_info": {
      "first_name": "João",
      "last_name": "Silva",
      "document": {
        "type": "CPF",
        "number": "12345678901",
        "nationality": "BR"
      },
      "country": "BR",
      "address_1": "Rua Teste, 123",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01234-567",
      "email": "joao.silva@test.com",
      "phone_number": "11987654321",
      "phone_type": "Mobile",
      "phone_area_code": "11"
    },
    "bill_to": {
      "id": "customer_test_123",
      "first_name": "João",
      "last_name": "Silva",
      "document": {
        "type": "CPF",
        "number": "12345678901",
        "nationality": "BR"
      },
      "country": "BR",
      "address_1": "Rua Teste, 123",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01234-567",
      "email": "joao.silva@test.com",
      "phone_number": "11987654321",
      "phone_type": "Mobile",
      "phone_area_code": "11",
      "profile": "test_customer"
    },
    "line_items": [
      {
        "id": "item_test_001",
        "name": "Produto Teste",
        "price": 1500,
        "quantity": 1,
        "type": "Physical"
      }
    ],
    "device_info": {
      "fingerprint_session_id": "test_session_' $(date +%s) '",
      "ip_address": "192.168.1.100"
    }
  }'

2. Authorization + Capture Flow

Step 1: Authorization

curl -X POST https://api.firstoken.co/v1/payments/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_info": {
      "type": "authorization",
      "transaction_id": "test_auth_' $(date +%s) '",
      "reference_code": "test_auth_ref_' $(date +%s) '"
    },
    "card": {
      "number": "5555555555554444",
      "expiration_date": "12/2030",
      "security_code": "123",
      "holder": "Maria Santos"
    },
    "order_info": {
      "amount_details": {
        "total_amount": 5000,
        "currency": "BRL",
        "items_amount": 5000
      },
      "installments": 1,
      "descriptor": "Teste Authorization"
    },
    "cardholder_info": {
      "first_name": "Maria",
      "last_name": "Santos",
      "document": {
        "type": "CPF",
        "number": "54672396002",
        "nationality": "BR"
      },
      "country": "BR",
      "address_1": "Avenida Teste, 456",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "postal_code": "20000-000",
      "email": "maria.santos@test.com",
      "phone_number": "21987654321",
      "phone_type": "Mobile",
      "phone_area_code": "21"
    },
    "bill_to": {
      "id": "customer_maria_456",
      "first_name": "Maria",
      "last_name": "Santos",
      "document": {
        "type": "CPF",
        "number": "54672396002",
        "nationality": "BR"
      },
      "country": "BR",
      "address_1": "Avenida Teste, 456",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "postal_code": "20000-000",
      "email": "maria.santos@test.com",
      "phone_number": "21987654321",
      "phone_type": "Mobile",
      "phone_area_code": "21",
      "profile": "premium_customer"
    },
    "line_items": [
      {
        "id": "service_001",
        "name": "Serviço Premium",
        "price": 5000,
        "quantity": 1,
        "type": "Service"
      }
    ],
    "device_info": {
      "fingerprint_session_id": "test_auth_session_' $(date +%s) '",
      "ip_address": "203.0.113.50"
    }
  }'

Step 2: Capture (use transaction_id from step 1)

curl -X POST https://api.firstoken.co/v1/payments/{TRANSACTION_ID_FROM_STEP_1}/capture \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_info": {
      "type": "capture",
      "reference_code": "test_capture_' $(date +%s) '"
    },
    "capture_info": {
      "amount_details": {
        "total_amount": 5000,
        "currency": "BRL"
      },
      "installments": 1
    },
    "device_info": {
      "ip_address": "203.0.113.50"
    }
  }'

3. Authorization + Void Flow

Step 1: Authorization (same as above)

Step 2: Void (use transaction_id from step 1)

curl -X POST https://api.firstoken.co/v1/payments/{TRANSACTION_ID_FROM_STEP_1}/void \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_info": {
      "type": "authorization_void",
      "reference_code": "test_void_' $(date +%s) '"
    },
    "device_info": {
      "ip_address": "203.0.113.50"
    }
  }'

4. Payment + Refund Flow

Step 1: Payment (use payment example above)

Step 2: Void (use transaction_id from step 1)

curl -X POST https://api.firstoken.co/v1/payments/{TRANSACTION_ID_FROM_STEP_1}/void \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_info": {
      "type": "payment_refund",
      "reference_code": "test_refund_' $(date +%s) '"
    },
    "refund_info": {
        "amount_details": {
            "total_amount": 1000,
            "currency": "BRL"
        },
        "installments": 1
    },
    "device_info": {
      "ip_address": "192.168.1.100"
    }
  }'

Error Testing Scenarios

1. Missing Required Fields

# Test missing CPF
curl -X POST https://api.firstoken.co/v1/payments/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_info": {
      "type": "payment",
      "reference_code": "test_error_ref"
    },
    "card": {
      "number": "4111111111111111",
      "expiration_date": "12/2030",
      "security_code": "123",
      "holder": "Test User"
    },
    "order_info": {
      "amount_details": {
        "total_amount": 1000,
        "currency": "BRL",
        "items_amount": 1000
      },
      "installments": 1,
      "descriptor": "Test Error"
    },
    "cardholder_info": {
      "first_name": "Test",
      "last_name": "User",
      "country": "BR",
      "email": "test@example.com"
      // Missing document field - should cause error
    }
  }'

2. Invalid CPF Format

# Test invalid CPF
curl -X POST https://api.firstoken.co/v1/payments/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_info": {
      "type": "payment",
      "reference_code": "test_invalid_cpf_ref"
    },
    "cardholder_info": {
      "first_name": "Test",
      "last_name": "User",
      "document": {
        "type": "CPF",
        "number": "00000000000",
        "nationality": "BR"
      },
      "country": "BR",
      "email": "test@example.com"
    }
    // ... rest of required fields
  }'

Best Practices for Testing

Use Unique IDs: Always generate unique transaction IDs
Test All Flows: Test complete workflows, not just individual endpoints
Error Handling: Test both success and failure scenarios
Documentation: Document test cases and expected results
Environment Separation: Keep test data clearly separated from production

PreviousAuthorization Void NextRisk

Last updated 12 days ago

Was this helpful?