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:

You have a valid payment session ID from initialization
Any required card data is encrypted following our encryption guide
You can handle authentication flows if needed

Endpoint

POST /payment-sessions/{payment_id}

Request Parameters

object

required

Encrypted card payment details

Show Card Object

string

required

Encrypted card number (PAN)

string

required

Encrypted CVV/CVC

integer

required

Card expiry month (1-12)

integer

required

Card expiry year (current or future)

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
    }
  }'

const response = await fetch(
  `https://api.spendjuice.com/payment-sessions/${paymentId}`,
  {
    method: 'POST',
    headers: {
      'Authorization': ` ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      card: {
        card_number: encryptedCardNumber,
        cvv: encryptedCvv,
        expiry_month: 1,
        expiry_year: 39
      }
    })
  }
);

Authentication Flows

Some card payments require additional authentication after capture:

3D Secure (3DS)

Capture Response

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

3DS Verification

Redirect customer to provided URL to complete 3DS

Wait for Completion

Monitor webhooks or status endpoint for final result

One-Time Password (OTP)

Capture Response

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

Submit OTP

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

PIN Verification

Capture Response

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

Submit PIN

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

Error Handling

error

Card declined by issuing bank

Status code: 402
Common reasons:
- Insufficient funds
- Invalid card
- Suspicious activity

error

Additional authentication needed

Status code: 401
Next steps:
- Handle 3DS redirect
- Collect OTP/PIN
- Retry with authentication

Best Practices

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
Error Handling
- Implement exponential backoff for retries
- Show user-friendly error messages
- Log errors with payment IDs
- Handle timeouts gracefully
Security
- Never log decrypted card data
- Use HTTPS for all requests
- Clear sensitive data after use
- Monitor for unusual patterns

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

Wallet As A Service

Cards

Card Payment Capture

Overview

Endpoint

Request Parameters

Example Request

Authentication Flows

3D Secure (3DS)

One-Time Password (OTP)

PIN Verification

Error Handling

Best Practices

Need Help?

​Card Payment Capture

​Overview

​Endpoint

​Request Parameters

​Example Request

​Authentication Flows

​3D Secure (3DS)

​One-Time Password (OTP)

​PIN Verification

​Error Handling

​Best Practices

Need Help?

Card Payment Capture

Overview

Endpoint

Request Parameters

Example Request

Authentication Flows

3D Secure (3DS)

One-Time Password (OTP)

PIN Verification

Error Handling

Best Practices