Skip to main content

​
Card Payment Capture

This guide explains how to capture an authorized card payment. The capture request processes the actual charge against the customer’s card after authentication.

​
Overview

Before capturing a payment, ensure:
  1. You have a valid payment session ID from initialization
  2. Any required card data is encrypted following our encryption guide
  3. You can handle authentication flows if needed

​
Endpoint

POST /payment-sessions/{payment_id}

​
Request Parameters

​
card
object
required
Encrypted card payment details

​
Example Request

curl -X POST "https://api.spendjuice.com/payment-sessions/{payment_id}" \
  -H "Authorization:  YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "card": {
      "card_number": "encrypted_card_number",
      "cvv": "encrypted_cvv", 
      "expiry_month": 1,
      "expiry_year": 39
    }
  }'

​
Authentication Flows

Some card payments require additional authentication after capture:

​
3D Secure (3DS)

1

Capture Response

{
  "data": {
    "status": "authenticating",
    "auth_type": "3ds",
    "message": "3D Secure authentication required",
    "links": {
      "redirect_url": "https://3ds.issuer-bank.com/auth"
    }
  }
}
2

3DS Verification

Redirect customer to provided URL to complete 3DS
3

Wait for Completion

Monitor webhooks or status endpoint for final result

​
One-Time Password (OTP)

1

Capture Response

{
  "data": {
    "status": "authenticating",
    "auth_type": "otp",
    "message": "OTP sent to registered phone number"
  }
}
2

Submit OTP

POST /payment-sessions/{payment_id}/authorize
{
  "otp": "123456"
}

​
PIN Verification

1

Capture Response

{
  "data": {
    "status": "authenticating",
    "auth_type": "pin",
    "message": "Enter card PIN"
  }
}
2

Submit PIN

POST /payment-sessions/{payment_id}/authorize
{
  "pin": "1234"
}

​
Error Handling

​
card_declined
error
Card declined by issuing bank
  • Status code: 402
  • Common reasons:
    • Insufficient funds
    • Invalid card
    • Suspicious activity
​
authentication_required
error
Additional authentication needed
  • Status code: 401
  • Next steps:
    • Handle 3DS redirect
    • Collect OTP/PIN
    • Retry with authentication

​
Best Practices

  1. Authentication Flow
    • Handle all authentication types (3DS, OTP, PIN)
    • Provide clear user feedback during auth
    • Implement proper timeouts and retries
    • Monitor auth completion via webhooks
  2. Error Handling
    • Implement exponential backoff for retries
    • Show user-friendly error messages
    • Log errors with payment IDs
    • Handle timeouts gracefully
  3. Security
    • Never log decrypted card data
    • Use HTTPS for all requests
    • Clear sensitive data after use
    • Monitor for unusual patterns

Need Help?

⌘I