Payment Intents

Payment Intents let you accept card and Apple Pay payments into an account. Create an intent for the amount you want to collect, then confirm it with an intent action.

The Payment Intent object

string

Unique payment intent identifier.

string

ISO 4217 currency code. e.g. USD, GBP, EUR.

number

Amount in the smallest currency unit. 1000 = $10.00 USD.

string

Your unique order or transaction reference.

string

Optional human-readable payment description.

string

Intent status. One of requires_action, processing, completed, cancelled, or failed.

string

Reason for the current status. Present when the intent is cancelled with a reason. For a failed payment, check status_reason on the nested intent_action instead.

string

Entity that owns the payment intent.

string

Account credited when the payment completes.

number

Unix timestamp in milliseconds when the intent was created.

object | null

The most recent confirmation attempt for this payment intent. See The Intent Action object. null until a confirmation is submitted.

{
  "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
    }
  }
}

Payment intent statuses

Status	Description
`requires_action`	Intent created and ready to be confirmed.
`processing`	A confirmation action is being processed.
`completed`	Payment completed successfully.
`cancelled`	Intent was cancelled before completion.
`failed`	Payment failed. Check `status_reason`.

The Intent Action object

string

Unique intent action identifier.

string

Currency inherited from the payment intent.

number

Payment amount inherited from the payment intent.

number

Fee charged for the payment in the smallest currency unit.

number

Amount charged for the payment.

number

Amount refunded so far in the smallest currency unit. See Payment Refund to issue a refund.

string

Client reference inherited from the payment intent.

string

Action performed. Currently confirm.

string

Payment category. Currently collections.

string

Payment method. One of card-acq or applepay-acq.

object

Payment method data returned for the action. Sensitive card details are never returned.

Show payment_type_data fields

string

The country the card or Apple Pay account is issued in.

string

The authentication model used for this action. Present for card-acq only.

string

The last four digits of the card. Present for card-acq only.

string

The card network, e.g. visa. Present for card-acq only, and only once the action reaches completed.

string

One of credit or debit. Present for card-acq only, and only once the action reaches completed.

string

Action status. One of pending, pending_user_action, completed, or failed.

string

Reason for the current status. Present when a payment fails.

string

Entity that owns the intent action.

string

Account credited when the payment completes.

string

Payment Intent linked to this action.

boolean

true when the customer must complete a redirect or challenge.

object

Next step for the customer when requires_action is true.

string

URL the customer is redirected to after authentication.

number

Unix timestamp in milliseconds when the action was created.

{
  "status": "success",
  "message": "Payment intent action fetched 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",
      "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
  }
}

Intent action statuses

Status	Description
`pending`	Action created and being processed.
`pending_user_action`	Customer must complete authentication.
`completed`	Payment completed successfully.
`failed`	Payment failed. Check `status_reason`.

Card data encryption

For card-acq, send encrypted card details in intent_action.payment_type_data.data. See Encryption for how to get your public key, validate card data before encrypting, and implementation examples in Node.js and Python. Encrypt this JSON object with RSA-OAEP SHA-256 using the encryption_public_key returned when you create or rotate an API key:

{
  "card_number": "4111111111111111",
  "expiration_month": "12",
  "expiration_year": "2030",
  "cvv": "123",
  "card_holder_name": "Ada Lovelace"
}

string

required

Card PAN. 13–19 digits. Spaces are ignored after decryption.

string

required

Expiry month, 1–12 or zero-padded 01–12.

string

required

Four-digit expiry year. The expiry date must not be in the past.

string

required

Card verification value. 3 or 4 digits.

string

Optional name printed on the card.

Never send raw card details in an API request. Only send the encrypted Base64 value in payment_type_data.data.

Create a payment intent

POST /payment-intents Creates a payment intent for a card payment.

Request parameters

string

required

ISO 4217 currency code. e.g. USD.

number

required

Amount in the smallest currency unit. 1000 = $10.00 USD.

string

required

Account to credit when the payment completes.

string

required

Unique order or transaction reference. 1–100 characters. The same reference cannot be reused for the same account.

string

A human-readable payment description. Maximum 250 characters.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

