This guide shows you how to accept credit and debit card payments using Tonder’s unified API. You’ll learn to process both regular card payments and handle 3D Secure authentication when required.

​
Step 1: Prepare Your Card Payment Request

Create your payment request with the card payment method. Always use tokenized card data when possible for enhanced security. 
{
  "operation_type": "payment",
  "amount": 150.00,
  "currency": "MXN",
  "customer": {
    "name": "Ana María Rodríguez",
    "email": "ana.rodriguez@email.com"
  },
  "payment_method": {
    "type": "CARD",
    "card_number": "9230-0892-4469-1474",        // Tokenized
    "cardholder_name": "c05d89b2-299c-4f93-b49a-42be00d3b64b", // Tokenized
    "cvv": "d31f0da3-0ed3-4ad8-8b68-14c2669a99a7",             // Tokenized
    "expiration_month": "e401a32e-4174-424f-9688-727005f6a80e", // Tokenized
    "expiration_year": "bd9ccc23-3d00-4109-9626-fc6581389063"  // Tokenized
  },
  "client_reference": "order-789",
  "return_url": "https://yourstore.com/payment/return"
}
Always include a return_url when processing card payments. This is required for 3D Secure authentication flows.

​
Step 2: Send the Payment Request

Make a POST request to the unified payment endpoint: 
curl -X POST https://stage.tonder.io/api/v1/process/ \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_type": "payment",
    "amount": 150.00,
    "currency": "MXN",
    "customer": {
      "name": "Ana María Rodríguez",
      "email": "ana.rodriguez@email.com"
    },
    "payment_method": {
      "type": "CARD",
      "card_number": "9230-0892-4469-1474",
      "cardholder_name": "c05d89b2-299c-4f93-b49a-42be00d3b64b",
      "cvv": "d31f0da3-0ed3-4ad8-8b68-14c2669a99a7",
      "expiration_month": "e401a32e-4174-424f-9688-727005f6a80e",
      "expiration_year": "bd9ccc23-3d00-4109-9626-fc6581389063"
    },
    "client_reference": "order-789",
    "return_url": "https://yourstore.com/payment/return"
  }'

​
Step 3: Handle the Response

​
Payment Response Scenarios

Card payments can have different response flows depending on whether 3D Secure authentication is required. When no additional authentication is needed, the payment is processed immediately and returns an authorized status. When additional authentication is required, the customer will be redirected to their bank and the response includes redirect information. 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "payment",
  "status": "authorized",
  "amount": 150.00,
  "currency": "MXN",
  "payment_id": 12345,
  "transaction_id": "txn_abc123",
  "created_at": "2024-07-26T10:30:00Z"
}

​
Step 4: Handle 3D Secure Authentication

When 3D Secure is required, follow these steps:
1

Redirect the customer to the 3DS URL

Use the URL provided in next_action.redirect_to_url.url to redirect your customer.
2

Customer completes authentication

The customer will complete the 3D Secure challenge on their bank’s page.
3

Customer returns to your site

After authentication, the customer is redirected back to your return_url.
4

Check the final payment status

Make a GET request to verify the final payment status.
curl -X GET https://stage.tonder.io/api/v1/transactions/550e8400-e29b-41d4-a716-446655440000/ \
  -H "Authorization: Token YOUR_API_KEY"

​
Implementation Tips

Follow the best practices below to handle card payments:
  • Always use tokenized card data to reduce PCI compliance scope.
  • Ensure your UI can handle redirect flows smoothly for 3D Secure authentication.
  • Save the transaction ID for future reference and reconciliation.
  • Use test cards to verify both successful and failed scenarios.
  • Never store raw card data on your servers.
  • Always use HTTPS for all API communications.
  • Implement proper error handling to avoid exposing sensitive information.
  • Use webhooks to track payment status changes asynchronously.

​
PCI Compliant Raw Card Processing

For merchants with full PCI DSS Level 1 compliance, Tonder offers direct raw card processing that bypasses tokenization. This section covers the security requirements and considerations for this approach. When processing raw card data, you must maintain full PCI DSS Level 1 compliance. This section provides the essential requirements and best practices to ensure secure card data handling.
These are the core security requirements for PCI compliant processing:
  • Protect stored, processed, and transmitted card data at all times.
  • Use TLS 1.2+ for all card data transmissions.
  • Restrict access to card data on need-to-know basis only.
  • Log and monitor all access to cardholder data environments.
  • Continuously test security systems and processes.
  • Maintain ongoing compliance validation and documentation.
Prohibited ActionsThese are the prohibited actions with card data:
  • Do not store CVV data after authorization.
  • Do not store card data without encryption or tokenization.
  • Do not log card numbers, CVV, or expiration dates.
  • Do not use HTTP without TLS 1.2+ encryption.
Required ActionsAlways make sure to perform these actions when processing card data:
  • Check card data format before processing.
  • Confirm HTTPS before transmission.
  • Log all access to payment processing systems.
  • Apply security patches regularly.

​
PCI Compliant vs Tokenized Processing

The following table compares PCI compliant raw card processing with tokenized processing to help you choose the right approach:
AspectPCI Compliant ProcessingTokenized Processing
API Calls1 step (direct process)3 steps (auth → tokenize → process)
PCI ComplianceFull PCI DSS Level 1 requiredNot required for merchant
Integration ComplexityLower (single endpoint)Higher (multiple endpoints)
LatencyLower (direct processing)Higher (additional API calls)
Security ResponsibilityMerchant responsibilityHandled by Tonder/Skyflow
Maintenance CostHigher (compliance audits)Lower
Card Data StorageProhibited without encryptionTokens can be safely stored
Infrastructure RequirementsDedicated secure serversStandard infrastructure
Audit RequirementsAnnual PCI DSS auditsMinimal compliance requirements
Choose PCI compliant processing only if you already have full PCI DSS Level 1 certification and dedicated infrastructure. For most merchants, tokenized processing is the recommended approach.

​
Next Steps