Skip to main content

​
Your First Payment

Get started with Cheqpay by processing your first test payment. This guide will walk you through a simple card payment.
1

Get Your API Key

Sign up for a Cheqpay account and copy your sandbox API key from the dashboard.
export CHEQPAY_API_KEY="your_sandbox_api_key"
2

Make Your First API Call

Create a payment with a test card:
curl -X POST https://api.cheqpay.dev/payment-orders \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "order-123",
    "customer": {
      "firstName": "María",
      "lastName": "González",
      "email": "[email protected]",
      "phoneNumber": "+31431453454"
    },
    "amount": 10000,
    "currency": "MXN",
    "description": "Product purchase",
    "paymentMethod": {
      "type": "card",
      "options": {
        "card": {
          "number": "4000000000002503",
          "expiryMonth": "12",
          "expiryYear": "2025",
          "cvc": "123"
        }
      }
    }
  }'
3

Check the Response

You’ll receive a successful response with the payment details:
{
  "id": "291348e9-62f3-48dd-83c1-eef69d71c16a",
  "orderNumber": "C2510301",
  "externalMerchantReference": "ORDER-8-test",
  "amount": 100,
  "currency": "MXN",
  "status": "COMPLETED",
  "description": "Payment with existing customer and new card",
  "createdAt": "2025-10-30T23:02:16.715Z",
  "paymentMethod": {
    "type": "CARD",
    "id": "6b987cae-dd80-47d1-965a-776db006e2a9",
    "cardDetails": {
        "id": "29a2bd07-5dcd-4877-a9e2-4496d06bcfec",
        "bin": "411111",
        "last4": "1111",
        "brand": "VISA",
        "type": "DEBIT",
        "country": "POLAND",
        "issuerBank": "CONOTOXIA SP. Z O.O",
        "expiryMonth": "04",
        "expiryYear": "28"
    }
  },
  "customer": {
    "id": "0e045958-5dea-491e-8b3d-70663b1ee992",
    "firstName": "María",
    "lastName": "González",
    "email": "[email protected]",
    "phoneNumber": "+31431453454"
  }
}
That’s it! You’ve processed your first payment with Cheqpay. 🎉

​
Understanding the Request

Let’s break down the key fields in the payment request:

​
Required Fields

FieldTypeDescription
externalIdstringYour unique order ID (prevents duplicate charges)
amountintegerAmount in the smallest currency unit (10000 = $100.00 MXN)
currencystringISO currency code (MXN, USD)
paymentMethodobjectPayment method details

​
Customer Information

{
  "customer": {
    "firstName": "María",
    "lastName": "González",
    "email": "[email protected]",
    "phoneNumber": "+521555123456"
  }
}
Customers are automatically created on first payment. Use the the id returned by the first payment to retrieve the existing customer and on subsequent payments.

​
Card Details

{
  "paymentMethod": {
    "type": "card",
    "options": {
      "card": {
        "number": "4000000000002503",
        "expiryMonth": "12",
        "expiryYear": "2025",
        "cvc": "123"
      }
    }
  }
}
Card data is automatically tokenized for security. Sensitive information never touches your servers.

​
What Happens Next?

When you create a payment, Cheqpay:
  1. Creates or updates the customer record
  2. Tokenizes the card securely
  3. Authorizes the payment with the card network
  4. Captures the funds immediately
  5. Updates the status to COMPLETED
  6. Sends a confirmation to the customer (if enabled)
The entire process typically takes 2-5 seconds.

​
Important Notes

Always specify amounts in cents (minor units). For example:
  • 10000 = $100.00 MXN
  • 150 = $1.50 MXN
  • 999999 = $9,999.99 MXN
The externalId prevents duplicate charges. If you send the same request twice:
  • Successful payment → Returns existing payment (no duplicate)
  • Failed payment → Creates new payment (allows retry)
Card numbers are instantly converted to secure tokens. You never need to handle raw card data on your servers.

​
Next Steps

Now that you’ve processed your first payment, explore more features:

Save Payment Methods

Store cards for returning customers

Handle 3D Secure

Implement authentication challenges

Manage Customers

Track customer information and history

Process Refunds

Issue full or partial refunds

View Complete Testing Guide

Learn about test cards, scenarios, and going live