object

Optional confirmation action. Include this to create and confirm the Payment Intent in one request.

Request

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

Response

Returns a Payment Intent with status: "requires_action".

{
  "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
  }
}

Create and confirm in one request

Include intent_action when your server already has the encrypted card payload. This still goes through the same authentication rules as a standalone confirmation: if the issuer requires 3DS, the response returns status: "processing", the nested intent_action.status: "pending_user_action", and a next_action.url to redirect the customer to, the same as confirming separately.

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

Confirm a payment intent

POST /intent-actions Confirms a payment intent with card or Apple Pay payment data.

Request parameters

string

required

Payment Intent to confirm. The intent must have status: "requires_action".

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

object

required

Confirmation action details.

string

required

Always confirm.

string

required

Always collections.

string

required

Payment method. One of card-acq or applepay-acq.

object

required

Payment method data.

string

Encrypted Base64 card data. Required for card-acq; omit for applepay-acq.

object

required

Billing address. For applepay-acq, only country is required.

Show billing_address fields

string

required

First line of the billing address. Required for card-acq.

string

required

Billing city. Required for card-acq.

string

required

Billing state, region, or province. Required for card-acq.

string

required

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

string

Apartment, suite, or second address line.

string

Postal or ZIP code.

string

Card authentication model. Defaults to 3ds_required.

object

Browser data used for 3DS authentication. Required when auth_model is 3ds_required.

Show browser_info fields

string

required

The Accept header sent by the cardholder’s browser.

string

required

The cardholder’s browser user agent string.

string

required

The cardholder’s IP address.

string

required

The cardholder’s browser language, e.g. en-US.

boolean

required

Whether Java is enabled in the cardholder’s browser.

boolean

required

Whether JavaScript is enabled in the cardholder’s browser.

string

required

The cardholder’s screen color depth, in bits.

string

required

The cardholder’s screen width, in pixels.

string

required

The cardholder’s screen height, in pixels.

string

required

The cardholder’s timezone offset from UTC, in minutes.

string

The channel the payment is being made from. e.g. browser.

object

required

Customer details for the payment.

Show customer fields

string

required

Customer first name.

string

required

Customer last name.

string

required

Customer email address.

string

Customer phone number in E.164 format, when available.

string

URL to redirect the customer to after authentication. Required unless auth_model is 3ds_disabled.

Card request

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

Apple Pay request

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

Response

Returns an Intent Action. If requires_action is true, redirect the customer to next_action.url.

{
  "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.

Payment intent webhooks

Payment Intent webhooks notify your server when a payment reaches a final state. Subscribe to payment_intent.completed, payment_intent.failed, and payment_intent.cancelled to track a payment intent after confirmation. See Event types for the full payload schema, including the nested intent_action. Return a 2xx response to acknowledge receipt. See Webhooks for delivery and retry details.

Retrieve a payment intent

GET /payment-intents/{id} Returns a single Payment Intent, including its most recent intent_action if one exists.

string

required

Payment Intent ID.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

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

Response

Returns the Payment Intent object.

List payment intents

GET /payment-intents Returns a paginated list of Payment Intents.

string

Filter by status.

string

Filter by client reference.

string

Filter by currency.

string

Filter by account.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

string

Filter by creation date start.

string

Filter by creation date end.

number

Maximum number of records to return.

string

Cursor for the next page.

string

Cursor for the previous page.

curl "https://api.nuvion.dev/payment-intents?limit=2" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

List endpoints for Payment Intents and Intent Actions return the page under data.items, not data.data. This differs from the standard pagination envelope used elsewhere in the API.

{
  "status": "success",
  "message": "Payment intents fetched successfully",
  "data": {
    "items": [
      {
        "id": "01HXYZ5501ABCDEFGHJKMNPQRS",
        "currency": "USD",
        "amount": 1000,
        "reference": "order_abc123",
        "description": "Order #1042",
        "status": "completed",
        "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
        "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
        "created": 1787943000000
      },
      {
        "id": "01HXYZ5507ABCDEFGHJKMNPQRS",
        "currency": "USD",
        "amount": 100,
        "reference": "order_abc124",
        "description": "Order #1043",
        "status": "processing",
        "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
        "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
        "created": 1787944000000
      }
    ],
    "meta": {
      "pagination": {
        "order": "desc",
        "has_next": true,
        "limit": 2,
        "has_previous": false,
        "next_cursor": "01HXYZ5507ABCDEFGHJKMNPQRS",
        "previous_cursor": null
      },
      "filters_applied": {
        "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
        "sort": {
          "field": "created",
          "order": "desc"
        }
      }
    }
  }
}

Cancel a payment intent

PATCH /payment-intents/{id} Cancels a Payment Intent that has not been confirmed. Only intents with status: "requires_action" can be cancelled.

string

required

Payment Intent ID.

string

required

Must be cancel.

string

Cancellation reason. 1–100 characters.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

curl -X PATCH https://api.nuvion.dev/payment-intents/01HXYZ5511ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "cancel",
    "reason": "Customer abandoned checkout"
  }'

