Card Payment Initialization
Learn how to initialize card payments securely via the Juicyway API
Overview
Card payment initialization is the first step in processing a card payment. This endpoint creates a payment session that can be used to securely process credit and debit card transactions.
Endpoint
Request Parameters
Payment amount in minor units (e.g., cents, kobo)
-
Minimum: 100
-
Must be positive integer
-
Example: 10000 = $100.00 USD
Three-letter ISO currency code
-
Supported: NGN, USD, CAD
-
Must match payment method
-
Example: “USD”
Customer information object
Payment description
-
Maximum length: 200 characters
-
Will appear on statements
Unique transaction reference
-
Must be unique per transaction
-
Maximum length: 50 characters
Order information object
Optional additional data
- Nested objects allowed
Example Requests
Test Cards
Use these test cards in your sandbox environment to simulate different payment scenarios:
Successful Payments
Successful Payments
VISA Test Card (NGN)
-
Card Number: 4012000033330026
-
Expiry Date: 01/39
-
CVV: 100
Mastercard Test Card (USD)
-
Card Number: 5123450000000008
-
Expiry Date: 12/25
-
CVV: 100
3DS Authentication Required
3DS Authentication Required
VISA 3DS Test Card
-
Card Number: 4761530000000008
-
Expiry Date: 05/25
-
CVV: 100
-
Test OTP: 123456
Mastercard 3DS Test Card
-
Card Number: 5200000000001005
-
Expiry Date: 12/25
-
CVV: 100
-
Test OTP: 123456
Failed Transactions
Failed Transactions
Insufficient Funds
-
Card Number: 4000000000000010
-
Expiry Date: 01/25
-
CVV: 100
Declined Card
-
Card Number: 4000000000000002
-
Expiry Date: 01/25
-
CVV: 100
Response Examples
Authentication Flows
Some card payments may require additional authentication steps. The response will indicate the required authentication type:
3D Secure Authentication
If 3DS is required, you’ll receive:
Redirect the customer to complete 3DS verification, then:
-
Listen for webhook notification, or
-
Poll payment status endpoint
OTP Validation
For OTP authentication:
Submit OTP via:
PIN Verification
For PIN authentication:
Submit PIN via:
Security Requirements
Data Encryption
Data Encryption
-
All card data must be encrypted before transmission
-
Use our encryption guide for implementation
-
Never log or store raw card details
PCI Compliance
PCI Compliance
-
Use our secure payment fields when collecting card data
-
Follow PCI DSS requirements if handling card data
-
Implement proper data sanitization
API Authentication
API Authentication
-
Use HTTPS for all API calls
-
Include proper authorization headers
-
Rotate API keys regularly
Error Handling
Card declined by issuing bank
-
Status code: 402
-
Possible reasons:
-
Insufficient funds
-
Suspicious activity
-
Expired card
-
Invalid card details provided
-
Status code: 400
-
Check:
-
Card number
-
Expiry date
-
CVV
-
Failed authentication (3DS/OTP/PIN)
-
Status code: 401
-
Verify credentials and retry
Common error scenarios to handle:
-
Invalid currency code
-
Amount below minimum
-
Missing customer information
-
Invalid phone/email format
-
Incorrect billing address
-
Network timeouts
Next Steps
After successful initialization:
-
Handle any required authentication
-
Listen for webhook notifications
Need Help?
- Review Authentication Guide
-
Check Error Handling
-
Contact Support