Card Payments

Nuvion’s card payment flow uses a Payment Intent and an Intent Action. Create a Payment Intent to declare the charge, then submit an Intent Action to confirm the payment.

Step 1: Create a payment intent

A Payment Intent represents your intent to charge a card. No funds are moved at this stage. See Create a payment intent for the full request and response field reference.

curl -X POST https://api.nuvion.dev/payment-intents \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "amount": 1000,
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
    "reference": "order_abc123",
    "description": "Order #1042"
  }'

{
  "status": "success",
  "message": "Payment intent created successfully",
  "data": {
    "id": "01HXYZ5501ABCDEFGHJKMNPQRS",
    "currency": "USD",
    "amount": 1000,
    "reference": "order_abc123",
    "description": "Order #1042",
    "status": "requires_action",
    "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "created": 1787943000000
  }
}

The intent is created with status: requires_action. No charge happens until you submit an Intent Action.

Create and confirm in one request

If your server already has the encrypted card payload, you can include intent_action when creating the Payment Intent. It takes the same shape as the Submit an intent action request below, and goes through the same 3DS rules: if the issuer requires customer interaction, the response still returns status: "processing", the nested intent_action.status: "pending_user_action", and a next_action.url to redirect the cardholder to.

curl -X POST https://api.nuvion.dev/payment-intents \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "amount": 100,
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
    "reference": "order_abc124",
    "description": "Order #1043",
    "intent_action": {
      "action": "confirm",
      "category": "collections",
      "payment_type": "card-acq",
      "payment_type_data": {
        "data": "<base64_encrypted_card_data>",
        "auth_model": "3ds_required",
        "browser_info": {
          "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
          "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
          "language": "en-US",
          "screen_width": "1440",
          "screen_height": "900",
          "java_enabled": false,
          "color_depth": "24",
          "timezone_offset": "-300",
          "javascript_enabled": true,
          "channel": "browser",
          "ip_address": "213.93.4.172"
        },
        "billing_address": {
          "address_line_one": "350 Fifth Avenue",
          "city": "New York",
          "state": "NY",
          "country": "US"
        }
      },
      "customer": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com"
      },
      "return_url": "https://yourplatform.com/checkout/complete"
    }
  }'

{
  "status": "success",
  "message": "Payment intent created successfully",
  "data": {
    "id": "01HXYZ5507ABCDEFGHJKMNPQRS",
    "currency": "USD",
    "amount": 100,
    "reference": "order_abc124",
    "description": "Order #1043",
    "status": "processing",
    "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "created": 1787944000000,
    "intent_action": {
      "id": "01HXYZ5508ABCDEFGHJKMNPQRS",
      "currency": "USD",
      "amount": 100,
      "applicable_fee": 33,
      "charge_amount": 100,
      "refunded_amount": 0,
      "reference": "order_abc124",
      "action": "confirm",
      "category": "collections",
      "payment_type": "card-acq",
      "payment_type_data": {
        "payment_country": "US",
        "auth_model": "3ds_required",
        "last_four_digits": "1111"
      },
      "status": "pending_user_action",
      "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
      "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
      "payment_intent_id": "01HXYZ5507ABCDEFGHJKMNPQRS",
      "return_url": "https://yourplatform.com/checkout/complete",
      "requires_action": true,
      "next_action": {
        "type": "redirect_to_url",
        "url": "https://app.nuvion.dev/sessions/1111111111111111111111111111aaaa"
      },
      "created": 1787944005000
    }
  }
}

Step 2: Submit an intent action

Submit the card payment using POST /intent-actions with payment_type set to card-acq and the encrypted card payload in payment_type_data.data. See Confirm a payment intent for the full request parameter reference, and Card data encryption for how to create the encrypted payload.

3DS authentication

3DS is the default card authentication model. If you omit auth_model, Nuvion treats the payment as 3ds_required, and browser_info becomes required. If the issuer requires customer interaction, the response returns status: pending_user_action, requires_action: true, and a next_action.url to redirect the cardholder to.

curl -X POST https://api.nuvion.dev/intent-actions \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "01HXYZ5501ABCDEFGHJKMNPQRS",
    "intent_action": {
      "action": "confirm",
      "category": "collections",
      "payment_type": "card-acq",
      "payment_type_data": {
        "data": "<base64_encrypted_card_data>",
        "auth_model": "3ds_required",
        "browser_info": {
          "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
          "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
          "language": "en-US",
          "screen_width": "1440",
          "screen_height": "900",
          "java_enabled": false,
          "color_depth": "24",
          "timezone_offset": "-300",
          "javascript_enabled": true,
          "channel": "browser",
          "ip_address": "213.93.4.172"
        },
        "billing_address": {
          "address_line_one": "350 Fifth Avenue",
          "city": "New York",
          "state": "NY",
          "country": "US"
        }
      },
      "customer": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com"
      },
      "return_url": "https://yourplatform.com/checkout/complete"
    }
  }'