Response

{
  "status": "success",
  "message": "Payment intent modified successfully",
  "data": {
    "id": "01HXYZ5511ABCDEFGHJKMNPQRS",
    "currency": "USD",
    "amount": 1000,
    "reference": "order_abc126",
    "description": "Order #1045",
    "status": "cancelled",
    "status_reason": "Customer abandoned checkout",
    "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "created": 1787946000000,
    "intent_action": null
  }
}

Retrieve an intent action

GET /intent-actions/{id} Returns a single Intent Action.

string

required

Intent Action ID.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

curl https://api.nuvion.dev/intent-actions/01HXYZ5504ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

Returns the Intent Action object.

List intent actions

GET /intent-actions Returns a paginated list of Intent Actions.

string

Filter by currency.

string

Filter by client reference.

string

Filter by payment type. e.g. card-acq.

string

Filter by status.

string

Filter by Payment Intent ID.

string

Filter by account.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

string

Filter by creation date start.

string

Filter by creation date end.

number

Maximum number of records to return.

string

Cursor for the next page.

string

Cursor for the previous page.

curl "https://api.nuvion.dev/intent-actions?limit=2" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

Like List payment intents, this endpoint returns the page under data.items, not data.data.

{
  "status": "success",
  "message": "Payment intent actions fetched successfully",
  "data": {
    "items": [
      {
        "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",
        "created": 1787943005000
      },
      {
        "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",
        "created": 1787944005000
      }
    ],
    "meta": {
      "pagination": {
        "order": "desc",
        "has_next": true,
        "limit": 2,
        "has_previous": false,
        "next_cursor": "01HXYZ5508ABCDEFGHJKMNPQRS",
        "previous_cursor": null
      },
      "filters_applied": {
        "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
        "sort": {
          "field": "created",
          "order": "desc"
        }
      }
    }
  }
}

Verify an intent action

POST /intent-verifications/{id} Rechecks an Intent Action that has not reached a final status. If the action is already completed or failed, the current action is returned.

string

required

Intent Action ID.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

curl -X POST https://api.nuvion.dev/intent-verifications/01HXYZ5504ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

Returns the Intent Action object.

​The Payment Intent object

​Payment intent statuses

​The Intent Action object

​Intent action statuses

​Card data encryption

​Create a payment intent

​Request parameters

​Request

​Response

​Create and confirm in one request

​Confirm a payment intent

​Request parameters

​Card request

​Apple Pay request

​Response

​Payment intent webhooks

​Retrieve a payment intent

​Response

​List payment intents

​Response

​Cancel a payment intent

​Response

​Retrieve an intent action

​Response

​List intent actions

​Response

​Verify an intent action

​Response

The Payment Intent object

Payment intent statuses

The Intent Action object

Intent action statuses

Card data encryption

Create a payment intent

Request parameters

Request

Response

Create and confirm in one request

Confirm a payment intent

Request parameters

Card request

Apple Pay request

Response

Payment intent webhooks

Retrieve a payment intent

Response

List payment intents

Response

Cancel a payment intent

Response

Retrieve an intent action

Response

List intent actions

Response

Verify an intent action

Response