3DS Card Payments

Process card payments with 3D Secure authentication for enhanced security and fraud protection.

Overview

3DS (3D Secure) payments add an authentication step where the customer verifies their identity with their card issuer. This provides:

Enhanced security - Reduces fraud risk

Liability shift - Card issuer assumes fraud liability (not merchant)

Regulatory compliance - Required for PSD2 in Europe

Higher approval rates - Issuers trust authenticated transactions

Trade-off: Additional redirect step (slightly longer checkout) compared to non-3DS payments.

Authentication

All requests must include your Client ID in the Authorization header.
See Authentication Guide for details.

Encryption

Card data must be encrypted before sending.
See Encryption Guide for implementation details.

Endpoint

POST /v2/payments

Base URLs:

Sandbox: https://sandbox-acquiring.globalremitfs.com

Production: https://acquiring.globalremitfs.com

Payment Flow

3DS payments follow a redirect-based flow:

1. Merchant initiates payment → POST /v2/payments
2. API returns challenge_url → Redirect customer to this URL
3. Customer completes 3DS challenge → Authentication on card issuer page
4. Nuvion processes payment → Customer redirected back to merchant
5. Merchant receives webhook → Payment confirmation (optional)

Request Parameters

Field	Type	Required	Description
`merchant_reference`	string	Yes	Your unique order/transaction reference (must be unique)
`merchant_meta`	object	No	Custom metadata (max 10 key-value pairs)
`amount`	integer	Yes	Amount in smallest currency unit (cents for USD, pence for GBP)
`currency`	string	Yes	ISO 4217 currency code (USD, GBP, EUR, etc.)
`description`	string	No	Payment description (shown to customer)
`payment_method`	object	Yes	Payment method details
`payment_method.type`	string	Yes	Must be `"card"`
`payment_method.data`	string	Yes	RSA-encrypted card data (see encryption guide)
`billing_address`	object	Yes	Customer billing address
`billing_address.first_name`	string	Yes	Customer first name
`billing_address.last_name`	string	Yes	Customer last name
`billing_address.email`	string	Yes	Customer email (must be valid format)
`billing_address.address_line_one`	string	Yes	The first line of the billing address
`billing_address.address_line_one`	string	No	The second line of the billing address
`billing_address.country`	string	Yes	ISO 3166-1 alpha-2 country code (US, GB, etc.)
`billing_address.city`	string	Yes	City name
`billing_address.state`	string	Yes	State name
`billing_address.zip`	string	No	Postal/ZIP code
`browser_info`	object	Recommended	Browser details (required for 3DS2)
`browser_info.accept_header`	string	No	Browser Accept header
`browser_info.user_agent`	string	No	Browser User-Agent
`browser_info.java_enabled`	boolean	No	Java enabled in browser
`browser_info.javascript_enabled`	boolean	No	JavaScript enabled (usually true)
`browser_info.language`	string	No	Browser language (en-US, etc.)
`browser_info.color_depth`	string	No	Screen color depth (24, 32, etc.)
`browser_info.screen_height`	string	No	Screen height in pixels
`browser_info.screen_width`	string	No	Screen width in pixels
`browser_info.timezone_offset`	string	No	Timezone offset in minutes
`ip_address`	string	Yes	Customer IP address (for fraud detection)
`redirect_url`	string	Yes	URL to redirect customer after payment completion
`webhook_url`	string	No	URL for payment status webhooks
`enable_3ds`	boolean	No	Set to `true` to force 3DS. Default: auto-detect

Note: browser_info is highly recommended for 3DS2 compliance and better approval rates.

Response Fields (Initiation)

Success Response (HTTP 200)

Field	Type	Description
`status`	string	Always `"successful"`
`message`	string	Success message
`data`	object	Payment response data
`data.payment_id`	string	Unique payment identifier (ULID format)
`data.merchant_reference`	string	Your original transaction reference
`data.merchant_meta`	object	Your custom metadata (if provided)
`data.amount`	integer	Payment amount
`data.currency`	string	Payment currency
`data.status`	string	`"3ds_required"` - customer needs to complete 3DS
`data.session_id`	string	3DS session identifier
`data.challenge_url`	string	Redirect customer to this URL
`data.created_at`	number	Payment creation timestamp (Unix ms)
`data.completed_at`	number	`null` (payment not yet complete)

