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.

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

string

required

ISO 4217 currency code. e.g. USD.

number

required

Amount in the smallest currency unit. 5000 = $50.00 USD.

string

required

The ID of the account to credit on successful charge.

string

required

Your unique internal order or transaction reference.

string

A human-readable payment description. Maximum 250 characters.

object

Optional confirmation details. Include this when you want to create the Payment Intent and submit the card payment in the same request.

{
  "id": "01HXYZ7K3M9PQRST4UVWXY2Z6",
  "currency": "USD",
  "amount": 5000,
  "reference": "order_abc123",
  "description": "Order #1042",
  "status": "requires_action",
  "entity_id": "ent_01HXYZ1234ABCD",
  "account_id": "acc_01HXYZ5678EFGH",
  "created": 1735725600000
}

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.

curl -X POST https://api.nuvion.dev/payment-intents \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "amount": 5000,
    "account_id": "acc_01HXYZ5678EFGH",
    "reference": "order_abc124",
    "description": "Order #1043",
    "intent_action": {
      "action": "confirm",
      "category": "collections",
      "payment_type": "card-acq",
      "payment_type_data": {
        "data": "<base64_encrypted_card_data>",
        "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"
      }
    }
  }'

{
  "id": "01HXYZ7K3M9PQRST4UVWXY2Z7",
  "currency": "USD",
  "amount": 5000,
  "reference": "order_abc124",
  "description": "Order #1043",
  "status": "completed",
  "entity_id": "ent_01HXYZ1234ABCD",
  "account_id": "acc_01HXYZ5678EFGH",
  "created": 1735725600000,
  "intent_action": {
    "id": "01HACT9012EFGI",
    "currency": "USD",
    "amount": 5000,
    "applicable_fee": 75,
    "charge_amount": 5000,
    "refunded_amount": 0,
    "reference": "order_abc124",
    "action": "confirm",
    "category": "collections",
    "payment_type": "card-acq",
    "payment_type_data": {
      "payment_country": "US",
      "last_four_digits": "1111",
      "card_brand": "visa",
      "card_type": "credit"
    },
    "status": "completed",
    "entity_id": "ent_01HXYZ1234ABCD",
    "account_id": "acc_01HXYZ5678EFGH",
    "payment_intent_id": "01HXYZ7K3M9PQRST4UVWXY2Z7",
    "created": 1735725600000
  }
}

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 Card data encryption for how to create this value.

string

required

The ID of the Payment Intent to charge against. The intent must still have status: requires_action.

string

required

Always confirm.

string

required

Always collections.

string

required

The payment method. Use card-acq for card payments.

string

required

Base64-encoded RSA-OAEP SHA-256 encrypted card object.

object

required

Cardholder billing address.

Show billing_address fields

string

required

First line of the billing address.

string

Apartment, suite, or second address line.

string

required

Billing city.

string

required

Billing state, region, or province.

string

required

Two-letter country code. e.g. US.

string

Postal or ZIP code.

string

Card authentication model. 3ds_required.

object

required

Browser data used for 3DS authentication.

object

required

Cardholder identity details.

Show customer fields

string

required

Customer first name.

string

required

Customer last name.

string

required

Customer email address.

string

Customer phone number, when available.

string

URL to redirect the cardholder to after 3DS completes. Required unless auth_model is 3ds_disabled.

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": "01HXYZ7K3M9PQRST4UVWXY2Z6",
    "intent_action": {
      "action": "confirm",
      "category": "collections",
      "payment_type": "card-acq",
      "payment_type_data": {
        "data": "<base64_encrypted_card_data>",
        "billing_address": {
          "address_line_one": "350 Fifth Avenue",
          "city": "New York",
          "state": "NY",
          "country": "US"
        },
        "browser_info": {
          "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
          "ip_address":"213.93.4.172",
          "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
          "java_enabled": false,
          "javascript_enabled": true,
          "language": "en-US",
          "color_depth": "24",
          "screen_height": "900",
          "screen_width": "1440",
          "timezone_offset": "-300"
        }
      },
      "customer": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com"
      },
      "return_url": "https://yourplatform.com/checkout/complete"
    }
  }'

{
  "id": "01HACT9012EFGH",
  "currency": "USD",
  "amount": 5000,
  "applicable_fee": 75,
  "charge_amount": 5000,
  "refunded_amount": 0,
  "reference": "order_abc123",
  "action": "confirm",
  "category": "collections",
  "payment_type": "card-acq",
  "payment_type_data": {
    "auth_model": "3ds_required",
    "payment_country": "US",
    "last_four_digits": "1111",
    "card_brand": "visa",
    "card_type": "credit"
  },
  "status": "pending_user_action",
  "entity_id": "ent_01HXYZ1234ABCD",
  "account_id": "acc_01HXYZ5678EFGH",
  "payment_intent_id": "01HXYZ7K3M9PQRST4UVWXY2Z6",
  "return_url": "https://yourplatform.com/checkout/complete",
  "requires_action": true,
  "next_action": {
    "type": "redirect_to_url",
    "url": "https://checkout.nuvion.co/card/01HACT9012EFGH"
  },
  "created": 1735725600000
}

Redirect the cardholder to next_action.url. After authentication, Nuvion redirects the cardholder to return_url. Payment details such as status will be 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=01KVFT796D5M1RQ0S853P4XXXX&status=completed&payment_intent_id=01KVFT2B67R57FWGVDFNZ1XXXX&amount=300&currency=EUR

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/01HXYZ7K3M9PQRST4UVWXY2Z6 \
  -H "Authorization: Bearer $NUVION_API_KEY"

{
  "id": "01HXYZ7K3M9PQRST4UVWXY2Z6",
  "currency": "USD",
  "amount": 5000,
  "reference": "order_abc123",
  "description": "Order #1042",
  "status": "completed",
  "entity_id": "ent_01HXYZ1234ABCD",
  "account_id": "acc_01HXYZ5678EFGH",
  "created": 1735725600000
}

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": "01HXYZ7K3M9PQRST4UVWXY2Z6",
    "intent_action": {
      "action": "confirm",
      "category": "collections",
      "payment_type": "applepay-acq",
      "payment_type_data": {
        "billing_address": {
          "country": "US"
        }
      },
      "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

Webhook payloads use Nuvion’s standard webhook envelope:

{
  "event": "payment_intent.completed",
  "data": {
    "id": "01HXYZ7K3M9PQRST4UVWXY2Z6",
    "currency": "USD",
    "amount": 5000,
    "reference": "order_abc123",
    "description": "Order #1042",
    "status": "completed",
    "entity_id": "ent_01HXYZ1234ABCD",
    "account_id": "acc_01HXYZ5678EFGH",
    "created": 1735725600000
  }
}

Return a 2xx response after receiving the webhook. If delivery fails, Nuvion retries with exponential backoff. See Webhooks for delivery and retry details.

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

​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

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