Accept Card Payments Accept card payments in a single API request. Process credit and debit cards from Visa, Mastercard, and American Express through a unified checkout experience.
PCI Compliance Required If you integrate directly with the Payments API and handle raw card data (card number, CVV, expiry), your business must be PCI DSS compliant. This involves annual security audits, network scans, and strict security controls. Not PCI compliant? Use our hosted payment page or JavaScript SDK instead - these solutions keep card data off your servers and remove PCI compliance requirements from your business.Contact support@cheqpay.com to learn about hosted payment options. Create a Card Payment POST /checkout/pay Authorization : Bearer YOUR_API_KEY Content-Type : application/json
Complete Request Example { "externalId" : "order-123" , "customer" : { "externalId" : "customer-abc" , "firstName" : "María" , "lastName" : "González" , "email" : "maria@example.com" , "phoneNumber" : "+521555123456" }, "billingAddress" : { "address" : "Av. Reforma 123" , "city" : "Mexico City" , "state" : "CDMX" , "postalCode" : "01000" , "country" : "MX" }, "amount" : 10000 , "currency" : "MXN" , "description" : "Order #12345" , "paymentMethod" : { "type" : "card" , "cardDetails" : { "number" : "4000000000002503" , "expiryMonth" : "12" , "expiryYear" : "25" , "cvc" : "123" } } }
Successful Response { "paymentOrder" : { "id" : "ord_abc123" , "externalId" : "order-123" , "amount" : 10000 , "currency" : "MXN" , "status" : "COMPLETED" , "description" : "Order #12345" }, "customer" : { "id" : "cus_xyz789" , "firstName" : "María" , "lastName" : "González" , "email" : "maria@example.com" }, "paymentMethod" : { "id" : "pm_def456" , "type" : "card" , "card" : { "brand" : "visa" , "last4" : "1111" , "expiryMonth" : "12" , "expiryYear" : "25" } } }
What Happens During Payment
Customer Created or Updated
Cheqpay creates a new customer record or updates an existing one based on the externalId.
Card Tokenized
The card is securely tokenized. Sensitive data never touches your servers.
Authorization
The payment is authorized by the card network (Visa, Mastercard, Amex).
Funds Captured
Funds are captured immediately upon successful authorization.
Status Updated
Payment status updates to COMPLETED and you can fulfill the order.
Customer Notified
Customer receives a confirmation email (if notifications are enabled).
The entire process typically takes 2-5 seconds for successful payments.
Required Fields Field Type Required Description externalIdstring Yes Your unique order ID amountinteger Yes Amount in cents (10000 = $100.00) currencystring Yes ISO currency code (MXN, USD) descriptionstring No Payment description
Field Type Required Description customer.firstNamestring Yes Customer’s first name customer.lastNamestring Yes Customer’s last name customer.emailstring Yes Customer’s email address customer.phoneNumberstring No Phone with country code customer.externalIdstring No Your customer ID
Card Details Field Type Required Description paymentMethod.typestring Yes Must be “card” paymentMethod.cardDetails.numberstring Yes Card number (13-19 digits) paymentMethod.cardDetails.expiryMonthstring Yes Expiry month (01-12) paymentMethod.cardDetails.expiryYearstring Yes Expiry year (2-digit YY format, e.g., “25” for 2025) paymentMethod.cardDetails.cvcstring Yes Card security code
Billing Address (Required) Billing address is required for all card payments:
{ "billingAddress" : { "address" : "Av. Reforma 123" , "city" : "Mexico City" , "state" : "CDMX" , "postalCode" : "01000" , "country" : "MX" } }
Billing address is required when processing card payments. Including complete billing information also helps improve approval rates by 3-5%.
Save Cards for Future Use Enable one-click checkout by saving the card:
{ "paymentMethod" : { "type" : "card" , "cardDetails" : { "number" : "4000000000002503" , "expiryMonth" : "12" , "expiryYear" : "25" , "cvc" : "123" }, "persist" : true } }
The response includes a paymentMethodId you can use for future charges:
{ "paymentMethod" : { "id" : "pm_abc123" , "type" : "card" , "card" : { "brand" : "visa" , "last4" : "1111" } } }
Learn More About Saved Cards View complete payment methods documentation
Charge a Saved Card Use a previously saved card with just the payment method ID:
{ "externalId" : "order-456" , "amount" : 5000 , "currency" : "MXN" , "paymentMethod" : { "type" : "payment_method_id" , "paymentMethodId" : "pm_abc123" , "cvc" : "123" } }
Always collect the CVC for saved card payments. This improves approval rates and reduces fraud.
Handle Authentication (3D Secure) Some payments require 3D Secure authentication. When this happens, the status will be PAYER_AUTHENTICATION_CHALLENGE_REQUIRED:
{ "paymentOrder" : { "id" : "ord_abc123" , "status" : "PAYER_AUTHENTICATION_CHALLENGE_REQUIRED" }, "payerAuthentication" : { "stepUpUrl" : "https://..." , "jwt" : "eyJhbGc..." } }
You’ll need to show an authentication challenge to the customer.
Complete 3D Secure Guide Learn how to implement 3D Secure authentication
Improve Approval Rates Sending device data helps banks assess risk and approve more payments:
{ "deviceInformation" : { "ipAddress" : "192.168.1.100" , "userAgent" : "Mozilla/5.0..." , "httpBrowserLanguage" : "es-MX" , "httpBrowserScreenWidth" : "1920" , "httpBrowserScreenHeight" : "1080" } }
Best Practices
Billing address verification helps prevent fraud and improves approval rates by 3-5%.
Device information enables better fraud detection and smoother 3D Secure flows.
Use Consistent Customer Data
Keep customer information consistent across payments for better approval rates.
Returning customers with saved cards have higher approval rates.
Error Handling Handle declined payments gracefully:
{ "error" : { "code" : "DECLINED" , "message" : "Payment declined by issuing bank" , "declineReason" : "insufficient_funds" } }
Error Handling Guide Learn how to handle errors and declined payments
Testing Use these test cards in sandbox:
Card Number Brand Result 4000000000002503 Visa Successful payment 5200000000002151 Mastercard Successful payment 4000000000000002 Visa Card declined
Complete Testing Guide View all test scenarios and cards
Next Steps 