Response Fields (After 3DS Completion)

After the customer completes 3DS, they're redirected to your redirect_url with query parameters:

Parameter	Description
`payment_id`	Nuvion payment ID
`merchant_reference`	Your original transaction reference
`status`	Either `"success"` or `"failed"`

You should then retrieve the payment details or rely on the webhook.

Example Request

Full JSON

{
  "merchant_reference": "order_67890",
  "merchant_meta": {
    "customer_id": "cust_456",
    "subscription_id": "sub_789"
  },
  "amount": 15000,
  "currency": "USD",
  "description": "Premium Plan - 6 Months",
  "payment_method": {
    "type": "card",
    "data": "tbjH0nx6WaEkzHOjgw2crsusmVBuL8s+PxWFqYb5cWZ3k1..."
  },
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "country": "US",
    "city": "Los Angeles",
    "zip": "90001"
  },
  "browser_info": {
    "accept_header": "text/html,application/xhtml+xml",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
    "java_enabled": false,
    "javascript_enabled": true,
    "language": "en-US",
    "color_depth": "24",
    "screen_height": "1080",
    "screen_width": "1920",
    "timezone_offset": "-300"
  },
  "ip_address": "203.0.113.42",
  "redirect_url": "https://yoursite.com/payment/callback",
  "webhook_url": "https://yoursite.com/webhooks/payment",
  "enable_3ds": true
}

cURL

Node.js

Collecting Browser Info (Frontend)

Example Responses

3DS Challenge Required

{
  "status": "successful",
  "message": "3DS authentication required",
  "data": {
    "payment_id": "01HXYZ123ABC456DEF789GHI",
    "merchant_reference": "order_67890",
    "merchant_meta": {
      "customer_id": "cust_456",
      "subscription_id": "sub_789"
    },
    "amount": 15000,
    "currency": "USD",
    "status": "3ds_required",
    "session_id": "01HXYZ987SESSION654XYZ",
    "challenge_url": "https://acquiring.globalremitfs.com/3ds-sessions/01HXYZ987SESSION654XYZ",
    "created_at": 1699564800000,
    "completed_at": null
  }
}

Action: Redirect the customer to challenge_url.

Frictionless Flow (No Challenge)

Sometimes the card issuer approves without requiring customer interaction:

{
  "status": "successful",
  "message": "Payment processed successfully",
  "data": {
    "payment_id": "01HXYZ123ABC456DEF789GHI",
    "merchant_reference": "order_67890",
    "merchant_meta": {
      "customer_id": "cust_456",
      "subscription_id": "sub_789"
    },
    "amount": 15000,
    "currency": "USD",
    "status": "completed",
    "authorization_code": "AUTH123456",
    "created_at": 1699564800000,
    "completed_at": 1699564802000
  }
}

Note: Check data.status - if it's "completed", payment succeeded without redirect!

Redirect URL Parameters

After 3DS completion, the customer is redirected to your redirect_url with these query parameters:

Parameter	Description
`payment_id`	Nuvion payment ID
`merchant_reference`	Your original transaction reference
`status`	Either `"success"` or `"failed"`

Example successful redirect:

https://yoursite.com/payment/callback?payment_id=01HXYZ123ABC456DEF789GHI&merchant_reference=order_67890&status=success

Example failed redirect:

https://yoursite.com/payment/callback?payment_id=01HXYZ123ABC456DEF789GHI&merchant_reference=order_67890&status=failed

Your redirect URL may already have query parameters. Nuvion's parameters are appended safely:

https://yoursite.com/callback?session=abc123&payment_id=01HXYZ...&merchant_reference=order_67890&status=success

Handling the Redirect

Webhooks

If you provide a webhook_url, Nuvion will send a POST request with the payment result:

{
  "event": "payment.completed",
  "payment_id": "01HXYZ123ABC456DEF789GHI",
  "merchant_reference": "order_67890",
  "merchant_meta": {
    "customer_id": "cust_456",
    "subscription_id": "sub_789"
  },
  "status": "completed",
  "amount": 15000,
  "currency": "USD",
  "authorization_code": "AUTH123456",
  "created_at": 1699564800000,
  "completed_at": 1699564825000
}

Failed payment webhook:

{
  "event": "payment.failed",
  "payment_id": "01HXYZ123ABC456DEF789GHI",
  "merchant_reference": "order_67890",
  "merchant_meta": {
    "customer_id": "cust_456",
    "subscription_id": "sub_789"
  },
  "status": "failed",
  "failure_reason": "3DS authentication failed",
  "amount": 15000,
  "currency": "USD",
  "created_at": 1699564800000,
  "completed_at": 1699564820000
}

Always verify webhook signatures (documentation coming soon).

Testing

Test Card Numbers (Sandbox)

Card Number	3DS Behavior
4000000000001091	3DS challenge (authentication required)
4000000000001000	3DS frictionless (no challenge, auto-approved)
4000000000001018	3DS failed (customer fails authentication)
4111111111111111	Standard test card (3DS behavior varies)

Note: Use any future expiry date and any 3-digit CVV.

Test 3DS Challenge

When redirected to the 3DS challenge page in sandbox:

Password: Any value (e.g., "password", "test", "123")

The challenge will auto-submit and process the payment

Common Errors

Missing browser_info

Impact: May result in lower approval rates or 3DS failures
Solution: Always collect and send browser_info for 3DS payments

Duplicate merchant_reference

Error: "A payment with this merchant reference already exists"
Solution: Each merchant_reference must be unique

Decryption failed

Error: "Failed to decrypt payment data"
Solution: Check your encryption implementation. See Encryption Guide

Client ID not found

Error: "Client ID not found"
Solution: Verify your Client ID. See Authentication Guide

When to Use Non-3DS Instead

Consider using non-3DS payments for:

Very low-risk transactions

Recurring payments with saved cards

Faster checkout (no redirect)

Regions where 3DS is not required

Warning: Non-3DS has higher fraud risk and merchant liability.

3DS2 vs 3DS1

Nuvion automatically uses 3DS2 when available, with fallback to 3DS1:

Feature	3DS2	3DS1
Authentication	Frictionless (70%+ cases)	Always challenge
Mobile Support	Native app integration	Browser only
Data Sharing	Rich context (browser_info)	Limited
User Experience	Seamless	Pop-up/redirect

Recommendation: Always provide browser_info for optimal 3DS2 experience.

Best Practices

✅ DO

Always collect and send browser_info

Handle both 3ds_required and completed status responses

Implement webhook handling for reliable notifications

Show clear messaging during 3DS redirect

Test with all test cards in sandbox

Log payment_id for support inquiries

❌ DON'T

Skip browser_info (reduces approval rates)

Assume all 3DS payments require redirect (frictionless exists)

Rely only on redirects (use webhooks too)

Show technical errors to customers

Use same merchant_reference for retries

Support

Email: support@nuvion.com

Documentation: https://acquiring-docs.globalremitfs.com

Card (3DS)

3DS Card Payments#

Overview#

Authentication#

Encryption#

Endpoint#

Payment Flow#

Request Parameters#

Response Fields (Initiation)#

Success Response (HTTP 200)#

Response Fields (After 3DS Completion)#

Example Request#

Full JSON#

cURL#

Node.js#

Collecting Browser Info (Frontend)#

Example Responses#

3DS Challenge Required#

Frictionless Flow (No Challenge)#

Redirect URL Parameters#

Handling the Redirect#

Webhooks#

Testing#

Test Card Numbers (Sandbox)#

Test 3DS Challenge#

Common Errors#

Missing browser_info#

Duplicate merchant_reference#

Decryption failed#

Client ID not found#

When to Use Non-3DS Instead#

3DS2 vs 3DS1#

Best Practices#

✅ DO#

❌ DON'T#

Support#