{
  "status": "success",
  "message": "Payment intent action created successfully",
  "data": {
    "id": "01HXYZ5504ABCDEFGHJKMNPQRS",
    "currency": "USD",
    "amount": 1000,
    "applicable_fee": 60,
    "charge_amount": 1000,
    "refunded_amount": 0,
    "reference": "order_abc123",
    "action": "confirm",
    "category": "collections",
    "payment_type": "card-acq",
    "payment_type_data": {
      "payment_country": "US",
      "auth_model": "3ds_required",
      "last_four_digits": "1111"
    },
    "status": "pending_user_action",
    "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "payment_intent_id": "01HXYZ5501ABCDEFGHJKMNPQRS",
    "return_url": "https://yourplatform.com/checkout/complete",
    "requires_action": true,
    "next_action": {
      "type": "redirect_to_url",
      "url": "https://app.nuvion.dev/sessions/1111111111111111111111111111aaaa"
    },
    "created": 1787943005000
  }
}

payment_type_data.card_brand and card_type are not populated while the action is pending_user_action. They appear once the action reaches completed.

Redirect the cardholder to next_action.url. After authentication, Nuvion redirects the cardholder to return_url. Payment details such as status are appended as query params to the return URL. Do not treat the redirect as proof of payment; confirm completion from the payment intent status or webhook. Like so:

<return-url>?payment_intent_action_id=01HXYZ5504ABCDEFGHJKMNPQRS&status=completed&payment_intent_id=01HXYZ5501ABCDEFGHJKMNPQRS&amount=1000&currency=USD

Step 3: Check payment status

Use GET /payment-intents/{id} to check the latest status after redirect or while waiting for a webhook.

curl https://api.nuvion.dev/payment-intents/01HXYZ5501ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY"

{
  "status": "success",
  "message": "Payment intent fetched successfully",
  "data": {
    "id": "01HXYZ5501ABCDEFGHJKMNPQRS",
    "currency": "USD",
    "amount": 1000,
    "reference": "order_abc123",
    "description": "Order #1042",
    "status": "completed",
    "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "created": 1787943000000,
    "intent_action": {
      "id": "01HXYZ5504ABCDEFGHJKMNPQRS",
      "currency": "USD",
      "amount": 1000,
      "applicable_fee": 60,
      "charge_amount": 1000,
      "refunded_amount": 0,
      "reference": "order_abc123",
      "action": "confirm",
      "category": "collections",
      "payment_type": "card-acq",
      "payment_type_data": {
        "payment_country": "US",
        "auth_model": "3ds_required",
        "last_four_digits": "1111",
        "card_brand": "visa",
        "card_type": "credit"
      },
      "status": "completed",
      "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
      "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
      "payment_intent_id": "01HXYZ5501ABCDEFGHJKMNPQRS",
      "return_url": "https://yourplatform.com/checkout/complete",
      "created": 1787943005000
    }
  }
}

Apple Pay

For Apple Pay, set intent_action.payment_type to applepay-acq. Apple Pay does not use payment_type_data.data, full billing address fields, or card encryption in this request. The only required billing field is payment_type_data.billing_address.country.

curl -X POST https://api.nuvion.dev/intent-actions \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "01HXYZ5509ABCDEFGHJKMNPQRS",
    "intent_action": {
      "action": "confirm",
      "category": "collections",
      "payment_type": "applepay-acq",
      "payment_type_data": {
        "billing_address": {
          "country": "NL"
        }
      },
      "customer": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com"
      },
      "return_url": "https://yourplatform.com/checkout/complete"
    }
  }'

Payment intent statuses

Status	Description
`requires_action`	Intent created, no action submitted yet
`processing`	Intent action is being processed
`completed`	Charge successful
`cancelled`	Intent cancelled before completion
`failed`	Payment could not be completed, check `status_reason`

Intent action statuses

Status	Description
`pending`	Action created and being processed
`pending_user_action`	Awaiting 3DS completion from the cardholder
`completed`	Charge successful
`failed`	Charge declined or failed

Webhooks

Use Payment Intent webhooks as the final confirmation that a card payment succeeded, failed, or was cancelled. This is especially important after a 3DS redirect, because the redirect only tells you the customer returned to your site.

Event	Trigger
`payment_intent.completed`	Charge successful, funds credited to the account
`payment_intent.failed`	Charge declined or failed
`payment_intent.cancelled`	Payment Intent cancelled before confirmation

See Event types for the full payload schema, including the nested intent_action. Return a 2xx response after receiving the webhook. If delivery fails, Nuvion retries with exponential backoff. See Webhooks for delivery and retry details.

What’s next

Payment Refunds API reference

Refund all or part of a completed card or Apple Pay payment.

Payment Intents API reference

Full endpoint documentation for payment intents and intent actions.

Event types

Full payload schema for payment_intent.* and every other webhook event.

Get Started

Core Concepts

Webhooks

Guides

Step 1: Create a payment intent

Create and confirm in one request

Step 2: Submit an intent action

3DS authentication

Step 3: Check payment status

Apple Pay

Payment intent statuses

Intent action statuses

Webhooks

What’s next

Payment Refunds API reference

Payment Intents API reference

Event types

​Step 1: Create a payment intent

​Create and confirm in one request

​Step 2: Submit an intent action

​3DS authentication

​Step 3: Check payment status

​Apple Pay

​Payment intent statuses

​Intent action statuses

​Webhooks

​What’s next

Payment Refunds API reference

Payment Intents API reference

Event types

Step 1: Create a payment intent

Create and confirm in one request

Step 2: Submit an intent action

3DS authentication

Step 3: Check payment status

Apple Pay

Payment intent statuses

Intent action statuses

Webhooks

What’s next